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 At this point, you may be confused, since you have never seen a
53 @code{\score@{@}} before. This is because LilyPond automatically
54 adds the extra commands when you give it simple input. LilyPond
55 treats input like this:
64 as shorthand for this:
75 In other words, if the input contains a single music expression,
76 LilyPond will interpret the file as though the music expression
77 was wrapped up inside a @code{\score@{@}}.
81 A @code{\score} must begin with a compound music expression.
82 Remember that a music expression could be anything from a single
88 @var{...insert the whole score of a Wagner opera in here...}
94 Since everything is inside @code{@{ ... @}}, it counts
95 as one music expression.
97 As we saw previously, the @code{\score} can contain other things,
110 Some people put some of those commands outside the @code{\score}
111 block -- for example, @code{\header} is often placed above the
112 @code{\score}. That's just another shorthand that LilyPond
113 accepts. Two more commands you have not previously seen are
114 @code{\layout @{ @}} and @code{\midi @{@}}. If these appear as
115 shown they will cause LilyPond to produce a printed output and a
116 MIDI out respectively. They are described fully in the
117 Notation Reference - @ruser{Score layout} and
118 @ruser{Creating MIDI files}.
124 Another great shorthand is the ability to define variables. All
125 the templates use this
128 melody = \relative c' @{
137 When LilyPond looks at this file, it takes the value of
138 @code{melody} (everything after the equals sign) and inserts it
139 whenever it sees @code{\melody}. There's nothing special about
140 the names -- it could be @code{melody}, @code{global},
141 @code{pianorighthand}, or @code{foofoobarbaz}. You can use
142 whatever variable names you want as along as they contain just
143 alphabetic characters. For more details, see
144 @ruser{Saving typing with variables and functions}.
149 For a complete definition of the input format, see
150 @ruser{File structure}.
152 @node Score is a (single) compound musical expression
153 @subsection Score is a (single) compound musical expression
155 @cindex Compound music expression
156 @cindex Music expression, compound
158 We saw the general organization of LilyPond input files in the
159 previous section, @ref{How LilyPond files work}. But we seemed to
160 skip over the most important part: how do we figure out what to
161 write after @code{\score}?
163 We didn't skip over it at all. The big mystery is simply that
164 there @emph{is} no mystery. This line explains it all:
167 @emph{A @code{\score} must begin with a compound music expression.}
171 You may find it useful to review
172 @ref{Music expressions explained}. In that section, we saw how to
173 build big music expressions from small pieces -- we started from
174 notes, then chords, etc. Now we're going to start from a big
175 music expression and work our way down.
179 @{ % this brace begins the overall compound music expression
181 @var{...insert the whole score of a Wagner opera in here...}
183 @} % this brace ends the overall compound music expression
188 A whole Wagner opera would easily double the length of this
189 manual, so let's just add a singer and piano. We don't need a
190 @code{GrandStaff} for this ensemble, which simply groups a number
191 of staves together with a brace at the left, so we shall remove
192 it. We @emph{do} need a singer and a piano, though.
198 \new Staff = "singer" <<
200 \new PianoStaff = piano <<
208 Remember that we use @code{<<} and @code{>>} to show simultaneous
209 music. And we definitely want to show the vocal part and piano
210 part at the same time, not one after the other! However, the
211 @code{<< .. >>} construct is not really necessary for the Singer
212 staff, as it contains only one music expression, but Staves often
213 do require simultaneous Voices within them, so using @code{<< .. >>}
214 rather than braces is a good habit to adopt.
220 \new Staff = "singer" <<
221 \new Voice = "vocal" @{ @}
224 \new PianoStaff = "piano" <<
225 \new Staff = "upper" @{ @}
226 \new Staff = "lower" @{ @}
234 Now we have a lot more details. We have the singer's staff: it
235 contains a @code{Voice} (in LilyPond, this term refers to a set of
236 notes, not necessarily vocal notes -- for example, a violin
237 generally plays one voice) and some lyrics. We also have a piano
238 staff: it contains an upper staff (right hand) and a lower staff
241 At this stage, we could start filling in notes. Inside the curly
242 braces next to @code{\new Voice = vocal}, we could start writing
250 But if we did that, the @code{\score} section would get pretty
251 long, and it would be harder to understand what was happening. So
252 let's use variables instead.
255 melody = \relative c'' @{ @}
256 text = \lyricmode @{ @}
257 upper = \relative c'' @{ @}
258 lower = \relative c @{ @}
262 \new Staff = "singer" <<
263 \new Voice = "vocal" @{ \melody @}
264 \addlyrics @{ \text @}
266 \new PianoStaff = "piano" <<
267 \new Staff = "upper" @{ \upper @}
268 \new Staff = "lower" @{ \lower @}
277 Remember that you can use almost any name you like as long
278 as it contains just alphabetic characters. The exact
279 limitations on variable names are detailed in
280 @ruser{File structure}.
282 Be careful about the difference between notes, which are introduced
283 with @code{\relative}, and lyrics, which are introduced with
284 @code{\lyricmode}. These are essential to tell LilyPond
285 to interpret the following content as music and text
288 When writing (or reading) a @code{\score} section, just take it
289 slowly and carefully. Start with the outer layer, then work on
290 each smaller layer. It also really helps to be strict with
291 indentation -- make sure that each item on the same layer starts
292 on the same horizontal position in your text editor.
295 @node Nesting Music Expressions
296 @subsection Nesting Music Expressions
298 It is not essential to declare all staves at the beginning;
299 they may be introduced temporarily at any point. This is
300 particularly useful for creating ossia sections
301 (see @rglos{ossia}). Here is a simple example showing how
302 to introduce a new staff temporarily for the duration of
305 @lilypond[verbatim,quote,ragged-right]
321 The ossia section may be placed above the staff
324 @lilypond[verbatim,quote,ragged-right]
332 alignAboveContext = "main" }
340 This example uses @code{\with}, which will be explained more
341 fully later. It is a means of modifying the default behaviour
342 of a Staff. Here it says that the new staff should be placed
343 above the staff called @qq{main} instead of the default position
346 Ossia are often written without clef and without
347 time signature and are usually in a smaller font.
348 These require further commands which
349 have not yet been introduced. See ...
350 TODO Add ref to tweaks section where this example should
351 be placed and explained.
352 FIXME Move following example to Tweaks
354 @lilypond[verbatim,quote,ragged-right]
355 \new Staff = "main" {
359 << % Start main and ossia in parallel
360 { r8 f c c } % Main music
361 \new Staff \with { % Start ossia staff
362 \remove "Clef_engraver"
363 \remove "Time_signature_engraver"
364 % Reduce size of notes and staff
366 \override StaffSymbol #'staff-space = #(magstep -2)
367 alignAboveContext = "main" % Place above main staff
369 { s8 f f c } % Ossia music
370 >> % End parallel music
376 @node On the un-nestedness of brackets and ties
377 @subsection On the un-nestedness of brackets and ties
379 You have already met a number of different types of bracket in
380 writing the input file to LilyPond. These obey different rules
381 which can be confusing at first. Before we explain the rules
382 let's first review the different types of bracket.
384 @multitable @columnfractions .3 .7
385 @headitem Bracket Type
387 @item @code{@{ .. @}}
388 @tab Encloses a sequential segment of music
390 @tab Encloses the notes of a chord
391 @item @code{<< .. >>}
392 @tab Encloses concurrent or simultaneous sections
394 @tab Marks the start and end of a slur
395 @item @code{\( .. \)}
396 @tab Marks the start and end of a phrase mark
398 @tab Marks the start and end of a manual beam
401 To these we should add other constructs which generate lines
402 between or across notes: ties (marked by a tilde, @code{~}),
403 tuplets written as @code{\times x/y @{..@}}, and grace notes
404 written as @code{\grace@{..@}}.
406 Outside LilyPond, the conventional use of brackets requires
407 the different types to be properly nested, like this,
408 @code{<< [ @{ ( .. ) @} ] >>}, with the closing brackets being
409 encountered in exactly the opposite order to the opening
410 brackets. This @strong{is} a requirement for the three types of
411 bracket described by the word @q{Encloses} in the table above -
412 they must nest properly.
413 However, the remaining brackets, described with the word
414 @q{Marks} in the table above together with ties and tuplets,
415 do @strong{not} have to nest
416 properly with any of the brackets. In fact, these are not
417 brackets in the sense that
418 they enclose something - they are simply markers to indicate
419 where something starts and ends.
421 So, for example, a phrasing slur can start before a manually
422 inserted beam and end before the end of the beam - not very
423 musical, perhaps, but possible:
425 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
426 { g8\( a b[ c b\) a] }
429 In general, different kinds of brackets, and those implied by
430 tuplets, ties and grace notes, may be mixed freely.
431 This example shows a beam extending into a tuplet (line 1),
432 a slur extending into a tuplet (line 2),
433 a beam and a slur extending into a tuplet, a tie crossing
434 two tuplets, and a phrasing slur extending out of a tuplet
437 @lilypond[quote,verbatim,fragment,ragged-right]
439 r16[ g16 \times 2/3 {r16 e'8] }
440 g16( a \times 2/3 {b d) e' }
441 g8[( a \times 2/3 {b d') e'~]}
442 \times 4/5 {e'32\( a b d' e'} a'4.\)
447 @node Voices contain music
448 @section Voices contain music
450 Singers need voices to sing, and so does LilyPond.
451 The actual music for all instruments in a score
452 is contained in Voices - the most fundamental
453 of all LilyPond's concepts.
456 * I'm hearing Voices::
457 * Explicitly instantiating voices::
458 * Voices and vocals::
461 @node I'm hearing Voices
462 @subsection I'm hearing Voices
466 @cindex Voice context
468 The lowest, most fundamental or innermost layers in a LilyPond
469 score are called @q{Voice contexts} or just @q{Voices} for short.
470 Voices are sometimes called @q{layers} in other notation
473 In fact, a Voice layer or context is the only one which can
474 contain music. If a Voice context is not explicitly declared
475 one is created automatically. Some instruments such as an
476 Oboe can play only one note at a time. Music written for
477 such instruments is monophonic and requires just a single
478 voice. Instruments which can play more than one note at a
479 time like the piano will often require multiple voices to
480 encode the different concurrent notes and rhythms they are
483 A single voice can contain many notes in a chord, of course,
484 so when exactly are multiple voices needed?
485 Let us analyse a short piece of music to see how many voices
486 are required. Here are the notes from the first two bars
487 of the second of Chopin's Deux Nocturnes, Op 32.
489 @c The following should appear as music without code
490 @lilypond[quote,ragged-right]
491 \new Staff \relative c'' {
499 \once \override NoteColumn #'force-hshift = #0 <ees c>2
500 \once \override NoteColumn #'force-hshift = #0.5 des2 }
506 The direction of the stems is often used to indicate the
507 continuity of two simultaneous melodic lines. Here the
508 stems of the highest notes are all pointing up and the
509 stems of the lower notes are all pointing down.
510 This is the first indication that more than one voice
513 But the real need for multiple voices arises when notes
514 which start at the same time have different durations.
515 Look at the notes which start at beat three in the first
516 bar. The a-flat is a dotted quarter note, the f is a
517 quarter note and the d-flat is a half note. These
518 cannot be written as a chord as all the notes in a chord
519 must have the same duration. Neither can they be written
520 as sequential notes, as they must start at the same time.
521 This section of the bar requires three voices, and the
522 normal practice would be to write the whole bar as three
523 voices, as shown here, where we have used different noteheads
524 and colors for the three voices.
526 @c The following should appear as music without code
527 @c The three voice styles should be defined in -init
528 @lilypond[quote,ragged-right]
529 \new Staff \relative c'' {
540 \once \override NoteColumn #'force-hshift = #0 <ees c>2
541 \once \override NoteColumn #'force-hshift = #0.5 des2 }
547 Let us see how this is done.
551 The easiest way to enter fragments with more than one voice on a
552 staff is to enter each voice as a sequence (with @code{@{...@}}),
553 and combine them simultaneously with angle brackets, @code{<<...>>}.
554 The fragments must also be separated with double backward slashes,
555 @code{\\}, to place them in separate voices. Without these, the
556 notes would be entered into a single voice, which would usually
557 cause errors. This technique is particularly suited to pieces of
558 music which are largely monophonic with occasional short sections
559 of polyphony. Here's a simple example:
561 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
563 % Voice "1" Voice "2"
564 << { r4 g g4. a8 } \\ { d,2 d4 g } >> |
565 << { bes4 bes c bes } \\ { g4 g g8( a) g4 } >> |
566 << { a2. r4 } \\ { fis2. s4 } >>
569 This example has just two voices, but the same contruct may be
570 used to encode three or more voices by adding more back-slash
573 The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
574 In each of these contexts, the vertical direction of slurs,
575 stems, ties, dynamics etc., is set appropriately.
577 @lilypond[quote,verbatim,fragment]
578 \new Staff \relative c' {
581 % Voice "1" Voice "2" Voice "3"
582 << { g4 f e } \\ { r8 e4 d c8 ~ } >> |
583 << { d2 e2 } \\ { c8 b16 a b8 g ~ g2 } \\ { s4 b4 c2 } >> |
587 These voices are all separate from the main voice that contains
588 the notes just outside the @code{<< .. >>} construct. Let's call
589 this the @emph{simultaneous construct}. Slurs and ties may only
590 connect notes within the same voice, so slurs and ties cannot go
591 into or out of a simultaneous construct. Conversely,
592 parallel voices from separate simultaneous constructs on the same
593 staff are the same voice. Other voice-related properties also
594 carry across simultaneous constructs. Here is the same example,
595 with different colors and noteheads for each voice. Note that
596 changes in one Voice do not affect other voices, but they do
597 persist in the same Voice later. Note also that tied notes may be
598 split across the same voices in two constructs, shown here in the
601 @lilypond[quote,verbatim]
602 \new Staff \relative c' {
612 { c8 b16 a b8 g ~ g2 } \\
619 The commands @code{\voiceXXXStyle} are mainly intended for use in
620 educational documents such as this one. They modify the color
621 of the notehead, the stem and the beams, and the style of the
622 notehead, so that the voices may be easily distinguished.
623 Voice one is set to red diamonds, voice two to blue triangles,
624 voice three to green crossed circles, and voice four (not used
625 here) to magenta crosses. We shall see later how commands like
626 these may be created by the user.
627 TODO: add ref to appropriate section in Tweaks
629 Polyphony does not change the relationship of notes within a
630 @code{\relative @{ @}} block. Each note is still calculated
631 relative to the note immediately preceding it, or to the first
632 note of the preceding chord. So in
635 \relative c' @{ noteA << < noteB noteC > \\ noteD >> noteE @}
639 @code{noteB} is relative to @code{noteA} @*
640 @code{noteC} is relative to @code{noteB}, not @code{noteA}; @*
641 @code{noteD} is relative to @code{noteB}, not @code{noteA} or
643 @code{noteE} is relative to @code{noteD}, not @code{noteA}
645 We are now in a position to return to the first example from
646 the Chopin Nocturne to see how this might be encoded. As we
647 shall see, this encounters some difficulties. We begin as
648 we have learnt, using the @code{<< \\ >>} construct to
649 enter the music of the first bar in three voices:
651 @lilypond[quote,verbatim,fragment,ragged-right]
652 \new Staff \relative c'' {
655 { c2 aes4. bes8 } \\ { aes2 f4 fes } \\ { <ees c>2 des2 }
665 @funindex \voiceThree
668 The stem directions are automatically assigned with the
669 odd-numbered voices taking upward stems and the even-numbered
670 voices downward ones. The stems for voices 1 and 2 are right,
671 but the stems in voice 3 should go down in this particular piece
672 of music. We can correct this
673 by telling LilyPond that this third voice is really a fourth
674 voice, with stems going down, using the @code{\voiceFour}
675 command. There are also corresponding @code{\voiceOne},
676 @code{\voiceTwo}, and @code{voiceThree}
677 commands. This results in the following:
679 @lilypond[quote,verbatim,fragment,ragged-right]
680 \new Staff \relative c'' {
685 { \voiceFour <ees c>2 des2 }
692 and exposes a problem commonly encountered with multiple
693 voices: the stems of notes can collide with noteheads
694 in other voices. In laying out the notes, LilyPond allows the
695 notes or chords from two voices to occupy the same vertical
696 note column provided the stems are in opposite directions, but
697 the notes from a third voice are displaced to avoid the stems
698 colliding. This often works well, but in this example the
699 notes of the third voice are clearly not well placed by default.
700 LilyPond provides several ways to adjust the horizontal placing
701 of notes. We are not quite ready yet to see how to correct this,
702 so we shall leave this problem until a later section (see ... )
706 @node Explicitly instantiating voices
707 @subsection Explicitly instantiating voices
709 Voice contexts can also be created manually
710 inside a @code{<< >>} block to create polyphonic music, using
711 @code{\voiceOne} ... @code{\voiceFour} to indicate the required
712 directions of stems, slurs, etc.
714 Specifically, the construct @code{<< \\ >>} which we used in
715 the previous section:
718 << \upper \\ \lower >>
722 where @code{upper} and @code{lower} are user-defined variables
723 containing the music for the two voices, is equivalent to
727 \new Voice = "1" @{ \voiceOne \upper @}
728 \new Voice = "2" @{ \voiceTwo \lower @}
732 The @code{\voiceXXX} commands set the direction of stems, slurs,
733 ties, articulations, text annotations, augmentation dots of dotted
734 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
735 make these objects point upwards, while @code{\voiceTwo} and
736 @code{\voiceFour} make them point downwards. These commands also
737 generate a horizontal shift for each voice when this is required
738 to avoid clashes of note heads. The command @code{\oneVoice}
739 reverts the settings back to the normal values for a single voice.
741 Let us see in some simple examples exactly what effect
742 @code{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on
743 markup, ties, slurs, and dynamics:
745 @lilypond[quote,ragged-right,verbatim]
747 c-"default" d8 ~ d e4 ( f g a ) b-> c
751 @lilypond[quote,ragged-right,verbatim]
754 c-"\\voiceOne" d8 ~ d e4 ( f g a ) b-> c
756 c,-"\\oneVoice" d8 ~ d e4 ( f g a ) b-> c
760 @lilypond[quote,ragged-right,verbatim]
763 c-"\\voiceTwo" d8 ~ d e4 ( f g a ) b-> c
765 c,-"\\oneVoice" d8 ~ d e4 ( f g a ) b-> c
769 An expression that appears directly inside a @code{<< >>} belongs
770 to the main voice (but, note, @strong{not} in a @code{<< \\ >>}
771 contruct). This is useful when extra voices appear while the main
772 voice is playing. Here is a more correct rendition of the example
773 from the previous section. The red diamond-shaped notes
774 demonstrate that the main melody is now in a single voice context,
775 permitting a phrasing slur to be drawn over them.
777 @lilypond[quote,ragged-right,verbatim]
778 \new Staff \relative c' {
780 c16^( d e f % These notes are monophonic
781 << % Start simultaneous section of three voices
782 { g4 f e | d2 e2) } % Continue the main voice in parallel
783 \new Voice { % Initiate second voice
784 \voiceTwo % Set stems, etc, down
785 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
787 \new Voice { % Initiate third voice
788 \voiceThree % Set stems, etc, up
795 @cindex nesting music expressions
796 @cindex nesting simultaneous constructs
798 More deeply nested polyphony constructs are possible, and if a
799 voice appears only briefly this might be a more natural way to
802 @lilypond[quote,ragged-right,verbatim]
803 \new Staff \relative c' {
823 This method of nesting new voices briefly is useful
824 when only small sections of the music
825 are polyphonic, but when the whole staff is largely polyphonic
826 it can be clearer to use multiple voices throughout, using
827 spacing notes to step over sections where the voice is silent,
830 @lilypond[quote,ragged-right,verbatim]
831 \new Staff \relative c' <<
832 \new Voice { % Initiate first voice
834 c16^( d e f g4 f e | d2 e2) |
836 \new Voice { % Initiate second voice
837 \voiceTwo % set stems, etc down
838 s4 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 |
840 \new Voice { % Initiate third voice
841 \voiceThree % set stems, etc up
848 @node Voices and vocals
849 @subsection Voices and vocals
851 Vocal music presents a special difficulty: we need to combine two
852 expressions -- notes and lyrics.
854 You have already seen the @code{\addlyricsd@{@}} command, which
855 handles simple scores well. However, this technique is
856 quite limited. For more complex music, you must introduce the
857 lyrics in a @code{Lyrics} context using @code{\new Lyrics} and
859 the lyrics to the notes with @code{\lyricsto@{@}}, using the
860 name assigned to the Voice.
862 @lilypond[quote,verbatim,fragment]
864 \new Voice = "one" \relative c'' {
867 c4 b8. a16 g4. f8 e4 d c2
869 \new Lyrics \lyricsto "one" {
870 No more let sins and sor -- rows grow.
875 The automatic beaming which LilyPond uses by default works well
876 for instrumental music, but not so well for music with lyrics,
877 where beaming is either not required at all or is used to indicate
878 melismata in the lyrics. In the example above we use the command
879 @code{\autoBeamOff} to turn off the automatic beaming.
881 Let us reuse the earlier example from Judas Maccabæus to
882 illustrate this more flexible technique. We first recast
883 it to use variables so the music and lyrics can be separated
884 from the staff structure. We also introduce a choirstaff
885 bracket. The lyrics themselves must be introduced with
886 @code{\lyricmode} to ensure they are interpreted as lyrics
889 @lilypond[quote,verbatim]
890 global = { \time 6/8 \partial 8 \key f \major}
891 SopOneMusic = \relative c'' {
892 c8 | c([ bes)] a a([ g)] f | f'4. b, | c4.~ c4 }
893 SopTwoMusic = \relative c' {
894 r8 | r4. r4 c8 | a'([ g)] f f([ e)] d | e([ d)] c bes' }
895 SopOneLyrics = \lyricmode {
896 Let | flee -- cy flocks the | hills a -- dorn, __ }
897 SopTwoLyrics = \lyricmode {
898 Let | flee -- cy flocks the | hills a -- dorn, }
903 \new Voice = "SopOne" {
907 \new Lyrics \lyricsto "SopOne" {
912 \new Voice = "SopTwo" {
915 \new Lyrics \lyricsto "SopTwo" {
923 This is the basic structure of all vocal scores. More staves may
924 be added as required, more voices may be added to the staves,
925 more verses may be added to the lyrics,
926 and the variables containing the music can easily be placed
927 in separate files should they become too long.
929 Here is a final example of the first line of a hymn with four
930 verses, set for SATB. In this case the words for all four
933 @lilypond[quote,verbatim]
934 global = { \time 4/4 \partial 4 \key c \major}
935 SopMusic = \relative c' { c4 | e4. e8 g4 g | a a g }
936 AltoMusic = \relative c' { c4 | c4. c8 e4 e | f f e }
937 TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 }
938 BassMusic = \relative c { c4 | c4. c8 c4 c | f8 g a b c4 }
939 VerseOne = \lyricmode {
940 E -- | ter -- nal fa -- ther, | strong to save, }
941 VerseTwo = \lyricmode {
942 O | Christ, whose voice the | wa -- ters heard, }
943 VerseThree = \lyricmode {
944 O | Ho -- ly Spi -- rit, | who didst brood }
945 VerseFour = \lyricmode {
946 O | Tri -- ni -- ty of | love and pow'r }
952 \new Voice = "Sop" { \voiceOne \global \SopMusic }
953 \new Voice = "Alto" { \voiceTwo \AltoMusic }
954 \new Lyrics \lyricsto "Sop" { \VerseOne }
955 \new Lyrics \lyricsto "Sop" { \VerseTwo }
956 \new Lyrics \lyricsto "Sop" { \VerseThree }
957 \new Lyrics \lyricsto "Sop" { \VerseFour }
961 \new Voice = "Tenor" { \voiceOne \TenorMusic }
962 \new Voice = "Bass" { \voiceTwo \BassMusic }
968 @node Contexts and engravers
969 @section Contexts and engravers
971 Contexts and engravers have been mentioned informally
972 in earlier sections; we now must look at
973 these concepts in more detail, as they are important
974 in the fine-tuning of LilyPond output.
978 * Contexts explained::
979 * Creating contexts::
981 * Modifying contexts::
984 @node Contexts explained
985 @subsection Contexts explained
987 When music is printed, many notational elements which do not
988 appear explicitly in the input file must be added to the
989 output. For example, compare the input and output of the
992 @lilypond[quote,verbatim,relative=2,fragment]
996 The input is rather sparse, but in the output, bar lines,
997 accidentals, clef, and time signature have been added. When
998 LilyPond @emph{interprets} the input the musical information
999 is inspected in time order, similar to reading a score from left
1000 to right. While reading the input, the program remembers where
1001 measure boundaries are, and which pitches require explicit
1002 accidentals. This information must be held on several levels.
1003 For example, the effect of an accidental is limited
1004 to a single staff, while a bar line must be synchronized across
1007 Within LilyPond, these rules and bits of information are grouped
1008 in @emph{Contexts}. We have already met the @context{Voice}
1010 Others are the @context{Staff} and @context{Score} contexts.
1011 Contexts are hierarchical to reflect the heirarchical nature of
1013 For example: a @context{Staff} context can contain many
1014 @context{Voice} contexts, and a @context{Score} context can
1015 contain many @context{Staff} contexts.
1018 @image{context-example,5cm,,}
1021 Each context has the responsibility for enforcing some notation rules,
1022 creating some notation objects and maintaining the associated
1023 properties. For example, the @context{Voice} context may introduce an
1024 accidental and then the @context{Staff} context maintains the rule to
1025 show or suppress the accidental for the remainder of the measure.
1027 As another example, the synchronization of bar lines is by default
1028 handled in the @context{Score} context.
1029 However, in some music we may not want the bar lines to be
1030 synchronized -- consider a polymetric score in 4/4 and 3/4 time.
1031 In such cases, we must modify the default settings of the
1032 @context{Score} and @context{Staff} contexts.
1034 For very simple scores, contexts are created implicitly, and you need
1035 not be aware of them. For larger pieces, such as anything with more
1036 than one staff, they must be
1037 created explicitly to make sure that you get as many staves as you
1038 need, and that they are in the correct order. For typesetting pieces
1039 with specialized notation, it is usual to modify existing or
1040 even to define totally new contexts.
1042 In addition to the @context{Score,} @context{Staff} and
1043 @context{Voice} contexts there are contexts which fit between
1044 the score and staff levels to control staff groups, such as the
1045 @context{PianoStaff} and @context{ChoirStaff} contexts. There
1046 are also alternative staff and voice contexts, and contexts for
1047 lyrics, percussion, fret boards, figured bass, etc. A complete
1048 list is shown in the Notation Reference.
1051 The names of all context types are formed from one or more
1052 words, each word being capitalised and joined immediately to the
1053 preceding word with no hyphen or underscore, e.g.,
1054 @context{GregorianTranscriptionStaff}.
1056 @node Creating contexts
1057 @subsection Creating contexts
1059 There can be only one top level context, the @context{Score}
1060 context. This is created with the @code{\score} command,
1061 or, in simple scores, it is created automatically.
1063 For scores with only one voice and one staff, the
1064 @context{Voice} and @context{Staff} contexts may be left to be
1065 created automatically, but for more complex scores it is
1066 necessary to create them by hand.
1067 The simplest command that does this is @code{\new}.
1068 It is prepended to a music expression, for example
1071 @cindex new contexts
1072 @cindex Context, creating
1075 \new @var{type} @var{music expression}
1079 where @var{type} is a context name (like @code{Staff} or
1080 @code{Voice}). This command creates a new context, and starts
1081 interpreting the @var{music expression} within that context.
1083 Note that there is no @code{\new Score % Invalid!} command;
1084 the single top-level @context{Score} context is introduced
1085 with @code{\score}. This is because there can be only one
1086 @context{Score} context, whereas there may be multiple
1087 @context{Staff} and @context{Voice} contexts - each created
1090 So a practical application of @code{\new} is a score with many
1091 staves. Each part that should be on its own staff is preceded
1092 with @code{\new Staff}.
1094 @lilypond[quote,verbatim,relative=2,ragged-right,fragment]
1101 The @code{\new} command may also give a identifying name to the
1102 context to distinguish it from other contexts of the same type,
1105 \new @var{type} = @var{id} @var{music}
1108 Note the distinction between the name of the context type,
1109 @context{Staff}, @context{Voice}, etc, and
1110 the identifying name of a particular instance of that type,
1111 which can be any sequence of letters invented by the user.
1112 The identifying name is used to refer back to that particular
1113 instance of a context. We saw this in use in the section on
1114 lyrics in @ref{Voices and vocals}.
1118 @subsection Engravers
1120 Every mark on the printed output of a score produced by LilyPond
1121 is produced by an @code{Engraver}. Thus there is an engraver
1122 to print staves, one to print noteheads, one for stems, one for
1123 beams, etc, etc. In total there are over 120 such engravers!
1124 Fortunately, for most scores it is not necessary to know about
1125 more than a few, and for simple scores you do not need to know
1128 A musical score can be viewed heirarchically. At the top level
1129 is the whole score. This consists of one or more staves.
1130 Each staff contains one or more voices. As we have seen, there
1131 are contexts which correspond to each of these levels and it
1132 is in these contexts that the Engravers operate.
1134 Engravers such as the @code{Metronome_mark_engraver}, whose
1135 action and output applies to the score as a whole, live in
1136 the highest level context - the @context{Score} context. There
1137 can be only one of these engravers as there can be only one tempo
1138 at any particular point in the score.
1140 The @code{Clef_engraver} and @code{Key_engraver} are to be
1141 found in the Staff Context, as different staves may require
1142 different clefs and keys.
1144 The @code{Note_heads_engraver} and @code{Stem_engraver} live
1145 in a @context{Voice} context, the lowest level context of all.
1147 Each engraver processes the particular objects associated
1148 with its function, and contains the properties that relate
1149 to that function. These properties, like the properties
1150 associated with contexts, may be modified to change the
1151 operation of the engraver or the appearance of those elements
1152 in the printed score.
1154 Engravers all have compound names formed from words which
1155 describe their function. Just the first word is capitalised,
1156 and the remainder are joined to it with underscores. Thus
1157 the @code{Staff_symbol_engraver} is responsible for creating the
1158 lines of the staff, the @code{Clef_engraver} determines and sets
1159 the pitch reference point on the staff by drawing a clef symbol.
1161 Here are some of the most common engravers together with their
1162 function. You will see it is easy to guess the function from
1163 the name, or vice versa.
1165 @multitable @columnfractions .3 .7
1168 @item Accidental_engraver
1169 @tab Makes accidentals, cautionary and suggested accidentals
1174 @item Dynamic_engraver
1175 @tab Creates hairpins and dynamic texts
1177 @tab Creates the key signature
1178 @item Metronome_mark_engraver
1179 @tab Engraves metronome marking
1180 @item Note_heads_engraver
1181 @tab Engraves noteheads
1184 @item Staff_symbol_engraver
1185 @tab Engraves the five (by default) lines of the staff
1187 @tab Creates stems and single-stem tremulos
1190 We shall see later how the output of LilyPond can be changed
1191 by modifying the action of Engravers.
1194 @node Modifying contexts
1195 @subsection Modifying contexts
1198 * Changing context properties::
1199 * Adding and removing engravers::
1202 @node Changing context properties
1203 @subsubsection Changing context properties
1205 @cindex context properties
1209 Contexts are responsible for holding the values of a number of
1210 context @emph{properties}. Many of them can be changed to
1211 influence the interpretation of the input and so change the
1212 appearance of the output. They are changed by the
1213 @code{\set} command. This takes the form
1216 \set @emph{ContextName}.@emph{propertyName} = @emph{value}
1219 Where the @emph{ContextName} is usually @context{Score},
1220 @context{Staff} or @context{Voice}. It may be omitted,
1221 in which case @context{Voice} is assumed.
1223 The names of context properties consist of words joined
1224 together with no hyphens or underscores, all except the
1225 first having a capital letter. Here are a few examples
1226 of some commonly used ones. There are many more.
1228 @multitable @columnfractions .3 .2 .5
1229 @headitem propertyName
1234 @tab If true (##t), set extra natural sign before accidentals
1235 @item currentBarNumber
1237 @tab Set the current bar number
1240 @tab If true (##t), print slurs both above and below notes
1241 @item instrumentName
1243 @tab Set the name to be placed at the start of the staff
1246 @tab Increase or decrease the font size
1249 @tab Set the text to print before the start of a verse
1252 Before we can set any of these properties we need to know
1253 which context they operate in. Sometimes this is obvious,
1254 but occasionally it can be tricky. If the wrong context
1255 is specified, no error message is produced, but the expected
1256 action will not be taken. For example, the
1257 @code{instrumentName} clearly lives in the Staff context, since
1258 it is the staff that is named.
1259 In this example the first staff is labelled, but the second,
1260 Alto, staff is not, because we omitted the context name.
1262 @lilypond[quote,verbatim,ragged-right]
1264 \new Staff \relative c'' {
1265 \set Staff.instrumentName = "Soprano"
1268 \new Staff \relative c' {
1269 \set instrumentName = "Alto"
1275 Remember the default context name is Voice, so the second
1276 @code{\set} command set the property @emph{instrumentName} in the
1277 Voice context to @qq{Alto}, but as LilyPond does not look
1278 for any such property in the @context{Voice} context, no
1279 further action took place. No error message is logged in
1282 Similarly, if the property name is mis-spelt no error message
1283 is produced, and the expected action clearly is not performed.
1284 If fact, you can set any (fictitious) @q{property} using any
1285 name you like in any context that exists by using the
1286 @code{\set} command. But if the name is not
1287 known to LilyPond it will not cause any action to be taken.
1289 The @code{instrumentName} property will take effect only
1290 if it is set in the @context{Staff} context, but
1291 some properties can be set in more than one context.
1292 For example, the property @code{extraNatural} is by
1293 default set to ##t (true) for all staves.
1294 If it is set to ##f (false) in the @context{Staff} context
1295 it applies just to the accidentals on that staff.
1296 If it is set to false in the @context{Score} context
1297 it applies to all staves.
1299 So this sets @code{extraNatural} in one staff:
1301 @lilypond[quote,verbatim,ragged-right]
1303 \new Staff \relative c'' {
1306 \new Staff \relative c'' {
1307 \set Staff.extraNatural = ##f
1314 and this sets it in all staves:
1316 @lilypond[quote,verbatim,ragged-right]
1318 \new Staff \relative c'' {
1321 \new Staff \relative c'' {
1322 \set Score.extraNatural = ##f
1328 The value of every property set in this way can be reset
1329 to its original value with the @code{\unset} command
1331 The @code{\set} and @code{\unset} commands can appear anywhere
1332 in the input file and will take effect from the time they are
1333 encountered until the end of the score or until the property is
1334 @code{\set} or @code{\unset} again. Let's try changing the
1335 font size, which affects the size of the note heads (among
1336 other things) several times.
1338 @lilypond[quote,verbatim,ragged-right,relative=1,fragment]
1340 \set fontSize = #-4 % make noteheads smaller
1342 \set fontSize = #2.5 % make noteheads larger
1344 \unset fontSize % return to original size
1348 We have now seen how to set the values of several different
1349 types of property. Note that integers and numbers are alway
1350 preceded by a hash sign, @code{#}, while a true or false value
1351 is specified by ##t and ##f, with two hash signs. A text
1352 property should be enclosed in double quotation signs, as above,
1353 although we shall see later that text can actually be specified
1354 in a much more general way by using the very powerful
1355 @code{markup} command.
1360 Context properties may also be set at the time the context is
1361 created. Sometimes this is a clearer way of specifying a
1362 property value if it is to remain fixed for the duration of
1363 the context. When a context is created with a @code{\new}
1364 command it may be immediately followed by a
1365 @code{\with @{ .. @}} block in which the property values are
1366 set. For example, if we wish to suppress the printing of
1367 extra naturals for the duration of a staff we would write:
1369 @lilypond[quote,verbatim,ragged-right]
1378 In effect this overrides the default value of the property. It
1379 may still be changed dynamically using @code{\set} and
1382 @node Adding and removing engravers
1383 @subsubsection Adding and removing engravers
1385 @cindex Engravers, adding
1386 @cindex Engravers, removing
1391 We have seen that contexts each contain several engravers, each
1392 of which is responsible for producing a particular part of the
1393 output, like barlines, staves, note heads, stems, etc. If an
1394 engraver is removed from a context it can no longer produce its
1395 output. This is a crude way of modifying the output, but it
1396 can sometimes be useful.
1398 To remove an engraver we can use the @code{\with} command placed
1399 immediately after the context creation command, as in the
1403 illustration let's repeat an example from the previous
1404 section with the staff lines removed. Remember that the
1405 staff lines are produced by the Staff_symbol_engraver.
1407 @lilypond[quote,verbatim,ragged-right]
1409 \remove Staff_symbol_engraver
1413 \set fontSize = #-4 % make noteheads smaller
1415 \set fontSize = #2.5 % make noteheads larger
1417 \unset fontSize % return to original size
1422 @cindex ambitus engraver
1424 Engravers can also be added to contexts. The command
1425 to do this is @code{\consists @emph{Engraver_name}},
1426 placed inside a @code{\with} block. Some vocal scores
1427 have an @rglos{ambitus} placed at the beginning of a
1428 staff to indicate the range of notes in that staff.
1429 The ambitus is produced by the @code{Ambitus_engraver},
1430 which is not normally included in any context. If
1431 we add it to the @context{Voice} context it calculates
1432 the range from that voice only:
1434 @lilypond[quote,verbatim,ragged-right]
1437 \consists Ambitus_engraver
1452 but if we add the Ambitus engraver to the
1453 @context{Staff} context it calculates the range from all
1454 the notes in all the voices on that staff:
1456 @lilypond[quote,verbatim,ragged-right]
1458 \consists Ambitus_engraver
1475 @node Extending the templates
1476 @section Extending the templates
1478 You've read the tutorial, you know how to write music, you
1479 understand the fundamental concepts. But how can you
1480 get the staves that you want? Well, you can find lots of
1481 templates in Appendix A which may give you a start. But what
1482 if you want something that isn't covered there? Read on.
1485 * Soprano and cello::
1486 * Four-part SATB vocal score::
1487 * Building a score from scratch::
1490 @node Soprano and cello
1491 @subsection Soprano and cello
1493 Start off with the template that seems closest to what you want to end
1494 up with. Let's say that you want to write something for soprano and
1495 cello. In this case, we would start with @q{Notes and lyrics} (for the
1500 melody = \relative c' @{
1508 text = \lyricmode @{
1514 \new Voice = "one" @{
1518 \new Lyrics \lyricsto "one" \text
1525 Now we want to add a cello part. Let's look at the @q{Notes only} example:
1529 melody = \relative c' @{
1544 We don't need two @code{\version} commands. We'll need the @code{melody}
1545 section. We don't want two @code{\score} sections -- if we had two
1546 @code{\score}s, we'd get the two parts separately. We want them together,
1547 as a duet. Within the @code{\score} section, we don't need two
1548 @code{\layout} or @code{\midi}.
1550 If we simply cut and paste the @code{melody} section, we would end up with
1551 two @code{melody} sections. So let's rename them. We'll call the section
1552 for the soprano @code{sopranoMusic} and the section for the cello
1553 @code{celloMusic}. While we're doing this, let's rename @code{text}
1554 to be @code{sopranoLyrics}. Remember to rename both instances of all
1555 these names -- both the initial definition (the
1556 @code{melody = relative c' @{ } part) and the name's use (in the
1557 @code{\score} section).
1559 While we're doing this, let's change the cello part's staff -- celli
1560 normally use bass clef. We'll also give the cello some different
1565 sopranoMusic = \relative c' @{
1573 sopranoLyrics = \lyricmode @{
1577 celloMusic = \relative c @{
1587 \new Voice = "one" @{
1591 \new Lyrics \lyricsto "one" \sopranoLyrics
1598 This is looking promising, but the cello part won't appear in the
1599 score -- we haven't used it in the @code{\score} section. If we
1600 want the cello part to appear under the soprano part, we need to add
1603 \new Staff \celloMusic
1607 underneath the soprano stuff. We also need to add @code{<<} and
1608 @code{>>} around the music -- that tells LilyPond that there's
1609 more than one thing (in this case, @code{Staff}) happening at once. The
1610 @code{\score} looks like this now
1612 @c Indentation in this example is deliberately poor
1617 \new Voice = "one" @{
1621 \new Lyrics \lyricsto "one" \sopranoLyrics
1623 \new Staff \celloMusic
1631 This looks a bit messy; the indentation is messed up now. That is
1632 easily fixed. Here's the complete soprano and cello template.
1634 @lilypond[quote,verbatim,ragged-right]
1636 sopranoMusic = \relative c' {
1644 sopranoLyrics = \lyricmode {
1648 celloMusic = \relative c {
1659 \new Voice = "one" {
1663 \new Lyrics \lyricsto "one" \sopranoLyrics
1665 \new Staff \celloMusic
1673 @node Four-part SATB vocal score
1674 @subsection Four-part SATB vocal score
1676 Most vocal scores of music written for four-part mixed choir
1677 with orchestral accompaniment such as Mendelssohn's Elijah or
1678 Handel's Messiah have the choral music and words on four
1679 staves, one for each of SATB, with a piano reduction of the
1680 orchestral accompaniment underneath. Here's an example
1681 from Handel's Messiah:
1683 @c The following should appear as music without code
1684 @lilypond[quote,ragged-right]
1686 global = { \key d \major \time 4/4 }
1687 sopMusic = \relative c'' {
1689 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
1691 sopWords = \lyricmode {
1692 Wor -- thy is the lamb that was slain
1694 altoMusic = \relative a' {
1696 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
1698 altoWords = \sopWords
1699 tenorMusic = \relative c' {
1701 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
1703 tenorWords = \sopWords
1704 bassMusic = \relative c' {
1706 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
1708 bassWords = \sopWords
1709 upper = \relative a' {
1712 r4 <a d fis>2 <a e' a>4 |
1713 <d fis d'>4. <d fis d'>8 <a d a'>2 |
1714 <g cis g'>4 <a d fis> <a cis e>2 |
1716 lower = \relative c, {
1719 <d d'>4 <d d'>2 <cis cis'>4 |
1720 <b b'>4. <b' b'>8 <fis fis'>2 |
1721 <e e'>4 <d d'> <a' a'>2 |
1725 << % combine ChoirStaff and PianoStaff in parallel
1727 \new Staff = "sopranos" <<
1728 \set Staff.instrumentName = "Soprano"
1729 \new Voice = "sopranos" { \global \sopMusic }
1731 \new Lyrics \lyricsto "sopranos" { \sopWords }
1732 \new Staff = "altos" <<
1733 \set Staff.instrumentName = "Alto"
1734 \new Voice = "altos" { \global \altoMusic }
1736 \new Lyrics \lyricsto "altos" { \altoWords }
1737 \new Staff = "tenors" <<
1738 \set Staff.instrumentName = "Tenor"
1739 \new Voice = "tenors" { \global \tenorMusic }
1741 \new Lyrics \lyricsto "tenors" { \tenorWords }
1742 \new Staff = "basses" <<
1743 \set Staff.instrumentName = "Bass"
1744 \new Voice = "basses" { \global \bassMusic }
1746 \new Lyrics \lyricsto "basses" { \bassWords }
1750 \set PianoStaff.instrumentName = "Piano "
1751 \new Staff = "upper" \upper
1752 \new Staff = "lower" \lower
1758 None of the templates provides this layout exactly. The
1759 nearest is @q{SATB vocal score and automatic piano reduction},
1760 but we shall need to change the layout and add a piano
1761 accompaniment which is not derived automatically from the
1762 vocal parts. The variables holding the music and words for
1763 the vocal parts are fine, but we shall need to add variables for
1764 the piano reduction.
1766 The order in which the contexts appear in the ChoirStaff of
1767 the template do not correspond with the order in the vocal
1768 score shown above. We need to rearrange them so there are
1769 four staves with the words written directly underneath the
1770 notes for each part.
1771 All the voices should be @code{voiceOne}, which is
1772 the default, so the @code{\voiceXXX} commands can be removed.
1773 We also need to specify the tenor clef for the tenors.
1774 The way in which lyrics are specified has also been simplified
1775 as we have not yet encountered the method used in the template.
1776 We've also added the names of each staff.
1778 Doing this gives for our ChoirStaff:
1782 \new Staff = "sopranos" <<
1783 \set Staff.instrumentName = "Soprano"
1784 \new Voice = "sopranos" @{ \global \sopMusic @}
1786 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
1787 \new Staff = "altos" <<
1788 \set Staff.instrumentName = "Alto"
1789 \new Voice = "altos" @{ \global \altoMusic @}
1791 \new Lyrics \lyricsto "altos" @{ \altoWords @}
1792 \new Staff = "tenors" <<
1793 \set Staff.instrumentName = "Tenor"
1794 \new Voice = "tenors" @{ \global \tenorMusic @}
1796 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
1797 \new Staff = "basses" <<
1798 \set Staff.instrumentName = "Bass"
1799 \new Voice = "basses" @{ \global \bassMusic @}
1801 \new Lyrics \lyricsto "basses" @{ \bassWords @}
1805 Next we must work out the piano part. This is
1806 easy - we just pull out the piano part from the
1807 @q{Solo piano} template:
1811 \set PianoStaff.instrumentName = "Piano "
1812 \new Staff = "upper" \upper
1813 \new Staff = "lower" \lower
1817 and add the variable definitions for @code{upper}
1820 The ChoirStaff and PianoStaff must be combined
1821 using angle brackets as we want them to be
1822 stacked one above the other:
1825 << % combine ChoirStaff and PianoStaff one above the other
1827 \new Staff = "sopranos" <<
1828 \new Voice = "sopranos" @{ \global \sopMusic @}
1830 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
1831 \new Staff = "altos" <<
1832 \new Voice = "altos" @{ \global \altoMusic @}
1834 \new Lyrics \lyricsto "altos" @{ \altoWords @}
1835 \new Staff = "tenors" <<
1836 \clef "G_8" % tenor clef
1837 \new Voice = "tenors" @{ \global \tenorMusic @}
1839 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
1840 \new Staff = "basses" <<
1842 \new Voice = "basses" @{ \global \bassMusic @}
1844 \new Lyrics \lyricsto "basses" @{ bassWords @}
1848 \set PianoStaff.instrumentName = "Piano "
1849 \new Staff = "upper" \upper
1850 \new Staff = "lower" \lower
1855 Combining all these together and adding the music
1856 for the three bars of the example above gives:
1858 @lilypond[quote,verbatim,ragged-right]
1860 global = { \key d \major \time 4/4 }
1861 sopMusic = \relative c'' {
1863 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
1865 sopWords = \lyricmode {
1866 Wor -- thy is the lamb that was slain
1868 altoMusic = \relative a' {
1870 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
1872 altoWords = \sopWords
1873 tenorMusic = \relative c' {
1875 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
1877 tenorWords = \sopWords
1878 bassMusic = \relative c' {
1880 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
1882 bassWords = \sopWords
1883 upper = \relative a' {
1886 r4 <a d fis>2 <a e' a>4 |
1887 <d fis d'>4. <d fis d'>8 <a d a'>2 |
1888 <g cis g'>4 <a d fis> <a cis e>2 |
1890 lower = \relative c, {
1893 <d d'>4 <d d'>2 <cis cis'>4 |
1894 <b b'>4. <b' b'>8 <fis fis'>2 |
1895 <e e'>4 <d d'> <a' a'>2 |
1899 << % combine ChoirStaff and PianoStaff in parallel
1901 \new Staff = "sopranos" <<
1902 \set Staff.instrumentName = "Soprano"
1903 \new Voice = "sopranos" { \global \sopMusic }
1905 \new Lyrics \lyricsto "sopranos" { \sopWords }
1906 \new Staff = "altos" <<
1907 \set Staff.instrumentName = "Alto"
1908 \new Voice = "altos" { \global \altoMusic }
1910 \new Lyrics \lyricsto "altos" { \altoWords }
1911 \new Staff = "tenors" <<
1912 \set Staff.instrumentName = "Tenor"
1913 \new Voice = "tenors" { \global \tenorMusic }
1915 \new Lyrics \lyricsto "tenors" { \tenorWords }
1916 \new Staff = "basses" <<
1917 \set Staff.instrumentName = "Bass"
1918 \new Voice = "basses" { \global \bassMusic }
1920 \new Lyrics \lyricsto "basses" { \bassWords }
1924 \set PianoStaff.instrumentName = "Piano "
1925 \new Staff = "upper" \upper
1926 \new Staff = "lower" \lower
1933 @node Building a score from scratch
1934 @subsection Building a score from scratch
1936 After gaining some facility with writing LilyPond code you
1937 may find that it is easier to build a score from scratch
1938 rather than modifying one of the templates. You can also
1939 develop your own style this way to suit the sort of music you
1940 like. Let's see how to put together the score for an organ
1941 prelude as an example.
1943 We begin with a header section. Here go the title, name
1944 of composer, etc followed by the variable definitions
1945 and ending with the score block. Let's start with these and
1946 fill in the details later.
1948 We'll use the first two bars of Bach's prelude
1949 based on @emph{Jesu, meine Freude} which is set in two
1950 manuals and pedal organ. The top manual has two voices,
1951 the lower and pedal organ one each. So we need four
1952 music definitions and one to define the time signature
1958 title = "Jesu, meine Freude"
1959 composer = "J S Bach"
1961 TimeKey = @{ \time 4/4 \key c \minor @}
1962 ManualOneVoiceOneMusic = @{s1@}
1963 ManualOneVoiceTwoMusic = @{s1@}
1964 ManualTwoMusic = @{s1@}
1965 PedalOrganMusic = @{s1@}
1971 For now we've just used a spacer note, @code{s1},
1972 instead of the real music. We'll add that later.
1974 Next let's see what should go in the score block.
1975 We simply mirror the staff structure we want.
1976 Organ music is usually written on three staves,
1977 one for each manual and one for the pedals. The
1978 manual staves should be bracketed together so we
1979 need to use a PianoStaff for them. The first
1980 manual part needs two voices and the second manual
1985 \new Staff = "ManualOne" <<
1986 \new Voice @{ \ManualOneVoiceOneMusic @}
1987 \new Voice @{ \ManualOneVoiceTwoMusic @}
1988 >> % end ManualOne Staff context
1989 \new Staff = "ManualTwo" <<
1990 \new Voice @{ \ManualTwoMusic @}
1991 >> % end ManualTwo Staff context
1992 >> % end PianoStaff context
1995 Next we need to add a staff for the pedal organ.
1996 This goes underneath the PianoStaff, but it must
1997 be simultaneous with it, so we need angle brackets
1998 round the two. Missing these out would generate
1999 an error in the log file. It's a common mistake
2000 which you'll make sooner or later! Try copying
2001 the final example at the end of this section,
2002 remove these angle brackets, and compile it to
2003 see what errors it generates.
2006 << % PianoStaff and Pedal Staff must be simultaneous
2008 \new Staff = "ManualOne" <<
2009 \new Voice @{ \ManualOneVoiceOneMusic @}
2010 \new Voice @{ \ManualOneVoiceTwoMusic @}
2011 >> % end ManualOne Staff context
2012 \new Staff = "ManualTwo" <<
2013 \new Voice @{ \ManualTwoMusic @}
2014 >> % end ManualTwo Staff context
2015 >> % end PianoStaff context
2016 \new Staff = "PedalOrgan" <<
2017 \new Voice @{ \PedalOrganMusic @}
2022 It is not strictly necessary to use the simultaneous contruct
2023 @code{<< >>} for the manual two staff and the pedal organ staff,
2024 since they contain only one music expression, but it does no harm
2025 and always using angle brackets after @code{\new Staff} is a good
2026 habit to cultivate in case there are multiple voices.
2028 Let's add this structure to the score block, and adjust the
2029 indenting. We also add the appropriate clefs, ensure the
2030 second voice stems point down with @code{\voiceTwo} and
2031 enter the time signature and key to each staff using our
2032 predefined variable, @code{\TimeKey}.
2036 << % PianoStaff and Pedal Staff must be simultaneous
2038 \new Staff = "ManualOne" <<
2039 \TimeKey % set time signature and key
2041 \new Voice @{ \ManualOneVoiceOneMusic @}
2042 \new Voice @{ \voiceTwo \ManualOneVoiceTwoMusic @}
2043 >> % end ManualOne Staff context
2044 \new Staff = "ManualTwo" <<
2047 \new Voice @{ \ManualTwoMusic @}
2048 >> % end ManualTwo Staff context
2049 >> % end PianoStaff context
2050 \new Staff = "PedalOrgan" <<
2053 \new Voice @{ \PedalOrganMusic @}
2054 >> % end PedalOrgan Staff
2056 @} % end Score context
2059 That completes the structure. Any three-staff organ music
2060 will have a similar structure, although the number of voices
2061 may vary. All that remains now
2062 is to add the music, and combine all the parts together.
2064 @lilypond[quote,verbatim,ragged-right]
2067 title = "Jesu, meine Freude"
2068 composer = "J S Bach"
2070 TimeKey = { \time 4/4 \key c \minor }
2071 ManualOneVoiceOneMusic = \relative g' {
2072 g4 g f ees | d2 c2 |
2074 ManualOneVoiceTwoMusic = \relative c' {
2075 ees16 d ees8~ ees16 f ees s c8 d~ d c~ |
2076 c c4 b8 c8. g16 c b c d |
2078 ManualTwoMusic = \relative c' {
2079 c16 b c8~ c16 b c g a8 g~ g16 g aes ees |
2080 f ees f d g aes g f ees d e8~ ees16 f ees d |
2082 PedalOrganMusic = \relative c {
2083 r8 c16 d ees d ees8~ ees16 a, b g c b c8 |
2084 r16 g ees f g f g8 c,2 |
2088 << % PianoStaff and Pedal Staff must be simultaneous
2090 \new Staff = "ManualOne" <<
2091 \TimeKey % set time signature and key
2093 \new Voice { \ManualOneVoiceOneMusic }
2094 \new Voice { \voiceTwo \ManualOneVoiceTwoMusic }
2095 >> % end ManualOne Staff context
2096 \new Staff = "ManualTwo" <<
2099 \new Voice { \ManualTwoMusic }
2100 >> % end ManualTwo Staff context
2101 >> % end PianoStaff context
2102 \new Staff = "PedalOrgan" <<
2105 \new Voice { \PedalOrganMusic }
2106 >> % end PedalOrgan Staff
2108 } % end Score context