1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond-learning.tely
4 @node Fundamental concepts
5 @chapter Fundamental concepts
9 * How LilyPond files work::
10 * Voices contain music::
11 * Contexts and engravers::
12 * Extending the templates::
16 @node How LilyPond files work
17 @section How LilyPond files work
19 The LilyPond input format is quite free-form, giving experienced
20 users a lot of flexibility to structure their files however they
21 wish. But this flexibility can make things confusing for new
22 users. This section will explain some of this structure, but may
23 gloss over some details in favor of simplicity. For a complete
24 description of the input format, see @ruser{File structure}.
27 * Introduction to the LilyPond file structure::
28 * Score is a (single) compound musical expression::
29 * Nesting Music Expressions::
30 * On the un-nestedness of brackets and ties::
33 @node Introduction to the LilyPond file structure
34 @subsection Introduction to the LilyPond file structure
36 A basic example of a lilypond input file is
41 @var{...compound music expression...} % all the music goes here!
49 There are many variations of this basic pattern, but this
50 example serves as a useful starting place.
52 Up to this point none of the examples you have seen have used a
53 @code{\score@{@}} command. This is because LilyPond automatically
54 adds the extra commands which are needed when you give it simple
55 input. LilyPond treats input like this:
64 as shorthand for this:
81 In other words, if the input contains a single music expression,
82 LilyPond will interpret the file as though the music expression
83 was wrapped up inside the commands shown above. For now, though,
84 let us return to the first example and examine the @code{\score}
85 command, leaving the others to default.
87 A @code{\score} block must always contain just one music
89 this must appear first within the @code{\score @{..@}} block.
90 Remember that a music expression could be anything from a single
91 note to a huge compound expression like
96 @var{...insert the whole score of a Wagner opera in here...}
102 Since everything is inside @code{@{ ... @}}, it counts
103 as one music expression.
105 As we saw previously, the @code{\score} can contain other things,
118 Some people put some of those commands outside the @code{\score}
119 block -- for example, @code{\header} is often placed above the
120 @code{\score}. That's just another shorthand that LilyPond
123 Two more commands you have not previously seen are
124 @code{\layout @{ @}} and @code{\midi @{@}}. If these appear as
125 shown they will cause LilyPond to produce a printed output and a
126 MIDI out respectively. They are described fully in the
127 Notation Reference -- @ruser{Score layout} and
128 @ruser{Creating MIDI files}.
130 The @code{\book} command allows
131 several @code{\score} blocks to be combined into one output.
132 If there are several @code{\book} blocks each one produces a
133 separate output file. For details see @ruser{Multiple scores
138 Another great shorthand is the ability to define variables. All
139 the templates use this
142 melody = \relative c' @{
151 When LilyPond looks at this file, it takes the value of
152 @code{melody} (everything after the equals sign) and inserts it
153 whenever it sees @code{\melody}. There's nothing special about
154 the names -- it could be @code{melody}, @code{global},
156 @code{pianorighthand}, or @code{foofoobarbaz}. For more details,
157 see @ruser{Saving typing with variables and functions}.
158 Remember that you can use almost any name you like as long
159 as it contains just alphabetic characters and is distinct from
160 LilyPond command names. The exact
161 limitations on variable names are detailed in
162 @ruser{File structure}.
168 For a complete definition of the input format, see
169 @ruser{File structure}.
171 @node Score is a (single) compound musical expression
172 @subsection Score is a (single) compound musical expression
174 @cindex Compound music expression
175 @cindex Music expression, compound
177 We saw the general organization of LilyPond input files in the
178 previous section, @ref{How LilyPond files work}. But we seemed to
179 skip over the most important part: how do we figure out what to
180 write after @code{\score}?
182 We didn't skip over it at all. The big mystery is simply that
183 there @emph{is} no mystery. This line explains it all:
186 @emph{A @code{\score} must begin with a compound music expression.}
190 You may find it useful to review
191 @ref{Music expressions explained}. In that section, we saw how to
192 build big music expressions from small pieces -- we started from
193 notes, then chords, etc. Now we're going to start from a big
194 music expression and work our way down.
198 @{ % this brace begins the overall compound music expression
200 @var{...insert the whole score of a Wagner opera in here...}
202 @} % this brace ends the overall compound music expression
207 A whole Wagner opera would easily double the length of this
208 manual, so let's just add a singer and piano. We don't need a
209 @code{GrandStaff} for this ensemble, which simply groups a number
210 of staves together with a brace at the left, so we shall remove
211 it. We @emph{do} need a singer and a piano, though.
217 \new Staff = "singer" <<
219 \new PianoStaff = piano <<
227 Remember that we use @code{<<} and @code{>>} to show simultaneous
228 music. And we definitely want to show the vocal part and piano
229 part at the same time, not one after the other! However, the
230 @code{<< .. >>} construct is not really necessary for the Singer
231 staff, as it contains only one music expression, but Staves often
232 do require simultaneous Voices within them, so using @code{<< .. >>}
233 rather than braces is a good habit to adopt.
239 \new Staff = "singer" <<
240 \new Voice = "vocal" @{ @}
243 \new PianoStaff = "piano" <<
244 \new Staff = "upper" @{ @}
245 \new Staff = "lower" @{ @}
253 Now we have a lot more details. We have the singer's staff: it
254 contains a @code{Voice} (in LilyPond, this term refers to a set of
255 notes, not necessarily vocal notes -- for example, a violin
256 generally plays one voice) and some lyrics. We also have a piano
257 staff: it contains an upper staff (right hand) and a lower staff
260 At this stage, we could start filling in notes. Inside the curly
261 braces next to @code{\new Voice = vocal}, we could start writing
269 But if we did that, the @code{\score} section would get pretty
270 long, and it would be harder to understand what was happening. So
271 let's use variables instead.
274 melody = \relative c'' @{ @}
275 text = \lyricmode @{ @}
276 upper = \relative c'' @{ @}
277 lower = \relative c @{ @}
281 \new Staff = "singer" <<
282 \new Voice = "vocal" @{ \melody @}
283 \addlyrics @{ \text @}
285 \new PianoStaff = "piano" <<
286 \new Staff = "upper" @{ \upper @}
287 \new Staff = "lower" @{ \lower @}
295 Be careful about the difference between notes, which are introduced
296 with @code{\relative}, and lyrics, which are introduced with
297 @code{\lyricmode}. These are essential to tell LilyPond
298 to interpret the following content as music and text
301 When writing (or reading) a @code{\score} section, just take it
302 slowly and carefully. Start with the outer layer, then work on
303 each smaller layer. It also really helps to be strict with
304 indentation -- make sure that each item on the same layer starts
305 on the same horizontal position in your text editor.
308 @node Nesting Music Expressions
309 @subsection Nesting Music Expressions
311 It is not essential to declare all staves at the beginning;
312 they may be introduced temporarily at any point. This is
313 particularly useful for creating ossia sections
314 (see @rglos{ossia}). Here is a simple example showing how
315 to introduce a new staff temporarily for the duration of
318 @lilypond[verbatim,quote,ragged-right]
334 The ossia section may be placed above the staff
337 @lilypond[verbatim,quote,ragged-right]
345 alignAboveContext = "main" }
353 This example uses @code{\with}, which will be explained more
354 fully later. It is a means of modifying the default behaviour
355 of a Staff. Here it says that the new staff should be placed
356 above the staff called @qq{main} instead of the default position
359 Ossia are often written without clef and without
360 time signature and are usually in a smaller font.
361 These require further commands which
362 have not yet been introduced. See ...
364 TODO Add ref to tweaks section where this example should
365 be placed and explained.
367 @node On the un-nestedness of brackets and ties
368 @subsection On the un-nestedness of brackets and ties
370 You have already met a number of different types of bracket in
371 writing the input file to LilyPond. These obey different rules
372 which can be confusing at first. Before we explain the rules
373 let's first review the different types of bracket.
375 @c attempt to force this onto a new page
377 @multitable @columnfractions .3 .7
378 @headitem Bracket Type
380 @item @code{@{ .. @}}
381 @tab Encloses a sequential segment of music
383 @tab Encloses the notes of a chord
384 @item @code{<< .. >>}
385 @tab Encloses concurrent or simultaneous sections
387 @tab Marks the start and end of a slur
388 @item @code{\( .. \)}
389 @tab Marks the start and end of a phrase mark
391 @tab Marks the start and end of a manual beam
394 To these we should add other constructs which generate lines
395 between or across notes: ties (marked by a tilde, @code{~}),
396 tuplets written as @code{\times x/y @{..@}}, and grace notes
397 written as @code{\grace@{..@}}.
399 Outside LilyPond, the conventional use of brackets requires
400 the different types to be properly nested, like this,
401 @code{<< [ @{ ( .. ) @} ] >>}, with the closing brackets being
402 encountered in exactly the opposite order to the opening
403 brackets. This @strong{is} a requirement for the three types of
404 bracket described by the word @q{Encloses} in the table above --
405 they must nest properly.
406 However, the remaining brackets, described with the word
407 @q{Marks} in the table above together with ties and tuplets,
408 do @strong{not} have to nest
409 properly with any of the brackets. In fact, these are not
410 brackets in the sense that
411 they enclose something -- they are simply markers to indicate
412 where something starts and ends.
414 So, for example, a phrasing slur can start before a manually
415 inserted beam and end before the end of the beam -- not very
416 musical, perhaps, but possible:
418 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
419 { g8\( a b[ c b\) a] }
422 In general, different kinds of brackets, and those implied by
423 tuplets, ties and grace notes, may be mixed freely.
424 This example shows a beam extending into a tuplet (line 1),
425 a slur extending into a tuplet (line 2),
426 a beam and a slur extending into a tuplet, a tie crossing
427 two tuplets, and a phrasing slur extending out of a tuplet
430 @lilypond[quote,verbatim,fragment,ragged-right]
432 r16[ g16 \times 2/3 {r16 e'8] }
433 g16( a \times 2/3 {b d) e' }
434 g8[( a \times 2/3 {b d') e'~]}
435 \times 4/5 {e'32\( a b d' e'} a'4.\)
440 @node Voices contain music
441 @section Voices contain music
443 Singers need voices to sing, and so does LilyPond.
444 The actual music for all instruments in a score
445 is contained in Voices -- the most fundamental
446 of all LilyPond's concepts.
449 * I'm hearing Voices::
450 * Explicitly instantiating voices::
451 * Voices and vocals::
454 @node I'm hearing Voices
455 @subsection I'm hearing Voices
459 @cindex Voice context
461 The lowest, most fundamental or innermost layers in a LilyPond
462 score are called @q{Voice contexts} or just @q{Voices} for short.
463 Voices are sometimes called @q{layers} in other notation
466 In fact, a Voice layer or context is the only one which can
467 contain music. If a Voice context is not explicitly declared
468 one is created automatically, as we saw at the beginning of
469 this chapter. Some instruments such as an
470 Oboe can play only one note at a time. Music written for
471 such instruments is monophonic and requires just a single
472 voice. Instruments which can play more than one note at a
473 time like the piano will often require multiple voices to
474 encode the different concurrent notes and rhythms they are
477 A single voice can contain many notes in a chord, of course,
478 so when exactly are multiple voices needed?
479 Let us analyse a short piece of music to see how many voices
480 are required. Here are the notes from the first two bars
481 of the second of Chopin's Deux Nocturnes, Op 32.
483 @c The following should appear as music without code
484 @lilypond[quote,ragged-right]
485 \new Staff \relative c'' {
493 \once \override NoteColumn #'force-hshift = #0 <ees c>2
494 \once \override NoteColumn #'force-hshift = #0.5 des2 }
500 The direction of the stems is often used to indicate the
501 continuity of two simultaneous melodic lines. Here the
502 stems of the highest notes are all pointing up and the
503 stems of the lower notes are all pointing down.
504 This is the first indication that more than one voice
507 But the real need for multiple voices arises when notes
508 which start at the same time have different durations.
509 Look at the notes which start at beat three in the first
510 bar. The a-flat is a dotted quarter note, the f is a
511 quarter note and the d-flat is a half note. These
512 cannot be written as a chord as all the notes in a chord
513 must have the same duration. Neither can they be written
514 as sequential notes, as they must start at the same time.
515 This section of the bar requires three voices, and the
516 normal practice would be to write the whole bar as three
517 voices, as shown here, where we have used different noteheads
518 and colors for the three voices.
520 @c The following should appear as music without code
521 @c The three voice styles should be defined in -init
522 @lilypond[quote,ragged-right]
523 \new Staff \relative c'' {
534 \once \override NoteColumn #'force-hshift = #0 <ees c>2
535 \once \override NoteColumn #'force-hshift = #0.5 des2 }
541 Let us see how this is done.
545 The easiest way to enter fragments with more than one voice on a
546 staff is to enter each voice as a sequence (with @code{@{...@}}),
547 and combine them simultaneously with angle brackets, @code{<<...>>}.
548 The fragments must also be separated with double backward slashes,
549 @code{\\}, to place them in separate voices. Without these, the
550 notes would be entered into a single voice, which would usually
551 cause errors. This technique is particularly suited to pieces of
552 music which are largely monophonic with occasional short sections
553 of polyphony. Here's a simple example:
555 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
557 % Voice "1" Voice "2"
558 << { r4 g g4. a8 } \\ { d,2 d4 g } >> |
559 << { bes4 bes c bes } \\ { g4 g g8( a) g4 } >> |
560 << { a2. r4 } \\ { fis2. s4 } >>
563 It is not necessary to use a separate @code{<< \\ >>} construct
564 for each bar, but it does help the legibility of the code. TODO
566 This example has just two voices, but the same contruct may be
567 used to encode three or more voices by adding more back-slash
570 The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
571 In each of these contexts, the vertical direction of slurs,
572 stems, ties, dynamics etc., is set appropriately.
574 @lilypond[quote,verbatim,fragment]
575 \new Staff \relative c' {
578 % Voice "1" Voice "2" Voice "3"
579 << { g4 f e } \\ { r8 e4 d c8 ~ } >> |
580 << { d2 e2 } \\ { c8 b16 a b8 g ~ g2 } \\ { s4 b4 c2 } >> |
584 These voices are all separate from the main voice that contains
585 the notes just outside the @code{<< .. >>} construct. Let's call
586 this the @emph{simultaneous construct}. Slurs and ties may only
587 connect notes within the same voice, so slurs and ties cannot go
588 into or out of a simultaneous construct. Conversely,
589 parallel voices from separate simultaneous constructs on the same
590 staff are the same voice. Other voice-related properties also
591 carry across simultaneous constructs. Here is the same example,
592 with different colors and noteheads for each voice. Note that
593 changes in one Voice do not affect other voices, but they do
594 persist in the same Voice later. Note also that tied notes may be
595 split across the same voices in two constructs, shown here in the
598 @lilypond[quote,verbatim]
599 \new Staff \relative c' {
611 { c8 b16 a b8 g ~ g2 } \\
620 The commands @code{\voiceXXXStyle} are mainly intended for use in
621 educational documents such as this one. They modify the color
622 of the notehead, the stem and the beams, and the style of the
623 notehead, so that the voices may be easily distinguished.
624 Voice one is set to red diamonds, voice two to blue triangles,
625 voice three to green crossed circles, and voice four (not used
626 here) to magenta crosses. We shall see later how commands like
627 these may be created by the user.
628 TODO: add ref to appropriate section in Tweaks
630 Polyphony does not change the relationship of notes within a
631 @code{\relative @{ @}} block. Each note is still calculated
632 relative to the note immediately preceding it, or to the first
633 note of the preceding chord. So in
636 \relative c' @{ noteA << < noteB noteC > \\ noteD >> noteE @}
640 @code{noteB} is relative to @code{noteA} @*
641 @code{noteC} is relative to @code{noteB}, not @code{noteA}; @*
642 @code{noteD} is relative to @code{noteB}, not @code{noteA} or
644 @code{noteE} is relative to @code{noteD}, not @code{noteA}
646 We are now in a position to return to the first example from
647 the Chopin Nocturne to see how this might be encoded. As we
648 shall see, this encounters some difficulties. We begin as
649 we have learnt, using the @code{<< \\ >>} construct to
650 enter the music of the first bar in three voices:
652 @lilypond[quote,verbatim,fragment,ragged-right]
653 \new Staff \relative c'' {
656 { c2 aes4. bes8 } \\ { aes2 f4 fes } \\ { <ees c>2 des2 }
666 @funindex \voiceThree
669 The stem directions are automatically assigned with the
670 odd-numbered voices taking upward stems and the even-numbered
671 voices downward ones. The stems for voices 1 and 2 are right,
672 but the stems in voice 3 should go down in this particular piece
673 of music. We can correct this
674 by telling LilyPond that this third voice is really a fourth
675 voice, with stems going down, using the @code{\voiceFour}
676 command. There are also corresponding @code{\voiceOne},
677 @code{\voiceTwo}, and @code{\voiceThree}
678 commands. This results in the following:
680 @lilypond[quote,verbatim,fragment,ragged-right]
681 \new Staff \relative c'' {
686 { \voiceFour <ees c>2 des2 }
693 and exposes a problem commonly encountered with multiple
694 voices: the stems of notes can collide with noteheads
695 in other voices. In laying out the notes, LilyPond allows the
696 notes or chords from two voices to occupy the same vertical
697 note column provided the stems are in opposite directions, but
698 the notes from a third voice are displaced to avoid the stems
699 colliding. This often works well, but in this example the
700 notes of the third voice are clearly not well placed by default.
701 LilyPond provides several ways to adjust the horizontal placing
702 of notes. We are not quite ready yet to see how to correct this,
703 so we shall leave this problem until a later section (see ... )
707 @node Explicitly instantiating voices
708 @subsection Explicitly instantiating voices
710 Voice contexts can also be created manually
711 inside a @code{<< >>} block to create polyphonic music, using
712 @code{\voiceOne} ... @code{\voiceFour} to indicate the required
713 directions of stems, slurs, etc. In longer scores this method
714 is clearer, as it permits the voices to be separated and to be
715 given more descriptive names.
717 Specifically, the construct @code{<< \\ >>} which we used in
718 the previous section:
723 << @{ e4 f g a @} \\ @{ c,4 d e f @} >>
733 \new Voice = "1" @{ \voiceOne \relative c' @{ e4 f g a @} @}
734 \new Voice = "2" @{ \voiceTwo \relative c' @{ c4 d e f @} @}
738 Both of the above would produce
740 @c The following example should not display the code
741 FIXME: weird compiling bug! Leave for gp.
742 @c @lilypond{ragged-right,quote]
744 @c % << { e4 f g a } \\ { c,4 d e f } >>
748 The @code{\voiceXXX} commands set the direction of stems, slurs,
749 ties, articulations, text annotations, augmentation dots of dotted
750 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
751 make these objects point upwards, while @code{\voiceTwo} and
752 @code{\voiceFour} make them point downwards. These commands also
753 generate a horizontal shift for each voice when this is required
754 to avoid clashes of note heads. The command @code{\oneVoice}
755 reverts the settings back to the normal values for a single voice.
757 Let us see in some simple examples exactly what effect
758 @code{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on
759 markup, ties, slurs, and dynamics:
761 @lilypond[quote,ragged-right,verbatim]
763 c-"default" d8 ~ d e4 ( f g a ) b-> c
767 @lilypond[quote,ragged-right,verbatim]
770 c d8 ~ d e4 ( f g a ) b-> c
772 c, d8 ~ d e4 ( f g a ) b-> c
776 @lilypond[quote,ragged-right,verbatim]
779 c d8 ~ d e4 ( f g a ) b-> c
781 c, d8 ~ d e4 ( f g a ) b-> c
785 An expression that appears directly inside a @code{<< >>} belongs
786 to the main voice (but, note, @strong{not} in a @code{<< \\ >>}
787 construct). This is useful when extra voices appear while the
788 main voice is playing. Here is a more correct rendition of the
789 example from the previous section. The red diamond-shaped notes
790 demonstrate that the main melody is now in a single voice context,
791 permitting a phrasing slur to be drawn over them.
793 @lilypond[quote,ragged-right,verbatim]
794 \new Staff \relative c' {
796 c16^( d e f % These notes are monophonic
797 << % Start simultaneous section of three voices
798 { g4 f e | d2 e2) } % Continue the main voice in parallel
799 \new Voice { % Initiate second voice
800 \voiceTwo % Set stems, etc, down
801 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
803 \new Voice { % Initiate third voice
804 \voiceThree % Set stems, etc, up
811 @cindex nesting music expressions
812 @cindex nesting simultaneous constructs
814 More deeply nested polyphony constructs are possible, and if a
815 voice appears only briefly this might be a more natural way to
818 @lilypond[quote,ragged-right,verbatim]
819 \new Staff \relative c' {
839 This method of nesting new voices briefly is useful
840 when only small sections of the music
841 are polyphonic, but when the whole staff is largely polyphonic
842 it can be clearer to use multiple voices throughout, using
843 spacing notes to step over sections where the voice is silent,
846 @lilypond[quote,ragged-right,verbatim]
847 \new Staff \relative c' <<
848 \new Voice { % Initiate first voice
850 c16^( d e f g4 f e | d2 e2) |
852 \new Voice { % Initiate second voice
853 \voiceTwo % set stems, etc down
854 s4 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 |
856 \new Voice { % Initiate third voice
857 \voiceThree % set stems, etc up
864 @node Voices and vocals
865 @subsection Voices and vocals
867 Vocal music presents a special difficulty: we need to combine two
868 expressions -- notes and lyrics.
870 You have already seen the @code{\addlyrics@{@}} command, which
871 handles simple scores well. However, this technique is
872 quite limited. For more complex music, you must introduce the
873 lyrics in a @code{Lyrics} context using @code{\new Lyrics} and
875 the lyrics to the notes with @code{\lyricsto@{@}}, using the
876 name assigned to the Voice.
878 @lilypond[quote,verbatim,fragment]
880 \new Voice = "one" \relative c'' {
883 c4 b8. a16 g4. f8 e4 d c2
885 \new Lyrics \lyricsto "one" {
886 No more let sins and sor -- rows grow.
891 The automatic beaming which LilyPond uses by default works well
892 for instrumental music, but not so well for music with lyrics,
893 where beaming is either not required at all or is used to indicate
894 melismata in the lyrics. In the example above we use the command
895 @code{\autoBeamOff} to turn off the automatic beaming.
897 Let us reuse the earlier example from Judas Maccabæus to
898 illustrate this more flexible technique. We first recast
899 it to use variables so the music and lyrics can be separated
900 from the staff structure. We also introduce a ChoirStaff
901 bracket. The lyrics themselves must be introduced with
902 @code{\lyricmode} to ensure they are interpreted as lyrics
905 @lilypond[quote,verbatim]
906 global = { \time 6/8 \partial 8 \key f \major}
907 SopOneMusic = \relative c'' {
908 c8 | c([ bes)] a a([ g)] f | f'4. b, | c4.~ c4 }
909 SopTwoMusic = \relative c' {
910 r8 | r4. r4 c8 | a'([ g)] f f([ e)] d | e([ d)] c bes' }
911 SopOneLyrics = \lyricmode {
912 Let | flee -- cy flocks the | hills a -- dorn, __ }
913 SopTwoLyrics = \lyricmode {
914 Let | flee -- cy flocks the | hills a -- dorn, }
919 \new Voice = "SopOne" {
923 \new Lyrics \lyricsto "SopOne" {
928 \new Voice = "SopTwo" {
931 \new Lyrics \lyricsto "SopTwo" {
939 This is the basic structure of all vocal scores. More staves may
940 be added as required, more voices may be added to the staves,
941 more verses may be added to the lyrics,
942 and the variables containing the music can easily be placed
943 in separate files should they become too long.
945 Here is a final example of the first line of a hymn with four
946 verses, set for SATB. In this case the words for all four
949 @lilypond[quote,verbatim]
950 TimeKey = { \time 4/4 \partial 4 \key c \major}
951 SopMusic = \relative c' { c4 | e4. e8 g4 g | a a g }
952 AltoMusic = \relative c' { c4 | c4. c8 e4 e | f f e }
953 TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 }
954 BassMusic = \relative c { c4 | c4. c8 c4 c | f8 g a b c4 }
955 VerseOne = \lyricmode {
956 E -- | ter -- nal fa -- ther, | strong to save, }
957 VerseTwo = \lyricmode {
958 O | Christ, whose voice the | wa -- ters heard, }
959 VerseThree = \lyricmode {
960 O | Ho -- ly Spi -- rit, | who didst brood }
961 VerseFour = \lyricmode {
962 O | Tri -- ni -- ty of | love and pow'r }
968 \new Voice = "Sop" { \voiceOne \TimeKey \SopMusic }
969 \new Voice = "Alto" { \voiceTwo \AltoMusic }
970 \new Lyrics \lyricsto "Sop" { \VerseOne }
971 \new Lyrics \lyricsto "Sop" { \VerseTwo }
972 \new Lyrics \lyricsto "Sop" { \VerseThree }
973 \new Lyrics \lyricsto "Sop" { \VerseFour }
977 \new Voice = "Tenor" { \voiceOne \TenorMusic }
978 \new Voice = "Bass" { \voiceTwo \BassMusic }
984 @node Contexts and engravers
985 @section Contexts and engravers
987 Contexts and engravers have been mentioned informally
988 in earlier sections; we now must look at
989 these concepts in more detail, as they are important
990 in the fine-tuning of LilyPond output.
994 * Contexts explained::
995 * Creating contexts::
996 * Engravers explained::
997 * Modifying context properties::
998 * Adding and removing engravers::
1001 @node Contexts explained
1002 @subsection Contexts explained
1004 When music is printed, many notational elements which do not
1005 appear explicitly in the input file must be added to the
1006 output. For example, compare the input and output of the
1009 @lilypond[quote,verbatim,relative=2,fragment]
1013 The input is rather sparse, but in the output, bar lines,
1014 accidentals, clef, and time signature have been added. When
1015 LilyPond @emph{interprets} the input the musical information
1016 is inspected in time order, similar to reading a score from left
1017 to right. While reading the input, the program remembers where
1018 measure boundaries are, and which pitches require explicit
1019 accidentals. This information must be held on several levels.
1020 For example, the effect of an accidental is limited
1021 to a single staff, while a bar line must be synchronized across
1024 Within LilyPond, these rules and bits of information are grouped
1025 in @emph{Contexts}. We have already met the
1026 @code{Voice} context.
1027 Others are the @code{Staff} and @code{Score} contexts.
1028 Contexts are hierarchical to reflect the heirarchical nature of
1030 For example: a @code{Staff} context can contain many
1031 @code{Voice} contexts, and a @code{Score} context can
1032 contain many @code{Staff} contexts.
1035 @image{context-example,5cm,,}
1038 Each context has the responsibility for enforcing some notation rules,
1039 creating some notation objects and maintaining the associated
1040 properties. For example, the @code{Voice} context may introduce an
1041 accidental and then the @code{Staff} context maintains the rule to
1042 show or suppress the accidental for the remainder of the measure.
1044 As another example, the synchronization of bar lines is, by default,
1045 handled in the @code{Score} context.
1046 However, in some music we may not want the bar lines to be
1047 synchronized -- consider a polymetric score in 4/4 and 3/4 time.
1048 In such cases, we must modify the default settings of the
1049 @code{Score} and @code{Staff} contexts.
1051 For very simple scores, contexts are created implicitly, and you need
1052 not be aware of them. For larger pieces, such as anything with more
1053 than one staff, they must be
1054 created explicitly to make sure that you get as many staves as you
1055 need, and that they are in the correct order. For typesetting pieces
1056 with specialized notation, it is usual to modify existing, or
1057 even to define totally new, contexts.
1059 In addition to the @code{Score,} @code{Staff} and
1060 @code{Voice} contexts there are contexts which fit between
1061 the score and staff levels to control staff groups, such as the
1062 @code{PianoStaff} and @code{ChoirStaff} contexts. There
1063 are also alternative staff and voice contexts, and contexts for
1064 lyrics, percussion, fret boards, figured bass, etc. A complete
1065 list is shown in the Notation Reference.
1068 The names of all context types are formed from one or more
1069 words, each word being capitalised and joined immediately to the
1070 preceding word with no hyphen or underscore, e.g.,
1071 @code{GregorianTranscriptionStaff}.
1073 @node Creating contexts
1074 @subsection Creating contexts
1076 There can be only one top level context: the
1078 context. This is created with the @code{\score} command,
1079 or, in simple scores, it is created automatically.
1081 For scores with only one voice and one staff, the
1082 @code{Voice} and @code{Staff} contexts may be left to be
1083 created automatically, but for more complex scores it is
1084 necessary to create them by hand.
1085 The simplest command that does this is @code{\new}.
1086 It is prepended to a music expression, for example
1089 @cindex new contexts
1090 @cindex Context, creating
1093 \new @var{type} @var{music-expression}
1097 where @var{type} is a context name (like @code{Staff} or
1098 @code{Voice}). This command creates a new context, and starts
1099 interpreting the @var{music-expression} within that context.
1101 Note that there is no @code{\new Score} command;
1102 the single top-level @code{Score} context is introduced
1105 The @code{\new} command may also give a identifying name to the
1106 context to distinguish it from other contexts of the same type,
1109 \new @var{type} = @var{id} @var{music-expression}
1112 Note the distinction between the name of the context type,
1113 @code{Staff}, @code{Voice}, etc, and
1114 the identifying name of a particular instance of that type,
1115 which can be any sequence of letters invented by the user.
1116 The identifying name is used to refer back to that particular
1117 instance of a context. We saw this in use in the section on
1118 lyrics in @ref{Voices and vocals}.
1121 @node Engravers explained
1122 @subsection Engravers explained
1126 Every mark on the printed output of a score produced by LilyPond
1127 is produced by an @code{Engraver}. Thus there is an engraver
1128 to print staves, one to print noteheads, one for stems, one for
1129 beams, etc, etc. In total there are over 120 such engravers!
1130 Fortunately, for most scores it is not necessary to know about
1131 more than a few, and for simple scores you do not need to know
1134 Engravers live and operate in Contexts.
1135 Engravers such as the @code{Metronome_mark_engraver}, whose
1136 action and output applies to the score as a whole, operate in
1137 the highest level context -- the @code{Score} context.
1139 The @code{Clef_engraver} and @code{Key_engraver} are to be
1140 found in every Staff Context, as different staves may require
1141 different clefs and keys.
1143 The @code{Note_heads_engraver} and @code{Stem_engraver} live
1144 in each @code{Voice} context, the lowest level context of all.
1146 Each engraver processes the particular objects associated
1147 with its function, and maintains the properties that relate
1148 to that function. These properties, like the properties
1149 associated with contexts, may be modified to change the
1150 operation of the engraver or the appearance of those elements
1151 in the printed score.
1153 Engravers all have compound names formed from words which
1154 describe their function. Just the first word is capitalised,
1155 and the remainder are joined to it with underscores. Thus
1156 the @code{Staff_symbol_engraver} is responsible for creating the
1157 lines of the staff, the @code{Clef_engraver} determines and sets
1158 the pitch reference point on the staff by drawing a clef symbol.
1160 Here are some of the most common engravers together with their
1161 function. You will see it is easy to guess the function from
1162 the name, or vice versa.
1164 @multitable @columnfractions .3 .7
1167 @item Accidental_engraver
1168 @tab Makes accidentals, cautionary and suggested accidentals
1173 @item Dynamic_engraver
1174 @tab Creates hairpins and dynamic texts
1176 @tab Creates the key signature
1177 @item Metronome_mark_engraver
1178 @tab Engraves metronome marking
1179 @item Note_heads_engraver
1180 @tab Engraves noteheads
1183 @item Staff_symbol_engraver
1184 @tab Engraves the five (by default) lines of the staff
1186 @tab Creates stems and single-stem tremulos
1187 @item Time_signature_engraver
1188 @tab Creates time signatures
1193 We shall see later how the output of LilyPond can be changed
1194 by modifying the action of Engravers.
1197 @node Modifying context properties
1198 @subsection Modifying context properties
1200 @cindex context properties
1204 Contexts are responsible for holding the values of a number of
1205 context @emph{properties}. Many of them can be changed to
1206 influence the interpretation of the input and so change the
1207 appearance of the output. They are changed by the
1208 @code{\set} command. This takes the form
1211 \set @emph{ContextName}.@emph{propertyName} = @emph{value}
1214 Where the @emph{ContextName} is usually @code{Score},
1215 @code{Staff} or @code{Voice}. It may be omitted,
1216 in which case @code{Voice} is assumed.
1218 The names of context properties consist of words joined
1219 together with no hyphens or underscores, all except the
1220 first having a capital letter. Here are a few examples
1221 of some commonly used ones. There are many more.
1223 @c attempt to force this onto a new page
1225 @multitable @columnfractions .2 .2 .6
1226 @headitem propertyName
1231 @tab If true (##t), set extra natural signs before accidentals
1232 @item currentBarNumber
1234 @tab Set the current bar number
1237 @tab If true (##t), print slurs both above and below notes
1238 @item instrumentName
1240 @tab Set the name to be placed at the start of the staff
1243 @tab Increase or decrease the font size
1246 @tab Set the text to print before the start of a verse
1251 Before we can set any of these properties we need to know
1252 in which context they operate. Sometimes this is obvious,
1253 but occasionally it can be tricky. If the wrong context
1254 is specified, no error message is produced, but the expected
1255 action will not be taken. For example, the
1256 @code{instrumentName} clearly lives in the Staff context, since
1257 it is the staff that is to be named.
1258 In this example the first staff is labelled, but not the second,
1259 because we omitted the context name.
1261 @lilypond[quote,verbatim,ragged-right]
1263 \new Staff \relative c'' {
1264 \set Staff.instrumentName = "Soprano"
1267 \new Staff \relative c' {
1268 \set instrumentName = "Alto" % Wrong!
1274 Remember the default context name is Voice, so the second
1275 @code{\set} command set the property @code{instrumentName} in the
1276 Voice context to @qq{Alto}, but as LilyPond does not look
1277 for any such property in the @code{Voice} context, no
1278 further action took place. This is not an error, and no error
1279 message is logged in the log file.
1281 Similarly, if the property name is mis-spelt no error message
1282 is produced, and clearly the expected action cannot be performed.
1283 If fact, you can set any (fictitious) @q{property} using any
1284 name you like in any context that exists by using the
1285 @code{\set} command. But if the name is not
1286 known to LilyPond it will not cause any action to be taken.
1287 This is one of the reasons why it is highly recommended to
1288 use a context-sensitive editor with syntax highlighting for
1289 editing LilyPond files, such as Vim, Jedit, ConTEXT or Emacs,
1290 since unknown property names will be highlighted differently.
1292 The @code{instrumentName} property will take effect only
1293 if it is set in the @code{Staff} context, but
1294 some properties can be set in more than one context.
1295 For example, the property @code{extraNatural} is by
1296 default set to ##t (true) for all staves.
1297 If it is set to ##f (false) in the @code{Staff} context
1298 it applies just to the accidentals on that staff.
1299 If it is set to false in the @code{Score} context
1300 it applies to all staves.
1302 So this turns off extra naturals in one staff:
1304 @lilypond[quote,verbatim,ragged-right]
1306 \new Staff \relative c'' {
1309 \new Staff \relative c'' {
1310 \set Staff.extraNatural = ##f
1317 and this turns them off in all staves:
1319 @lilypond[quote,verbatim,ragged-right]
1321 \new Staff \relative c'' {
1324 \new Staff \relative c'' {
1325 \set Score.extraNatural = ##f
1331 The value of every property set in this way can be reset
1332 to its original value with the @code{\unset} command.
1334 The @code{\set} and @code{\unset} commands can appear anywhere
1335 in the input file and will take effect from the time they are
1336 encountered until the end of the score or until the property is
1337 @code{\set} or @code{\unset} again. Let's try changing the
1338 font size, which affects the size of the note heads (among
1339 other things) several times.
1341 @lilypond[quote,verbatim,ragged-right,relative=1,fragment]
1343 \set fontSize = #-4 % make noteheads smaller
1345 \set fontSize = #2.5 % make noteheads larger
1347 \unset fontSize % return to original size
1351 We have now seen how to set the values of several different
1352 types of property. Note that integers and numbers are alway
1353 preceded by a hash sign, @code{#}, while a true or false value
1354 is specified by ##t and ##f, with two hash signs. A text
1355 property should be enclosed in double quotation signs, as above,
1356 although we shall see later that text can actually be specified
1357 in a much more general way by using the very powerful
1358 @code{markup} command.
1363 Context properties may also be set at the time the context is
1364 created. Sometimes this is a clearer way of specifying a
1365 property value if it is to remain fixed for the duration of
1366 the context. When a context is created with a @code{\new}
1367 command it may be immediately followed by a
1368 @code{\with @{ .. @}} block in which the property values are
1369 set. For example, if we wish to suppress the printing of
1370 extra naturals for the duration of a staff we would write:
1372 @lilypond[quote,verbatim,ragged-right]
1381 In effect this overrides the default value of the property. It
1382 may still be changed dynamically using @code{\set} and
1385 @node Adding and removing engravers
1386 @subsection Adding and removing engravers
1388 @cindex Engravers, adding
1389 @cindex Engravers, removing
1394 We have seen that contexts each contain several engravers, each
1395 of which is responsible for producing a particular part of the
1396 output, like barlines, staves, note heads, stems, etc. If an
1397 engraver is removed from a context it can no longer produce its
1398 output. This is a crude way of modifying the output, but it
1399 can sometimes be useful.
1401 To remove an engraver we can use the @code{\with} command placed
1402 immediately after the context creation command, as in the
1406 illustration let's repeat an example from the previous
1407 section with the staff lines removed. Remember that the
1408 staff lines are produced by the Staff_symbol_engraver.
1410 @lilypond[quote,verbatim,ragged-right]
1412 \remove Staff_symbol_engraver
1416 \set fontSize = #-4 % make noteheads smaller
1418 \set fontSize = #2.5 % make noteheads larger
1420 \unset fontSize % return to original size
1425 @cindex ambitus engraver
1427 Engravers can also be added to contexts. The command
1430 @code{\consists @emph{Engraver_name}},
1432 placed inside a @code{\with} block. Some vocal scores
1433 have an @rglos{ambitus} placed at the beginning of a
1434 staff to indicate the range of notes in that staff.
1435 The ambitus is produced by the @code{Ambitus_engraver},
1436 which is not normally included in any context. If
1437 we add it to the @code{Voice} context it calculates
1438 the range from that voice only:
1440 @lilypond[quote,verbatim,ragged-right]
1443 \consists Ambitus_engraver
1458 but if we add the Ambitus engraver to the
1459 @code{Staff} context it calculates the range from all
1460 the notes in all the voices on that staff:
1462 @lilypond[quote,verbatim,ragged-right]
1464 \consists Ambitus_engraver
1481 @node Extending the templates
1482 @section Extending the templates
1484 You've read the tutorial, you know how to write music, you
1485 understand the fundamental concepts. But how can you
1486 get the staves that you want? Well, you can find lots of
1487 templates (see @ref{Templates}) which may give you a start.
1489 if you want something that isn't covered there? Read on.
1492 * Soprano and cello::
1493 * Four-part SATB vocal score::
1494 * Building a score from scratch::
1497 @node Soprano and cello
1498 @subsection Soprano and cello
1500 Start off with the template that seems closest to what you want to end
1501 up with. Let's say that you want to write something for soprano and
1502 cello. In this case, we would start with @q{Notes and lyrics} (for the
1507 melody = \relative c' @{
1515 text = \lyricmode @{
1521 \new Voice = "one" @{
1525 \new Lyrics \lyricsto "one" \text
1532 Now we want to add a cello part. Let's look at the @q{Notes only} example:
1536 melody = \relative c' @{
1551 We don't need two @code{\version} commands. We'll need the @code{melody}
1552 section. We don't want two @code{\score} sections -- if we had two
1553 @code{\score}s, we'd get the two parts separately. We want them together,
1554 as a duet. Within the @code{\score} section, we don't need two
1555 @code{\layout} or @code{\midi}.
1557 If we simply cut and paste the @code{melody} section, we would end up with
1558 two @code{melody} sections. So let's rename them. We'll call the section
1559 for the soprano @code{sopranoMusic} and the section for the cello
1560 @code{celloMusic}. While we're doing this, let's rename @code{text}
1561 to be @code{sopranoLyrics}. Remember to rename both instances of all
1562 these names -- both the initial definition (the
1563 @code{melody = relative c' @{ } part) and the name's use (in the
1564 @code{\score} section).
1566 While we're doing this, let's change the cello part's staff -- celli
1567 normally use bass clef. We'll also give the cello some different
1572 sopranoMusic = \relative c' @{
1580 sopranoLyrics = \lyricmode @{
1584 celloMusic = \relative c @{
1594 \new Voice = "one" @{
1598 \new Lyrics \lyricsto "one" \sopranoLyrics
1605 This is looking promising, but the cello part won't appear in the
1606 score -- we haven't used it in the @code{\score} section. If we
1607 want the cello part to appear under the soprano part, we need to add
1610 \new Staff \celloMusic
1614 underneath the soprano stuff. We also need to add @code{<<} and
1615 @code{>>} around the music -- that tells LilyPond that there's
1616 more than one thing (in this case, two @code{Staves}) happening
1617 at once. The @code{\score} looks like this now
1619 @c Indentation in this example is deliberately poor
1624 \new Voice = "one" @{
1628 \new Lyrics \lyricsto "one" \sopranoLyrics
1630 \new Staff \celloMusic
1638 This looks a bit messy; the indentation is messed up now. That is
1639 easily fixed. Here's the complete soprano and cello template.
1641 @lilypond[quote,verbatim,ragged-right]
1643 sopranoMusic = \relative c' {
1651 sopranoLyrics = \lyricmode {
1655 celloMusic = \relative c {
1666 \new Voice = "one" {
1670 \new Lyrics \lyricsto "one" \sopranoLyrics
1672 \new Staff \celloMusic
1680 @node Four-part SATB vocal score
1681 @subsection Four-part SATB vocal score
1683 Most vocal scores of music written for four-part mixed choir
1684 with orchestral accompaniment such as Mendelssohn's Elijah or
1685 Handel's Messiah have the choral music and words on four
1686 staves, one for each of SATB, with a piano reduction of the
1687 orchestral accompaniment underneath. Here's an example
1688 from Handel's Messiah:
1690 @c The following should appear as music without code
1691 @lilypond[quote,ragged-right]
1693 global = { \key d \major \time 4/4 }
1694 sopMusic = \relative c'' {
1696 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
1698 sopWords = \lyricmode {
1699 Wor -- thy is the lamb that was slain
1701 altoMusic = \relative a' {
1703 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
1705 altoWords = \sopWords
1706 tenorMusic = \relative c' {
1708 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
1710 tenorWords = \sopWords
1711 bassMusic = \relative c' {
1713 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
1715 bassWords = \sopWords
1716 upper = \relative a' {
1719 r4 <a d fis>2 <a e' a>4 |
1720 <d fis d'>4. <d fis d'>8 <a d a'>2 |
1721 <g cis g'>4 <a d fis> <a cis e>2 |
1723 lower = \relative c, {
1726 <d d'>4 <d d'>2 <cis cis'>4 |
1727 <b b'>4. <b' b'>8 <fis fis'>2 |
1728 <e e'>4 <d d'> <a' a'>2 |
1732 << % combine ChoirStaff and PianoStaff in parallel
1734 \new Staff = "sopranos" <<
1735 \set Staff.instrumentName = "Soprano"
1736 \new Voice = "sopranos" { \global \sopMusic }
1738 \new Lyrics \lyricsto "sopranos" { \sopWords }
1739 \new Staff = "altos" <<
1740 \set Staff.instrumentName = "Alto"
1741 \new Voice = "altos" { \global \altoMusic }
1743 \new Lyrics \lyricsto "altos" { \altoWords }
1744 \new Staff = "tenors" <<
1745 \set Staff.instrumentName = "Tenor"
1746 \new Voice = "tenors" { \global \tenorMusic }
1748 \new Lyrics \lyricsto "tenors" { \tenorWords }
1749 \new Staff = "basses" <<
1750 \set Staff.instrumentName = "Bass"
1751 \new Voice = "basses" { \global \bassMusic }
1753 \new Lyrics \lyricsto "basses" { \bassWords }
1757 \set PianoStaff.instrumentName = "Piano "
1758 \new Staff = "upper" \upper
1759 \new Staff = "lower" \lower
1765 None of the templates provides this layout exactly. The
1766 nearest is @q{SATB vocal score and automatic piano reduction},
1767 but we shall need to change the layout and add a piano
1768 accompaniment which is not derived automatically from the
1769 vocal parts. The variables holding the music and words for
1770 the vocal parts are fine, but we shall need to add variables for
1771 the piano reduction.
1773 The order in which the contexts appear in the ChoirStaff of
1774 the template do not correspond with the order in the vocal
1775 score shown above. We need to rearrange them so there are
1776 four staves with the words written directly underneath the
1777 notes for each part.
1778 All the voices should be @code{\voiceOne}, which is
1779 the default, so the @code{\voiceXXX} commands can be removed.
1780 We also need to specify the tenor clef for the tenors.
1781 The way in which lyrics are specified has also been simplified
1782 as we have not yet encountered the method used in the template.
1783 We've also added the names of each staff.
1785 Doing this gives for our ChoirStaff:
1789 \new Staff = "sopranos" <<
1790 \set Staff.instrumentName = "Soprano"
1791 \new Voice = "sopranos" @{ \global \sopMusic @}
1793 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
1794 \new Staff = "altos" <<
1795 \set Staff.instrumentName = "Alto"
1796 \new Voice = "altos" @{ \global \altoMusic @}
1798 \new Lyrics \lyricsto "altos" @{ \altoWords @}
1799 \new Staff = "tenors" <<
1800 \set Staff.instrumentName = "Tenor"
1801 \new Voice = "tenors" @{ \global \tenorMusic @}
1803 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
1804 \new Staff = "basses" <<
1805 \set Staff.instrumentName = "Bass"
1806 \new Voice = "basses" @{ \global \bassMusic @}
1808 \new Lyrics \lyricsto "basses" @{ \bassWords @}
1812 Next we must work out the piano part. This is
1813 easy - we just pull out the piano part from the
1814 @q{Solo piano} template:
1818 \set PianoStaff.instrumentName = "Piano "
1819 \new Staff = "upper" \upper
1820 \new Staff = "lower" \lower
1824 and add the variable definitions for @code{upper}
1827 The ChoirStaff and PianoStaff must be combined
1828 using angle brackets as we want them to be
1829 stacked one above the other:
1832 << % combine ChoirStaff and PianoStaff one above the other
1834 \new Staff = "sopranos" <<
1835 \new Voice = "sopranos" @{ \global \sopMusic @}
1837 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
1838 \new Staff = "altos" <<
1839 \new Voice = "altos" @{ \global \altoMusic @}
1841 \new Lyrics \lyricsto "altos" @{ \altoWords @}
1842 \new Staff = "tenors" <<
1843 \clef "G_8" % tenor clef
1844 \new Voice = "tenors" @{ \global \tenorMusic @}
1846 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
1847 \new Staff = "basses" <<
1849 \new Voice = "basses" @{ \global \bassMusic @}
1851 \new Lyrics \lyricsto "basses" @{ bassWords @}
1855 \set PianoStaff.instrumentName = "Piano "
1856 \new Staff = "upper" \upper
1857 \new Staff = "lower" \lower
1862 Combining all these together and adding the music
1863 for the three bars of the example above gives:
1865 @lilypond[quote,verbatim,ragged-right]
1867 global = { \key d \major \time 4/4 }
1868 sopMusic = \relative c'' {
1870 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
1872 sopWords = \lyricmode {
1873 Wor -- thy is the lamb that was slain
1875 altoMusic = \relative a' {
1877 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
1879 altoWords = \sopWords
1880 tenorMusic = \relative c' {
1882 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
1884 tenorWords = \sopWords
1885 bassMusic = \relative c' {
1887 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
1889 bassWords = \sopWords
1890 upper = \relative a' {
1893 r4 <a d fis>2 <a e' a>4 |
1894 <d fis d'>4. <d fis d'>8 <a d a'>2 |
1895 <g cis g'>4 <a d fis> <a cis e>2 |
1897 lower = \relative c, {
1900 <d d'>4 <d d'>2 <cis cis'>4 |
1901 <b b'>4. <b' b'>8 <fis fis'>2 |
1902 <e e'>4 <d d'> <a' a'>2 |
1906 << % combine ChoirStaff and PianoStaff in parallel
1908 \new Staff = "sopranos" <<
1909 \set Staff.instrumentName = "Soprano"
1910 \new Voice = "sopranos" { \global \sopMusic }
1912 \new Lyrics \lyricsto "sopranos" { \sopWords }
1913 \new Staff = "altos" <<
1914 \set Staff.instrumentName = "Alto"
1915 \new Voice = "altos" { \global \altoMusic }
1917 \new Lyrics \lyricsto "altos" { \altoWords }
1918 \new Staff = "tenors" <<
1919 \set Staff.instrumentName = "Tenor"
1920 \new Voice = "tenors" { \global \tenorMusic }
1922 \new Lyrics \lyricsto "tenors" { \tenorWords }
1923 \new Staff = "basses" <<
1924 \set Staff.instrumentName = "Bass"
1925 \new Voice = "basses" { \global \bassMusic }
1927 \new Lyrics \lyricsto "basses" { \bassWords }
1931 \set PianoStaff.instrumentName = "Piano "
1932 \new Staff = "upper" \upper
1933 \new Staff = "lower" \lower
1940 @node Building a score from scratch
1941 @subsection Building a score from scratch
1943 After gaining some facility with writing LilyPond code you
1944 may find that it is easier to build a score from scratch
1945 rather than modifying one of the templates. You can also
1946 develop your own style this way to suit the sort of music you
1947 like. Let's see how to put together the score for an organ
1948 prelude as an example.
1950 We begin with a header section. Here go the title, name
1951 of composer, etc, then come any variable definitions, and
1952 finally the score block. Let's start with these in outline
1953 and fill in the details later.
1955 We'll use the first two bars of Bach's prelude
1956 based on @emph{Jesu, meine Freude} which is written for two
1957 manuals and pedal organ. The top manual part has two voices,
1958 the lower and pedal organ one each. So we need four
1959 music definitions and one to define the time signature
1965 title = "Jesu, meine Freude"
1966 composer = "J S Bach"
1968 TimeKey = @{ \time 4/4 \key c \minor @}
1969 ManualOneVoiceOneMusic = @{s1@}
1970 ManualOneVoiceTwoMusic = @{s1@}
1971 ManualTwoMusic = @{s1@}
1972 PedalOrganMusic = @{s1@}
1978 For now we've just used a spacer note, @code{s1},
1979 instead of the real music. We'll add that later.
1981 Next let's see what should go in the score block.
1982 We simply mirror the staff structure we want.
1983 Organ music is usually written on three staves,
1984 one for each manual and one for the pedals. The
1985 manual staves should be bracketed together so we
1986 need to use a PianoStaff for them. The first
1987 manual part needs two voices and the second manual
1992 \new Staff = "ManualOne" <<
1993 \new Voice @{ \ManualOneVoiceOneMusic @}
1994 \new Voice @{ \ManualOneVoiceTwoMusic @}
1995 >> % end ManualOne Staff context
1996 \new Staff = "ManualTwo" <<
1997 \new Voice @{ \ManualTwoMusic @}
1998 >> % end ManualTwo Staff context
1999 >> % end PianoStaff context
2002 Next we need to add a staff for the pedal organ.
2003 This goes underneath the PianoStaff, but it must
2004 be simultaneous with it, so we need angle brackets
2005 round the two. Missing these out would generate
2006 an error in the log file. It's a common mistake
2007 which you'll make sooner or later! Try copying
2008 the final example at the end of this section,
2009 remove these angle brackets, and compile it to
2010 see what errors it generates.
2013 << % PianoStaff and Pedal Staff must be simultaneous
2015 \new Staff = "ManualOne" <<
2016 \new Voice @{ \ManualOneVoiceOneMusic @}
2017 \new Voice @{ \ManualOneVoiceTwoMusic @}
2018 >> % end ManualOne Staff context
2019 \new Staff = "ManualTwo" <<
2020 \new Voice @{ \ManualTwoMusic @}
2021 >> % end ManualTwo Staff context
2022 >> % end PianoStaff context
2023 \new Staff = "PedalOrgan" <<
2024 \new Voice @{ \PedalOrganMusic @}
2029 It is not strictly necessary to use the simultaneous construct
2030 @code{<< >>} for the manual two staff and the pedal organ staff,
2031 since they contain only one music expression, but it does no harm
2032 and always using angle brackets after @code{\new Staff} is a good
2033 habit to cultivate in case there are multiple voices.
2035 Let's add this structure to the score block, and adjust the
2036 indenting. We also add the appropriate clefs, ensure the
2037 second voice stems point down with @code{\voiceTwo} and
2038 enter the time signature and key to each staff using our
2039 predefined variable, @code{\TimeKey}.
2043 << % PianoStaff and Pedal Staff must be simultaneous
2045 \new Staff = "ManualOne" <<
2046 \TimeKey % set time signature and key
2048 \new Voice @{ \ManualOneVoiceOneMusic @}
2049 \new Voice @{ \voiceTwo \ManualOneVoiceTwoMusic @}
2050 >> % end ManualOne Staff context
2051 \new Staff = "ManualTwo" <<
2054 \new Voice @{ \ManualTwoMusic @}
2055 >> % end ManualTwo Staff context
2056 >> % end PianoStaff context
2057 \new Staff = "PedalOrgan" <<
2060 \new Voice @{ \PedalOrganMusic @}
2061 >> % end PedalOrgan Staff
2063 @} % end Score context
2066 That completes the structure. Any three-staff organ music
2067 will have a similar structure, although the number of voices
2068 may vary. All that remains now
2069 is to add the music, and combine all the parts together.
2071 @lilypond[quote,verbatim,ragged-right]
2074 title = "Jesu, meine Freude"
2075 composer = "J S Bach"
2077 TimeKey = { \time 4/4 \key c \minor }
2078 ManualOneVoiceOneMusic = \relative g' {
2079 g4 g f ees | d2 c2 |
2081 ManualOneVoiceTwoMusic = \relative c' {
2082 ees16 d ees8~ ees16 f ees s c8 d~ d c~ |
2083 c c4 b8 c8. g16 c b c d |
2085 ManualTwoMusic = \relative c' {
2086 c16 b c8~ c16 b c g a8 g~ g16 g aes ees |
2087 f ees f d g aes g f ees d e8~ ees16 f ees d |
2089 PedalOrganMusic = \relative c {
2090 r8 c16 d ees d ees8~ ees16 a, b g c b c8 |
2091 r16 g ees f g f g8 c,2 |
2095 << % PianoStaff and Pedal Staff must be simultaneous
2097 \new Staff = "ManualOne" <<
2098 \TimeKey % set time signature and key
2100 \new Voice { \ManualOneVoiceOneMusic }
2101 \new Voice { \voiceTwo \ManualOneVoiceTwoMusic }
2102 >> % end ManualOne Staff context
2103 \new Staff = "ManualTwo" <<
2106 \new Voice { \ManualTwoMusic }
2107 >> % end ManualTwo Staff context
2108 >> % end PianoStaff context
2109 \new Staff = "PedalOrgan" <<
2112 \new Voice { \PedalOrganMusic }
2113 >> % end PedalOrgan Staff
2115 } % end Score context