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 ...
351 TODO Add ref to tweaks section where this example should
352 be placed and explained.
354 @node On the un-nestedness of brackets and ties
355 @subsection On the un-nestedness of brackets and ties
357 You have already met a number of different types of bracket in
358 writing the input file to LilyPond. These obey different rules
359 which can be confusing at first. Before we explain the rules
360 let's first review the different types of bracket.
362 @multitable @columnfractions .3 .7
363 @headitem Bracket Type
365 @item @code{@{ .. @}}
366 @tab Encloses a sequential segment of music
368 @tab Encloses the notes of a chord
369 @item @code{<< .. >>}
370 @tab Encloses concurrent or simultaneous sections
372 @tab Marks the start and end of a slur
373 @item @code{\( .. \)}
374 @tab Marks the start and end of a phrase mark
376 @tab Marks the start and end of a manual beam
379 To these we should add other constructs which generate lines
380 between or across notes: ties (marked by a tilde, @code{~}),
381 tuplets written as @code{\times x/y @{..@}}, and grace notes
382 written as @code{\grace@{..@}}.
384 Outside LilyPond, the conventional use of brackets requires
385 the different types to be properly nested, like this,
386 @code{<< [ @{ ( .. ) @} ] >>}, with the closing brackets being
387 encountered in exactly the opposite order to the opening
388 brackets. This @strong{is} a requirement for the three types of
389 bracket described by the word @q{Encloses} in the table above -
390 they must nest properly.
391 However, the remaining brackets, described with the word
392 @q{Marks} in the table above together with ties and tuplets,
393 do @strong{not} have to nest
394 properly with any of the brackets. In fact, these are not
395 brackets in the sense that
396 they enclose something - they are simply markers to indicate
397 where something starts and ends.
399 So, for example, a phrasing slur can start before a manually
400 inserted beam and end before the end of the beam - not very
401 musical, perhaps, but possible:
403 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
404 { g8\( a b[ c b\) a] }
407 In general, different kinds of brackets, and those implied by
408 tuplets, ties and grace notes, may be mixed freely.
409 This example shows a beam extending into a tuplet (line 1),
410 a slur extending into a tuplet (line 2),
411 a beam and a slur extending into a tuplet, a tie crossing
412 two tuplets, and a phrasing slur extending out of a tuplet
415 @lilypond[quote,verbatim,fragment,ragged-right]
417 r16[ g16 \times 2/3 {r16 e'8] }
418 g16( a \times 2/3 {b d) e' }
419 g8[( a \times 2/3 {b d') e'~]}
420 \times 4/5 {e'32\( a b d' e'} a'4.\)
425 @node Voices contain music
426 @section Voices contain music
428 Singers need voices to sing, and so does LilyPond.
429 The actual music for all instruments in a score
430 is contained in Voices - the most fundamental
431 of all LilyPond's concepts.
434 * I'm hearing Voices::
435 * Explicitly instantiating voices::
436 * Voices and vocals::
439 @node I'm hearing Voices
440 @subsection I'm hearing Voices
444 @cindex Voice context
446 The lowest, most fundamental or innermost layers in a LilyPond
447 score are called @q{Voice contexts} or just @q{Voices} for short.
448 Voices are sometimes called @q{layers} in other notation
451 In fact, a Voice layer or context is the only one which can
452 contain music. If a Voice context is not explicitly declared
453 one is created automatically. Some instruments such as an
454 Oboe can play only one note at a time. Music written for
455 such instruments is monophonic and requires just a single
456 voice. Instruments which can play more than one note at a
457 time like the piano will often require multiple voices to
458 encode the different concurrent notes and rhythms they are
461 A single voice can contain many notes in a chord, of course,
462 so when exactly are multiple voices needed?
463 Let us analyse a short piece of music to see how many voices
464 are required. Here are the notes from the first two bars
465 of the second of Chopin's Deux Nocturnes, Op 32.
467 @c The following should appear as music without code
468 @lilypond[quote,ragged-right]
469 \new Staff \relative c'' {
477 \once \override NoteColumn #'force-hshift = #0 <ees c>2
478 \once \override NoteColumn #'force-hshift = #0.5 des2 }
484 The direction of the stems is often used to indicate the
485 continuity of two simultaneous melodic lines. Here the
486 stems of the highest notes are all pointing up and the
487 stems of the lower notes are all pointing down.
488 This is the first indication that more than one voice
491 But the real need for multiple voices arises when notes
492 which start at the same time have different durations.
493 Look at the notes which start at beat three in the first
494 bar. The a-flat is a dotted quarter note, the f is a
495 quarter note and the d-flat is a half note. These
496 cannot be written as a chord as all the notes in a chord
497 must have the same duration. Neither can they be written
498 as sequential notes, as they must start at the same time.
499 This section of the bar requires three voices, and the
500 normal practice would be to write the whole bar as three
501 voices, as shown here, where we have used different noteheads
502 and colors for the three voices.
504 @c The following should appear as music without code
505 @c The three voice styles should be defined in -init
506 @lilypond[quote,ragged-right]
507 \new Staff \relative c'' {
518 \once \override NoteColumn #'force-hshift = #0 <ees c>2
519 \once \override NoteColumn #'force-hshift = #0.5 des2 }
525 Let us see how this is done.
529 The easiest way to enter fragments with more than one voice on a
530 staff is to enter each voice as a sequence (with @code{@{...@}}),
531 and combine them simultaneously with angle brackets, @code{<<...>>}.
532 The fragments must also be separated with double backward slashes,
533 @code{\\}, to place them in separate voices. Without these, the
534 notes would be entered into a single voice, which would usually
535 cause errors. This technique is particularly suited to pieces of
536 music which are largely monophonic with occasional short sections
537 of polyphony. Here's a simple example:
539 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
541 % Voice "1" Voice "2"
542 << { r4 g g4. a8 } \\ { d,2 d4 g } >> |
543 << { bes4 bes c bes } \\ { g4 g g8( a) g4 } >> |
544 << { a2. r4 } \\ { fis2. s4 } >>
547 This example has just two voices, but the same contruct may be
548 used to encode three or more voices by adding more back-slash
551 The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
552 In each of these contexts, the vertical direction of slurs,
553 stems, ties, dynamics etc., is set appropriately.
555 @lilypond[quote,verbatim,fragment]
556 \new Staff \relative c' {
559 % Voice "1" Voice "2" Voice "3"
560 << { g4 f e } \\ { r8 e4 d c8 ~ } >> |
561 << { d2 e2 } \\ { c8 b16 a b8 g ~ g2 } \\ { s4 b4 c2 } >> |
565 These voices are all separate from the main voice that contains
566 the notes just outside the @code{<< .. >>} construct. Let's call
567 this the @emph{simultaneous construct}. Slurs and ties may only
568 connect notes within the same voice, so slurs and ties cannot go
569 into or out of a simultaneous construct. Conversely,
570 parallel voices from separate simultaneous constructs on the same
571 staff are the same voice. Other voice-related properties also
572 carry across simultaneous constructs. Here is the same example,
573 with different colors and noteheads for each voice. Note that
574 changes in one Voice do not affect other voices, but they do
575 persist in the same Voice later. Note also that tied notes may be
576 split across the same voices in two constructs, shown here in the
579 @lilypond[quote,verbatim]
580 \new Staff \relative c' {
590 { c8 b16 a b8 g ~ g2 } \\
597 The commands @code{\voiceXXXStyle} are mainly intended for use in
598 educational documents such as this one. They modify the color
599 of the notehead, the stem and the beams, and the style of the
600 notehead, so that the voices may be easily distinguished.
601 Voice one is set to red diamonds, voice two to blue triangles,
602 voice three to green crossed circles, and voice four (not used
603 here) to magenta crosses. We shall see later how commands like
604 these may be created by the user.
605 TODO: add ref to appropriate section in Tweaks
607 Polyphony does not change the relationship of notes within a
608 @code{\relative @{ @}} block. Each note is still calculated
609 relative to the note immediately preceding it, or to the first
610 note of the preceding chord. So in
613 \relative c' @{ noteA << < noteB noteC > \\ noteD >> noteE @}
617 @code{noteB} is relative to @code{noteA} @*
618 @code{noteC} is relative to @code{noteB}, not @code{noteA}; @*
619 @code{noteD} is relative to @code{noteB}, not @code{noteA} or
621 @code{noteE} is relative to @code{noteD}, not @code{noteA}
623 We are now in a position to return to the first example from
624 the Chopin Nocturne to see how this might be encoded. As we
625 shall see, this encounters some difficulties. We begin as
626 we have learnt, using the @code{<< \\ >>} construct to
627 enter the music of the first bar in three voices:
629 @lilypond[quote,verbatim,fragment,ragged-right]
630 \new Staff \relative c'' {
633 { c2 aes4. bes8 } \\ { aes2 f4 fes } \\ { <ees c>2 des2 }
643 @funindex \voiceThree
646 The stem directions are automatically assigned with the
647 odd-numbered voices taking upward stems and the even-numbered
648 voices downward ones. The stems for voices 1 and 2 are right,
649 but the stems in voice 3 should go down in this particular piece
650 of music. We can correct this
651 by telling LilyPond that this third voice is really a fourth
652 voice, with stems going down, using the @code{\voiceFour}
653 command. There are also corresponding @code{\voiceOne},
654 @code{\voiceTwo}, and @code{voiceThree}
655 commands. This results in the following:
657 @lilypond[quote,verbatim,fragment,ragged-right]
658 \new Staff \relative c'' {
663 { \voiceFour <ees c>2 des2 }
670 and exposes a problem commonly encountered with multiple
671 voices: the stems of notes can collide with noteheads
672 in other voices. In laying out the notes, LilyPond allows the
673 notes or chords from two voices to occupy the same vertical
674 note column provided the stems are in opposite directions, but
675 the notes from a third voice are displaced to avoid the stems
676 colliding. This often works well, but in this example the
677 notes of the third voice are clearly not well placed by default.
678 LilyPond provides several ways to adjust the horizontal placing
679 of notes. We are not quite ready yet to see how to correct this,
680 so we shall leave this problem until a later section (see ... )
684 @node Explicitly instantiating voices
685 @subsection Explicitly instantiating voices
687 Voice contexts can also be created manually
688 inside a @code{<< >>} block to create polyphonic music, using
689 @code{\voiceOne} ... @code{\voiceFour} to indicate the required
690 directions of stems, slurs, etc.
692 Specifically, the construct @code{<< \\ >>} which we used in
693 the previous section:
696 << \upper \\ \lower >>
700 where @code{upper} and @code{lower} are user-defined variables
701 containing the music for the two voices, is equivalent to
705 \new Voice = "1" @{ \voiceOne \upper @}
706 \new Voice = "2" @{ \voiceTwo \lower @}
710 The @code{\voiceXXX} commands set the direction of stems, slurs,
711 ties, articulations, text annotations, augmentation dots of dotted
712 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
713 make these objects point upwards, while @code{\voiceTwo} and
714 @code{\voiceFour} make them point downwards. These commands also
715 generate a horizontal shift for each voice when this is required
716 to avoid clashes of note heads. The command @code{\oneVoice}
717 reverts the settings back to the normal values for a single voice.
719 Let us see in some simple examples exactly what effect
720 @code{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on
721 markup, ties, slurs, and dynamics:
723 @lilypond[quote,ragged-right,verbatim]
725 c-"default" d8 ~ d e4 ( f g a ) b-> c
729 @lilypond[quote,ragged-right,verbatim]
732 c-"\\voiceOne" d8 ~ d e4 ( f g a ) b-> c
734 c,-"\\oneVoice" d8 ~ d e4 ( f g a ) b-> c
738 @lilypond[quote,ragged-right,verbatim]
741 c-"\\voiceTwo" d8 ~ d e4 ( f g a ) b-> c
743 c,-"\\oneVoice" d8 ~ d e4 ( f g a ) b-> c
747 An expression that appears directly inside a @code{<< >>} belongs
748 to the main voice (but, note, @strong{not} in a @code{<< \\ >>}
749 contruct). This is useful when extra voices appear while the main
750 voice is playing. Here is a more correct rendition of the example
751 from the previous section. The red diamond-shaped notes
752 demonstrate that the main melody is now in a single voice context,
753 permitting a phrasing slur to be drawn over them.
755 @lilypond[quote,ragged-right,verbatim]
756 \new Staff \relative c' {
758 c16^( d e f % These notes are monophonic
759 << % Start simultaneous section of three voices
760 { g4 f e | d2 e2) } % Continue the main voice in parallel
761 \new Voice { % Initiate second voice
762 \voiceTwo % Set stems, etc, down
763 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
765 \new Voice { % Initiate third voice
766 \voiceThree % Set stems, etc, up
773 @cindex nesting music expressions
774 @cindex nesting simultaneous constructs
776 More deeply nested polyphony constructs are possible, and if a
777 voice appears only briefly this might be a more natural way to
780 @lilypond[quote,ragged-right,verbatim]
781 \new Staff \relative c' {
801 This method of nesting new voices briefly is useful
802 when only small sections of the music
803 are polyphonic, but when the whole staff is largely polyphonic
804 it can be clearer to use multiple voices throughout, using
805 spacing notes to step over sections where the voice is silent,
808 @lilypond[quote,ragged-right,verbatim]
809 \new Staff \relative c' <<
810 \new Voice { % Initiate first voice
812 c16^( d e f g4 f e | d2 e2) |
814 \new Voice { % Initiate second voice
815 \voiceTwo % set stems, etc down
816 s4 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 |
818 \new Voice { % Initiate third voice
819 \voiceThree % set stems, etc up
826 @node Voices and vocals
827 @subsection Voices and vocals
829 Vocal music presents a special difficulty: we need to combine two
830 expressions -- notes and lyrics.
832 You have already seen the @code{\addlyricsd@{@}} command, which
833 handles simple scores well. However, this technique is
834 quite limited. For more complex music, you must introduce the
835 lyrics in a @code{Lyrics} context using @code{\new Lyrics} and
837 the lyrics to the notes with @code{\lyricsto@{@}}, using the
838 name assigned to the Voice.
840 @lilypond[quote,verbatim,fragment]
842 \new Voice = "one" \relative c'' {
845 c4 b8. a16 g4. f8 e4 d c2
847 \new Lyrics \lyricsto "one" {
848 No more let sins and sor -- rows grow.
853 The automatic beaming which LilyPond uses by default works well
854 for instrumental music, but not so well for music with lyrics,
855 where beaming is either not required at all or is used to indicate
856 melismata in the lyrics. In the example above we use the command
857 @code{\autoBeamOff} to turn off the automatic beaming.
859 Let us reuse the earlier example from Judas Maccabæus to
860 illustrate this more flexible technique. We first recast
861 it to use variables so the music and lyrics can be separated
862 from the staff structure. We also introduce a ChoirStaff
863 bracket. The lyrics themselves must be introduced with
864 @code{\lyricmode} to ensure they are interpreted as lyrics
867 @lilypond[quote,verbatim]
868 global = { \time 6/8 \partial 8 \key f \major}
869 SopOneMusic = \relative c'' {
870 c8 | c([ bes)] a a([ g)] f | f'4. b, | c4.~ c4 }
871 SopTwoMusic = \relative c' {
872 r8 | r4. r4 c8 | a'([ g)] f f([ e)] d | e([ d)] c bes' }
873 SopOneLyrics = \lyricmode {
874 Let | flee -- cy flocks the | hills a -- dorn, __ }
875 SopTwoLyrics = \lyricmode {
876 Let | flee -- cy flocks the | hills a -- dorn, }
881 \new Voice = "SopOne" {
885 \new Lyrics \lyricsto "SopOne" {
890 \new Voice = "SopTwo" {
893 \new Lyrics \lyricsto "SopTwo" {
901 This is the basic structure of all vocal scores. More staves may
902 be added as required, more voices may be added to the staves,
903 more verses may be added to the lyrics,
904 and the variables containing the music can easily be placed
905 in separate files should they become too long.
907 Here is a final example of the first line of a hymn with four
908 verses, set for SATB. In this case the words for all four
911 @lilypond[quote,verbatim]
912 global = { \time 4/4 \partial 4 \key c \major}
913 SopMusic = \relative c' { c4 | e4. e8 g4 g | a a g }
914 AltoMusic = \relative c' { c4 | c4. c8 e4 e | f f e }
915 TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 }
916 BassMusic = \relative c { c4 | c4. c8 c4 c | f8 g a b c4 }
917 VerseOne = \lyricmode {
918 E -- | ter -- nal fa -- ther, | strong to save, }
919 VerseTwo = \lyricmode {
920 O | Christ, whose voice the | wa -- ters heard, }
921 VerseThree = \lyricmode {
922 O | Ho -- ly Spi -- rit, | who didst brood }
923 VerseFour = \lyricmode {
924 O | Tri -- ni -- ty of | love and pow'r }
930 \new Voice = "Sop" { \voiceOne \global \SopMusic }
931 \new Voice = "Alto" { \voiceTwo \AltoMusic }
932 \new Lyrics \lyricsto "Sop" { \VerseOne }
933 \new Lyrics \lyricsto "Sop" { \VerseTwo }
934 \new Lyrics \lyricsto "Sop" { \VerseThree }
935 \new Lyrics \lyricsto "Sop" { \VerseFour }
939 \new Voice = "Tenor" { \voiceOne \TenorMusic }
940 \new Voice = "Bass" { \voiceTwo \BassMusic }
946 @node Contexts and engravers
947 @section Contexts and engravers
949 Contexts and engravers have been mentioned informally
950 in earlier sections; we now must look at
951 these concepts in more detail, as they are important
952 in the fine-tuning of LilyPond output.
956 * Contexts explained::
957 * Creating contexts::
959 * Modifying contexts::
962 @node Contexts explained
963 @subsection Contexts explained
965 When music is printed, many notational elements which do not
966 appear explicitly in the input file must be added to the
967 output. For example, compare the input and output of the
970 @lilypond[quote,verbatim,relative=2,fragment]
974 The input is rather sparse, but in the output, bar lines,
975 accidentals, clef, and time signature have been added. When
976 LilyPond @emph{interprets} the input the musical information
977 is inspected in time order, similar to reading a score from left
978 to right. While reading the input, the program remembers where
979 measure boundaries are, and which pitches require explicit
980 accidentals. This information must be held on several levels.
981 For example, the effect of an accidental is limited
982 to a single staff, while a bar line must be synchronized across
985 Within LilyPond, these rules and bits of information are grouped
986 in @emph{Contexts}. We have already met the @context{Voice}
988 Others are the @context{Staff} and @context{Score} contexts.
989 Contexts are hierarchical to reflect the heirarchical nature of
991 For example: a @context{Staff} context can contain many
992 @context{Voice} contexts, and a @context{Score} context can
993 contain many @context{Staff} contexts.
996 @image{context-example,5cm,,}
999 Each context has the responsibility for enforcing some notation rules,
1000 creating some notation objects and maintaining the associated
1001 properties. For example, the @context{Voice} context may introduce an
1002 accidental and then the @context{Staff} context maintains the rule to
1003 show or suppress the accidental for the remainder of the measure.
1005 As another example, the synchronization of bar lines is, by default,
1006 handled in the @context{Score} context.
1007 However, in some music we may not want the bar lines to be
1008 synchronized -- consider a polymetric score in 4/4 and 3/4 time.
1009 In such cases, we must modify the default settings of the
1010 @context{Score} and @context{Staff} contexts.
1012 For very simple scores, contexts are created implicitly, and you need
1013 not be aware of them. For larger pieces, such as anything with more
1014 than one staff, they must be
1015 created explicitly to make sure that you get as many staves as you
1016 need, and that they are in the correct order. For typesetting pieces
1017 with specialized notation, it is usual to modify existing, or
1018 even to define totally new, contexts.
1020 In addition to the @context{Score,} @context{Staff} and
1021 @context{Voice} contexts there are contexts which fit between
1022 the score and staff levels to control staff groups, such as the
1023 @context{PianoStaff} and @context{ChoirStaff} contexts. There
1024 are also alternative staff and voice contexts, and contexts for
1025 lyrics, percussion, fret boards, figured bass, etc. A complete
1026 list is shown in the Notation Reference.
1029 The names of all context types are formed from one or more
1030 words, each word being capitalised and joined immediately to the
1031 preceding word with no hyphen or underscore, e.g.,
1032 @context{GregorianTranscriptionStaff}.
1034 @node Creating contexts
1035 @subsection Creating contexts
1037 There can be only one top level context: the @context{Score}
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}.
1085 @subsection Engravers
1087 Every mark on the printed output of a score produced by LilyPond
1088 is produced by an @code{Engraver}. Thus there is an engraver
1089 to print staves, one to print noteheads, one for stems, one for
1090 beams, etc, etc. In total there are over 120 such engravers!
1091 Fortunately, for most scores it is not necessary to know about
1092 more than a few, and for simple scores you do not need to know
1095 Engravers live and operate in Contexts.
1096 Engravers such as the @code{Metronome_mark_engraver}, whose
1097 action and output applies to the score as a whole, operate in
1098 the highest level context - the @context{Score} context.
1100 The @code{Clef_engraver} and @code{Key_engraver} are to be
1101 found in every Staff Context, as different staves may require
1102 different clefs and keys.
1104 The @code{Note_heads_engraver} and @code{Stem_engraver} live
1105 in each @context{Voice} context, the lowest level context of all.
1107 Each engraver processes the particular objects associated
1108 with its function, and maintains the properties that relate
1109 to that function. These properties, like the properties
1110 associated with contexts, may be modified to change the
1111 operation of the engraver or the appearance of those elements
1112 in the printed score.
1114 Engravers all have compound names formed from words which
1115 describe their function. Just the first word is capitalised,
1116 and the remainder are joined to it with underscores. Thus
1117 the @code{Staff_symbol_engraver} is responsible for creating the
1118 lines of the staff, the @code{Clef_engraver} determines and sets
1119 the pitch reference point on the staff by drawing a clef symbol.
1121 Here are some of the most common engravers together with their
1122 function. You will see it is easy to guess the function from
1123 the name, or vice versa.
1125 @multitable @columnfractions .3 .7
1128 @item Accidental_engraver
1129 @tab Makes accidentals, cautionary and suggested accidentals
1134 @item Dynamic_engraver
1135 @tab Creates hairpins and dynamic texts
1137 @tab Creates the key signature
1138 @item Metronome_mark_engraver
1139 @tab Engraves metronome marking
1140 @item Note_heads_engraver
1141 @tab Engraves noteheads
1144 @item Staff_symbol_engraver
1145 @tab Engraves the five (by default) lines of the staff
1147 @tab Creates stems and single-stem tremulos
1152 We shall see later how the output of LilyPond can be changed
1153 by modifying the action of Engravers.
1156 @node Modifying contexts
1157 @subsection Modifying contexts
1160 * Changing context properties::
1163 @node Changing context properties
1164 @subsubsection Changing context properties
1166 @cindex context properties
1170 Contexts are responsible for holding the values of a number of
1171 context @emph{properties}. Many of them can be changed to
1172 influence the interpretation of the input and so change the
1173 appearance of the output. They are changed by the
1174 @code{\set} command. This takes the form
1177 \set @emph{ContextName}.@emph{propertyName} = @emph{value}
1180 Where the @emph{ContextName} is usually @context{Score},
1181 @context{Staff} or @context{Voice}. It may be omitted,
1182 in which case @context{Voice} is assumed.
1184 The names of context properties consist of words joined
1185 together with no hyphens or underscores, all except the
1186 first having a capital letter. Here are a few examples
1187 of some commonly used ones. There are many more.
1189 @multitable @columnfractions .3 .2 .5
1190 @headitem propertyName
1195 @tab If true (##t), set extra natural sign before accidentals
1196 @item currentBarNumber
1198 @tab Set the current bar number
1201 @tab If true (##t), print slurs both above and below notes
1202 @item instrumentName
1204 @tab Set the name to be placed at the start of the staff
1207 @tab Increase or decrease the font size
1210 @tab Set the text to print before the start of a verse
1213 Before we can set any of these properties we need to know
1214 which context they operate in. Sometimes this is obvious,
1215 but occasionally it can be tricky. If the wrong context
1216 is specified, no error message is produced, but the expected
1217 action will not be taken. For example, the
1218 @code{instrumentName} clearly lives in the Staff context, since
1219 it is the staff that is named.
1220 In this example the first staff is labelled, but the second,
1221 Alto, staff is not, because we omitted the context name.
1223 @lilypond[quote,verbatim,ragged-right]
1225 \new Staff \relative c'' {
1226 \set Staff.instrumentName = "Soprano"
1229 \new Staff \relative c' {
1230 \set instrumentName = "Alto"
1236 Remember the default context name is Voice, so the second
1237 @code{\set} command set the property @emph{instrumentName} in the
1238 Voice context to @qq{Alto}, but as LilyPond does not look
1239 for any such property in the @context{Voice} context, no
1240 further action took place. No error message is logged in
1243 Similarly, if the property name is mis-spelt no error message
1244 is produced, and the expected action clearly is not performed.
1245 If fact, you can set any (fictitious) @q{property} using any
1246 name you like in any context that exists by using the
1247 @code{\set} command. But if the name is not
1248 known to LilyPond it will not cause any action to be taken.
1250 The @code{instrumentName} property will take effect only
1251 if it is set in the @context{Staff} context, but
1252 some properties can be set in more than one context.
1253 For example, the property @code{extraNatural} is by
1254 default set to ##t (true) for all staves.
1255 If it is set to ##f (false) in the @context{Staff} context
1256 it applies just to the accidentals on that staff.
1257 If it is set to false in the @context{Score} context
1258 it applies to all staves.
1260 So this sets @code{extraNatural} in one staff:
1262 @lilypond[quote,verbatim,ragged-right]
1264 \new Staff \relative c'' {
1267 \new Staff \relative c'' {
1268 \set Staff.extraNatural = ##f
1275 and this sets it in all staves:
1277 @lilypond[quote,verbatim,ragged-right]
1279 \new Staff \relative c'' {
1282 \new Staff \relative c'' {
1283 \set Score.extraNatural = ##f
1289 The value of every property set in this way can be reset
1290 to its original value with the @code{\unset} command.
1292 The @code{\set} and @code{\unset} commands can appear anywhere
1293 in the input file and will take effect from the time they are
1294 encountered until the end of the score or until the property is
1295 @code{\set} or @code{\unset} again. Let's try changing the
1296 font size, which affects the size of the note heads (among
1297 other things) several times.
1299 @lilypond[quote,verbatim,ragged-right,relative=1,fragment]
1301 \set fontSize = #-4 % make noteheads smaller
1303 \set fontSize = #2.5 % make noteheads larger
1305 \unset fontSize % return to original size
1309 We have now seen how to set the values of several different
1310 types of property. Note that integers and numbers are alway
1311 preceded by a hash sign, @code{#}, while a true or false value
1312 is specified by ##t and ##f, with two hash signs. A text
1313 property should be enclosed in double quotation signs, as above,
1314 although we shall see later that text can actually be specified
1315 in a much more general way by using the very powerful
1316 @code{markup} command.
1321 Context properties may also be set at the time the context is
1322 created. Sometimes this is a clearer way of specifying a
1323 property value if it is to remain fixed for the duration of
1324 the context. When a context is created with a @code{\new}
1325 command it may be immediately followed by a
1326 @code{\with @{ .. @}} block in which the property values are
1327 set. For example, if we wish to suppress the printing of
1328 extra naturals for the duration of a staff we would write:
1330 @lilypond[quote,verbatim,ragged-right]
1339 In effect this overrides the default value of the property. It
1340 may still be changed dynamically using @code{\set} and
1344 @cindex Engravers, adding
1345 @cindex Engravers, removing
1350 We have seen that contexts each contain several engravers, each
1351 of which is responsible for producing a particular part of the
1352 output, like barlines, staves, note heads, stems, etc. If an
1353 engraver is removed from a context it can no longer produce its
1354 output. This is a crude way of modifying the output, but it
1355 can sometimes be useful.
1357 To remove an engraver we can use the @code{\with} command placed
1358 immediately after the context creation command, as in the
1362 illustration let's repeat an example from the previous
1363 section with the staff lines removed. Remember that the
1364 staff lines are produced by the Staff_symbol_engraver.
1366 @lilypond[quote,verbatim,ragged-right]
1368 \remove Staff_symbol_engraver
1372 \set fontSize = #-4 % make noteheads smaller
1374 \set fontSize = #2.5 % make noteheads larger
1376 \unset fontSize % return to original size
1381 @cindex ambitus engraver
1383 Engravers can also be added to contexts. The command
1386 @code{\consists @emph{Engraver_name}},
1388 placed inside a @code{\with} block. Some vocal scores
1389 have an @rglos{ambitus} placed at the beginning of a
1390 staff to indicate the range of notes in that staff.
1391 The ambitus is produced by the @code{Ambitus_engraver},
1392 which is not normally included in any context. If
1393 we add it to the @context{Voice} context it calculates
1394 the range from that voice only:
1396 @lilypond[quote,verbatim,ragged-right]
1399 \consists Ambitus_engraver
1414 but if we add the Ambitus engraver to the
1415 @context{Staff} context it calculates the range from all
1416 the notes in all the voices on that staff:
1418 @lilypond[quote,verbatim,ragged-right]
1420 \consists Ambitus_engraver
1437 @node Extending the templates
1438 @section Extending the templates
1440 You've read the tutorial, you know how to write music, you
1441 understand the fundamental concepts. But how can you
1442 get the staves that you want? Well, you can find lots of
1443 templates (see @ref{Templates}) which may give you a start.
1445 if you want something that isn't covered there? Read on.
1448 * Soprano and cello::
1449 * Four-part SATB vocal score::
1450 * Building a score from scratch::
1453 @node Soprano and cello
1454 @subsection Soprano and cello
1456 Start off with the template that seems closest to what you want to end
1457 up with. Let's say that you want to write something for soprano and
1458 cello. In this case, we would start with @q{Notes and lyrics} (for the
1463 melody = \relative c' @{
1471 text = \lyricmode @{
1477 \new Voice = "one" @{
1481 \new Lyrics \lyricsto "one" \text
1488 Now we want to add a cello part. Let's look at the @q{Notes only} example:
1492 melody = \relative c' @{
1507 We don't need two @code{\version} commands. We'll need the @code{melody}
1508 section. We don't want two @code{\score} sections -- if we had two
1509 @code{\score}s, we'd get the two parts separately. We want them together,
1510 as a duet. Within the @code{\score} section, we don't need two
1511 @code{\layout} or @code{\midi}.
1513 If we simply cut and paste the @code{melody} section, we would end up with
1514 two @code{melody} sections. So let's rename them. We'll call the section
1515 for the soprano @code{sopranoMusic} and the section for the cello
1516 @code{celloMusic}. While we're doing this, let's rename @code{text}
1517 to be @code{sopranoLyrics}. Remember to rename both instances of all
1518 these names -- both the initial definition (the
1519 @code{melody = relative c' @{ } part) and the name's use (in the
1520 @code{\score} section).
1522 While we're doing this, let's change the cello part's staff -- celli
1523 normally use bass clef. We'll also give the cello some different
1528 sopranoMusic = \relative c' @{
1536 sopranoLyrics = \lyricmode @{
1540 celloMusic = \relative c @{
1550 \new Voice = "one" @{
1554 \new Lyrics \lyricsto "one" \sopranoLyrics
1561 This is looking promising, but the cello part won't appear in the
1562 score -- we haven't used it in the @code{\score} section. If we
1563 want the cello part to appear under the soprano part, we need to add
1566 \new Staff \celloMusic
1570 underneath the soprano stuff. We also need to add @code{<<} and
1571 @code{>>} around the music -- that tells LilyPond that there's
1572 more than one thing (in this case, two @code{Staves}) happening
1573 at once. The @code{\score} looks like this now
1575 @c Indentation in this example is deliberately poor
1580 \new Voice = "one" @{
1584 \new Lyrics \lyricsto "one" \sopranoLyrics
1586 \new Staff \celloMusic
1594 This looks a bit messy; the indentation is messed up now. That is
1595 easily fixed. Here's the complete soprano and cello template.
1597 @lilypond[quote,verbatim,ragged-right]
1599 sopranoMusic = \relative c' {
1607 sopranoLyrics = \lyricmode {
1611 celloMusic = \relative c {
1622 \new Voice = "one" {
1626 \new Lyrics \lyricsto "one" \sopranoLyrics
1628 \new Staff \celloMusic
1636 @node Four-part SATB vocal score
1637 @subsection Four-part SATB vocal score
1639 Most vocal scores of music written for four-part mixed choir
1640 with orchestral accompaniment such as Mendelssohn's Elijah or
1641 Handel's Messiah have the choral music and words on four
1642 staves, one for each of SATB, with a piano reduction of the
1643 orchestral accompaniment underneath. Here's an example
1644 from Handel's Messiah:
1646 @c The following should appear as music without code
1647 @lilypond[quote,ragged-right]
1649 global = { \key d \major \time 4/4 }
1650 sopMusic = \relative c'' {
1652 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
1654 sopWords = \lyricmode {
1655 Wor -- thy is the lamb that was slain
1657 altoMusic = \relative a' {
1659 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
1661 altoWords = \sopWords
1662 tenorMusic = \relative c' {
1664 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
1666 tenorWords = \sopWords
1667 bassMusic = \relative c' {
1669 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
1671 bassWords = \sopWords
1672 upper = \relative a' {
1675 r4 <a d fis>2 <a e' a>4 |
1676 <d fis d'>4. <d fis d'>8 <a d a'>2 |
1677 <g cis g'>4 <a d fis> <a cis e>2 |
1679 lower = \relative c, {
1682 <d d'>4 <d d'>2 <cis cis'>4 |
1683 <b b'>4. <b' b'>8 <fis fis'>2 |
1684 <e e'>4 <d d'> <a' a'>2 |
1688 << % combine ChoirStaff and PianoStaff in parallel
1690 \new Staff = "sopranos" <<
1691 \set Staff.instrumentName = "Soprano"
1692 \new Voice = "sopranos" { \global \sopMusic }
1694 \new Lyrics \lyricsto "sopranos" { \sopWords }
1695 \new Staff = "altos" <<
1696 \set Staff.instrumentName = "Alto"
1697 \new Voice = "altos" { \global \altoMusic }
1699 \new Lyrics \lyricsto "altos" { \altoWords }
1700 \new Staff = "tenors" <<
1701 \set Staff.instrumentName = "Tenor"
1702 \new Voice = "tenors" { \global \tenorMusic }
1704 \new Lyrics \lyricsto "tenors" { \tenorWords }
1705 \new Staff = "basses" <<
1706 \set Staff.instrumentName = "Bass"
1707 \new Voice = "basses" { \global \bassMusic }
1709 \new Lyrics \lyricsto "basses" { \bassWords }
1713 \set PianoStaff.instrumentName = "Piano "
1714 \new Staff = "upper" \upper
1715 \new Staff = "lower" \lower
1721 None of the templates provides this layout exactly. The
1722 nearest is @q{SATB vocal score and automatic piano reduction},
1723 but we shall need to change the layout and add a piano
1724 accompaniment which is not derived automatically from the
1725 vocal parts. The variables holding the music and words for
1726 the vocal parts are fine, but we shall need to add variables for
1727 the piano reduction.
1729 The order in which the contexts appear in the ChoirStaff of
1730 the template do not correspond with the order in the vocal
1731 score shown above. We need to rearrange them so there are
1732 four staves with the words written directly underneath the
1733 notes for each part.
1734 All the voices should be @code{voiceOne}, which is
1735 the default, so the @code{\voiceXXX} commands can be removed.
1736 We also need to specify the tenor clef for the tenors.
1737 The way in which lyrics are specified has also been simplified
1738 as we have not yet encountered the method used in the template.
1739 We've also added the names of each staff.
1741 Doing this gives for our ChoirStaff:
1745 \new Staff = "sopranos" <<
1746 \set Staff.instrumentName = "Soprano"
1747 \new Voice = "sopranos" @{ \global \sopMusic @}
1749 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
1750 \new Staff = "altos" <<
1751 \set Staff.instrumentName = "Alto"
1752 \new Voice = "altos" @{ \global \altoMusic @}
1754 \new Lyrics \lyricsto "altos" @{ \altoWords @}
1755 \new Staff = "tenors" <<
1756 \set Staff.instrumentName = "Tenor"
1757 \new Voice = "tenors" @{ \global \tenorMusic @}
1759 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
1760 \new Staff = "basses" <<
1761 \set Staff.instrumentName = "Bass"
1762 \new Voice = "basses" @{ \global \bassMusic @}
1764 \new Lyrics \lyricsto "basses" @{ \bassWords @}
1768 Next we must work out the piano part. This is
1769 easy - we just pull out the piano part from the
1770 @q{Solo piano} template:
1774 \set PianoStaff.instrumentName = "Piano "
1775 \new Staff = "upper" \upper
1776 \new Staff = "lower" \lower
1780 and add the variable definitions for @code{upper}
1783 The ChoirStaff and PianoStaff must be combined
1784 using angle brackets as we want them to be
1785 stacked one above the other:
1788 << % combine ChoirStaff and PianoStaff one above the other
1790 \new Staff = "sopranos" <<
1791 \new Voice = "sopranos" @{ \global \sopMusic @}
1793 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
1794 \new Staff = "altos" <<
1795 \new Voice = "altos" @{ \global \altoMusic @}
1797 \new Lyrics \lyricsto "altos" @{ \altoWords @}
1798 \new Staff = "tenors" <<
1799 \clef "G_8" % tenor clef
1800 \new Voice = "tenors" @{ \global \tenorMusic @}
1802 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
1803 \new Staff = "basses" <<
1805 \new Voice = "basses" @{ \global \bassMusic @}
1807 \new Lyrics \lyricsto "basses" @{ bassWords @}
1811 \set PianoStaff.instrumentName = "Piano "
1812 \new Staff = "upper" \upper
1813 \new Staff = "lower" \lower
1818 Combining all these together and adding the music
1819 for the three bars of the example above gives:
1821 @lilypond[quote,verbatim,ragged-right]
1823 global = { \key d \major \time 4/4 }
1824 sopMusic = \relative c'' {
1826 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
1828 sopWords = \lyricmode {
1829 Wor -- thy is the lamb that was slain
1831 altoMusic = \relative a' {
1833 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
1835 altoWords = \sopWords
1836 tenorMusic = \relative c' {
1838 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
1840 tenorWords = \sopWords
1841 bassMusic = \relative c' {
1843 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
1845 bassWords = \sopWords
1846 upper = \relative a' {
1849 r4 <a d fis>2 <a e' a>4 |
1850 <d fis d'>4. <d fis d'>8 <a d a'>2 |
1851 <g cis g'>4 <a d fis> <a cis e>2 |
1853 lower = \relative c, {
1856 <d d'>4 <d d'>2 <cis cis'>4 |
1857 <b b'>4. <b' b'>8 <fis fis'>2 |
1858 <e e'>4 <d d'> <a' a'>2 |
1862 << % combine ChoirStaff and PianoStaff in parallel
1864 \new Staff = "sopranos" <<
1865 \set Staff.instrumentName = "Soprano"
1866 \new Voice = "sopranos" { \global \sopMusic }
1868 \new Lyrics \lyricsto "sopranos" { \sopWords }
1869 \new Staff = "altos" <<
1870 \set Staff.instrumentName = "Alto"
1871 \new Voice = "altos" { \global \altoMusic }
1873 \new Lyrics \lyricsto "altos" { \altoWords }
1874 \new Staff = "tenors" <<
1875 \set Staff.instrumentName = "Tenor"
1876 \new Voice = "tenors" { \global \tenorMusic }
1878 \new Lyrics \lyricsto "tenors" { \tenorWords }
1879 \new Staff = "basses" <<
1880 \set Staff.instrumentName = "Bass"
1881 \new Voice = "basses" { \global \bassMusic }
1883 \new Lyrics \lyricsto "basses" { \bassWords }
1887 \set PianoStaff.instrumentName = "Piano "
1888 \new Staff = "upper" \upper
1889 \new Staff = "lower" \lower
1896 @node Building a score from scratch
1897 @subsection Building a score from scratch
1899 After gaining some facility with writing LilyPond code you
1900 may find that it is easier to build a score from scratch
1901 rather than modifying one of the templates. You can also
1902 develop your own style this way to suit the sort of music you
1903 like. Let's see how to put together the score for an organ
1904 prelude as an example.
1906 We begin with a header section. Here go the title, name
1907 of composer, etc, then come any variable definitions, and
1908 finally the score block. Let's start with these in outline
1909 and fill in the details later.
1911 We'll use the first two bars of Bach's prelude
1912 based on @emph{Jesu, meine Freude} which is written for two
1913 manuals and pedal organ. The top manual part has two voices,
1914 the lower and pedal organ one each. So we need four
1915 music definitions and one to define the time signature
1921 title = "Jesu, meine Freude"
1922 composer = "J S Bach"
1924 TimeKey = @{ \time 4/4 \key c \minor @}
1925 ManualOneVoiceOneMusic = @{s1@}
1926 ManualOneVoiceTwoMusic = @{s1@}
1927 ManualTwoMusic = @{s1@}
1928 PedalOrganMusic = @{s1@}
1934 For now we've just used a spacer note, @code{s1},
1935 instead of the real music. We'll add that later.
1937 Next let's see what should go in the score block.
1938 We simply mirror the staff structure we want.
1939 Organ music is usually written on three staves,
1940 one for each manual and one for the pedals. The
1941 manual staves should be bracketed together so we
1942 need to use a PianoStaff for them. The first
1943 manual part needs two voices and the second manual
1948 \new Staff = "ManualOne" <<
1949 \new Voice @{ \ManualOneVoiceOneMusic @}
1950 \new Voice @{ \ManualOneVoiceTwoMusic @}
1951 >> % end ManualOne Staff context
1952 \new Staff = "ManualTwo" <<
1953 \new Voice @{ \ManualTwoMusic @}
1954 >> % end ManualTwo Staff context
1955 >> % end PianoStaff context
1958 Next we need to add a staff for the pedal organ.
1959 This goes underneath the PianoStaff, but it must
1960 be simultaneous with it, so we need angle brackets
1961 round the two. Missing these out would generate
1962 an error in the log file. It's a common mistake
1963 which you'll make sooner or later! Try copying
1964 the final example at the end of this section,
1965 remove these angle brackets, and compile it to
1966 see what errors it generates.
1969 << % PianoStaff and Pedal Staff must be simultaneous
1971 \new Staff = "ManualOne" <<
1972 \new Voice @{ \ManualOneVoiceOneMusic @}
1973 \new Voice @{ \ManualOneVoiceTwoMusic @}
1974 >> % end ManualOne Staff context
1975 \new Staff = "ManualTwo" <<
1976 \new Voice @{ \ManualTwoMusic @}
1977 >> % end ManualTwo Staff context
1978 >> % end PianoStaff context
1979 \new Staff = "PedalOrgan" <<
1980 \new Voice @{ \PedalOrganMusic @}
1985 It is not strictly necessary to use the simultaneous contruct
1986 @code{<< >>} for the manual two staff and the pedal organ staff,
1987 since they contain only one music expression, but it does no harm
1988 and always using angle brackets after @code{\new Staff} is a good
1989 habit to cultivate in case there are multiple voices.
1991 Let's add this structure to the score block, and adjust the
1992 indenting. We also add the appropriate clefs, ensure the
1993 second voice stems point down with @code{\voiceTwo} and
1994 enter the time signature and key to each staff using our
1995 predefined variable, @code{\TimeKey}.
1999 << % PianoStaff and Pedal Staff must be simultaneous
2001 \new Staff = "ManualOne" <<
2002 \TimeKey % set time signature and key
2004 \new Voice @{ \ManualOneVoiceOneMusic @}
2005 \new Voice @{ \voiceTwo \ManualOneVoiceTwoMusic @}
2006 >> % end ManualOne Staff context
2007 \new Staff = "ManualTwo" <<
2010 \new Voice @{ \ManualTwoMusic @}
2011 >> % end ManualTwo Staff context
2012 >> % end PianoStaff context
2013 \new Staff = "PedalOrgan" <<
2016 \new Voice @{ \PedalOrganMusic @}
2017 >> % end PedalOrgan Staff
2019 @} % end Score context
2022 That completes the structure. Any three-staff organ music
2023 will have a similar structure, although the number of voices
2024 may vary. All that remains now
2025 is to add the music, and combine all the parts together.
2027 @lilypond[quote,verbatim,ragged-right]
2030 title = "Jesu, meine Freude"
2031 composer = "J S Bach"
2033 TimeKey = { \time 4/4 \key c \minor }
2034 ManualOneVoiceOneMusic = \relative g' {
2035 g4 g f ees | d2 c2 |
2037 ManualOneVoiceTwoMusic = \relative c' {
2038 ees16 d ees8~ ees16 f ees s c8 d~ d c~ |
2039 c c4 b8 c8. g16 c b c d |
2041 ManualTwoMusic = \relative c' {
2042 c16 b c8~ c16 b c g a8 g~ g16 g aes ees |
2043 f ees f d g aes g f ees d e8~ ees16 f ees d |
2045 PedalOrganMusic = \relative c {
2046 r8 c16 d ees d ees8~ ees16 a, b g c b c8 |
2047 r16 g ees f g f g8 c,2 |
2051 << % PianoStaff and Pedal Staff must be simultaneous
2053 \new Staff = "ManualOne" <<
2054 \TimeKey % set time signature and key
2056 \new Voice { \ManualOneVoiceOneMusic }
2057 \new Voice { \voiceTwo \ManualOneVoiceTwoMusic }
2058 >> % end ManualOne Staff context
2059 \new Staff = "ManualTwo" <<
2062 \new Voice { \ManualTwoMusic }
2063 >> % end ManualTwo Staff context
2064 >> % end PianoStaff context
2065 \new Staff = "PedalOrgan" <<
2068 \new Voice { \PedalOrganMusic }
2069 >> % end PedalOrgan Staff
2071 } % end Score context