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. However, 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
119 Another great shorthand is the ability to define variables. All
120 the templates use this
123 melody = \relative c' @{
132 When LilyPond looks at this file, it takes the value of
133 @code{melody} (everything after the equals sign) and inserts it
134 whenever it sees @code{\melody}. There's nothing special about
135 the names -- it could be @code{melody}, @code{global},
136 @code{pianorighthand}, or @code{foofoobarbaz}. You can use
137 whatever variable names you want as along as they contain just
138 alphabetic characters. For more details, see
139 @ruser{Saving typing with variables and functions}.
144 For a complete definition of the input format, see
145 @ruser{File structure}.
147 @node Score is a (single) compound musical expression
148 @subsection Score is a (single) compound musical expression
150 @cindex Compound music expression
151 @cindex Music expression, compound
153 We saw the general organization of LilyPond input files in the
154 previous section, @ref{How LilyPond files work}. But we seemed to
155 skip over the most important part: how do we figure out what to
156 write after @code{\score}?
158 We didn't skip over it at all. The big mystery is simply that
159 there @emph{is} no mystery. This line explains it all:
162 @emph{A @code{\score} must begin with a compound music expression.}
166 You may find it useful to review
167 @ref{Music expressions explained}. In that section, we saw how to
168 build big music expressions from small pieces -- we started from
169 notes, then chords, etc. Now we're going to start from a big
170 music expression and work our way down.
174 @{ % this brace begins the overall compound music expression
176 @var{...insert the whole score of a Wagner opera in here...}
178 @} % this brace ends the overall compound music expression
183 A whole Wagner opera would easily double the length of this
184 manual, so let's just add a singer and piano. We don't need a
185 @code{GrandStaff} for this ensemble, so we shall remove it. We
186 @emph{do} need a singer and a piano, though.
192 \new Staff = "singer" <<
194 \new PianoStaff = piano <<
202 Remember that we use @code{<<} and @code{>>} to show simultaneous
203 music. And we definitely want to show the vocal part and piano
204 part at the same time, not one after the other! However, the
205 @code{<< .. >>} construct is not really necessary for the Singer
206 staff, as it contains only one music expression, but Staves often
207 do require simultaneous Voices within them, so using @code{<< .. >>}
208 rather than braces is a good habit to adopt.
214 \new Staff = "singer" <<
215 \new Voice = "vocal" @{ @}
217 \new Lyrics \lyricsto vocal \new Lyrics @{ @}
218 \new PianoStaff = "piano" <<
219 \new Staff = "upper" @{ @}
220 \new Staff = "lower" @{ @}
228 Now we have a lot more details. We have the singer's staff: it
229 contains a @code{Voice} (in LilyPond, this term refers to a set of
230 notes, not necessarily vocal notes -- for example, a violin
231 generally plays one voice) and some lyrics. We also have a piano
232 staff: it contains an upper staff (right hand) and a lower staff
235 At this stage, we could start filling in notes. Inside the curly
236 braces next to @code{\new Voice = vocal}, we could start writing
244 But if we did that, the @code{\score} section would get pretty
245 long, and it would be harder to understand what was happening. So
246 let's use variables instead.
256 \new Staff = "singer" <<
257 \new Voice = "vocal" @{ \melody @}
259 \new Lyrics \lyricsto vocal \new Lyrics @{ \text @}
260 \new PianoStaff = "piano" <<
261 \new Staff = "upper" @{ \upper @}
262 \new Staff = "lower" @{ \lower @}
271 Remember that you can use almost any name you like as long
272 as it contains just alphabetic characters. The exact
273 limitations on variable names are detailed in
274 @ruser{File structure}.
276 When writing (or reading) a @code{\score} section, just take it
277 slowly and carefully. Start with the outer layer, then work on
278 each smaller layer. It also really helps to be strict with
279 indentation -- make sure that each item on the same layer starts
280 on the same horizontal position in your text editor.
283 @node Nesting Music Expressions
284 @subsection Nesting Music Expressions
286 New staves do not have to all be declared at the beginning;
287 they may be introduced temporarily at any point. This is
288 particularly useful for creating ossia sections
289 (see @rglos{ossia}). Here's a simple example showing how
290 to introduce a new staff temporarily for the duration of
293 @lilypond[verbatim,quote,ragged-right]
309 The ossia section may be placed above the staff
312 @lilypond[verbatim,quote,ragged-right]
320 alignAboveContext = "main" }
328 This example uses @code{\with}, which will be explained more
329 fully later. It is a means of modifying the default behaviour
330 of a Staff. Here it says that the new staff should be placed
331 above the staff called @qq{main} instead of the default position
334 Ossia are often written without clef and without
335 time signature and are usually in a smaller font.
336 These require further commands which
337 have not yet been introduced. See ...
338 TODO Add ref to tweaks section where this example should
339 be placed and explained.
341 @lilypond[verbatim,quote,ragged-right]
342 \new Staff = "main" {
346 << % Start main and ossia in parallel
347 { r8 f c c } % Main music
348 \new Staff \with { % Start ossia staff
349 \remove "Clef_engraver"
350 \remove "Time_signature_engraver"
351 % Reduce size of notes and staff
353 \override StaffSymbol #'staff-space = #(magstep -2)
354 alignAboveContext = "main" % Place above main staff
356 { s8 f f c } % Ossia music
357 >> % End parallel music
363 @node On the un-nestedness of brackets and ties
364 @subsection On the un-nestedness of brackets and ties
366 You have already met a number of different types of bracket in
367 writing the input file to LilyPond. These obey different rules
368 which can be confusing at first. Before we explain the rules
369 let's first review the different types of bracket.
371 @multitable @columnfractions .3 .7
372 @headitem Bracket Type
374 @item @code{@{ .. @}}
375 @tab Encloses a sequential segment of music
377 @tab Encloses the notes of a chord
378 @item @code{<< .. >>}
379 @tab Encloses concurrent or simultaneous sections
381 @tab Marks the start and end of a slur
382 @item @code{\( .. \)}
383 @tab Marks the start and end of a phrase mark
385 @tab Marks the start and end of a manual beam
388 To these we should add other constructs which generate lines
389 between or across notes: ties (marked by a tilde, @code{~}),
390 tuplets written as @code{\times x/y @{ .. @}}, and grace notes
391 written as @code{\grace@{ .. @}}.
393 Outside LilyPond, the conventional use of brackets requires
394 the different types to be properly nested, like this,
395 @code{<< @{ ( .. ) @} >>}, with the closing brackets being
396 encountered in exactly the opposite order to the opening
397 brackets. This @strong{is} a requirement for the three types of
398 bracket described by the word @q{Encloses} in the table above -
399 they must nest properly.
400 However, the remaining brackets, described with the word
401 @q{Marks} in the table above together with ties and tuplets,
402 do @strong{not} have to nest
403 properly with any of the brackets. In fact, these are not
404 brackets in the sense that
405 they enclose something - they are simply markers to indicate
406 where something starts and ends.
408 So, for example, a phrasing slur can start before a manually
409 inserted beam and end before the end of the beam - not very
410 musical, perhaps, but possible:
412 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
413 { g8\( a b[ c b\) a] }
416 In general, different kinds of brackets, and those implied by
417 tuplets, ties and grace notes, may be mixed freely.
418 This example shows a beam extending into a tuplet (line 1),
419 a slur extending into a tuplet (line 2),
420 a beam and a slur extending into a tuplet, a tie crossing
421 two tuplets, and a phrasing slur extending out of a tuplet
424 @lilypond[quote,verbatim,fragment,ragged-right]
426 r16[ g16 \times 2/3 {r16 e'8] }
427 g16( a \times 2/3 {b d) e' }
428 g8[( a \times 2/3 {b d') e'~]}
429 \times 4/5 {e'32\( a b d' e'} a'4.\)
434 @node Voices contain music
435 @section Voices contain music
437 Singers need voices to sing, and so does LilyPond.
438 The actual music for all instruments in a score
439 is contained in Voices - the most fundamental
440 of all LilyPond's concepts.
443 * I'm hearing Voices::
444 * Explicitly instantiating voices::
445 * Voices and vocals::
448 @node I'm hearing Voices
449 @subsection I'm hearing Voices
453 @cindex Voice context
455 The lowest, most fundamental or innermost layers in a LilyPond
456 score are called @q{Voice contexts} or just @q{Voices} for short.
457 Voices are sometimes called @q{layers} in other notation
460 In fact, a Voice layer or context is the only one which can
461 contain music. If a Voice context is not explicitly declared
462 one is created automatically. Some instruments such as an
463 Oboe can play only one note at a time. Music written for
464 such instruments is monophonic and requires just a single
465 voice. Instruments which can play more than one note at a
466 time like the piano will often require multiple voices to
467 encode the different concurrent notes and rhythms they are
470 A single voice can contain many notes in a chord, of course,
471 so when exactly are multiple voices needed?
472 Let us analyse a short piece of music to see how many voices
473 are required. Here are the notes from the first two bars
474 of the second of Chopin's Deux Nocturnes, Op 32.
476 @c The following should appear as music without code
477 @lilypond[quote,ragged-right]
478 \new Staff \relative c'' {
486 \once \override NoteColumn #'force-hshift = #0 <ees c>2
487 \once \override NoteColumn #'force-hshift = #0.5 des2 }
493 The direction of the stems is often used to indicate the
494 continuity of two simultaneous melodic lines. Here the
495 stems of the highest notes are all pointing up and the
496 stems of the lower notes are all pointing down.
497 This is the first indication that more than one voice
500 But the real need for multiple voices arises when notes
501 which start at the same time have different durations.
502 Look at the notes which start at beat three in the first
503 bar. The a-flat is a dotted quarter note, the f is a
504 quarter note and the d-flat is a half note. These
505 cannot be written as a chord as all the notes in a chord
506 must have the same duration. Neither can they be written
507 as sequential notes, as they must start at the same time.
508 This section of the bar requires three voices, and the
509 normal practice would be to write the whole bar as three
510 voices, as shown here, where we have used different noteheads
511 and colors for the three voices.
513 @c The following should appear as music without code
514 @c The three voice styles should be defined in -init
515 @lilypond[quote,ragged-right]
516 \new Staff \relative c'' {
527 \once \override NoteColumn #'force-hshift = #0 <ees c>2
528 \once \override NoteColumn #'force-hshift = #0.5 des2 }
534 Let us see how this is done.
538 The easiest way to enter fragments with more than one voice on a
539 staff is to enter each voice as a sequence (with @code{@{...@}}),
540 and combine them simultaneously with angle brackets, @code{<<...>>}.
541 The fragments must also be separated with double backward slashes,
542 @code{\\}, to place them in separate voices. Without these, the
543 notes would be entered into a single voice, which would usually
544 cause errors. This technique is particularly suited to pieces of
545 music which are largely monophonic with occasional short sections
546 of polyphony. Here's a simple example:
548 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
550 % Voice "1" Voice "2"
551 << { r4 g g4. a8 } \\ { d,2 d4 g } >> |
552 << { bes4 bes c bes } \\ { g4 g g8( a) g4 } >> |
553 << { a2. r4 } \\ { fis2. s4 } >>
556 This example has just two voices, but the same contruct may be
557 used to encode three or more voices by adding more back-slash
560 The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
561 In each of these contexts, vertical direction of slurs, stems, ties,
562 dynamics etc., is set appropriately.
564 @lilypond[quote,verbatim,fragment]
565 \new Staff \relative c' {
568 % Voice "1" Voice "2" Voice "3"
569 << { g4 f e } \\ { r8 e4 d c8 ~ } >> |
570 << { d2 e2 } \\ { c8 b16 a b8 g ~ g2 } \\ { s4 b4 c2 } >> |
574 These voices are all separate from the main voice that contains
575 the notes just outside the @code{<< .. >>} construct. Let's call
576 this the @emph{simultaneous construct}. Slurs and ties may only
577 connect notes within the same voice, so slurs and ties cannot go
578 into or out of a simultaneous construct. Conversely,
579 parallel voices from separate simultaneous constructs on the same
580 staff are the same voice. Other voice-related properties also
581 carry across simultaneous constructs. Here is the same example,
582 with different colors and noteheads for each voice. Note that
583 changes in one Voice do not affect other voices, but they do
584 persist in the same Voice later. Note also that tied notes may be
585 split across the same voices in two constructs, shown here in the
588 @lilypond[quote,verbatim]
589 \new Staff \relative c' {
599 { c8 b16 a b8 g ~ g2 } \\
606 The commands @code{\voiceXXXStyle} are mainly intended for use in
607 educational documents such as this one. They modify the color
608 of the notehead, the stem and the beams, and the style of the
609 notehead, so that the voices may be easily distinguished.
610 Voice one is set to red diamonds, voice two to blue triangles,
611 voice four to green crossed circles, and voice four (not used
612 here) to magenta crosses. We shall see later how commands like
613 these may be created by the user.
614 TODO: add ref to appropriate section in Tweaks
616 Polyphony does not change the relationship of notes within a
617 @code{\relative @{ @}} block. Each note is still calculated
618 relative to the note immediately preceding it, or to the first
619 note of the preceding chord. So in
622 \relative c' @{ noteA << <noteB noteC> \\ noteD >> noteE @}
625 @code{noteB} is relative to @code{noteA} @*
626 @code{noteC} is relative to @code{noteB}, not @code{noteA}; @*
627 @code{noteD} is relative to @code{noteB}, not @code{noteA} or
629 @code{noteE} is relative to @code{noteD}, not @code{noteA}
631 We are now in a position to return to the first example from
632 the Chopin Nocturne to see how this might be encoded. As we
633 shall see, this encounters some difficulties. We begin as
634 we have learnt, using the @code{<< \\ >>} construct to
635 enter the music of the first bar in three voices:
637 @lilypond[quote,verbatim,fragment,ragged-right]
638 \new Staff \relative c'' {
641 { c2 aes4. bes8 } \\ { aes2 f4 fes } \\ { <ees c>2 des2 }
651 @funindex \voiceThree
654 The stem directions are automatically assigned with the
655 odd-numbered voices taking upward stems and the even-numbered
656 voices downward ones. The stems for voices 1 and 2 are right,
657 but the stems in voice 3 should go down in this particular piece
658 of music. We can correct this
659 by telling LilyPond that this third voice is really a fourth
660 voice, with stems going down, using the @code{\voiceFour}
661 command. There are also corresponding @code{\voiceOne},
662 @code{\voiceTwo}, @code{voiceThree} and @code{voiceFour}
663 commands. This results in the following:
665 @lilypond[quote,verbatim,fragment,ragged-right]
666 \new Staff \relative c'' {
671 { \voiceFour <ees c>2 des2 }
678 and exposes a problem commonly encountered with multiple
679 voices: the stems of notes can collide with noteheads
680 in other voices. In laying out the notes, LilyPond allows the
681 notes or chords from two voices to occupy the same vertical
682 note column provided the stems are in opposite directions, but
683 the notes from a third voice are displaced to avoid the stems
684 colliding. This often works well, but in this example the
685 notes of the third voice are clearly not well placed by default.
686 LilyPond provides several ways to adjust the horizontal placing
687 of notes. We are not quite ready yet to see how to correct this,
688 so we shall leave this problem until a later section (see ... )
692 @node Explicitly instantiating voices
693 @subsection Explicitly instantiating voices
695 Voice contexts can also be created manually
696 inside a @code{<< >>} block to create polyphonic music, using
697 @code{\voiceOne} ... @code{\voiceFour} to indicate the required
698 directions of stems, slurs, etc.
700 Specifically, the construct @code{<< \\ >>} which we used in
701 the previous section:
704 << \upper \\ \lower >>
708 where @code{upper} and @code{lower} are user-defined variables
709 containing the music for the two voices, is equivalent to
713 \new Voice = "1" @{ \voiceOne \upper @}
714 \new Voice = "2" @{ \voiceTwo \lower @}
718 The @code{\voiceXXX} commands set the direction of stems, slurs,
719 ties, articulations, text annotations, augmentation dots of dotted
720 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
721 make these objects point upwards, while @code{\voiceTwo} and
722 @code{\voiceFour} make them point downwards. These commands also
723 generate a horizontal shift for each voice when this is required
724 to avoid clashes of note heads. The command @code{\oneVoice}
725 reverts the settings back to the normal values for a single voice.
727 Let us see in a simple example exactly what effect
728 @code{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on
729 markup, ties, slurs, and dynamics:
731 @lilypond[quote,ragged-right,verbatim]
733 c-"default" d8 ~ d e4 ( f g a ) b-> c \break
735 c,-"\\voiceOne" d8 ~ d e4 ( f g a ) b-> c \break
737 c,-"\\oneVoice" d8 ~ d e4 ( f g a ) b-> c \break
739 c,-"\\voiceTwo" d8 ~ d e4 ( f g a ) b-> c \break
743 An expression that appears directly inside a @code{<< >>} belongs
744 to the main voice. This is useful when extra voices appear while
745 the main voice is playing. Here is a more correct rendition of
746 the example from the previous section. The red diamond-shaped
747 notes demonstrate that the main melody is now in a single
748 voice context, permitting a phrasing slur to be drawn over them.
750 @lilypond[quote,ragged-right,verbatim]
751 \new Staff \relative c' {
753 c16^( d e f % These notes are monophonic
754 << % Start simultaneous section of three voices
755 { g4 f e | d2 e2) } % Continue the main voice in parallel
756 \new Voice { % Initiate second voice
757 \voiceTwo % Set stems, etc, down
758 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
760 \new Voice { % Initiate third voice
761 \voiceThree % Set stems, etc, up
768 @cindex nesting music expressions
769 @cindex nesting simultaneous constructs
771 More deeply nested polyphony constructs are possible, and if a
772 voice appears only briefly this might be a more natural way to
775 @lilypond[quote,ragged-right,verbatim]
776 \new Staff \relative c' {
796 This method of nesting new voices briefly is useful
797 when only small sections of the music
798 are polyphonic, but when the whole staff is largely polyphonic
799 it can be clearer to use multiple voices throughout, using
800 spacing notes to step over sections where the voice is silent,
803 @lilypond[quote,ragged-right,verbatim]
804 \new Staff \relative c' <<
805 \new Voice { % Initiate first voice
807 c16^( d e f g4 f e | d2 e2) |
809 \new Voice { % Initiate second voice
810 \voiceTwo % set stems, etc down
811 s4 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 |
813 \new Voice { % Initiate third voice
814 \voiceThree % set stems, etc up
821 @node Voices and vocals
822 @subsection Voices and vocals
824 Vocal music presents a special difficulty: we need to combine two
825 expressions -- notes and lyrics.
827 You have already seen the @code{\lyricsAdd@{@}} command, which
828 handles simple cases for you. However, this technique is
829 very limited. For most music, you must explicitly link the lyrics
830 to the notes with @code{\lyricsto@{@}}, using the name assigned
833 @lilypond[quote,verbatim,fragment]
835 \new Voice = "one" \relative c'' {
838 c4 b8. a16 g4. f8 e4 d c2
840 \new Lyrics \lyricsto "one" {
841 No more let sins and sor -- rows grow.
846 The automatic beaming which LilyPond uses by default works well
847 for instrumental music, but not so well for music with lyrics,
848 where beaming is either not required at all or is used to indicate
849 melismata in the lyrics. In the example above we use the command
850 @code{\autoBeamOff} to turn off the automatic beaming.
852 Let us reuse the earlier example from Judas Maccabæus to
853 illustrate this more flexible technique. We first recast
854 it to use variables so the music and lyrics can be separated
855 from the staff structure. We also introduce a choirstaff
856 bracket. The lyrics themselves must be introduced with
857 @code{\lyricmode} to ensure they are interpreted as lyrics
860 @lilypond[quote,verbatim]
861 global = { \time 6/8 \partial 8 \key f \major}
862 SopOneMusic = \relative c'' {
863 c8 | c([ bes)] a a([ g)] f | f'4. b, | c4.~ c4 }
864 SopTwoMusic = \relative c' {
865 r8 | r4. r4 c8 | a'([ g)] f f([ e)] d | e([ d)] c bes' }
866 SopOneLyrics = \lyricmode {
867 Let | flee -- cy flocks the | hills a -- dorn, __ }
868 SopTwoLyrics = \lyricmode {
869 Let | flee -- cy flocks the | hills a -- dorn, }
874 \new Voice = "SopOne" {
878 \new Lyrics \lyricsto "SopOne" {
883 \new Voice = "SopTwo" {
886 \new Lyrics \lyricsto "SopTwo" {
894 This is the basic structure of all vocal scores. More staves may
895 be added as required, more voices may be added to the staves,
896 more verses may be added to the lyrics,
897 and the variables containing the music can easily be placed
898 in separate files should they become too long.
900 Here is a final example of the first line of a hymn with four
901 verses, set for SATB. In this case the words for all four
904 @lilypond[quote,verbatim]
905 global = { \time 4/4 \partial 4 \key c \major}
906 SopMusic = \relative c' { c4 | e4. e8 g4 g | a a g }
907 AltoMusic = \relative c' { c4 | c4. c8 e4 e | f f e }
908 TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 }
909 BassMusic = \relative c { c4 | c4. c8 c4 c | f8 g a b c4 }
910 VerseOne = \lyricmode {
911 E -- | ter -- nal fa -- ther, | strong to save, }
912 VerseTwo = \lyricmode {
913 O | Christ, whose voice the | wa -- ters heard, }
914 VerseThree = \lyricmode {
915 O | Ho -- ly Spi -- rit, | who didst brood }
916 VerseFour = \lyricmode {
917 O | Tri -- ni -- ty of | love and pow'r }
923 \new Voice = "Sop" { \voiceOne \global \SopMusic }
924 \new Voice = "Alto" { \voiceTwo \AltoMusic }
925 \new Lyrics \lyricsto "Sop" { \VerseOne }
926 \new Lyrics \lyricsto "Sop" { \VerseTwo }
927 \new Lyrics \lyricsto "Sop" { \VerseThree }
928 \new Lyrics \lyricsto "Sop" { \VerseFour }
932 \new Voice = "Tenor" { \voiceOne \TenorMusic }
933 \new Voice = "Bass" { \voiceTwo \BassMusic }
939 @node Contexts and engravers
940 @section Contexts and engravers
942 Contexts and engravers have been mentioned informally
943 in earlier sections; we now must look at
944 these concepts in more detail, as they are important
945 in the fine-tuning of LilyPond output.
949 * Contexts explained::
950 * Creating contexts::
952 * Modifying contexts::
955 @node Contexts explained
956 @subsection Contexts explained
958 When music is printed, many notational elements which do not
959 appear explicitly in the input file must be added to the
960 output. For example, compare the input and output of the
963 @lilypond[quote,verbatim,relative=2,fragment]
967 The input is rather sparse, but in the output, bar lines,
968 accidentals, clef, and time signature have been added. When
969 LilyPond @emph{interprets} the input the musical information
970 is inspected in time order, similar to reading a score from left
971 to right. While reading the input, the program remembers where
972 measure boundaries are, and which pitches require explicit
973 accidentals. This information must be held on several levels.
974 For example, the effect of an accidental is limited
975 to a single staff, while a bar line must be synchronized across
978 Within LilyPond, these rules and bits of information are grouped
979 in @emph{Contexts}. We have already met the @context{Voice}
981 Others are the @context{Staff} and @context{Score} contexts.
982 Contexts are hierarchical to reflect the heirarchical nature of
984 For example: a @context{Staff} context can contain many
985 @context{Voice} contexts, and a @context{Score} context can
986 contain many @context{Staff} contexts.
989 @image{context-example,5cm,,}
992 Each context has the responsibility for enforcing some notation rules,
993 creating some notation objects and maintaining the associated
994 properties. For example, the @context{Voice} context may introduce an
995 accidental and then the @context{Staff} context maintains the rule to
996 show or suppress the accidental for the remainder of the measure.
998 As another example, the synchronization of bar lines is by default
999 handled in the @context{Score} context.
1000 However, in some music we may not want the bar lines to be
1001 synchronized -- consider a polymetric score in 4/4 and 3/4 time.
1002 In such cases, we must modify the default settings of the
1003 @context{Score} and @context{Staff} contexts.
1005 For very simple scores, contexts are created implicitly, and you need
1006 not be aware of them. For larger pieces, such as anything with more
1007 than one staff, they must be
1008 created explicitly to make sure that you get as many staves as you
1009 need, and that they are in the correct order. For typesetting pieces
1010 with specialized notation, it is usual to modify existing or
1011 even to define totally new contexts.
1013 In addition to the @context{Score,} @context{Staff} and
1014 @context{Voice} contexts there are contexts which fit between
1015 the score and staff levels to control staff groups, such as the
1016 @context{PianoStaff} and @context{ChoirStaff} contexts. There
1017 are also alternative staff and voice contexts, and contexts for
1018 lyrics, percussion, fret boards, figured bass, etc. A complete
1019 list is shown in the Notation Reference.
1022 The names of all context types are formed from one or more
1023 words, each word being capitalised and joined immediately to the
1024 preceding word with no hyphen or underscore, e.g.,
1025 @context{GregorianTranscriptionStaff}.
1027 @node Creating contexts
1028 @subsection Creating contexts
1030 There can be only one top level context, the @context{Score}
1031 context. This is created with the @code{\score} command,
1032 or, in simple scores, it is created automatically.
1034 For scores with only one voice and one staff, the
1035 @context{Voice} and @context{Staff} contexts may be left to be
1036 created automatically, but for more complex scores it is
1037 necessary to create them by hand.
1038 The simplest command that does this is @code{\new}.
1039 It is prepended to a music expression, for example
1042 @cindex new contexts
1043 @cindex Context, creating
1046 \new @var{type} @var{music expression}
1050 where @var{type} is a context name (like @code{Staff} or
1051 @code{Voice}). This command creates a new context, and starts
1052 interpreting the @var{music expression} within that context.
1054 Note that there is no @code{\new Score % Invalid!} command;
1055 the single top-level @context{Score} context is introduced
1056 with @code{\score}. This is because there can be only one
1057 @context{Score} context, whereas there may be multiple
1058 @context{Staff} and @context{Voice} contexts - each created
1061 So a practical application of @code{\new} is a score with many
1062 staves. Each part that should be on its own staff is preceded
1063 with @code{\new Staff}.
1065 @lilypond[quote,verbatim,relative=2,ragged-right,fragment]
1072 The @code{\new} command may also give a identifying name to the
1073 context to distinguish it from other contexts of the same type,
1076 \new @var{type} = @var{id} @var{music}
1079 Note the distinction between the name of the context type,
1080 @context{Staff}, @context{Voice}, etc, and
1081 the identifying name of a particular instance of that type,
1082 which can be any sequence of letters invented by the user.
1083 The identifying name is used to refer back to that particular
1084 instance of a context. We saw this in use in the section on
1085 lyrics in @ref{Voices and vocals}.
1089 @subsection Engravers
1091 Every mark on the printed output of a score produced by LilyPond
1092 is produced by an @code{Engraver}. Thus there is an engraver
1093 to print staves, one to print noteheads, one for stems, one for
1094 beams, etc, etc. In total there are over 120 such engravers!
1095 Fortunately, for most scores it is not necessary to know about
1096 more than a few, and for simple scores you do not need to know
1099 A musical score can be viewed heirarchically. At the top level
1100 is the whole score. This consists of one or more staves.
1101 Each staff contains one or more voices. As we have seen, there
1102 are contexts which correspond to each of these levels and it
1103 is in these contexts that the Engravers operate.
1105 Engravers such as the @code{Metronome_mark_engraver}, whose
1106 action and output applies to the score as a whole, live in
1107 the highest level context - the @context{Score} context. There
1108 can be only one of these engravers as there can be only one tempo
1109 at any particular point in the score.
1111 The @code{Clef_engraver} and @code{Key_engraver} are to be
1112 found in the Staff Context, as different staves may require
1113 different clefs and keys.
1115 The @code{Note_heads_engraver} and @code{Stem_engraver} live
1116 in a @context{Voice} context, the lowest level context of all.
1118 Each engraver processes the particular objects associated
1119 with its function, and contains the properties that relate
1120 to that function. These properties, like the properties
1121 associated with contexts, may be modified to change the
1122 operation of the engraver or the appearance of those elements
1123 in the printed score.
1125 Engravers all have compound names formed from words which
1126 describe their function. Just the first word is capitalised,
1127 and the remainder are joined to it with underscores. Thus
1128 the @code{Staff_symbol_engraver} is responsible for creating the
1129 lines of the staff, the @code{Clef_engraver} determines and sets
1130 the pitch reference point on the staff by drawing a clef symbol.
1132 Here are some of the most common engravers together with their
1133 function. You will see it is easy to guess the function from
1134 the name, or vice versa.
1136 @multitable @columnfractions .3 .7
1139 @item Accidental_engraver
1140 @tab Makes accidentals, cautionary and suggested accidentals
1145 @item Dynamic_engraver
1146 @tab Creates hairpins and dynamic texts
1148 @tab Creates the key signature
1149 @item Metronome_mark_engraver
1150 @tab Engraves metronome marking
1151 @item Note_heads_engraver
1152 @tab Engraves noteheads
1155 @item Staff_symbol_engraver
1156 @tab Engraves the five (by default) lines of the staff
1158 @tab Creates stems and single-stem tremulos
1161 We shall see later how the output of LilyPond can be changed
1162 by modifying the action of Engravers.
1165 @node Modifying contexts
1166 @subsection Modifying contexts
1169 * Changing context properties::
1170 * Adding and removing engravers::
1173 @node Changing context properties
1174 @subsubsection Changing context properties
1176 @cindex context properties
1180 Contexts are responsible for holding the values of a number of
1181 context @emph{properties}. Many of them can be changed to
1182 influence the interpretation of the input and so change the
1183 appearance of the output. They are changed by the
1184 @code{\set} command. This takes the form
1187 \set @emph{ContextName}.@emph{propertyName} = @emph{value}
1190 Where the @emph{ContextName} is usually @context{Score},
1191 @context{Staff} or @context{Voice}. It may be omitted,
1192 in which case @context{Voice} is assumed.
1194 The names of context properties consist of words joined
1195 together with no hyphens or underscores, all except the
1196 first having a capital letter. Here are a few examples
1197 of some commonly used ones. There are many more.
1199 @multitable @columnfractions .3 .2 .5
1200 @headitem propertyName
1205 @tab If true (##t), set extra natural sign before accidentals
1206 @item currentBarNumber
1208 @tab Set the current bar number
1211 @tab If true (##t), print slurs both above and below notes
1212 @item instrumentName
1214 @tab Set the name to be placed at the start of the staff
1217 @tab Increase or decrease the font size
1220 @tab Set the text to print before the start of a verse
1223 Before we can set any of these properties we need to know
1224 which context they operate in. Sometimes this is obvious,
1225 but occasionally it can be tricky. If the wrong context
1226 is specified, no error message is produced, but the expected
1227 action will not be taken. For example, the
1228 @code{instrumentName} clearly lives in the Staff context, since
1229 it is the staff that is named.
1230 In this example the first staff is labelled, but the second,
1231 Alto, staff is not, because we omitted the context name.
1233 @lilypond[quote,verbatim,ragged-right]
1235 \new Staff \relative c'' {
1236 \set Staff.instrumentName = "Soprano"
1239 \new Staff \relative c' {
1240 \set instrumentName = "Alto"
1246 Remember the default context name is Voice, so the second
1247 @code{\set} command set the property @emph{instrumentName} in the
1248 Voice context to @qq{Alto}, but as LilyPond does not look
1249 for any such property in the @context{Voice} context, no
1250 further action took place. No error message is logged in
1253 Similarly, if the property name is mis-spelt no error message
1254 is produced, and the expected action clearly is not performed.
1255 If fact, you can set any (fictitious) @q{property} using any
1256 name you like in any context that exists by using the
1257 @code{\set} command. But if the name is not
1258 known to LilyPond it will not cause any action to be taken.
1260 The @code{instrumentName} property will take effect only
1261 if it is set in the @context{Staff} context, but
1262 some properties can be set in more than one context.
1263 For example, the property @code{extraNatural} is by
1264 default set to ##t (true) for all staves.
1265 If it is set to ##f (false) in the @context{Staff} context
1266 it applies just to the accidentals on that staff.
1267 If it is set to false in the @context{Score} context
1268 it applies to all staves.
1270 So this sets @code{extraNatural} in one staff:
1272 @lilypond[quote,verbatim,ragged-right]
1274 \new Staff \relative c'' {
1277 \new Staff \relative c'' {
1278 \set Staff.extraNatural = ##f
1285 and this sets it in all staves:
1287 @lilypond[quote,verbatim,ragged-right]
1289 \new Staff \relative c'' {
1292 \new Staff \relative c'' {
1293 \set Score.extraNatural = ##f
1299 The value of every property set in this way can be reset
1300 to its original value with the @code{\unset} command
1302 The @code{\set} and @code{\unset} commands can appear anywhere
1303 in the input file and will take effect from the time they are
1304 encountered until the end of the score or until the property is
1305 @code{\set} or @code{\unset} again. Let's try changing the
1306 font size, which affects the size of the note heads (among
1307 other things) several times.
1309 @lilypond[quote,verbatim,ragged-right,relative=1,fragment]
1311 \set fontSize = #-4 % make noteheads smaller
1313 \set fontSize = #2.5 % make noteheads larger
1315 \unset fontSize % return to original size
1319 We have now seen how to set the values of several different
1320 types of property. Note that integers and numbers are alway
1321 preceded by a hash sign, @code{#}, while a true or false value
1322 is specified by ##t and ##f, with two hash signs. A text
1323 property should be enclosed in double quotation signs, as above,
1324 although we shall see later that text can actually be specified
1325 in a much more general way by using the very powerful
1326 @code{markup} command.
1331 Context properties may also be set at the time the context is
1332 created. Sometimes this is a clearer way of specifying a
1333 property value if it is to remain fixed for the duration of
1334 the context. When a context is created with a @code{\new}
1335 command it may be immediately followed by a
1336 @code{\with @{ .. @}} block in which the property values are
1337 set. For example, if we wish to suppress the printing of
1338 extra naturals for the duration of a staff we would write:
1340 @lilypond[quote,verbatim,ragged-right]
1349 In effect this overrides the default value of the property. It
1350 may still be changed dynamically using @code{\set} and
1353 @node Adding and removing engravers
1354 @subsubsection Adding and removing engravers
1356 @cindex Engravers, adding
1357 @cindex Engravers, removing
1362 We have seen that contexts each contain several engravers, each
1363 of which is responsible for producing a particular part of the
1364 output, like barlines, staves, note heads, stems, etc. If an
1365 engraver is removed from a context it can no longer produce its
1366 output. This is a crude way of modifying the output, but it
1367 can sometimes be useful.
1369 To remove an engraver we can use the @code{\with} command placed
1370 immediately after the context creation command, as in the
1374 illustration let's repeat an example from the previous
1375 section with the staff lines removed. Remember that the
1376 staff lines are produced by the Staff_symbol_engraver.
1378 @lilypond[quote,verbatim,ragged-right]
1380 \remove Staff_symbol_engraver
1384 \set fontSize = #-4 % make noteheads smaller
1386 \set fontSize = #2.5 % make noteheads larger
1388 \unset fontSize % return to original size
1393 @cindex ambitus engraver
1395 Engravers can also be added to contexts. The command
1396 to do this is @code{\consists @emph{Engraver_name}},
1397 placed inside a @code{\with} block. Some vocal scores
1398 have an @rglos{ambitus} placed at the beginning of a
1399 staff to indicate the range of notes in that staff.
1400 The ambitus is produced by the @code{Ambitus_engraver},
1401 which is not normally included in any context. If
1402 we add it to the @context{Voice} context it calculates
1403 the range from that voice only:
1405 @lilypond[quote,verbatim,ragged-right]
1408 \consists Ambitus_engraver
1423 but if we add the Ambitus engraver to the
1424 @context{Staff} context it calculates the range from all
1425 the notes in all the voices on that staff:
1427 @lilypond[quote,verbatim,ragged-right]
1429 \consists Ambitus_engraver
1446 @node Extending the templates
1447 @section Extending the templates
1449 You've read the tutorial, you know how to write music, you
1450 understand the fundamental concepts. But how can you
1451 get the staves that you want? Well, you can find lots of
1452 templates in Appendix A which may give you a start. But what
1453 if you want something that isn't covered there? Read on.
1456 * Soprano and cello::
1457 * Four-part SATB vocal score::
1458 * Building a score from scratch::
1461 @node Soprano and cello
1462 @subsection Soprano and cello
1464 Start off with the template that seems closest to what you want to end
1465 up with. Let's say that you want to write something for soprano and
1466 cello. In this case, we would start with @q{Notes and lyrics} (for the
1471 melody = \relative c' @{
1479 text = \lyricmode @{
1485 \new Voice = "one" @{
1489 \new Lyrics \lyricsto "one" \text
1496 Now we want to add a cello part. Let's look at the @q{Notes only} example:
1500 melody = \relative c' @{
1515 We don't need two @code{\version} commands. We'll need the @code{melody}
1516 section. We don't want two @code{\score} sections -- if we had two
1517 @code{\score}s, we'd get the two parts separately. We want them together,
1518 as a duet. Within the @code{\score} section, we don't need two
1519 @code{\layout} or @code{\midi}.
1521 If we simply cut and paste the @code{melody} section, we would end up with
1522 two @code{melody} sections. So let's rename them. We'll call the section
1523 for the soprano @code{sopranoMusic} and the section for the cello
1524 @code{celloMusic}. While we're doing this, let's rename @code{text}
1525 to be @code{sopranoLyrics}. Remember to rename both instances of all
1526 these names -- both the initial definition (the
1527 @code{melody = relative c' @{ } part) and the name's use (in the
1528 @code{\score} section).
1530 While we're doing this, let's change the cello part's staff -- celli
1531 normally use bass clef. We'll also give the cello some different
1536 sopranoMusic = \relative c' @{
1544 sopranoLyrics = \lyricmode @{
1548 celloMusic = \relative c @{
1558 \new Voice = "one" @{
1562 \new Lyrics \lyricsto "one" \sopranoLyrics
1569 This is looking promising, but the cello part won't appear in the
1570 score -- we haven't used it in the @code{\score} section. If we
1571 want the cello part to appear under the soprano part, we need to add
1574 \new Staff \celloMusic
1578 underneath the soprano stuff. We also need to add @code{<<} and
1579 @code{>>} around the music -- that tells LilyPond that there's
1580 more than one thing (in this case, @code{Staff}) happening at once. The
1581 @code{\score} looks like this now
1583 @c Indentation in this example is deliberately poor
1588 \new Voice = "one" @{
1592 \new Lyrics \lyricsto "one" \sopranoLyrics
1594 \new Staff \celloMusic
1602 This looks a bit messy; the indentation is messed up now. That is
1603 easily fixed. Here's the complete soprano and cello template.
1605 @lilypond[quote,verbatim,ragged-right]
1607 sopranoMusic = \relative c' {
1615 sopranoLyrics = \lyricmode {
1619 celloMusic = \relative c {
1630 \new Voice = "one" {
1634 \new Lyrics \lyricsto "one" \sopranoLyrics
1636 \new Staff \celloMusic
1644 @node Four-part SATB vocal score
1645 @subsection Four-part SATB vocal score
1647 Most vocal scores of music written for four-part mixed choir
1648 with orchestral accompaniment such as Mendelssohn's Elijah or
1649 Handel's Messiah have the choral music and words on four
1650 staves, one for each of SATB, with a piano reduction of the
1651 orchestral accompaniment underneath. Here's an example
1652 from Handel's Messiah:
1654 @c The following should appear as music without code
1655 @lilypond[quote,ragged-right]
1657 global = { \key d \major \time 4/4 }
1658 sopMusic = \relative c'' {
1660 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
1662 sopWords = \lyricmode {
1663 Wor -- thy is the lamb that was slain
1665 altoMusic = \relative a' {
1667 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
1669 altoWords = \sopWords
1670 tenorMusic = \relative c' {
1672 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
1674 tenorWords = \sopWords
1675 bassMusic = \relative c' {
1677 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
1679 bassWords = \sopWords
1680 upper = \relative a' {
1683 r4 <a d fis>2 <a e' a>4 |
1684 <d fis d'>4. <d fis d'>8 <a d a'>2 |
1685 <g cis g'>4 <a d fis> <a cis e>2 |
1687 lower = \relative c, {
1690 <d d'>4 <d d'>2 <cis cis'>4 |
1691 <b b'>4. <b' b'>8 <fis fis'>2 |
1692 <e e'>4 <d d'> <a' a'>2 |
1696 << % combine ChoirStaff and PianoStaff in parallel
1698 \new Staff = "sopranos" <<
1699 \set Staff.instrumentName = "Soprano"
1700 \new Voice = "sopranos" { \global \sopMusic }
1702 \new Lyrics \lyricsto "sopranos" { \sopWords }
1703 \new Staff = "altos" <<
1704 \set Staff.instrumentName = "Alto"
1705 \new Voice = "altos" { \global \altoMusic }
1707 \new Lyrics \lyricsto "altos" { \altoWords }
1708 \new Staff = "tenors" <<
1709 \set Staff.instrumentName = "Tenor"
1710 \new Voice = "tenors" { \global \tenorMusic }
1712 \new Lyrics \lyricsto "tenors" { \tenorWords }
1713 \new Staff = "basses" <<
1714 \set Staff.instrumentName = "Bass"
1715 \new Voice = "basses" { \global \bassMusic }
1717 \new Lyrics \lyricsto "basses" { \bassWords }
1721 \set PianoStaff.instrumentName = "Piano "
1722 \new Staff = "upper" \upper
1723 \new Staff = "lower" \lower
1729 None of the templates provides this layout exactly. The
1730 nearest is @q{SATB vocal score and automatic piano reduction},
1731 but we shall need to change the layout and add a piano
1732 accompaniment which is not derived automatically from the
1733 vocal parts. The variables holding the music and words for
1734 the vocal parts are fine, but we shall need to add variables for
1735 the piano reduction.
1737 The order in which the contexts appear in the ChoirStaff of
1738 the template do not correspond with the order in the vocal
1739 score shown above. We need to rearrange them so there are
1740 four staves with the words written directly underneath the
1741 notes for each part.
1742 All the voices should be @code{voiceOne}, which is
1743 the default, so the @code{\voiceXXX} commands can be removed.
1744 We also need to specify the tenor clef for the tenors.
1745 The way in which lyrics are specified has also been simplified
1746 as we have not yet encountered the method used in the template.
1747 We've also added the names of each staff.
1749 Doing this gives for our ChoirStaff:
1753 \new Staff = "sopranos" <<
1754 \set Staff.instrumentName = "Soprano"
1755 \new Voice = "sopranos" @{ \global \sopMusic @}
1757 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
1758 \new Staff = "altos" <<
1759 \set Staff.instrumentName = "Alto"
1760 \new Voice = "altos" @{ \global \altoMusic @}
1762 \new Lyrics \lyricsto "altos" @{ \altoWords @}
1763 \new Staff = "tenors" <<
1764 \set Staff.instrumentName = "Tenor"
1765 \new Voice = "tenors" @{ \global \tenorMusic @}
1767 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
1768 \new Staff = "basses" <<
1769 \set Staff.instrumentName = "Bass"
1770 \new Voice = "basses" @{ \global \bassMusic @}
1772 \new Lyrics \lyricsto "basses" @{ \bassWords @}
1776 Next we must work out the piano part. This is
1777 easy - we just pull out the piano part from the
1778 @q{Solo piano} template:
1782 \set PianoStaff.instrumentName = "Piano "
1783 \new Staff = "upper" \upper
1784 \new Staff = "lower" \lower
1788 and add the variable definitions for @code{upper}
1791 The ChoirStaff and PianoStaff must be combined
1792 using angle brackets as we want them to be
1793 stacked one above the other:
1796 << % combine ChoirStaff and PianoStaff one above the other
1798 \new Staff = "sopranos" <<
1799 \new Voice = "sopranos" @{ \global \sopMusic @}
1801 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
1802 \new Staff = "altos" <<
1803 \new Voice = "altos" @{ \global \altoMusic @}
1805 \new Lyrics \lyricsto "altos" @{ \altoWords @}
1806 \new Staff = "tenors" <<
1807 \clef "G_8" % tenor clef
1808 \new Voice = "tenors" @{ \global \tenorMusic @}
1810 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
1811 \new Staff = "basses" <<
1813 \new Voice = "basses" @{ \global \bassMusic @}
1815 \new Lyrics \lyricsto "basses" @{ bassWords @}
1819 \set PianoStaff.instrumentName = "Piano "
1820 \new Staff = "upper" \upper
1821 \new Staff = "lower" \lower
1826 Combining all these together and adding the music
1827 for the three bars of the example above gives:
1829 @lilypond[quote,verbatim,ragged-right]
1831 global = { \key d \major \time 4/4 }
1832 sopMusic = \relative c'' {
1834 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
1836 sopWords = \lyricmode {
1837 Wor -- thy is the lamb that was slain
1839 altoMusic = \relative a' {
1841 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
1843 altoWords = \sopWords
1844 tenorMusic = \relative c' {
1846 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
1848 tenorWords = \sopWords
1849 bassMusic = \relative c' {
1851 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
1853 bassWords = \sopWords
1854 upper = \relative a' {
1857 r4 <a d fis>2 <a e' a>4 |
1858 <d fis d'>4. <d fis d'>8 <a d a'>2 |
1859 <g cis g'>4 <a d fis> <a cis e>2 |
1861 lower = \relative c, {
1864 <d d'>4 <d d'>2 <cis cis'>4 |
1865 <b b'>4. <b' b'>8 <fis fis'>2 |
1866 <e e'>4 <d d'> <a' a'>2 |
1870 << % combine ChoirStaff and PianoStaff in parallel
1872 \new Staff = "sopranos" <<
1873 \set Staff.instrumentName = "Soprano"
1874 \new Voice = "sopranos" { \global \sopMusic }
1876 \new Lyrics \lyricsto "sopranos" { \sopWords }
1877 \new Staff = "altos" <<
1878 \set Staff.instrumentName = "Alto"
1879 \new Voice = "altos" { \global \altoMusic }
1881 \new Lyrics \lyricsto "altos" { \altoWords }
1882 \new Staff = "tenors" <<
1883 \set Staff.instrumentName = "Tenor"
1884 \new Voice = "tenors" { \global \tenorMusic }
1886 \new Lyrics \lyricsto "tenors" { \tenorWords }
1887 \new Staff = "basses" <<
1888 \set Staff.instrumentName = "Bass"
1889 \new Voice = "basses" { \global \bassMusic }
1891 \new Lyrics \lyricsto "basses" { \bassWords }
1895 \set PianoStaff.instrumentName = "Piano "
1896 \new Staff = "upper" \upper
1897 \new Staff = "lower" \lower
1904 @node Building a score from scratch
1905 @subsection Building a score from scratch
1907 After gaining some facility with writing LilyPond code you
1908 may find that it is easier to build a score from scratch
1909 rather than modifying one of the templates. You can also
1910 develop your own style this way to suit the sort of music you
1911 like. Let's see how to put together the score for an organ
1912 prelude as an example.
1914 We begin with a header section. Here go the title, name
1915 of composer, etc followed by the variable definitions
1916 and ending with the score block. Let's start with these and
1917 fill in the details later.
1919 We'll use the first two bars of Bach's prelude
1920 based on @emph{Jesu, meine Freude} which is set in two
1921 manuals and pedal organ. The top manual has two voices,
1922 the lower and pedal organ one each. So we need four
1923 music definitions and one to define the time signature
1929 title = "Jesu, meine Freude"
1930 composer = "J S Bach"
1932 TimeKey = @{ \time 4/4 \key c \minor @}
1933 ManualOneVoiceOneMusic = @{s1@}
1934 ManualOneVoiceTwoMusic = @{s1@}
1935 ManualTwoMusic = @{s1@}
1936 PedalOrganMusic = @{s1@}
1942 For now we've just used a spacer note, @code{s1},
1943 instead of the real music. We'll add that later.
1945 Next let's see what should go in the score block.
1946 We simply mirror the staff structure we want.
1947 Organ music is usually written on three staves,
1948 one for each manual and one for the pedals. The
1949 manual staves should be bracketed together so we
1950 need to use a PianoStaff for them. The first
1951 manual part needs two voices and the second manual
1956 \new Staff = "ManualOne" <<
1957 \new Voice @{ \ManualOneVoiceOneMusic @}
1958 \new Voice @{ \ManualOneVoiceTwoMusic @}
1959 >> % end ManualOne Staff context
1960 \new Staff = "ManualTwo" <<
1961 \new Voice @{ \ManualTwoMusic @}
1962 >> % end ManualTwo Staff context
1963 >> % end PianoStaff context
1966 Next we need to add a staff for the pedal organ.
1967 This goes underneath the PianoStaff, but it must
1968 be simultaneous with it, so we need angle brackets
1969 round the two. Missing these out would generate
1970 an error in the log file. It's a common mistake
1971 which you'll make sooner or later! Try copying
1972 the final example at the end of this section,
1973 remove these angle brackets, and compile it to
1974 see what errors it generates.
1977 << % PianoStaff and Pedal Staff must be simultaneous
1979 \new Staff = "ManualOne" <<
1980 \new Voice @{ \ManualOneVoiceOneMusic @}
1981 \new Voice @{ \ManualOneVoiceTwoMusic @}
1982 >> % end ManualOne Staff context
1983 \new Staff = "ManualTwo" <<
1984 \new Voice @{ \ManualTwoMusic @}
1985 >> % end ManualTwo Staff context
1986 >> % end PianoStaff context
1987 \new Staff = "PedalOrgan" <<
1988 \new Voice @{ \PedalOrganMusic @}
1993 It is not strictly necessary to use the simultaneous contruct
1994 @code{<< >>} for the manual two staff and the pedal organ staff,
1995 since they contain only one music expression, but it does no harm
1996 and always using angle brackets after @code{\new Staff} is a good
1997 habit to cultivate in case there are multiple voices.
1999 Let's add this structure to the score block, and adjust the
2000 indenting. We also add the appropriate clefs, ensure the
2001 second voice stems point down with @code{\voiceTwo} and
2002 enter the time signature and key to each staff using our
2003 predefined variable, @code{\TimeKey}.
2007 << % PianoStaff and Pedal Staff must be simultaneous
2009 \new Staff = "ManualOne" <<
2010 \TimeKey % set time signature and key
2012 \new Voice @{ \ManualOneVoiceOneMusic @}
2013 \new Voice @{ \voiceTwo \ManualOneVoiceTwoMusic @}
2014 >> % end ManualOne Staff context
2015 \new Staff = "ManualTwo" <<
2018 \new Voice @{ \ManualTwoMusic @}
2019 >> % end ManualTwo Staff context
2020 >> % end PianoStaff context
2021 \new Staff = "PedalOrgan" <<
2024 \new Voice @{ \PedalOrganMusic @}
2025 >> % end PedalOrgan Staff
2027 @} % end Score context
2030 That completes the structure. Any three-staff organ music
2031 will have a similar structure, although the number of voices
2032 may vary. All that remains now
2033 is to add the music, and combine all the parts together.
2035 @lilypond[quote,verbatim,ragged-right]
2038 title = "Jesu, meine Freude"
2039 composer = "J S Bach"
2041 TimeKey = { \time 4/4 \key c \minor }
2042 ManualOneVoiceOneMusic = \relative g' {
2043 g4 g f ees | d2 c2 |
2045 ManualOneVoiceTwoMusic = \relative c' {
2046 ees16 d ees8~ ees16 f ees s c8 d~ d c~ |
2047 c c4 b8 c8. g16 c b c d |
2049 ManualTwoMusic = \relative c' {
2050 c16 b c8~ c16 b c g a8 g~ g16 g aes ees |
2051 f ees f d g aes g f ees d e8~ ees16 f ees d |
2053 PedalOrganMusic = \relative c {
2054 r8 c16 d ees d ees8~ ees16 a, b g c b c8 |
2055 r16 g ees f g f g8 c,2 |
2059 << % PianoStaff and Pedal Staff must be simultaneous
2061 \new Staff = "ManualOne" <<
2062 \TimeKey % set time signature and key
2064 \new Voice { \ManualOneVoiceOneMusic }
2065 \new Voice { \voiceTwo \ManualOneVoiceTwoMusic }
2066 >> % end ManualOne Staff context
2067 \new Staff = "ManualTwo" <<
2070 \new Voice { \ManualTwoMusic }
2071 >> % end ManualTwo Staff context
2072 >> % end PianoStaff context
2073 \new Staff = "PedalOrgan" <<
2076 \new Voice { \PedalOrganMusic }
2077 >> % end PedalOrgan Staff
2079 } % end Score context