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@{@}}.
79 A @code{\score} must begin with a compound music expression.
80 Remember that a music expression could be anything from a single
86 @var{...insert the whole score of a Wagner opera in here...}
92 Since everything is inside @code{@{ ... @}}, it counts
93 as one music expression.
95 As we saw previously, the @code{\score} can contain other things,
108 Some people put some of those commands outside the @code{\score}
109 block -- for example, @code{\header} is often placed above the
110 @code{\score}. That's just another shorthand that LilyPond
111 accepts. Two more commands you have not previously seen are
112 @code{\layout @{ @}} and @code{\midi @{@}}. If these appear as
113 shown they will cause LilyPond to produce a printed output and a
114 MIDI out respectively. They are described fully in the
115 Notation Reference - @ruser{Score layout} and
116 @ruser{Creating MIDI files}.
120 Another great shorthand is the ability to define variables. All
121 the templates use this
124 melody = \relative c' @{
133 When LilyPond looks at this file, it takes the value of
134 @code{melody} (everything after the equals sign) and inserts it
135 whenever it sees @code{\melody}. There's nothing special about
136 the names -- it could be @code{melody}, @code{global},
137 @code{pianorighthand}, or @code{foofoobarbaz}. You can use
138 whatever variable names you want as along as they contain just
139 alphabetic characters. For more details, see
140 @ruser{Saving typing with variables and functions}.
145 For a complete definition of the input format, see
146 @ruser{File structure}.
148 @node Score is a (single) compound musical expression
149 @subsection Score is a (single) compound musical expression
151 @cindex Compound music expression
152 @cindex Music expression, compound
154 We saw the general organization of LilyPond input files in the
155 previous section, @ref{How LilyPond files work}. But we seemed to
156 skip over the most important part: how do we figure out what to
157 write after @code{\score}?
159 We didn't skip over it at all. The big mystery is simply that
160 there @emph{is} no mystery. This line explains it all:
163 @emph{A @code{\score} must begin with a compound music expression.}
167 You may find it useful to review
168 @ref{Music expressions explained}. In that section, we saw how to
169 build big music expressions from small pieces -- we started from
170 notes, then chords, etc. Now we're going to start from a big
171 music expression and work our way down.
175 @{ % this brace begins the overall compound music expression
177 @var{...insert the whole score of a Wagner opera in here...}
179 @} % this brace ends the overall compound music expression
184 A whole Wagner opera would easily double the length of this
185 manual, so let's just add a singer and piano. We don't need a
186 @code{GrandStaff} for this ensemble, which simply groups a number
187 of staves together with a brace at the left, so we shall remove
188 it. We @emph{do} need a singer and a piano, though.
194 \new Staff = "singer" <<
196 \new PianoStaff = piano <<
204 Remember that we use @code{<<} and @code{>>} to show simultaneous
205 music. And we definitely want to show the vocal part and piano
206 part at the same time, not one after the other! However, the
207 @code{<< .. >>} construct is not really necessary for the Singer
208 staff, as it contains only one music expression, but Staves often
209 do require simultaneous Voices within them, so using @code{<< .. >>}
210 rather than braces is a good habit to adopt.
216 \new Staff = "singer" <<
217 \new Voice = "vocal" @{ @}
220 \new PianoStaff = "piano" <<
221 \new Staff = "upper" @{ @}
222 \new Staff = "lower" @{ @}
230 Now we have a lot more details. We have the singer's staff: it
231 contains a @code{Voice} (in LilyPond, this term refers to a set of
232 notes, not necessarily vocal notes -- for example, a violin
233 generally plays one voice) and some lyrics. We also have a piano
234 staff: it contains an upper staff (right hand) and a lower staff
237 At this stage, we could start filling in notes. Inside the curly
238 braces next to @code{\new Voice = vocal}, we could start writing
246 But if we did that, the @code{\score} section would get pretty
247 long, and it would be harder to understand what was happening. So
248 let's use variables instead.
251 melody = \relative c'' @{ @}
252 text = \lyricmode @{ @}
253 upper = \relative c'' @{ @}
254 lower = \relative c @{ @}
258 \new Staff = "singer" <<
259 \new Voice = "vocal" @{ \melody @}
260 \addlyrics @{ \text @}
262 \new PianoStaff = "piano" <<
263 \new Staff = "upper" @{ \upper @}
264 \new Staff = "lower" @{ \lower @}
273 Remember that you can use almost any name you like as long
274 as it contains just alphabetic characters. The exact
275 limitations on variable names are detailed in
276 @ruser{File structure}.
278 Be careful about the difference between notes, which are introduced
279 with @code{\relative}, and lyrics, which are introduced with
280 @code{\lyricmode}. These are essential to tell LilyPond
281 to interpret the following content as music and text
284 When writing (or reading) a @code{\score} section, just take it
285 slowly and carefully. Start with the outer layer, then work on
286 each smaller layer. It also really helps to be strict with
287 indentation -- make sure that each item on the same layer starts
288 on the same horizontal position in your text editor.
291 @node Nesting Music Expressions
292 @subsection Nesting Music Expressions
294 It is not essential to declare all staves at the beginning;
295 they may be introduced temporarily at any point. This is
296 particularly useful for creating ossia sections
297 (see @rglos{ossia}). Here is a simple example showing how
298 to introduce a new staff temporarily for the duration of
301 @lilypond[verbatim,quote,ragged-right]
317 The ossia section may be placed above the staff
320 @lilypond[verbatim,quote,ragged-right]
328 alignAboveContext = "main" }
336 This example uses @code{\with}, which will be explained more
337 fully later. It is a means of modifying the default behaviour
338 of a Staff. Here it says that the new staff should be placed
339 above the staff called @qq{main} instead of the default position
342 Ossia are often written without clef and without
343 time signature and are usually in a smaller font.
344 These require further commands which
345 have not yet been introduced. See ...
347 TODO Add ref to tweaks section where this example should
348 be placed and explained.
350 @node On the un-nestedness of brackets and ties
351 @subsection On the un-nestedness of brackets and ties
353 You have already met a number of different types of bracket in
354 writing the input file to LilyPond. These obey different rules
355 which can be confusing at first. Before we explain the rules
356 let's first review the different types of bracket.
358 @c attempt to force this onto a new page
360 @multitable @columnfractions .3 .7
361 @headitem Bracket Type
363 @item @code{@{ .. @}}
364 @tab Encloses a sequential segment of music
366 @tab Encloses the notes of a chord
367 @item @code{<< .. >>}
368 @tab Encloses concurrent or simultaneous sections
370 @tab Marks the start and end of a slur
371 @item @code{\( .. \)}
372 @tab Marks the start and end of a phrase mark
374 @tab Marks the start and end of a manual beam
377 To these we should add other constructs which generate lines
378 between or across notes: ties (marked by a tilde, @code{~}),
379 tuplets written as @code{\times x/y @{..@}}, and grace notes
380 written as @code{\grace@{..@}}.
382 Outside LilyPond, the conventional use of brackets requires
383 the different types to be properly nested, like this,
384 @code{<< [ @{ ( .. ) @} ] >>}, with the closing brackets being
385 encountered in exactly the opposite order to the opening
386 brackets. This @strong{is} a requirement for the three types of
387 bracket described by the word @q{Encloses} in the table above -
388 they must nest properly.
389 However, the remaining brackets, described with the word
390 @q{Marks} in the table above together with ties and tuplets,
391 do @strong{not} have to nest
392 properly with any of the brackets. In fact, these are not
393 brackets in the sense that
394 they enclose something - they are simply markers to indicate
395 where something starts and ends.
397 So, for example, a phrasing slur can start before a manually
398 inserted beam and end before the end of the beam - not very
399 musical, perhaps, but possible:
401 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
402 { g8\( a b[ c b\) a] }
405 In general, different kinds of brackets, and those implied by
406 tuplets, ties and grace notes, may be mixed freely.
407 This example shows a beam extending into a tuplet (line 1),
408 a slur extending into a tuplet (line 2),
409 a beam and a slur extending into a tuplet, a tie crossing
410 two tuplets, and a phrasing slur extending out of a tuplet
413 @lilypond[quote,verbatim,fragment,ragged-right]
415 r16[ g16 \times 2/3 {r16 e'8] }
416 g16( a \times 2/3 {b d) e' }
417 g8[( a \times 2/3 {b d') e'~]}
418 \times 4/5 {e'32\( a b d' e'} a'4.\)
423 @node Voices contain music
424 @section Voices contain music
426 Singers need voices to sing, and so does LilyPond.
427 The actual music for all instruments in a score
428 is contained in Voices - the most fundamental
429 of all LilyPond's concepts.
432 * I'm hearing Voices::
433 * Explicitly instantiating voices::
434 * Voices and vocals::
437 @node I'm hearing Voices
438 @subsection I'm hearing Voices
442 @cindex Voice context
444 The lowest, most fundamental or innermost layers in a LilyPond
445 score are called @q{Voice contexts} or just @q{Voices} for short.
446 Voices are sometimes called @q{layers} in other notation
449 In fact, a Voice layer or context is the only one which can
450 contain music. If a Voice context is not explicitly declared
451 one is created automatically. Some instruments such as an
452 Oboe can play only one note at a time. Music written for
453 such instruments is monophonic and requires just a single
454 voice. Instruments which can play more than one note at a
455 time like the piano will often require multiple voices to
456 encode the different concurrent notes and rhythms they are
459 A single voice can contain many notes in a chord, of course,
460 so when exactly are multiple voices needed?
461 Let us analyse a short piece of music to see how many voices
462 are required. Here are the notes from the first two bars
463 of the second of Chopin's Deux Nocturnes, Op 32.
465 @c The following should appear as music without code
466 @lilypond[quote,ragged-right]
467 \new Staff \relative c'' {
475 \once \override NoteColumn #'force-hshift = #0 <ees c>2
476 \once \override NoteColumn #'force-hshift = #0.5 des2 }
482 The direction of the stems is often used to indicate the
483 continuity of two simultaneous melodic lines. Here the
484 stems of the highest notes are all pointing up and the
485 stems of the lower notes are all pointing down.
486 This is the first indication that more than one voice
489 But the real need for multiple voices arises when notes
490 which start at the same time have different durations.
491 Look at the notes which start at beat three in the first
492 bar. The a-flat is a dotted quarter note, the f is a
493 quarter note and the d-flat is a half note. These
494 cannot be written as a chord as all the notes in a chord
495 must have the same duration. Neither can they be written
496 as sequential notes, as they must start at the same time.
497 This section of the bar requires three voices, and the
498 normal practice would be to write the whole bar as three
499 voices, as shown here, where we have used different noteheads
500 and colors for the three voices.
502 @c The following should appear as music without code
503 @c The three voice styles should be defined in -init
504 @lilypond[quote,ragged-right]
505 \new Staff \relative c'' {
516 \once \override NoteColumn #'force-hshift = #0 <ees c>2
517 \once \override NoteColumn #'force-hshift = #0.5 des2 }
523 Let us see how this is done.
527 The easiest way to enter fragments with more than one voice on a
528 staff is to enter each voice as a sequence (with @code{@{...@}}),
529 and combine them simultaneously with angle brackets, @code{<<...>>}.
530 The fragments must also be separated with double backward slashes,
531 @code{\\}, to place them in separate voices. Without these, the
532 notes would be entered into a single voice, which would usually
533 cause errors. This technique is particularly suited to pieces of
534 music which are largely monophonic with occasional short sections
535 of polyphony. Here's a simple example:
537 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
539 % Voice "1" Voice "2"
540 << { r4 g g4. a8 } \\ { d,2 d4 g } >> |
541 << { bes4 bes c bes } \\ { g4 g g8( a) g4 } >> |
542 << { a2. r4 } \\ { fis2. s4 } >>
545 This example has just two voices, but the same contruct may be
546 used to encode three or more voices by adding more back-slash
549 The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
550 In each of these contexts, the vertical direction of slurs,
551 stems, ties, dynamics etc., is set appropriately.
553 @lilypond[quote,verbatim,fragment]
554 \new Staff \relative c' {
557 % Voice "1" Voice "2" Voice "3"
558 << { g4 f e } \\ { r8 e4 d c8 ~ } >> |
559 << { d2 e2 } \\ { c8 b16 a b8 g ~ g2 } \\ { s4 b4 c2 } >> |
563 These voices are all separate from the main voice that contains
564 the notes just outside the @code{<< .. >>} construct. Let's call
565 this the @emph{simultaneous construct}. Slurs and ties may only
566 connect notes within the same voice, so slurs and ties cannot go
567 into or out of a simultaneous construct. Conversely,
568 parallel voices from separate simultaneous constructs on the same
569 staff are the same voice. Other voice-related properties also
570 carry across simultaneous constructs. Here is the same example,
571 with different colors and noteheads for each voice. Note that
572 changes in one Voice do not affect other voices, but they do
573 persist in the same Voice later. Note also that tied notes may be
574 split across the same voices in two constructs, shown here in the
577 @lilypond[quote,verbatim]
578 \new Staff \relative c' {
588 { c8 b16 a b8 g ~ g2 } \\
595 The commands @code{\voiceXXXStyle} are mainly intended for use in
596 educational documents such as this one. They modify the color
597 of the notehead, the stem and the beams, and the style of the
598 notehead, so that the voices may be easily distinguished.
599 Voice one is set to red diamonds, voice two to blue triangles,
600 voice three to green crossed circles, and voice four (not used
601 here) to magenta crosses. We shall see later how commands like
602 these may be created by the user.
603 TODO: add ref to appropriate section in Tweaks
605 Polyphony does not change the relationship of notes within a
606 @code{\relative @{ @}} block. Each note is still calculated
607 relative to the note immediately preceding it, or to the first
608 note of the preceding chord. So in
611 \relative c' @{ noteA << < noteB noteC > \\ noteD >> noteE @}
615 @code{noteB} is relative to @code{noteA} @*
616 @code{noteC} is relative to @code{noteB}, not @code{noteA}; @*
617 @code{noteD} is relative to @code{noteB}, not @code{noteA} or
619 @code{noteE} is relative to @code{noteD}, not @code{noteA}
621 We are now in a position to return to the first example from
622 the Chopin Nocturne to see how this might be encoded. As we
623 shall see, this encounters some difficulties. We begin as
624 we have learnt, using the @code{<< \\ >>} construct to
625 enter the music of the first bar in three voices:
627 @lilypond[quote,verbatim,fragment,ragged-right]
628 \new Staff \relative c'' {
631 { c2 aes4. bes8 } \\ { aes2 f4 fes } \\ { <ees c>2 des2 }
641 @funindex \voiceThree
644 The stem directions are automatically assigned with the
645 odd-numbered voices taking upward stems and the even-numbered
646 voices downward ones. The stems for voices 1 and 2 are right,
647 but the stems in voice 3 should go down in this particular piece
648 of music. We can correct this
649 by telling LilyPond that this third voice is really a fourth
650 voice, with stems going down, using the @code{\voiceFour}
651 command. There are also corresponding @code{\voiceOne},
652 @code{\voiceTwo}, and @code{voiceThree}
653 commands. This results in the following:
655 @lilypond[quote,verbatim,fragment,ragged-right]
656 \new Staff \relative c'' {
661 { \voiceFour <ees c>2 des2 }
668 and exposes a problem commonly encountered with multiple
669 voices: the stems of notes can collide with noteheads
670 in other voices. In laying out the notes, LilyPond allows the
671 notes or chords from two voices to occupy the same vertical
672 note column provided the stems are in opposite directions, but
673 the notes from a third voice are displaced to avoid the stems
674 colliding. This often works well, but in this example the
675 notes of the third voice are clearly not well placed by default.
676 LilyPond provides several ways to adjust the horizontal placing
677 of notes. We are not quite ready yet to see how to correct this,
678 so we shall leave this problem until a later section (see ... )
682 @node Explicitly instantiating voices
683 @subsection Explicitly instantiating voices
685 Voice contexts can also be created manually
686 inside a @code{<< >>} block to create polyphonic music, using
687 @code{\voiceOne} ... @code{\voiceFour} to indicate the required
688 directions of stems, slurs, etc.
690 Specifically, the construct @code{<< \\ >>} which we used in
691 the previous section:
694 << \upper \\ \lower >>
698 where @code{upper} and @code{lower} are user-defined variables
699 containing the music for the two voices, is equivalent to
703 \new Voice = "1" @{ \voiceOne \upper @}
704 \new Voice = "2" @{ \voiceTwo \lower @}
708 The @code{\voiceXXX} commands set the direction of stems, slurs,
709 ties, articulations, text annotations, augmentation dots of dotted
710 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
711 make these objects point upwards, while @code{\voiceTwo} and
712 @code{\voiceFour} make them point downwards. These commands also
713 generate a horizontal shift for each voice when this is required
714 to avoid clashes of note heads. The command @code{\oneVoice}
715 reverts the settings back to the normal values for a single voice.
717 Let us see in some simple examples exactly what effect
718 @code{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on
719 markup, ties, slurs, and dynamics:
721 @lilypond[quote,ragged-right,verbatim]
723 c-"default" d8 ~ d e4 ( f g a ) b-> c
727 @lilypond[quote,ragged-right,verbatim]
730 c-"\\voiceOne" d8 ~ d e4 ( f g a ) b-> c
732 c,-"\\oneVoice" d8 ~ d e4 ( f g a ) b-> c
736 @lilypond[quote,ragged-right,verbatim]
739 c-"\\voiceTwo" d8 ~ d e4 ( f g a ) b-> c
741 c,-"\\oneVoice" d8 ~ d e4 ( f g a ) b-> c
745 An expression that appears directly inside a @code{<< >>} belongs
746 to the main voice (but, note, @strong{not} in a @code{<< \\ >>}
747 construct). This is useful when extra voices appear while the
748 main voice is playing. Here is a more correct rendition of the
749 example from the previous section. The red diamond-shaped notes
750 demonstrate that the main melody is now in a single voice context,
751 permitting a phrasing slur to be drawn over them.
753 @lilypond[quote,ragged-right,verbatim]
754 \new Staff \relative c' {
756 c16^( d e f % These notes are monophonic
757 << % Start simultaneous section of three voices
758 { g4 f e | d2 e2) } % Continue the main voice in parallel
759 \new Voice { % Initiate second voice
760 \voiceTwo % Set stems, etc, down
761 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
763 \new Voice { % Initiate third voice
764 \voiceThree % Set stems, etc, up
771 @cindex nesting music expressions
772 @cindex nesting simultaneous constructs
774 More deeply nested polyphony constructs are possible, and if a
775 voice appears only briefly this might be a more natural way to
778 @lilypond[quote,ragged-right,verbatim]
779 \new Staff \relative c' {
799 This method of nesting new voices briefly is useful
800 when only small sections of the music
801 are polyphonic, but when the whole staff is largely polyphonic
802 it can be clearer to use multiple voices throughout, using
803 spacing notes to step over sections where the voice is silent,
806 @lilypond[quote,ragged-right,verbatim]
807 \new Staff \relative c' <<
808 \new Voice { % Initiate first voice
810 c16^( d e f g4 f e | d2 e2) |
812 \new Voice { % Initiate second voice
813 \voiceTwo % set stems, etc down
814 s4 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 |
816 \new Voice { % Initiate third voice
817 \voiceThree % set stems, etc up
824 @node Voices and vocals
825 @subsection Voices and vocals
827 Vocal music presents a special difficulty: we need to combine two
828 expressions -- notes and lyrics.
830 You have already seen the @code{\addlyrics@{@}} command, which
831 handles simple scores well. However, this technique is
832 quite limited. For more complex music, you must introduce the
833 lyrics in a @code{Lyrics} context using @code{\new Lyrics} and
835 the lyrics to the notes with @code{\lyricsto@{@}}, using the
836 name assigned to the Voice.
838 @lilypond[quote,verbatim,fragment]
840 \new Voice = "one" \relative c'' {
843 c4 b8. a16 g4. f8 e4 d c2
845 \new Lyrics \lyricsto "one" {
846 No more let sins and sor -- rows grow.
851 The automatic beaming which LilyPond uses by default works well
852 for instrumental music, but not so well for music with lyrics,
853 where beaming is either not required at all or is used to indicate
854 melismata in the lyrics. In the example above we use the command
855 @code{\autoBeamOff} to turn off the automatic beaming.
857 Let us reuse the earlier example from Judas Maccabæus to
858 illustrate this more flexible technique. We first recast
859 it to use variables so the music and lyrics can be separated
860 from the staff structure. We also introduce a ChoirStaff
861 bracket. The lyrics themselves must be introduced with
862 @code{\lyricmode} to ensure they are interpreted as lyrics
865 @lilypond[quote,verbatim]
866 global = { \time 6/8 \partial 8 \key f \major}
867 SopOneMusic = \relative c'' {
868 c8 | c([ bes)] a a([ g)] f | f'4. b, | c4.~ c4 }
869 SopTwoMusic = \relative c' {
870 r8 | r4. r4 c8 | a'([ g)] f f([ e)] d | e([ d)] c bes' }
871 SopOneLyrics = \lyricmode {
872 Let | flee -- cy flocks the | hills a -- dorn, __ }
873 SopTwoLyrics = \lyricmode {
874 Let | flee -- cy flocks the | hills a -- dorn, }
879 \new Voice = "SopOne" {
883 \new Lyrics \lyricsto "SopOne" {
888 \new Voice = "SopTwo" {
891 \new Lyrics \lyricsto "SopTwo" {
899 This is the basic structure of all vocal scores. More staves may
900 be added as required, more voices may be added to the staves,
901 more verses may be added to the lyrics,
902 and the variables containing the music can easily be placed
903 in separate files should they become too long.
905 Here is a final example of the first line of a hymn with four
906 verses, set for SATB. In this case the words for all four
909 @lilypond[quote,verbatim]
910 global = { \time 4/4 \partial 4 \key c \major}
911 SopMusic = \relative c' { c4 | e4. e8 g4 g | a a g }
912 AltoMusic = \relative c' { c4 | c4. c8 e4 e | f f e }
913 TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 }
914 BassMusic = \relative c { c4 | c4. c8 c4 c | f8 g a b c4 }
915 VerseOne = \lyricmode {
916 E -- | ter -- nal fa -- ther, | strong to save, }
917 VerseTwo = \lyricmode {
918 O | Christ, whose voice the | wa -- ters heard, }
919 VerseThree = \lyricmode {
920 O | Ho -- ly Spi -- rit, | who didst brood }
921 VerseFour = \lyricmode {
922 O | Tri -- ni -- ty of | love and pow'r }
928 \new Voice = "Sop" { \voiceOne \global \SopMusic }
929 \new Voice = "Alto" { \voiceTwo \AltoMusic }
930 \new Lyrics \lyricsto "Sop" { \VerseOne }
931 \new Lyrics \lyricsto "Sop" { \VerseTwo }
932 \new Lyrics \lyricsto "Sop" { \VerseThree }
933 \new Lyrics \lyricsto "Sop" { \VerseFour }
937 \new Voice = "Tenor" { \voiceOne \TenorMusic }
938 \new Voice = "Bass" { \voiceTwo \BassMusic }
944 @node Contexts and engravers
945 @section Contexts and engravers
947 Contexts and engravers have been mentioned informally
948 in earlier sections; we now must look at
949 these concepts in more detail, as they are important
950 in the fine-tuning of LilyPond output.
954 * Contexts explained::
955 * Creating contexts::
956 * Engravers explained::
957 * Modifying context properties::
958 * Adding and removing engravers::
961 @node Contexts explained
962 @subsection Contexts explained
964 When music is printed, many notational elements which do not
965 appear explicitly in the input file must be added to the
966 output. For example, compare the input and output of the
969 @lilypond[quote,verbatim,relative=2,fragment]
973 The input is rather sparse, but in the output, bar lines,
974 accidentals, clef, and time signature have been added. When
975 LilyPond @emph{interprets} the input the musical information
976 is inspected in time order, similar to reading a score from left
977 to right. While reading the input, the program remembers where
978 measure boundaries are, and which pitches require explicit
979 accidentals. This information must be held on several levels.
980 For example, the effect of an accidental is limited
981 to a single staff, while a bar line must be synchronized across
984 Within LilyPond, these rules and bits of information are grouped
985 in @emph{Contexts}. We have already met the
986 @context{Voice} context.
987 Others are the @context{Staff} and @context{Score} contexts.
988 Contexts are hierarchical to reflect the heirarchical nature of
990 For example: a @context{Staff} context can contain many
991 @context{Voice} contexts, and a @context{Score} context can
992 contain many @context{Staff} contexts.
995 @image{context-example,5cm,,}
998 Each context has the responsibility for enforcing some notation rules,
999 creating some notation objects and maintaining the associated
1000 properties. For example, the @context{Voice} context may introduce an
1001 accidental and then the @context{Staff} context maintains the rule to
1002 show or suppress the accidental for the remainder of the measure.
1004 As another example, the synchronization of bar lines is, by default,
1005 handled in the @context{Score} context.
1006 However, in some music we may not want the bar lines to be
1007 synchronized -- consider a polymetric score in 4/4 and 3/4 time.
1008 In such cases, we must modify the default settings of the
1009 @context{Score} and @context{Staff} contexts.
1011 For very simple scores, contexts are created implicitly, and you need
1012 not be aware of them. For larger pieces, such as anything with more
1013 than one staff, they must be
1014 created explicitly to make sure that you get as many staves as you
1015 need, and that they are in the correct order. For typesetting pieces
1016 with specialized notation, it is usual to modify existing, or
1017 even to define totally new, contexts.
1019 In addition to the @context{Score,} @context{Staff} and
1020 @context{Voice} contexts there are contexts which fit between
1021 the score and staff levels to control staff groups, such as the
1022 @context{PianoStaff} and @context{ChoirStaff} contexts. There
1023 are also alternative staff and voice contexts, and contexts for
1024 lyrics, percussion, fret boards, figured bass, etc. A complete
1025 list is shown in the Notation Reference.
1028 The names of all context types are formed from one or more
1029 words, each word being capitalised and joined immediately to the
1030 preceding word with no hyphen or underscore, e.g.,
1031 @context{GregorianTranscriptionStaff}.
1033 @node Creating contexts
1034 @subsection Creating contexts
1036 There can be only one top level context: the
1038 context. This is created with the @code{\score} command,
1039 or, in simple scores, it is created automatically.
1041 For scores with only one voice and one staff, the
1042 @context{Voice} and @context{Staff} contexts may be left to be
1043 created automatically, but for more complex scores it is
1044 necessary to create them by hand.
1045 The simplest command that does this is @code{\new}.
1046 It is prepended to a music expression, for example
1049 @cindex new contexts
1050 @cindex Context, creating
1053 \new @var{type} @var{music expression}
1057 where @var{type} is a context name (like @code{Staff} or
1058 @code{Voice}). This command creates a new context, and starts
1059 interpreting the @var{music expression} within that context.
1061 Note that there is no @code{\new Score % Invalid!} command;
1062 the single top-level @context{Score} context is introduced
1063 with @code{\score}. This is because there can be only one
1064 @context{Score} context, whereas there may be multiple
1065 @context{Staff} and @context{Voice} contexts - each created
1068 The @code{\new} command may also give a identifying name to the
1069 context to distinguish it from other contexts of the same type,
1072 \new @var{type} = @var{id} @var{music}
1075 Note the distinction between the name of the context type,
1076 @context{Staff}, @context{Voice}, etc, and
1077 the identifying name of a particular instance of that type,
1078 which can be any sequence of letters invented by the user.
1079 The identifying name is used to refer back to that particular
1080 instance of a context. We saw this in use in the section on
1081 lyrics in @ref{Voices and vocals}.
1084 @node Engravers explained
1085 @subsection Engravers explained
1089 Every mark on the printed output of a score produced by LilyPond
1090 is produced by an @code{Engraver}. Thus there is an engraver
1091 to print staves, one to print noteheads, one for stems, one for
1092 beams, etc, etc. In total there are over 120 such engravers!
1093 Fortunately, for most scores it is not necessary to know about
1094 more than a few, and for simple scores you do not need to know
1097 Engravers live and operate in Contexts.
1098 Engravers such as the @code{Metronome_mark_engraver}, whose
1099 action and output applies to the score as a whole, operate in
1100 the highest level context - the @context{Score} context.
1102 The @code{Clef_engraver} and @code{Key_engraver} are to be
1103 found in every Staff Context, as different staves may require
1104 different clefs and keys.
1106 The @code{Note_heads_engraver} and @code{Stem_engraver} live
1107 in each @context{Voice} context, the lowest level context of all.
1109 Each engraver processes the particular objects associated
1110 with its function, and maintains the properties that relate
1111 to that function. These properties, like the properties
1112 associated with contexts, may be modified to change the
1113 operation of the engraver or the appearance of those elements
1114 in the printed score.
1116 Engravers all have compound names formed from words which
1117 describe their function. Just the first word is capitalised,
1118 and the remainder are joined to it with underscores. Thus
1119 the @code{Staff_symbol_engraver} is responsible for creating the
1120 lines of the staff, the @code{Clef_engraver} determines and sets
1121 the pitch reference point on the staff by drawing a clef symbol.
1123 Here are some of the most common engravers together with their
1124 function. You will see it is easy to guess the function from
1125 the name, or vice versa.
1127 @multitable @columnfractions .3 .7
1130 @item Accidental_engraver
1131 @tab Makes accidentals, cautionary and suggested accidentals
1136 @item Dynamic_engraver
1137 @tab Creates hairpins and dynamic texts
1139 @tab Creates the key signature
1140 @item Metronome_mark_engraver
1141 @tab Engraves metronome marking
1142 @item Note_heads_engraver
1143 @tab Engraves noteheads
1146 @item Staff_symbol_engraver
1147 @tab Engraves the five (by default) lines of the staff
1149 @tab Creates stems and single-stem tremulos
1154 We shall see later how the output of LilyPond can be changed
1155 by modifying the action of Engravers.
1158 @node Modifying context properties
1159 @subsection Modifying context properties
1161 @cindex context properties
1165 Contexts are responsible for holding the values of a number of
1166 context @emph{properties}. Many of them can be changed to
1167 influence the interpretation of the input and so change the
1168 appearance of the output. They are changed by the
1169 @code{\set} command. This takes the form
1172 \set @emph{ContextName}.@emph{propertyName} = @emph{value}
1175 Where the @emph{ContextName} is usually @context{Score},
1176 @context{Staff} or @context{Voice}. It may be omitted,
1177 in which case @context{Voice} is assumed.
1179 The names of context properties consist of words joined
1180 together with no hyphens or underscores, all except the
1181 first having a capital letter. Here are a few examples
1182 of some commonly used ones. There are many more.
1184 @c attempt to force this onto a new page
1186 @multitable @columnfractions .2 .2 .6
1187 @headitem propertyName
1192 @tab If true (##t), set extra natural signs before accidentals
1193 @item currentBarNumber
1195 @tab Set the current bar number
1198 @tab If true (##t), print slurs both above and below notes
1199 @item instrumentName
1201 @tab Set the name to be placed at the start of the staff
1204 @tab Increase or decrease the font size
1207 @tab Set the text to print before the start of a verse
1212 Before we can set any of these properties we need to know
1213 in which context they operate. Sometimes this is obvious,
1214 but occasionally it can be tricky. If the wrong context
1215 is specified, no error message is produced, but the expected
1216 action will not be taken. For example, the
1217 @code{instrumentName} clearly lives in the Staff context, since
1218 it is the staff that is to be named.
1219 In this example the first staff is labelled, but not the second,
1220 because we omitted the context name.
1222 @lilypond[quote,verbatim,ragged-right]
1224 \new Staff \relative c'' {
1225 \set Staff.instrumentName = "Soprano"
1228 \new Staff \relative c' {
1229 \set instrumentName = "Alto" % Wrong!
1235 Remember the default context name is Voice, so the second
1236 @code{\set} command set the property @code{instrumentName} in the
1237 Voice context to @qq{Alto}, but as LilyPond does not look
1238 for any such property in the @context{Voice} context, no
1239 further action took place. this is not an error, and no error
1240 message is logged in the log file.
1242 Similarly, if the property name is mis-spelt no error message
1243 is produced, and clearly the expected action cannot be performed.
1244 If fact, you can set any (fictitious) @q{property} using any
1245 name you like in any context that exists by using the
1246 @code{\set} command. But if the name is not
1247 known to LilyPond it will not cause any action to be taken.
1249 The @code{instrumentName} property will take effect only
1250 if it is set in the @context{Staff} context, but
1251 some properties can be set in more than one context.
1252 For example, the property @code{extraNatural} is by
1253 default set to ##t (true) for all staves.
1254 If it is set to ##f (false) in the @context{Staff} context
1255 it applies just to the accidentals on that staff.
1256 If it is set to false in the @context{Score} context
1257 it applies to all staves.
1259 So this turns off extra naturals in one staff:
1261 @lilypond[quote,verbatim,ragged-right]
1263 \new Staff \relative c'' {
1266 \new Staff \relative c'' {
1267 \set Staff.extraNatural = ##f
1274 and this turns them off in all staves:
1276 @lilypond[quote,verbatim,ragged-right]
1278 \new Staff \relative c'' {
1281 \new Staff \relative c'' {
1282 \set Score.extraNatural = ##f
1288 The value of every property set in this way can be reset
1289 to its original value with the @code{\unset} command.
1291 The @code{\set} and @code{\unset} commands can appear anywhere
1292 in the input file and will take effect from the time they are
1293 encountered until the end of the score or until the property is
1294 @code{\set} or @code{\unset} again. Let's try changing the
1295 font size, which affects the size of the note heads (among
1296 other things) several times.
1298 @lilypond[quote,verbatim,ragged-right,relative=1,fragment]
1300 \set fontSize = #-4 % make noteheads smaller
1302 \set fontSize = #2.5 % make noteheads larger
1304 \unset fontSize % return to original size
1308 We have now seen how to set the values of several different
1309 types of property. Note that integers and numbers are alway
1310 preceded by a hash sign, @code{#}, while a true or false value
1311 is specified by ##t and ##f, with two hash signs. A text
1312 property should be enclosed in double quotation signs, as above,
1313 although we shall see later that text can actually be specified
1314 in a much more general way by using the very powerful
1315 @code{markup} command.
1320 Context properties may also be set at the time the context is
1321 created. Sometimes this is a clearer way of specifying a
1322 property value if it is to remain fixed for the duration of
1323 the context. When a context is created with a @code{\new}
1324 command it may be immediately followed by a
1325 @code{\with @{ .. @}} block in which the property values are
1326 set. For example, if we wish to suppress the printing of
1327 extra naturals for the duration of a staff we would write:
1329 @lilypond[quote,verbatim,ragged-right]
1338 In effect this overrides the default value of the property. It
1339 may still be changed dynamically using @code{\set} and
1342 @node Adding and removing engravers
1343 @subsection Adding and removing engravers
1345 @cindex Engravers, adding
1346 @cindex Engravers, removing
1351 We have seen that contexts each contain several engravers, each
1352 of which is responsible for producing a particular part of the
1353 output, like barlines, staves, note heads, stems, etc. If an
1354 engraver is removed from a context it can no longer produce its
1355 output. This is a crude way of modifying the output, but it
1356 can sometimes be useful.
1358 To remove an engraver we can use the @code{\with} command placed
1359 immediately after the context creation command, as in the
1363 illustration let's repeat an example from the previous
1364 section with the staff lines removed. Remember that the
1365 staff lines are produced by the Staff_symbol_engraver.
1367 @lilypond[quote,verbatim,ragged-right]
1369 \remove Staff_symbol_engraver
1373 \set fontSize = #-4 % make noteheads smaller
1375 \set fontSize = #2.5 % make noteheads larger
1377 \unset fontSize % return to original size
1382 @cindex ambitus engraver
1384 Engravers can also be added to contexts. The command
1387 @code{\consists @emph{Engraver_name}},
1389 placed inside a @code{\with} block. Some vocal scores
1390 have an @rglos{ambitus} placed at the beginning of a
1391 staff to indicate the range of notes in that staff.
1392 The ambitus is produced by the @code{Ambitus_engraver},
1393 which is not normally included in any context. If
1394 we add it to the @context{Voice} context it calculates
1395 the range from that voice only:
1397 @lilypond[quote,verbatim,ragged-right]
1400 \consists Ambitus_engraver
1415 but if we add the Ambitus engraver to the
1416 @context{Staff} context it calculates the range from all
1417 the notes in all the voices on that staff:
1419 @lilypond[quote,verbatim,ragged-right]
1421 \consists Ambitus_engraver
1438 @node Extending the templates
1439 @section Extending the templates
1441 You've read the tutorial, you know how to write music, you
1442 understand the fundamental concepts. But how can you
1443 get the staves that you want? Well, you can find lots of
1444 templates (see @ref{Templates}) which may give you a start.
1446 if you want something that isn't covered there? Read on.
1449 * Soprano and cello::
1450 * Four-part SATB vocal score::
1451 * Building a score from scratch::
1454 @node Soprano and cello
1455 @subsection Soprano and cello
1457 Start off with the template that seems closest to what you want to end
1458 up with. Let's say that you want to write something for soprano and
1459 cello. In this case, we would start with @q{Notes and lyrics} (for the
1464 melody = \relative c' @{
1472 text = \lyricmode @{
1478 \new Voice = "one" @{
1482 \new Lyrics \lyricsto "one" \text
1489 Now we want to add a cello part. Let's look at the @q{Notes only} example:
1493 melody = \relative c' @{
1508 We don't need two @code{\version} commands. We'll need the @code{melody}
1509 section. We don't want two @code{\score} sections -- if we had two
1510 @code{\score}s, we'd get the two parts separately. We want them together,
1511 as a duet. Within the @code{\score} section, we don't need two
1512 @code{\layout} or @code{\midi}.
1514 If we simply cut and paste the @code{melody} section, we would end up with
1515 two @code{melody} sections. So let's rename them. We'll call the section
1516 for the soprano @code{sopranoMusic} and the section for the cello
1517 @code{celloMusic}. While we're doing this, let's rename @code{text}
1518 to be @code{sopranoLyrics}. Remember to rename both instances of all
1519 these names -- both the initial definition (the
1520 @code{melody = relative c' @{ } part) and the name's use (in the
1521 @code{\score} section).
1523 While we're doing this, let's change the cello part's staff -- celli
1524 normally use bass clef. We'll also give the cello some different
1529 sopranoMusic = \relative c' @{
1537 sopranoLyrics = \lyricmode @{
1541 celloMusic = \relative c @{
1551 \new Voice = "one" @{
1555 \new Lyrics \lyricsto "one" \sopranoLyrics
1562 This is looking promising, but the cello part won't appear in the
1563 score -- we haven't used it in the @code{\score} section. If we
1564 want the cello part to appear under the soprano part, we need to add
1567 \new Staff \celloMusic
1571 underneath the soprano stuff. We also need to add @code{<<} and
1572 @code{>>} around the music -- that tells LilyPond that there's
1573 more than one thing (in this case, two @code{Staves}) happening
1574 at once. The @code{\score} looks like this now
1576 @c Indentation in this example is deliberately poor
1581 \new Voice = "one" @{
1585 \new Lyrics \lyricsto "one" \sopranoLyrics
1587 \new Staff \celloMusic
1595 This looks a bit messy; the indentation is messed up now. That is
1596 easily fixed. Here's the complete soprano and cello template.
1598 @lilypond[quote,verbatim,ragged-right]
1600 sopranoMusic = \relative c' {
1608 sopranoLyrics = \lyricmode {
1612 celloMusic = \relative c {
1623 \new Voice = "one" {
1627 \new Lyrics \lyricsto "one" \sopranoLyrics
1629 \new Staff \celloMusic
1637 @node Four-part SATB vocal score
1638 @subsection Four-part SATB vocal score
1640 Most vocal scores of music written for four-part mixed choir
1641 with orchestral accompaniment such as Mendelssohn's Elijah or
1642 Handel's Messiah have the choral music and words on four
1643 staves, one for each of SATB, with a piano reduction of the
1644 orchestral accompaniment underneath. Here's an example
1645 from Handel's Messiah:
1647 @c The following should appear as music without code
1648 @lilypond[quote,ragged-right]
1650 global = { \key d \major \time 4/4 }
1651 sopMusic = \relative c'' {
1653 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
1655 sopWords = \lyricmode {
1656 Wor -- thy is the lamb that was slain
1658 altoMusic = \relative a' {
1660 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
1662 altoWords = \sopWords
1663 tenorMusic = \relative c' {
1665 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
1667 tenorWords = \sopWords
1668 bassMusic = \relative c' {
1670 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
1672 bassWords = \sopWords
1673 upper = \relative a' {
1676 r4 <a d fis>2 <a e' a>4 |
1677 <d fis d'>4. <d fis d'>8 <a d a'>2 |
1678 <g cis g'>4 <a d fis> <a cis e>2 |
1680 lower = \relative c, {
1683 <d d'>4 <d d'>2 <cis cis'>4 |
1684 <b b'>4. <b' b'>8 <fis fis'>2 |
1685 <e e'>4 <d d'> <a' a'>2 |
1689 << % combine ChoirStaff and PianoStaff in parallel
1691 \new Staff = "sopranos" <<
1692 \set Staff.instrumentName = "Soprano"
1693 \new Voice = "sopranos" { \global \sopMusic }
1695 \new Lyrics \lyricsto "sopranos" { \sopWords }
1696 \new Staff = "altos" <<
1697 \set Staff.instrumentName = "Alto"
1698 \new Voice = "altos" { \global \altoMusic }
1700 \new Lyrics \lyricsto "altos" { \altoWords }
1701 \new Staff = "tenors" <<
1702 \set Staff.instrumentName = "Tenor"
1703 \new Voice = "tenors" { \global \tenorMusic }
1705 \new Lyrics \lyricsto "tenors" { \tenorWords }
1706 \new Staff = "basses" <<
1707 \set Staff.instrumentName = "Bass"
1708 \new Voice = "basses" { \global \bassMusic }
1710 \new Lyrics \lyricsto "basses" { \bassWords }
1714 \set PianoStaff.instrumentName = "Piano "
1715 \new Staff = "upper" \upper
1716 \new Staff = "lower" \lower
1722 None of the templates provides this layout exactly. The
1723 nearest is @q{SATB vocal score and automatic piano reduction},
1724 but we shall need to change the layout and add a piano
1725 accompaniment which is not derived automatically from the
1726 vocal parts. The variables holding the music and words for
1727 the vocal parts are fine, but we shall need to add variables for
1728 the piano reduction.
1730 The order in which the contexts appear in the ChoirStaff of
1731 the template do not correspond with the order in the vocal
1732 score shown above. We need to rearrange them so there are
1733 four staves with the words written directly underneath the
1734 notes for each part.
1735 All the voices should be @code{voiceOne}, which is
1736 the default, so the @code{\voiceXXX} commands can be removed.
1737 We also need to specify the tenor clef for the tenors.
1738 The way in which lyrics are specified has also been simplified
1739 as we have not yet encountered the method used in the template.
1740 We've also added the names of each staff.
1742 Doing this gives for our ChoirStaff:
1746 \new Staff = "sopranos" <<
1747 \set Staff.instrumentName = "Soprano"
1748 \new Voice = "sopranos" @{ \global \sopMusic @}
1750 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
1751 \new Staff = "altos" <<
1752 \set Staff.instrumentName = "Alto"
1753 \new Voice = "altos" @{ \global \altoMusic @}
1755 \new Lyrics \lyricsto "altos" @{ \altoWords @}
1756 \new Staff = "tenors" <<
1757 \set Staff.instrumentName = "Tenor"
1758 \new Voice = "tenors" @{ \global \tenorMusic @}
1760 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
1761 \new Staff = "basses" <<
1762 \set Staff.instrumentName = "Bass"
1763 \new Voice = "basses" @{ \global \bassMusic @}
1765 \new Lyrics \lyricsto "basses" @{ \bassWords @}
1769 Next we must work out the piano part. This is
1770 easy - we just pull out the piano part from the
1771 @q{Solo piano} template:
1775 \set PianoStaff.instrumentName = "Piano "
1776 \new Staff = "upper" \upper
1777 \new Staff = "lower" \lower
1781 and add the variable definitions for @code{upper}
1784 The ChoirStaff and PianoStaff must be combined
1785 using angle brackets as we want them to be
1786 stacked one above the other:
1789 << % combine ChoirStaff and PianoStaff one above the other
1791 \new Staff = "sopranos" <<
1792 \new Voice = "sopranos" @{ \global \sopMusic @}
1794 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
1795 \new Staff = "altos" <<
1796 \new Voice = "altos" @{ \global \altoMusic @}
1798 \new Lyrics \lyricsto "altos" @{ \altoWords @}
1799 \new Staff = "tenors" <<
1800 \clef "G_8" % tenor clef
1801 \new Voice = "tenors" @{ \global \tenorMusic @}
1803 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
1804 \new Staff = "basses" <<
1806 \new Voice = "basses" @{ \global \bassMusic @}
1808 \new Lyrics \lyricsto "basses" @{ bassWords @}
1812 \set PianoStaff.instrumentName = "Piano "
1813 \new Staff = "upper" \upper
1814 \new Staff = "lower" \lower
1819 Combining all these together and adding the music
1820 for the three bars of the example above gives:
1822 @lilypond[quote,verbatim,ragged-right]
1824 global = { \key d \major \time 4/4 }
1825 sopMusic = \relative c'' {
1827 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
1829 sopWords = \lyricmode {
1830 Wor -- thy is the lamb that was slain
1832 altoMusic = \relative a' {
1834 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
1836 altoWords = \sopWords
1837 tenorMusic = \relative c' {
1839 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
1841 tenorWords = \sopWords
1842 bassMusic = \relative c' {
1844 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
1846 bassWords = \sopWords
1847 upper = \relative a' {
1850 r4 <a d fis>2 <a e' a>4 |
1851 <d fis d'>4. <d fis d'>8 <a d a'>2 |
1852 <g cis g'>4 <a d fis> <a cis e>2 |
1854 lower = \relative c, {
1857 <d d'>4 <d d'>2 <cis cis'>4 |
1858 <b b'>4. <b' b'>8 <fis fis'>2 |
1859 <e e'>4 <d d'> <a' a'>2 |
1863 << % combine ChoirStaff and PianoStaff in parallel
1865 \new Staff = "sopranos" <<
1866 \set Staff.instrumentName = "Soprano"
1867 \new Voice = "sopranos" { \global \sopMusic }
1869 \new Lyrics \lyricsto "sopranos" { \sopWords }
1870 \new Staff = "altos" <<
1871 \set Staff.instrumentName = "Alto"
1872 \new Voice = "altos" { \global \altoMusic }
1874 \new Lyrics \lyricsto "altos" { \altoWords }
1875 \new Staff = "tenors" <<
1876 \set Staff.instrumentName = "Tenor"
1877 \new Voice = "tenors" { \global \tenorMusic }
1879 \new Lyrics \lyricsto "tenors" { \tenorWords }
1880 \new Staff = "basses" <<
1881 \set Staff.instrumentName = "Bass"
1882 \new Voice = "basses" { \global \bassMusic }
1884 \new Lyrics \lyricsto "basses" { \bassWords }
1888 \set PianoStaff.instrumentName = "Piano "
1889 \new Staff = "upper" \upper
1890 \new Staff = "lower" \lower
1897 @node Building a score from scratch
1898 @subsection Building a score from scratch
1900 After gaining some facility with writing LilyPond code you
1901 may find that it is easier to build a score from scratch
1902 rather than modifying one of the templates. You can also
1903 develop your own style this way to suit the sort of music you
1904 like. Let's see how to put together the score for an organ
1905 prelude as an example.
1907 We begin with a header section. Here go the title, name
1908 of composer, etc, then come any variable definitions, and
1909 finally the score block. Let's start with these in outline
1910 and fill in the details later.
1912 We'll use the first two bars of Bach's prelude
1913 based on @emph{Jesu, meine Freude} which is written for two
1914 manuals and pedal organ. The top manual part has two voices,
1915 the lower and pedal organ one each. So we need four
1916 music definitions and one to define the time signature
1922 title = "Jesu, meine Freude"
1923 composer = "J S Bach"
1925 TimeKey = @{ \time 4/4 \key c \minor @}
1926 ManualOneVoiceOneMusic = @{s1@}
1927 ManualOneVoiceTwoMusic = @{s1@}
1928 ManualTwoMusic = @{s1@}
1929 PedalOrganMusic = @{s1@}
1935 For now we've just used a spacer note, @code{s1},
1936 instead of the real music. We'll add that later.
1938 Next let's see what should go in the score block.
1939 We simply mirror the staff structure we want.
1940 Organ music is usually written on three staves,
1941 one for each manual and one for the pedals. The
1942 manual staves should be bracketed together so we
1943 need to use a PianoStaff for them. The first
1944 manual part needs two voices and the second manual
1949 \new Staff = "ManualOne" <<
1950 \new Voice @{ \ManualOneVoiceOneMusic @}
1951 \new Voice @{ \ManualOneVoiceTwoMusic @}
1952 >> % end ManualOne Staff context
1953 \new Staff = "ManualTwo" <<
1954 \new Voice @{ \ManualTwoMusic @}
1955 >> % end ManualTwo Staff context
1956 >> % end PianoStaff context
1959 Next we need to add a staff for the pedal organ.
1960 This goes underneath the PianoStaff, but it must
1961 be simultaneous with it, so we need angle brackets
1962 round the two. Missing these out would generate
1963 an error in the log file. It's a common mistake
1964 which you'll make sooner or later! Try copying
1965 the final example at the end of this section,
1966 remove these angle brackets, and compile it to
1967 see what errors it generates.
1970 << % PianoStaff and Pedal Staff must be simultaneous
1972 \new Staff = "ManualOne" <<
1973 \new Voice @{ \ManualOneVoiceOneMusic @}
1974 \new Voice @{ \ManualOneVoiceTwoMusic @}
1975 >> % end ManualOne Staff context
1976 \new Staff = "ManualTwo" <<
1977 \new Voice @{ \ManualTwoMusic @}
1978 >> % end ManualTwo Staff context
1979 >> % end PianoStaff context
1980 \new Staff = "PedalOrgan" <<
1981 \new Voice @{ \PedalOrganMusic @}
1986 It is not strictly necessary to use the simultaneous construct
1987 @code{<< >>} for the manual two staff and the pedal organ staff,
1988 since they contain only one music expression, but it does no harm
1989 and always using angle brackets after @code{\new Staff} is a good
1990 habit to cultivate in case there are multiple voices.
1992 Let's add this structure to the score block, and adjust the
1993 indenting. We also add the appropriate clefs, ensure the
1994 second voice stems point down with @code{\voiceTwo} and
1995 enter the time signature and key to each staff using our
1996 predefined variable, @code{\TimeKey}.
2000 << % PianoStaff and Pedal Staff must be simultaneous
2002 \new Staff = "ManualOne" <<
2003 \TimeKey % set time signature and key
2005 \new Voice @{ \ManualOneVoiceOneMusic @}
2006 \new Voice @{ \voiceTwo \ManualOneVoiceTwoMusic @}
2007 >> % end ManualOne Staff context
2008 \new Staff = "ManualTwo" <<
2011 \new Voice @{ \ManualTwoMusic @}
2012 >> % end ManualTwo Staff context
2013 >> % end PianoStaff context
2014 \new Staff = "PedalOrgan" <<
2017 \new Voice @{ \PedalOrganMusic @}
2018 >> % end PedalOrgan Staff
2020 @} % end Score context
2023 That completes the structure. Any three-staff organ music
2024 will have a similar structure, although the number of voices
2025 may vary. All that remains now
2026 is to add the music, and combine all the parts together.
2028 @lilypond[quote,verbatim,ragged-right]
2031 title = "Jesu, meine Freude"
2032 composer = "J S Bach"
2034 TimeKey = { \time 4/4 \key c \minor }
2035 ManualOneVoiceOneMusic = \relative g' {
2036 g4 g f ees | d2 c2 |
2038 ManualOneVoiceTwoMusic = \relative c' {
2039 ees16 d ees8~ ees16 f ees s c8 d~ d c~ |
2040 c c4 b8 c8. g16 c b c d |
2042 ManualTwoMusic = \relative c' {
2043 c16 b c8~ c16 b c g a8 g~ g16 g aes ees |
2044 f ees f d g aes g f ees d e8~ ees16 f ees d |
2046 PedalOrganMusic = \relative c {
2047 r8 c16 d ees d ees8~ ees16 a, b g c b c8 |
2048 r16 g ees f g f g8 c,2 |
2052 << % PianoStaff and Pedal Staff must be simultaneous
2054 \new Staff = "ManualOne" <<
2055 \TimeKey % set time signature and key
2057 \new Voice { \ManualOneVoiceOneMusic }
2058 \new Voice { \voiceTwo \ManualOneVoiceTwoMusic }
2059 >> % end ManualOne Staff context
2060 \new Staff = "ManualTwo" <<
2063 \new Voice { \ManualTwoMusic }
2064 >> % end ManualTwo Staff context
2065 >> % end PianoStaff context
2066 \new Staff = "PedalOrgan" <<
2069 \new Voice { \PedalOrganMusic }
2070 >> % end PedalOrgan Staff
2072 } % end Score context