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 @ref{Size of objects}
364 @node On the un-nestedness of brackets and ties
365 @subsection On the un-nestedness of brackets and ties
367 You have already met a number of different types of bracket in
368 writing the input file to LilyPond. These obey different rules
369 which can be confusing at first. Before we explain the rules
370 let's first review the different types of bracket.
372 @c attempt to force this onto a new page
374 @multitable @columnfractions .3 .7
375 @headitem Bracket Type
377 @item @code{@{ .. @}}
378 @tab Encloses a sequential segment of music
380 @tab Encloses the notes of a chord
381 @item @code{<< .. >>}
382 @tab Encloses concurrent or simultaneous sections
384 @tab Marks the start and end of a slur
385 @item @code{\( .. \)}
386 @tab Marks the start and end of a phrase mark
388 @tab Marks the start and end of a manual beam
391 To these we should add other constructs which generate lines
392 between or across notes: ties (marked by a tilde, @code{~}),
393 tuplets written as @code{\times x/y @{..@}}, and grace notes
394 written as @code{\grace@{..@}}.
396 Outside LilyPond, the conventional use of brackets requires
397 the different types to be properly nested, like this,
398 @code{<< [ @{ ( .. ) @} ] >>}, with the closing brackets being
399 encountered in exactly the opposite order to the opening
400 brackets. This @strong{is} a requirement for the three types of
401 bracket described by the word @q{Encloses} in the table above --
402 they must nest properly.
403 However, the remaining brackets, described with the word
404 @q{Marks} in the table above together with ties and tuplets,
405 do @strong{not} have to nest
406 properly with any of the brackets. In fact, these are not
407 brackets in the sense that
408 they enclose something -- they are simply markers to indicate
409 where something starts and ends.
411 So, for example, a phrasing slur can start before a manually
412 inserted beam and end before the end of the beam -- not very
413 musical, perhaps, but possible:
415 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
416 { g8\( a b[ c b\) a] }
419 In general, different kinds of brackets, and those implied by
420 tuplets, ties and grace notes, may be mixed freely.
421 This example shows a beam extending into a tuplet (line 1),
422 a slur extending into a tuplet (line 2),
423 a beam and a slur extending into a tuplet, a tie crossing
424 two tuplets, and a phrasing slur extending out of a tuplet
427 @lilypond[quote,verbatim,fragment,ragged-right]
429 r16[ g16 \times 2/3 {r16 e'8] }
430 g16( a \times 2/3 {b d) e' }
431 g8[( a \times 2/3 {b d') e'~]}
432 \times 4/5 {e'32\( a b d' e'} a'4.\)
437 @node Voices contain music
438 @section Voices contain music
440 Singers need voices to sing, and so does LilyPond.
441 The actual music for all instruments in a score
442 is contained in Voices -- the most fundamental
443 of all LilyPond's concepts.
446 * I'm hearing Voices::
447 * Explicitly instantiating voices::
448 * Voices and vocals::
451 @node I'm hearing Voices
452 @subsection I'm hearing Voices
456 @cindex Voice context
458 The lowest, most fundamental or innermost layers in a LilyPond
459 score are called @q{Voice contexts} or just @q{Voices} for short.
460 Voices are sometimes called @q{layers} in other notation
463 In fact, a Voice layer or context is the only one which can
464 contain music. If a Voice context is not explicitly declared
465 one is created automatically, as we saw at the beginning of
466 this chapter. Some instruments such as an
467 Oboe can play only one note at a time. Music written for
468 such instruments is monophonic and requires just a single
469 voice. Instruments which can play more than one note at a
470 time like the piano will often require multiple voices to
471 encode the different concurrent notes and rhythms they are
474 A single voice can contain many notes in a chord, of course,
475 so when exactly are multiple voices needed?
476 Let us analyse a short piece of music to see how many voices
477 are required. Here are the notes from the first two bars
478 of the second of Chopin's Deux Nocturnes, Op 32.
480 @c The following should appear as music without code
481 @lilypond[quote,ragged-right]
482 \new Staff \relative c'' {
490 \once \override NoteColumn #'force-hshift = #0 <ees c>2
491 \once \override NoteColumn #'force-hshift = #0.5 des2 }
497 The direction of the stems is often used to indicate the
498 continuity of two simultaneous melodic lines. Here the
499 stems of the highest notes are all pointing up and the
500 stems of the lower notes are all pointing down.
501 This is the first indication that more than one voice
504 But the real need for multiple voices arises when notes
505 which start at the same time have different durations.
506 Look at the notes which start at beat three in the first
507 bar. The a-flat is a dotted quarter note, the f is a
508 quarter note and the d-flat is a half note. These
509 cannot be written as a chord as all the notes in a chord
510 must have the same duration. Neither can they be written
511 as sequential notes, as they must start at the same time.
512 This section of the bar requires three voices, and the
513 normal practice would be to write the whole bar as three
514 voices, as shown here, where we have used different noteheads
515 and colors for the three voices.
517 @c The following should appear as music without code
518 @c The three voice styles should be defined in -init
519 @lilypond[quote,ragged-right]
520 \new Staff \relative c'' {
531 \once \override NoteColumn #'force-hshift = #0 <ees c>2
532 \once \override NoteColumn #'force-hshift = #0.5 des2 }
538 Let us see how this is done.
542 The easiest way to enter fragments with more than one voice on a
543 staff is to enter each voice as a sequence (with @code{@{...@}}),
544 and combine them simultaneously with angle brackets, @code{<<...>>}.
545 The fragments must also be separated with double backward slashes,
546 @code{\\}, to place them in separate voices. Without these, the
547 notes would be entered into a single voice, which would usually
548 cause errors. This technique is particularly suited to pieces of
549 music which are largely monophonic with occasional short sections
550 of polyphony. Here's a simple example:
552 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
554 % Voice "1" Voice "2"
555 << { r4 g g4. a8 } \\ { d,2 d4 g } >> |
556 << { bes4 bes c bes } \\ { g4 g g8( a) g4 } >> |
557 << { a2. r4 } \\ { fis2. s4 } >>
560 It is not necessary to use a separate @code{<< \\ >>} construct
561 for each bar. For music with few notes in each bar this layout
562 can help the legibility of the code, but if there are many
563 notes in each bar it may be better to split out each voice
564 separately, like this:
566 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
582 This example has just two voices, but the same contruct may be
583 used to encode three or more voices by adding more back-slash
586 The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
587 In each of these contexts, the vertical direction of slurs,
588 stems, ties, dynamics etc., is set appropriately.
590 @lilypond[quote,verbatim,fragment]
591 \new Staff \relative c' {
594 % Voice "1" Voice "2" Voice "3"
595 << { g4 f e } \\ { r8 e4 d c8 ~ } >> |
596 << { d2 e2 } \\ { c8 b16 a b8 g ~ g2 } \\ { s4 b4 c2 } >> |
600 These voices are all separate from the main voice that contains
601 the notes just outside the @code{<< .. >>} construct. Let's call
602 this the @emph{simultaneous construct}. Slurs and ties may only
603 connect notes within the same voice, so slurs and ties cannot go
604 into or out of a simultaneous construct. Conversely,
605 parallel voices from separate simultaneous constructs on the same
606 staff are the same voice. Other voice-related properties also
607 carry across simultaneous constructs. Here is the same example,
608 with different colors and noteheads for each voice. Note that
609 changes in one Voice do not affect other voices, but they do
610 persist in the same Voice later. Note also that tied notes may be
611 split across the same voices in two constructs, shown here in the
614 @lilypond[quote,verbatim]
615 \new Staff \relative c' {
627 { c8 b16 a b8 g ~ g2 } \\
636 The commands @code{\voiceXXXStyle} are mainly intended for use in
637 educational documents such as this one. They modify the color
638 of the notehead, the stem and the beams, and the style of the
639 notehead, so that the voices may be easily distinguished.
640 Voice one is set to red diamonds, voice two to blue triangles,
641 voice three to green crossed circles, and voice four (not used
642 here) to magenta crosses. We shall see later how commands like
643 these may be created by the user.
644 See @ref{Visibility and color of objects}
645 TODO Add link to using variables for tweaks
647 Polyphony does not change the relationship of notes within a
648 @code{\relative @{ @}} block. Each note is still calculated
649 relative to the note immediately preceding it, or to the first
650 note of the preceding chord. So in
653 \relative c' @{ noteA << < noteB noteC > \\ noteD >> noteE @}
657 @code{noteB} is relative to @code{noteA} @*
658 @code{noteC} is relative to @code{noteB}, not @code{noteA}; @*
659 @code{noteD} is relative to @code{noteB}, not @code{noteA} or
661 @code{noteE} is relative to @code{noteD}, not @code{noteA}
663 We are now in a position to return to the first example from
664 the Chopin Nocturne to see how this might be encoded. As we
665 shall see, this encounters some difficulties. We begin as
666 we have learnt, using the @code{<< \\ >>} construct to
667 enter the music of the first bar in three voices:
669 @lilypond[quote,verbatim,fragment,ragged-right]
670 \new Staff \relative c'' {
673 { c2 aes4. bes8 } \\ { aes2 f4 fes } \\ { <ees c>2 des2 }
683 @funindex \voiceThree
686 The stem directions are automatically assigned with the
687 odd-numbered voices taking upward stems and the even-numbered
688 voices downward ones. The stems for voices 1 and 2 are right,
689 but the stems in voice 3 should go down in this particular piece
690 of music. We can correct this
691 by telling LilyPond that this third voice is really a fourth
692 voice, with stems going down, using the @code{\voiceFour}
693 command. There are also corresponding @code{\voiceOne},
694 @code{\voiceTwo}, and @code{\voiceThree}
695 commands. This results in the following:
697 @lilypond[quote,verbatim,fragment,ragged-right]
698 \new Staff \relative c'' {
703 { \voiceFour <ees c>2 des2 }
710 and exposes a problem commonly encountered with multiple
711 voices: the stems of notes can collide with noteheads
712 in other voices. In laying out the notes, LilyPond allows the
713 notes or chords from two voices to occupy the same vertical
714 note column provided the stems are in opposite directions, but
715 the notes from a third voice are displaced to avoid the stems
716 colliding. This often works well, but in this example the
717 notes of the third voice are clearly not well placed by default.
718 LilyPond provides several ways to adjust the horizontal placing
719 of notes. We are not quite ready yet to see how to correct this,
720 so we shall leave this problem until a later section (see ... )
724 @node Explicitly instantiating voices
725 @subsection Explicitly instantiating voices
727 Voice contexts can also be created manually
728 inside a @code{<< >>} block to create polyphonic music, using
729 @code{\voiceOne} ... @code{\voiceFour} to indicate the required
730 directions of stems, slurs, etc. In longer scores this method
731 is clearer, as it permits the voices to be separated and to be
732 given more descriptive names.
734 Specifically, the construct @code{<< \\ >>} which we used in
735 the previous section:
740 << @{ e4 f g a @} \\ @{ c,4 d e f @} >>
750 \new Voice = "1" @{ \voiceOne \relative c' @{ e4 f g a @} @}
751 \new Voice = "2" @{ \voiceTwo \relative c' @{ c4 d e f @} @}
755 Both of the above would produce
757 @c The following example should not display the code
758 FIXME: weird compiling bug! Leave for gp.
759 @c @lilypond{ragged-right,quote]
761 @c % << { e4 f g a } \\ { c,4 d e f } >>
765 The @code{\voiceXXX} commands set the direction of stems, slurs,
766 ties, articulations, text annotations, augmentation dots of dotted
767 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
768 make these objects point upwards, while @code{\voiceTwo} and
769 @code{\voiceFour} make them point downwards. These commands also
770 generate a horizontal shift for each voice when this is required
771 to avoid clashes of note heads. The command @code{\oneVoice}
772 reverts the settings back to the normal values for a single voice.
774 Let us see in some simple examples exactly what effect
775 @code{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on
776 markup, ties, slurs, and dynamics:
778 @lilypond[quote,ragged-right,verbatim]
780 c-"default" d8 ~ d e4 ( f g a ) b-> c
784 @lilypond[quote,ragged-right,verbatim]
787 c d8 ~ d e4 ( f g a ) b-> c
789 c, d8 ~ d e4 ( f g a ) b-> c
793 @lilypond[quote,ragged-right,verbatim]
796 c d8 ~ d e4 ( f g a ) b-> c
798 c, d8 ~ d e4 ( f g a ) b-> c
802 An expression that appears directly inside a @code{<< >>} belongs
803 to the main voice (but, note, @strong{not} in a @code{<< \\ >>}
804 construct). This is useful when extra voices appear while the
805 main voice is playing. Here is a more correct rendition of the
806 example from the previous section. The red diamond-shaped notes
807 demonstrate that the main melody is now in a single voice context,
808 permitting a phrasing slur to be drawn over them.
810 @lilypond[quote,ragged-right,verbatim]
811 \new Staff \relative c' {
813 c16^( d e f % These notes are monophonic
814 << % Start simultaneous section of three voices
815 { g4 f e | d2 e2) } % Continue the main voice in parallel
816 \new Voice { % Initiate second voice
817 \voiceTwo % Set stems, etc, down
818 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
820 \new Voice { % Initiate third voice
821 \voiceThree % Set stems, etc, up
828 @cindex nesting music expressions
829 @cindex nesting simultaneous constructs
831 More deeply nested polyphony constructs are possible, and if a
832 voice appears only briefly this might be a more natural way to
835 @lilypond[quote,ragged-right,verbatim]
836 \new Staff \relative c' {
856 This method of nesting new voices briefly is useful
857 when only small sections of the music
858 are polyphonic, but when the whole staff is largely polyphonic
859 it can be clearer to use multiple voices throughout, using
860 spacing notes to step over sections where the voice is silent,
863 @lilypond[quote,ragged-right,verbatim]
864 \new Staff \relative c' <<
865 \new Voice { % Initiate first voice
867 c16^( d e f g4 f e | d2 e2) |
869 \new Voice { % Initiate second voice
870 \voiceTwo % set stems, etc down
871 s4 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 |
873 \new Voice { % Initiate third voice
874 \voiceThree % set stems, etc up
881 @node Voices and vocals
882 @subsection Voices and vocals
884 Vocal music presents a special difficulty: we need to combine two
885 expressions -- notes and lyrics.
887 You have already seen the @code{\addlyrics@{@}} command, which
888 handles simple scores well. However, this technique is
889 quite limited. For more complex music, you must introduce the
890 lyrics in a @code{Lyrics} context using @code{\new Lyrics} and
892 the lyrics to the notes with @code{\lyricsto@{@}}, using the
893 name assigned to the Voice.
895 @lilypond[quote,verbatim,fragment]
897 \new Voice = "one" \relative c'' {
900 c4 b8. a16 g4. f8 e4 d c2
902 \new Lyrics \lyricsto "one" {
903 No more let sins and sor -- rows grow.
908 The automatic beaming which LilyPond uses by default works well
909 for instrumental music, but not so well for music with lyrics,
910 where beaming is either not required at all or is used to indicate
911 melismata in the lyrics. In the example above we use the command
912 @code{\autoBeamOff} to turn off the automatic beaming.
914 Let us reuse the earlier example from Judas Maccabæus to
915 illustrate this more flexible technique. We first recast
916 it to use variables so the music and lyrics can be separated
917 from the staff structure. We also introduce a ChoirStaff
918 bracket. The lyrics themselves must be introduced with
919 @code{\lyricmode} to ensure they are interpreted as lyrics
922 @lilypond[quote,verbatim]
923 global = { \time 6/8 \partial 8 \key f \major}
924 SopOneMusic = \relative c'' {
925 c8 | c([ bes)] a a([ g)] f | f'4. b, | c4.~ c4 }
926 SopTwoMusic = \relative c' {
927 r8 | r4. r4 c8 | a'([ g)] f f([ e)] d | e([ d)] c bes' }
928 SopOneLyrics = \lyricmode {
929 Let | flee -- cy flocks the | hills a -- dorn, __ }
930 SopTwoLyrics = \lyricmode {
931 Let | flee -- cy flocks the | hills a -- dorn, }
936 \new Voice = "SopOne" {
940 \new Lyrics \lyricsto "SopOne" {
945 \new Voice = "SopTwo" {
948 \new Lyrics \lyricsto "SopTwo" {
956 This is the basic structure of all vocal scores. More staves may
957 be added as required, more voices may be added to the staves,
958 more verses may be added to the lyrics,
959 and the variables containing the music can easily be placed
960 in separate files should they become too long.
962 Here is a final example of the first line of a hymn with four
963 verses, set for SATB. In this case the words for all four
966 @lilypond[quote,verbatim]
967 TimeKey = { \time 4/4 \partial 4 \key c \major}
968 SopMusic = \relative c' { c4 | e4. e8 g4 g | a a g }
969 AltoMusic = \relative c' { c4 | c4. c8 e4 e | f f e }
970 TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 }
971 BassMusic = \relative c { c4 | c4. c8 c4 c | f8 g a b c4 }
972 VerseOne = \lyricmode {
973 E -- | ter -- nal fa -- ther, | strong to save, }
974 VerseTwo = \lyricmode {
975 O | Christ, whose voice the | wa -- ters heard, }
976 VerseThree = \lyricmode {
977 O | Ho -- ly Spi -- rit, | who didst brood }
978 VerseFour = \lyricmode {
979 O | Tri -- ni -- ty of | love and pow'r }
985 \new Voice = "Sop" { \voiceOne \TimeKey \SopMusic }
986 \new Voice = "Alto" { \voiceTwo \AltoMusic }
987 \new Lyrics \lyricsto "Sop" { \VerseOne }
988 \new Lyrics \lyricsto "Sop" { \VerseTwo }
989 \new Lyrics \lyricsto "Sop" { \VerseThree }
990 \new Lyrics \lyricsto "Sop" { \VerseFour }
994 \new Voice = "Tenor" { \voiceOne \TenorMusic }
995 \new Voice = "Bass" { \voiceTwo \BassMusic }
1001 @node Contexts and engravers
1002 @section Contexts and engravers
1004 Contexts and engravers have been mentioned informally
1005 in earlier sections; we now must look at
1006 these concepts in more detail, as they are important
1007 in the fine-tuning of LilyPond output.
1011 * Contexts explained::
1012 * Creating contexts::
1013 * Engravers explained::
1014 * Modifying context properties::
1015 * Adding and removing engravers::
1018 @node Contexts explained
1019 @subsection Contexts explained
1021 When music is printed, many notational elements which do not
1022 appear explicitly in the input file must be added to the
1023 output. For example, compare the input and output of the
1026 @lilypond[quote,verbatim,relative=2,fragment]
1030 The input is rather sparse, but in the output, bar lines,
1031 accidentals, clef, and time signature have been added. When
1032 LilyPond @emph{interprets} the input the musical information
1033 is inspected in time order, similar to reading a score from left
1034 to right. While reading the input, the program remembers where
1035 measure boundaries are, and which pitches require explicit
1036 accidentals. This information must be held on several levels.
1037 For example, the effect of an accidental is limited
1038 to a single staff, while a bar line must be synchronized across
1041 Within LilyPond, these rules and bits of information are grouped
1042 in @emph{Contexts}. We have already met the
1043 @code{Voice} context.
1044 Others are the @code{Staff} and @code{Score} contexts.
1045 Contexts are hierarchical to reflect the heirarchical nature of
1047 For example: a @code{Staff} context can contain many
1048 @code{Voice} contexts, and a @code{Score} context can
1049 contain many @code{Staff} contexts.
1052 @image{context-example,5cm,,}
1055 Each context has the responsibility for enforcing some notation rules,
1056 creating some notation objects and maintaining the associated
1057 properties. For example, the @code{Voice} context may introduce an
1058 accidental and then the @code{Staff} context maintains the rule to
1059 show or suppress the accidental for the remainder of the measure.
1061 As another example, the synchronization of bar lines is, by default,
1062 handled in the @code{Score} context.
1063 However, in some music we may not want the bar lines to be
1064 synchronized -- consider a polymetric score in 4/4 and 3/4 time.
1065 In such cases, we must modify the default settings of the
1066 @code{Score} and @code{Staff} contexts.
1068 For very simple scores, contexts are created implicitly, and you need
1069 not be aware of them. For larger pieces, such as anything with more
1070 than one staff, they must be
1071 created explicitly to make sure that you get as many staves as you
1072 need, and that they are in the correct order. For typesetting pieces
1073 with specialized notation, it is usual to modify existing, or
1074 even to define totally new, contexts.
1076 In addition to the @code{Score,} @code{Staff} and
1077 @code{Voice} contexts there are contexts which fit between
1078 the score and staff levels to control staff groups, such as the
1079 @code{PianoStaff} and @code{ChoirStaff} contexts. There
1080 are also alternative staff and voice contexts, and contexts for
1081 lyrics, percussion, fret boards, figured bass, etc. A complete
1082 list is shown in the Notation Reference.
1085 The names of all context types are formed from one or more
1086 words, each word being capitalised and joined immediately to the
1087 preceding word with no hyphen or underscore, e.g.,
1088 @code{GregorianTranscriptionStaff}.
1090 @node Creating contexts
1091 @subsection Creating contexts
1093 There can be only one top level context: the
1095 context. This is created with the @code{\score} command,
1096 or, in simple scores, it is created automatically.
1098 For scores with only one voice and one staff, the
1099 @code{Voice} and @code{Staff} contexts may be left to be
1100 created automatically, but for more complex scores it is
1101 necessary to create them by hand.
1102 The simplest command that does this is @code{\new}.
1103 It is prepended to a music expression, for example
1106 @cindex new contexts
1107 @cindex Context, creating
1110 \new @var{type} @var{music-expression}
1114 where @var{type} is a context name (like @code{Staff} or
1115 @code{Voice}). This command creates a new context, and starts
1116 interpreting the @var{music-expression} within that context.
1118 Note that there is no @code{\new Score} command;
1119 the single top-level @code{Score} context is introduced
1122 The @code{\new} command may also give a identifying name to the
1123 context to distinguish it from other contexts of the same type,
1126 \new @var{type} = @var{id} @var{music-expression}
1129 Note the distinction between the name of the context type,
1130 @code{Staff}, @code{Voice}, etc, and
1131 the identifying name of a particular instance of that type,
1132 which can be any sequence of letters invented by the user.
1133 The identifying name is used to refer back to that particular
1134 instance of a context. We saw this in use in the section on
1135 lyrics in @ref{Voices and vocals}.
1138 @node Engravers explained
1139 @subsection Engravers explained
1143 Every mark on the printed output of a score produced by LilyPond
1144 is produced by an @code{Engraver}. Thus there is an engraver
1145 to print staves, one to print noteheads, one for stems, one for
1146 beams, etc, etc. In total there are over 120 such engravers!
1147 Fortunately, for most scores it is not necessary to know about
1148 more than a few, and for simple scores you do not need to know
1151 Engravers live and operate in Contexts.
1152 Engravers such as the @code{Metronome_mark_engraver}, whose
1153 action and output applies to the score as a whole, operate in
1154 the highest level context -- the @code{Score} context.
1156 The @code{Clef_engraver} and @code{Key_engraver} are to be
1157 found in every Staff Context, as different staves may require
1158 different clefs and keys.
1160 The @code{Note_heads_engraver} and @code{Stem_engraver} live
1161 in each @code{Voice} context, the lowest level context of all.
1163 Each engraver processes the particular objects associated
1164 with its function, and maintains the properties that relate
1165 to that function. These properties, like the properties
1166 associated with contexts, may be modified to change the
1167 operation of the engraver or the appearance of those elements
1168 in the printed score.
1170 Engravers all have compound names formed from words which
1171 describe their function. Just the first word is capitalised,
1172 and the remainder are joined to it with underscores. Thus
1173 the @code{Staff_symbol_engraver} is responsible for creating the
1174 lines of the staff, the @code{Clef_engraver} determines and sets
1175 the pitch reference point on the staff by drawing a clef symbol.
1177 Here are some of the most common engravers together with their
1178 function. You will see it is easy to guess the function from
1179 the name, or vice versa.
1181 @multitable @columnfractions .3 .7
1184 @item Accidental_engraver
1185 @tab Makes accidentals, cautionary and suggested accidentals
1190 @item Dynamic_engraver
1191 @tab Creates hairpins and dynamic texts
1193 @tab Creates the key signature
1194 @item Metronome_mark_engraver
1195 @tab Engraves metronome marking
1196 @item Note_heads_engraver
1197 @tab Engraves noteheads
1200 @item Staff_symbol_engraver
1201 @tab Engraves the five (by default) lines of the staff
1203 @tab Creates stems and single-stem tremulos
1204 @item Time_signature_engraver
1205 @tab Creates time signatures
1210 We shall see later how the output of LilyPond can be changed
1211 by modifying the action of Engravers.
1214 @node Modifying context properties
1215 @subsection Modifying context properties
1217 @cindex context properties
1221 Contexts are responsible for holding the values of a number of
1222 context @emph{properties}. Many of them can be changed to
1223 influence the interpretation of the input and so change the
1224 appearance of the output. They are changed by the
1225 @code{\set} command. This takes the form
1228 \set @emph{ContextName}.@emph{propertyName} = @emph{value}
1231 Where the @emph{ContextName} is usually @code{Score},
1232 @code{Staff} or @code{Voice}. It may be omitted,
1233 in which case @code{Voice} is assumed.
1235 The names of context properties consist of words joined
1236 together with no hyphens or underscores, all except the
1237 first having a capital letter. Here are a few examples
1238 of some commonly used ones. There are many more.
1240 @c attempt to force this onto a new page
1242 @multitable @columnfractions .2 .2 .6
1243 @headitem propertyName
1248 @tab If true (##t), set extra natural signs before accidentals
1249 @item currentBarNumber
1251 @tab Set the current bar number
1254 @tab If true (##t), print slurs both above and below notes
1255 @item instrumentName
1257 @tab Set the name to be placed at the start of the staff
1260 @tab Increase or decrease the font size
1263 @tab Set the text to print before the start of a verse
1268 Before we can set any of these properties we need to know
1269 in which context they operate. Sometimes this is obvious,
1270 but occasionally it can be tricky. If the wrong context
1271 is specified, no error message is produced, but the expected
1272 action will not be taken. For example, the
1273 @code{instrumentName} clearly lives in the Staff context, since
1274 it is the staff that is to be named.
1275 In this example the first staff is labelled, but not the second,
1276 because we omitted the context name.
1278 @lilypond[quote,verbatim,ragged-right]
1280 \new Staff \relative c'' {
1281 \set Staff.instrumentName = "Soprano"
1284 \new Staff \relative c' {
1285 \set instrumentName = "Alto" % Wrong!
1291 Remember the default context name is Voice, so the second
1292 @code{\set} command set the property @code{instrumentName} in the
1293 Voice context to @qq{Alto}, but as LilyPond does not look
1294 for any such property in the @code{Voice} context, no
1295 further action took place. This is not an error, and no error
1296 message is logged in the log file.
1298 Similarly, if the property name is mis-spelt no error message
1299 is produced, and clearly the expected action cannot be performed.
1300 If fact, you can set any (fictitious) @q{property} using any
1301 name you like in any context that exists by using the
1302 @code{\set} command. But if the name is not
1303 known to LilyPond it will not cause any action to be taken.
1304 This is one of the reasons why it is highly recommended to
1305 use a context-sensitive editor with syntax highlighting for
1306 editing LilyPond files, such as Vim, Jedit, ConTEXT or Emacs,
1307 since unknown property names will be highlighted differently.
1309 The @code{instrumentName} property will take effect only
1310 if it is set in the @code{Staff} context, but
1311 some properties can be set in more than one context.
1312 For example, the property @code{extraNatural} is by
1313 default set to ##t (true) for all staves.
1314 If it is set to ##f (false) in the @code{Staff} context
1315 it applies just to the accidentals on that staff.
1316 If it is set to false in the @code{Score} context
1317 it applies to all staves.
1319 So this turns off extra naturals in one staff:
1321 @lilypond[quote,verbatim,ragged-right]
1323 \new Staff \relative c'' {
1326 \new Staff \relative c'' {
1327 \set Staff.extraNatural = ##f
1334 and this turns them off in all staves:
1336 @lilypond[quote,verbatim,ragged-right]
1338 \new Staff \relative c'' {
1341 \new Staff \relative c'' {
1342 \set Score.extraNatural = ##f
1348 The value of every property set in this way can be reset
1349 to its original value with the @code{\unset} command.
1351 The @code{\set} and @code{\unset} commands can appear anywhere
1352 in the input file and will take effect from the time they are
1353 encountered until the end of the score or until the property is
1354 @code{\set} or @code{\unset} again. Let's try changing the
1355 font size, which affects the size of the note heads (among
1356 other things) several times.
1358 @lilypond[quote,verbatim,ragged-right,relative=1,fragment]
1360 \set fontSize = #-4 % make noteheads smaller
1362 \set fontSize = #2.5 % make noteheads larger
1364 \unset fontSize % return to original size
1368 We have now seen how to set the values of several different
1369 types of property. Note that integers and numbers are alway
1370 preceded by a hash sign, @code{#}, while a true or false value
1371 is specified by ##t and ##f, with two hash signs. A text
1372 property should be enclosed in double quotation signs, as above,
1373 although we shall see later that text can actually be specified
1374 in a much more general way by using the very powerful
1375 @code{markup} command.
1380 Context properties may also be set at the time the context is
1381 created. Sometimes this is a clearer way of specifying a
1382 property value if it is to remain fixed for the duration of
1383 the context. When a context is created with a @code{\new}
1384 command it may be immediately followed by a
1385 @code{\with @{ .. @}} block in which the property values are
1386 set. For example, if we wish to suppress the printing of
1387 extra naturals for the duration of a staff we would write:
1389 @lilypond[quote,verbatim,ragged-right]
1398 In effect this overrides the default value of the property. It
1399 may still be changed dynamically using @code{\set} and
1402 @node Adding and removing engravers
1403 @subsection Adding and removing engravers
1405 @cindex Engravers, adding
1406 @cindex Engravers, removing
1411 We have seen that contexts each contain several engravers, each
1412 of which is responsible for producing a particular part of the
1413 output, like barlines, staves, note heads, stems, etc. If an
1414 engraver is removed from a context it can no longer produce its
1415 output. This is a crude way of modifying the output, but it
1416 can sometimes be useful.
1418 To remove an engraver we can use the @code{\with} command placed
1419 immediately after the context creation command, as in the
1423 illustration let's repeat an example from the previous
1424 section with the staff lines removed. Remember that the
1425 staff lines are produced by the Staff_symbol_engraver.
1427 @lilypond[quote,verbatim,ragged-right]
1429 \remove Staff_symbol_engraver
1433 \set fontSize = #-4 % make noteheads smaller
1435 \set fontSize = #2.5 % make noteheads larger
1437 \unset fontSize % return to original size
1442 @cindex ambitus engraver
1444 Engravers can also be added to contexts. The command
1447 @code{\consists @emph{Engraver_name}},
1449 placed inside a @code{\with} block. Some vocal scores
1450 have an @rglos{ambitus} placed at the beginning of a
1451 staff to indicate the range of notes in that staff.
1452 The ambitus is produced by the @code{Ambitus_engraver},
1453 which is not normally included in any context. If
1454 we add it to the @code{Voice} context it calculates
1455 the range from that voice only:
1457 @lilypond[quote,verbatim,ragged-right]
1460 \consists Ambitus_engraver
1475 but if we add the Ambitus engraver to the
1476 @code{Staff} context it calculates the range from all
1477 the notes in all the voices on that staff:
1479 @lilypond[quote,verbatim,ragged-right]
1481 \consists Ambitus_engraver
1498 @node Extending the templates
1499 @section Extending the templates
1501 You've read the tutorial, you know how to write music, you
1502 understand the fundamental concepts. But how can you
1503 get the staves that you want? Well, you can find lots of
1504 templates (see @ref{Templates}) which may give you a start.
1506 if you want something that isn't covered there? Read on.
1509 * Soprano and cello::
1510 * Four-part SATB vocal score::
1511 * Building a score from scratch::
1514 @node Soprano and cello
1515 @subsection Soprano and cello
1517 Start off with the template that seems closest to what you want to end
1518 up with. Let's say that you want to write something for soprano and
1519 cello. In this case, we would start with @q{Notes and lyrics} (for the
1524 melody = \relative c' @{
1532 text = \lyricmode @{
1538 \new Voice = "one" @{
1542 \new Lyrics \lyricsto "one" \text
1549 Now we want to add a cello part. Let's look at the @q{Notes only} example:
1553 melody = \relative c' @{
1568 We don't need two @code{\version} commands. We'll need the @code{melody}
1569 section. We don't want two @code{\score} sections -- if we had two
1570 @code{\score}s, we'd get the two parts separately. We want them together,
1571 as a duet. Within the @code{\score} section, we don't need two
1572 @code{\layout} or @code{\midi}.
1574 If we simply cut and paste the @code{melody} section, we would end up with
1575 two @code{melody} sections. So let's rename them. We'll call the section
1576 for the soprano @code{sopranoMusic} and the section for the cello
1577 @code{celloMusic}. While we're doing this, let's rename @code{text}
1578 to be @code{sopranoLyrics}. Remember to rename both instances of all
1579 these names -- both the initial definition (the
1580 @code{melody = relative c' @{ } part) and the name's use (in the
1581 @code{\score} section).
1583 While we're doing this, let's change the cello part's staff -- celli
1584 normally use bass clef. We'll also give the cello some different
1589 sopranoMusic = \relative c' @{
1597 sopranoLyrics = \lyricmode @{
1601 celloMusic = \relative c @{
1611 \new Voice = "one" @{
1615 \new Lyrics \lyricsto "one" \sopranoLyrics
1622 This is looking promising, but the cello part won't appear in the
1623 score -- we haven't used it in the @code{\score} section. If we
1624 want the cello part to appear under the soprano part, we need to add
1627 \new Staff \celloMusic
1631 underneath the soprano stuff. We also need to add @code{<<} and
1632 @code{>>} around the music -- that tells LilyPond that there's
1633 more than one thing (in this case, two @code{Staves}) happening
1634 at once. The @code{\score} looks like this now
1636 @c Indentation in this example is deliberately poor
1641 \new Voice = "one" @{
1645 \new Lyrics \lyricsto "one" \sopranoLyrics
1647 \new Staff \celloMusic
1655 This looks a bit messy; the indentation is messed up now. That is
1656 easily fixed. Here's the complete soprano and cello template.
1658 @lilypond[quote,verbatim,ragged-right]
1660 sopranoMusic = \relative c' {
1668 sopranoLyrics = \lyricmode {
1672 celloMusic = \relative c {
1683 \new Voice = "one" {
1687 \new Lyrics \lyricsto "one" \sopranoLyrics
1689 \new Staff \celloMusic
1697 @node Four-part SATB vocal score
1698 @subsection Four-part SATB vocal score
1700 Most vocal scores of music written for four-part mixed choir
1701 with orchestral accompaniment such as Mendelssohn's Elijah or
1702 Handel's Messiah have the choral music and words on four
1703 staves, one for each of SATB, with a piano reduction of the
1704 orchestral accompaniment underneath. Here's an example
1705 from Handel's Messiah:
1707 @c The following should appear as music without code
1708 @lilypond[quote,ragged-right]
1710 global = { \key d \major \time 4/4 }
1711 sopMusic = \relative c'' {
1713 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
1715 sopWords = \lyricmode {
1716 Wor -- thy is the lamb that was slain
1718 altoMusic = \relative a' {
1720 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
1722 altoWords = \sopWords
1723 tenorMusic = \relative c' {
1725 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
1727 tenorWords = \sopWords
1728 bassMusic = \relative c' {
1730 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
1732 bassWords = \sopWords
1733 upper = \relative a' {
1736 r4 <a d fis>2 <a e' a>4 |
1737 <d fis d'>4. <d fis d'>8 <a d a'>2 |
1738 <g cis g'>4 <a d fis> <a cis e>2 |
1740 lower = \relative c, {
1743 <d d'>4 <d d'>2 <cis cis'>4 |
1744 <b b'>4. <b' b'>8 <fis fis'>2 |
1745 <e e'>4 <d d'> <a' a'>2 |
1749 << % combine ChoirStaff and PianoStaff in parallel
1751 \new Staff = "sopranos" <<
1752 \set Staff.instrumentName = "Soprano"
1753 \new Voice = "sopranos" { \global \sopMusic }
1755 \new Lyrics \lyricsto "sopranos" { \sopWords }
1756 \new Staff = "altos" <<
1757 \set Staff.instrumentName = "Alto"
1758 \new Voice = "altos" { \global \altoMusic }
1760 \new Lyrics \lyricsto "altos" { \altoWords }
1761 \new Staff = "tenors" <<
1762 \set Staff.instrumentName = "Tenor"
1763 \new Voice = "tenors" { \global \tenorMusic }
1765 \new Lyrics \lyricsto "tenors" { \tenorWords }
1766 \new Staff = "basses" <<
1767 \set Staff.instrumentName = "Bass"
1768 \new Voice = "basses" { \global \bassMusic }
1770 \new Lyrics \lyricsto "basses" { \bassWords }
1774 \set PianoStaff.instrumentName = "Piano "
1775 \new Staff = "upper" \upper
1776 \new Staff = "lower" \lower
1782 None of the templates provides this layout exactly. The
1783 nearest is @q{SATB vocal score and automatic piano reduction},
1784 but we shall need to change the layout and add a piano
1785 accompaniment which is not derived automatically from the
1786 vocal parts. The variables holding the music and words for
1787 the vocal parts are fine, but we shall need to add variables for
1788 the piano reduction.
1790 The order in which the contexts appear in the ChoirStaff of
1791 the template do not correspond with the order in the vocal
1792 score shown above. We need to rearrange them so there are
1793 four staves with the words written directly underneath the
1794 notes for each part.
1795 All the voices should be @code{\voiceOne}, which is
1796 the default, so the @code{\voiceXXX} commands can be removed.
1797 We also need to specify the tenor clef for the tenors.
1798 The way in which lyrics are specified has also been simplified
1799 as we have not yet encountered the method used in the template.
1800 We've also added the names of each staff.
1802 Doing this gives for our ChoirStaff:
1806 \new Staff = "sopranos" <<
1807 \set Staff.instrumentName = "Soprano"
1808 \new Voice = "sopranos" @{ \global \sopMusic @}
1810 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
1811 \new Staff = "altos" <<
1812 \set Staff.instrumentName = "Alto"
1813 \new Voice = "altos" @{ \global \altoMusic @}
1815 \new Lyrics \lyricsto "altos" @{ \altoWords @}
1816 \new Staff = "tenors" <<
1817 \set Staff.instrumentName = "Tenor"
1818 \new Voice = "tenors" @{ \global \tenorMusic @}
1820 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
1821 \new Staff = "basses" <<
1822 \set Staff.instrumentName = "Bass"
1823 \new Voice = "basses" @{ \global \bassMusic @}
1825 \new Lyrics \lyricsto "basses" @{ \bassWords @}
1829 Next we must work out the piano part. This is
1830 easy - we just pull out the piano part from the
1831 @q{Solo piano} template:
1835 \set PianoStaff.instrumentName = "Piano "
1836 \new Staff = "upper" \upper
1837 \new Staff = "lower" \lower
1841 and add the variable definitions for @code{upper}
1844 The ChoirStaff and PianoStaff must be combined
1845 using angle brackets as we want them to be
1846 stacked one above the other:
1849 << % combine ChoirStaff and PianoStaff one above the other
1851 \new Staff = "sopranos" <<
1852 \new Voice = "sopranos" @{ \global \sopMusic @}
1854 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
1855 \new Staff = "altos" <<
1856 \new Voice = "altos" @{ \global \altoMusic @}
1858 \new Lyrics \lyricsto "altos" @{ \altoWords @}
1859 \new Staff = "tenors" <<
1860 \clef "G_8" % tenor clef
1861 \new Voice = "tenors" @{ \global \tenorMusic @}
1863 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
1864 \new Staff = "basses" <<
1866 \new Voice = "basses" @{ \global \bassMusic @}
1868 \new Lyrics \lyricsto "basses" @{ bassWords @}
1872 \set PianoStaff.instrumentName = "Piano "
1873 \new Staff = "upper" \upper
1874 \new Staff = "lower" \lower
1879 Combining all these together and adding the music
1880 for the three bars of the example above gives:
1882 @lilypond[quote,verbatim,ragged-right]
1884 global = { \key d \major \time 4/4 }
1885 sopMusic = \relative c'' {
1887 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
1889 sopWords = \lyricmode {
1890 Wor -- thy is the lamb that was slain
1892 altoMusic = \relative a' {
1894 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
1896 altoWords = \sopWords
1897 tenorMusic = \relative c' {
1899 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
1901 tenorWords = \sopWords
1902 bassMusic = \relative c' {
1904 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
1906 bassWords = \sopWords
1907 upper = \relative a' {
1910 r4 <a d fis>2 <a e' a>4 |
1911 <d fis d'>4. <d fis d'>8 <a d a'>2 |
1912 <g cis g'>4 <a d fis> <a cis e>2 |
1914 lower = \relative c, {
1917 <d d'>4 <d d'>2 <cis cis'>4 |
1918 <b b'>4. <b' b'>8 <fis fis'>2 |
1919 <e e'>4 <d d'> <a' a'>2 |
1923 << % combine ChoirStaff and PianoStaff in parallel
1925 \new Staff = "sopranos" <<
1926 \set Staff.instrumentName = "Soprano"
1927 \new Voice = "sopranos" { \global \sopMusic }
1929 \new Lyrics \lyricsto "sopranos" { \sopWords }
1930 \new Staff = "altos" <<
1931 \set Staff.instrumentName = "Alto"
1932 \new Voice = "altos" { \global \altoMusic }
1934 \new Lyrics \lyricsto "altos" { \altoWords }
1935 \new Staff = "tenors" <<
1936 \set Staff.instrumentName = "Tenor"
1937 \new Voice = "tenors" { \global \tenorMusic }
1939 \new Lyrics \lyricsto "tenors" { \tenorWords }
1940 \new Staff = "basses" <<
1941 \set Staff.instrumentName = "Bass"
1942 \new Voice = "basses" { \global \bassMusic }
1944 \new Lyrics \lyricsto "basses" { \bassWords }
1948 \set PianoStaff.instrumentName = "Piano "
1949 \new Staff = "upper" \upper
1950 \new Staff = "lower" \lower
1957 @node Building a score from scratch
1958 @subsection Building a score from scratch
1960 After gaining some facility with writing LilyPond code you
1961 may find that it is easier to build a score from scratch
1962 rather than modifying one of the templates. You can also
1963 develop your own style this way to suit the sort of music you
1964 like. Let's see how to put together the score for an organ
1965 prelude as an example.
1967 We begin with a header section. Here go the title, name
1968 of composer, etc, then come any variable definitions, and
1969 finally the score block. Let's start with these in outline
1970 and fill in the details later.
1972 We'll use the first two bars of Bach's prelude
1973 based on @emph{Jesu, meine Freude} which is written for two
1974 manuals and pedal organ. The top manual part has two voices,
1975 the lower and pedal organ one each. So we need four
1976 music definitions and one to define the time signature
1982 title = "Jesu, meine Freude"
1983 composer = "J S Bach"
1985 TimeKey = @{ \time 4/4 \key c \minor @}
1986 ManualOneVoiceOneMusic = @{s1@}
1987 ManualOneVoiceTwoMusic = @{s1@}
1988 ManualTwoMusic = @{s1@}
1989 PedalOrganMusic = @{s1@}
1995 For now we've just used a spacer note, @code{s1},
1996 instead of the real music. We'll add that later.
1998 Next let's see what should go in the score block.
1999 We simply mirror the staff structure we want.
2000 Organ music is usually written on three staves,
2001 one for each manual and one for the pedals. The
2002 manual staves should be bracketed together so we
2003 need to use a PianoStaff for them. The first
2004 manual part needs two voices and the second manual
2009 \new Staff = "ManualOne" <<
2010 \new Voice @{ \ManualOneVoiceOneMusic @}
2011 \new Voice @{ \ManualOneVoiceTwoMusic @}
2012 >> % end ManualOne Staff context
2013 \new Staff = "ManualTwo" <<
2014 \new Voice @{ \ManualTwoMusic @}
2015 >> % end ManualTwo Staff context
2016 >> % end PianoStaff context
2019 Next we need to add a staff for the pedal organ.
2020 This goes underneath the PianoStaff, but it must
2021 be simultaneous with it, so we need angle brackets
2022 round the two. Missing these out would generate
2023 an error in the log file. It's a common mistake
2024 which you'll make sooner or later! Try copying
2025 the final example at the end of this section,
2026 remove these angle brackets, and compile it to
2027 see what errors it generates.
2030 << % PianoStaff and Pedal Staff must be simultaneous
2032 \new Staff = "ManualOne" <<
2033 \new Voice @{ \ManualOneVoiceOneMusic @}
2034 \new Voice @{ \ManualOneVoiceTwoMusic @}
2035 >> % end ManualOne Staff context
2036 \new Staff = "ManualTwo" <<
2037 \new Voice @{ \ManualTwoMusic @}
2038 >> % end ManualTwo Staff context
2039 >> % end PianoStaff context
2040 \new Staff = "PedalOrgan" <<
2041 \new Voice @{ \PedalOrganMusic @}
2046 It is not strictly necessary to use the simultaneous construct
2047 @code{<< >>} for the manual two staff and the pedal organ staff,
2048 since they contain only one music expression, but it does no harm
2049 and always using angle brackets after @code{\new Staff} is a good
2050 habit to cultivate in case there are multiple voices.
2052 Let's add this structure to the score block, and adjust the
2053 indenting. We also add the appropriate clefs, ensure the
2054 second voice stems point down with @code{\voiceTwo} and
2055 enter the time signature and key to each staff using our
2056 predefined variable, @code{\TimeKey}.
2060 << % PianoStaff and Pedal Staff must be simultaneous
2062 \new Staff = "ManualOne" <<
2063 \TimeKey % set time signature and key
2065 \new Voice @{ \ManualOneVoiceOneMusic @}
2066 \new Voice @{ \voiceTwo \ManualOneVoiceTwoMusic @}
2067 >> % end ManualOne Staff context
2068 \new Staff = "ManualTwo" <<
2071 \new Voice @{ \ManualTwoMusic @}
2072 >> % end ManualTwo Staff context
2073 >> % end PianoStaff context
2074 \new Staff = "PedalOrgan" <<
2077 \new Voice @{ \PedalOrganMusic @}
2078 >> % end PedalOrgan Staff
2080 @} % end Score context
2083 That completes the structure. Any three-staff organ music
2084 will have a similar structure, although the number of voices
2085 may vary. All that remains now
2086 is to add the music, and combine all the parts together.
2088 @lilypond[quote,verbatim,ragged-right]
2091 title = "Jesu, meine Freude"
2092 composer = "J S Bach"
2094 TimeKey = { \time 4/4 \key c \minor }
2095 ManualOneVoiceOneMusic = \relative g' {
2096 g4 g f ees | d2 c2 |
2098 ManualOneVoiceTwoMusic = \relative c' {
2099 ees16 d ees8~ ees16 f ees s c8 d~ d c~ |
2100 c c4 b8 c8. g16 c b c d |
2102 ManualTwoMusic = \relative c' {
2103 c16 b c8~ c16 b c g a8 g~ g16 g aes ees |
2104 f ees f d g aes g f ees d e8~ ees16 f ees d |
2106 PedalOrganMusic = \relative c {
2107 r8 c16 d ees d ees8~ ees16 a, b g c b c8 |
2108 r16 g ees f g f g8 c,2 |
2112 << % PianoStaff and Pedal Staff must be simultaneous
2114 \new Staff = "ManualOne" <<
2115 \TimeKey % set time signature and key
2117 \new Voice { \ManualOneVoiceOneMusic }
2118 \new Voice { \voiceTwo \ManualOneVoiceTwoMusic }
2119 >> % end ManualOne Staff context
2120 \new Staff = "ManualTwo" <<
2123 \new Voice { \ManualTwoMusic }
2124 >> % end ManualTwo Staff context
2125 >> % end PianoStaff context
2126 \new Staff = "PedalOrgan" <<
2129 \new Voice { \PedalOrganMusic }
2130 >> % end PedalOrgan Staff
2132 } % end Score context