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::
17 @node How LilyPond files work
18 @section How LilyPond files work
20 The LilyPond input format is quite free-form, giving experienced
21 users a lot of flexibility to structure their files however they
22 wish. However, this flexibility can make things confusing for new
23 users. This section will explain some of this structure, but may
24 gloss over some details in favor of simplicity. For a complete
25 description of the input format, see @ruser{File structure}.
28 * Introduction to the LilyPond file structure::
29 * Score is a (single) compound musical expression::
30 * Nesting Music Expressions::
31 * On the un-nestedness of brackets and ties::
34 @node Introduction to the LilyPond file structure
35 @subsection Introduction to the LilyPond file structure
37 A basic example of a lilypond input file is
42 @var{...compound music expression...} % all the music goes here!
50 There are many variations of this basic pattern, but this
51 example serves as a useful starting place.
53 At this point, you may be confused, since you have never seen a
54 @code{\score@{@}} before. This is because LilyPond automatically
55 adds the extra commands when you give it simple input. LilyPond
56 treats input like this:
65 as shorthand for this:
76 In other words, if the input contains a single music expression,
77 LilyPond will interpret the file as though the music expression
78 was wrapped up inside a @code{\score@{@}}.
82 A @code{\score} must begin with a compound music expression.
83 Remember that a music expression could be anything from a single
89 @var{...insert the whole score of a Wagner opera in here...}
95 Since everything is inside @code{@{ ... @}}, it counts
96 as one music expression.
98 As we saw previously, the @code{\score} can contain other things,
111 Some people put some of those commands outside the @code{\score}
112 block -- for example, @code{\header} is often placed above the
113 @code{\score}. That's just another shorthand that LilyPond
120 Another great shorthand is the ability to define variables. All
121 the templates use this
124 melody = \relative c' @{
133 When LilyPond looks at this file, it takes the value of
134 @code{melody} (everything after the equals sign) and inserts it
135 whenever it sees @code{\melody}. There's nothing special about
136 the names -- it could be @code{melody}, @code{global},
137 @code{pianorighthand}, or @code{foofoobarbaz}. You can use
138 whatever variable names you want as along as they contain just
139 alphabetic characters. For more details, see
140 @ruser{Saving typing with variables and functions}.
145 For a complete definition of the input format, see
146 @ruser{File structure}.
148 @node Score is a (single) compound musical expression
149 @subsection Score is a (single) compound musical expression
151 @cindex Compound music expression
152 @cindex Music expression, compound
154 We saw the general organization of LilyPond input files in the
155 previous section, @ref{How LilyPond files work}. But we seemed to
156 skip over the most important part: how do we figure out what to
157 write after @code{\score}?
159 We didn't skip over it at all. The big mystery is simply that
160 there @emph{is} no mystery. This line explains it all:
163 @emph{A @code{\score} must begin with a compound music expression.}
167 You may find it useful to review
168 @ref{Music expressions explained}. In that section, we saw how to
169 build big music expressions from small pieces -- we started from
170 notes, then chords, etc. Now we're going to start from a big
171 music expression and work our way down.
175 @{ % this brace begins the overall compound music expression
177 @var{...insert the whole score of a Wagner opera in here...}
179 @} % this brace ends the overall compound music expression
184 A whole Wagner opera would easily double the length of this
185 manual, so let's just add a singer and piano. We don't need a
186 @code{GrandStaff} for this ensemble, so we shall remove it. We
187 @emph{do} need a singer and a piano, though.
193 \new Staff = "singer" <<
195 \new PianoStaff = piano <<
203 Remember that we use @code{<<} and @code{>>} to show simultaneous
204 music. And we definitely want to show the vocal part and piano
205 part at the same time, not one after the other! However, the
206 @code{<< .. >>} construct is not really necessary for the Singer
207 staff, as it contains only one music expression, but Staves often
208 do require simultaneous Voices within them, so using @code{<< .. >>}
209 rather than braces is a good habit to adopt.
215 \new Staff = "singer" <<
216 \new Voice = "vocal" @{ @}
218 \new Lyrics \lyricsto vocal \new Lyrics @{ @}
219 \new PianoStaff = "piano" <<
220 \new Staff = "upper" @{ @}
221 \new Staff = "lower" @{ @}
229 Now we have a lot more details. We have the singer's staff: it
230 contains a @code{Voice} (in LilyPond, this term refers to a set of
231 notes, not necessarily vocal notes -- for example, a violin
232 generally plays one voice) and some lyrics. We also have a piano
233 staff: it contains an upper staff (right hand) and a lower staff
236 At this stage, we could start filling in notes. Inside the curly
237 braces next to @code{\new Voice = vocal}, we could start writing
245 But if we did that, the @code{\score} section would get pretty
246 long, and it would be harder to understand what was happening. So
247 let's use variables instead.
257 \new Staff = "singer" <<
258 \new Voice = "vocal" @{ \melody @}
260 \new Lyrics \lyricsto vocal \new Lyrics @{ \text @}
261 \new PianoStaff = "piano" <<
262 \new Staff = "upper" @{ \upper @}
263 \new Staff = "lower" @{ \lower @}
272 Remember that you can use almost any name you like as long
273 as it contains just alphabetic characters. The exact
274 limitations on variable names are detailed in
275 @ruser{File structure}.
277 When writing (or reading) a @code{\score} section, just take it
278 slowly and carefully. Start with the outer layer, then work on
279 each smaller layer. It also really helps to be strict with
280 indentation -- make sure that each item on the same layer starts
281 on the same horizontal position in your text editor.
284 @node Nesting Music Expressions
285 @subsection Nesting Music Expressions
287 New staves do not have to all be declared at the beginning;
288 they may be introduced temporarily at any point. This is
289 particularly useful for creating ossia sections
290 (see @rglos{ossia}). Here's a simple example showing how
291 to introduce a new staff temporarily for the duration of
294 @lilypond[verbatim,quote,ragged-right]
310 The ossia section may be placed above the staff
313 @lilypond[verbatim,quote,ragged-right]
321 alignAboveContext = "main" }
329 This example uses @code{\with}, which will be explained more
330 fully later. It is a means of modifying the default behaviour
331 of a Staff. Here it says that the new staff should be placed
332 above the staff called @qq{main} instead of the default position
335 Ossia are often written without clef and without
336 time signature and are usually in a smaller font.
337 These require further commands which
338 have not yet been introduced. See ...
339 TODO Add ref to tweaks section where this example should
340 be placed and explained.
342 @lilypond[verbatim,quote,ragged-right]
343 \new Staff = "main" {
347 << % Start main and ossia in parallel
348 { r8 f c c } % Main music
349 \new Staff \with { % Start ossia staff
350 \remove "Clef_engraver"
351 \remove "Time_signature_engraver"
352 % Reduce size of notes and staff
354 \override StaffSymbol #'staff-space = #(magstep -2)
355 alignAboveContext = "main" % Place above main staff
357 { s8 f f c } % Ossia music
358 >> % End parallel music
364 @node On the un-nestedness of brackets and ties
365 @subsection On the un-nestedness of brackets and ties
367 You have already met a number of different types of bracket in
368 writing the input file to LilyPond. These obey different rules
369 which can be confusing at first. Before we explain the rules
370 let's first review the different types of bracket.
372 @multitable @columnfractions .3 .7
373 @headitem Bracket Type
375 @item @code{@{ .. @}}
376 @tab Encloses a sequential segment of music
378 @tab Encloses the notes of a chord
379 @item @code{<< .. >>}
380 @tab Encloses concurrent or simultaneous sections
382 @tab Marks the start and end of a slur
383 @item @code{\( .. \)}
384 @tab Marks the start and end of a phrase mark
386 @tab Marks the start and end of a manual beam
389 To these we should add other constructs which generate lines
390 between or across notes: ties (marked by a tilde, @code{~}),
391 tuplets written as @code{\times x/y @{ .. @}}, and grace notes
392 written as @code{\grace@{ .. @}}.
394 Outside LilyPond, the conventional use of brackets requires
395 the different types to be properly nested, like this,
396 @code{<< @{ ( .. ) @} >>}, with the closing brackets being
397 encountered in exactly the opposite order to the opening
398 brackets. This @strong{is} a requirement for the three types of
399 bracket described by the word @q{Encloses} in the table above -
400 they must nest properly.
401 However, the remaining brackets, described with the word
402 @q{Marks} in the table above together with ties and tuplets,
403 do @strong{not} have to nest
404 properly with any of the brackets. In fact, these are not
405 brackets in the sense that
406 they enclose something - they are simply markers to indicate
407 where something starts and ends.
409 So, for example, a phrasing slur can start before a manually
410 inserted beam and end before the end of the beam - not very
411 musical, perhaps, but possible:
413 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
414 { g8\( a b[ c b\) a] }
417 In general, different kinds of brackets, and those implied by
418 tuplets, ties and grace notes, may be mixed freely.
419 This example shows a beam extending into a tuplet (line 1),
420 a slur extending into a tuplet (line 2),
421 a beam and a slur extending into a tuplet, a tie crossing
422 two tuplets, and a phrasing slur extending out of a tuplet
425 @lilypond[quote,verbatim,fragment,ragged-right]
427 r16[ g16 \times 2/3 {r16 e'8] }
428 g16( a \times 2/3 {b d) e' }
429 g8[( a \times 2/3 {b d') e'~]}
430 \times 4/5 {e'32\( a b d' e'} a'4.\)
435 @node Voices contain music
436 @section Voices contain music
438 Singers need voices to sing, and so does LilyPond.
439 The actual music for all instruments in a score
440 is contained in Voices - the most fundamental
441 of all LilyPond's concepts.
444 * I'm hearing Voices::
445 * Explicitly instantiating voices::
446 * Voices and vocals::
449 @node I'm hearing Voices
450 @subsection I'm hearing Voices
454 @cindex Voice context
456 The lowest, most fundamental or innermost layers in a LilyPond
457 score are called @q{Voice contexts} or just @q{Voices} for short.
458 Voices are sometimes called @q{layers} in other notation
461 In fact, a Voice layer or context is the only one which can
462 contain music. If a Voice context is not explicitly declared
463 one is created automatically. Some instruments such as an
464 Oboe can play only one note at a time. Music written for
465 such instruments is monophonic and requires just a single
466 voice. Instruments which can play more than one note at a
467 time like the piano will often require multiple voices to
468 encode the different concurrent notes and rhythms they are
471 A single voice can contain many notes in a chord, of course,
472 so when exactly are multiple voices needed?
473 Let us analyse a short piece of music to see how many voices
474 are required. Here are the notes from the first two bars
475 of the second of Chopin's Deux Nocturnes, Op 32.
477 @c The following should appear as music without code
478 @lilypond[quote,ragged-right]
479 \new Staff \relative c'' {
487 \once \override NoteColumn #'force-hshift = #0 <ees c>2
488 \once \override NoteColumn #'force-hshift = #0.5 des2 }
494 The direction of the stems is often used to indicate the
495 continuity of two simultaneous melodic lines. Here the
496 stems of the highest notes are all pointing up and the
497 stems of the lower notes are all pointing down.
498 This is the first indication that more than one voice
501 But the real need for multiple voices arises when notes
502 which start at the same time have different durations.
503 Look at the notes which start at beat three in the first
504 bar. The a-flat is a dotted quarter note, the f is a
505 quarter note and the d-flat is a half note. These
506 cannot be written as a chord as all the notes in a chord
507 must have the same duration. Neither can they be written
508 as sequential notes, as they must start at the same time.
509 This section of the bar requires three voices, and the
510 normal practice would be to write the whole bar as three
511 voices, as shown here, where we have used different noteheads
512 and colors for the three voices.
514 @c The following should appear as music without code
515 @c The three voice styles should be defined in -init
516 @lilypond[quote,ragged-right]
517 \new Staff \relative c'' {
528 \once \override NoteColumn #'force-hshift = #0 <ees c>2
529 \once \override NoteColumn #'force-hshift = #0.5 des2 }
535 Let us see how this is done.
539 The easiest way to enter fragments with more than one voice on a
540 staff is to enter each voice as a sequence (with @code{@{...@}}),
541 and combine them simultaneously with angle brackets, @code{<<...>>}.
542 The fragments must also be separated with double backward slashes,
543 @code{\\}, to place them in separate voices. Without these, the
544 notes would be entered into a single voice, which would usually
545 cause errors. This technique is particularly suited to pieces of
546 music which are largely monophonic with occasional short sections
547 of polyphony. Here's a simple example:
549 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
551 % Voice "1" Voice "2"
552 << { r4 g g4. a8 } \\ { d,2 d4 g } >> |
553 << { bes4 bes c bes } \\ { g4 g g8( a) g4 } >> |
554 << { a2. r4 } \\ { fis2. s4 } >>
557 This example has just two voices, but the same contruct may be
558 used to encode three or more voices by adding more back-slash
561 The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
562 In each of these contexts, vertical direction of slurs, stems, ties,
563 dynamics etc., is set appropriately.
565 @lilypond[quote,verbatim,fragment]
566 \new Staff \relative c' {
569 % Voice "1" Voice "2" Voice "3"
570 << { g4 f e } \\ { r8 e4 d c8 ~ } >> |
571 << { d2 e2 } \\ { c8 b16 a b8 g ~ g2 } \\ { s4 b4 c2 } >> |
575 These voices are all separate from the main voice that contains
576 the notes just outside the @code{<< .. >>} construct. Let's call
577 this the @emph{simultaneous construct}. Slurs and ties may only
578 connect notes within the same voice, so slurs and ties cannot go
579 into or out of a simultaneous construct. Conversely,
580 parallel voices from separate simultaneous constructs on the same
581 staff are the same voice. Other voice-related properties also
582 carry across simultaneous constructs. Here is the same example,
583 with different colors and noteheads for each voice. Note that
584 changes in one Voice do not affect other voices, but they do
585 persist in the same Voice later. Note also that tied notes may be
586 split across the same voices in two constructs, shown here in the
589 @lilypond[quote,verbatim]
590 \new Staff \relative c' {
600 { c8 b16 a b8 g ~ g2 } \\
607 The commands @code{\voiceXXXStyle} are mainly intended for use in
608 educational documents such as this one. They modify the color
609 of the notehead, the stem and the beams, and the style of the
610 notehead, so that the voices may be easily distinguished.
611 Voice one is set to red diamonds, voice two to blue triangles,
612 voice four to green crossed circles, and voice four (not used
613 here) to magenta crosses. We shall see later how commands like
614 these may be created by the user.
615 TODO: add ref to appropriate section in Tweaks
617 Polyphony does not change the relationship of notes within a
618 @code{\relative @{ @}} block. Each note is still calculated
619 relative to the note immediately preceding it, or to the first
620 note of the preceding chord. So in
623 \relative c' @{ noteA << <noteB noteC> \\ noteD >> noteE @}
626 @code{noteB} is relative to @code{noteA} @*
627 @code{noteC} is relative to @code{noteB}, not @code{noteA}; @*
628 @code{noteD} is relative to @code{noteB}, not @code{noteA} or
630 @code{noteE} is relative to @code{noteD}, not @code{noteA}
632 We are now in a position to return to the first example from
633 the Chopin Nocturne to see how this might be encoded. As we
634 shall see, this encounters some difficulties. We begin as
635 we have learnt, using the @code{<< \\ >>} construct to
636 enter the music of the first bar in three voices:
638 @lilypond[quote,verbatim,fragment,ragged-right]
639 \new Staff \relative c'' {
642 { c2 aes4. bes8 } \\ { aes2 f4 fes } \\ { <ees c>2 des2 }
652 @funindex \voiceThree
655 The stem directions are automatically assigned with the
656 odd-numbered voices taking upward stems and the even-numbered
657 voices downward ones. The stems for voices 1 and 2 are right,
658 but the stems in voice 3 should go down in this particular piece
659 of music. We can correct this
660 by telling LilyPond that this third voice is really a fourth
661 voice, with stems going down, using the @code{\voiceFour}
662 command. There are also corresponding @code{\voiceOne},
663 @code{\voiceTwo}, @code{voiceThree} and @code{voiceFour}
664 commands. This results in the following:
666 @lilypond[quote,verbatim,fragment,ragged-right]
667 \new Staff \relative c'' {
672 { \voiceFour <ees c>2 des2 }
679 and exposes a problem commonly encountered with multiple
680 voices: the stems of notes can collide with noteheads
681 in other voices. In laying out the notes, LilyPond allows the
682 notes or chords from two voices to occupy the same vertical
683 note column provided the stems are in opposite directions, but
684 the notes from a third voice are displaced to avoid the stems
685 colliding. This often works well, but in this example the
686 notes of the third voice are clearly not well placed by default.
687 LilyPond provides several ways to adjust the horizontal placing
688 of notes. We are not quite ready yet to see how to correct this,
689 so we shall leave this problem until a later section (see ... )
691 FIXME: Move the following words and example into Tweaks or
692 somewhere more suitable, leaving just a ref here. -td
694 Ways of correcting horizontal placings are described fully
695 in the Notation Reference.
696 We introduce just one here, the @code{force-hshift} property of
697 @code{NoteColumn}. The lower two notes of the first chord (i.e,
698 those in the third voice) should not be shifted away from the
699 note column of the higher two notes. To correct this we set
700 @code{force-hshift} of these notes to zero.
701 The lower note of the second chord is best placed just to the
702 right of the higher notes. We achieve this by setting
703 @code{force-hshift} of this note to 0.5, ie half a notehead's
704 width to the right of the note column of the higher notes.
706 Here's the final result:
708 @lilypond[quote,verbatim,fragment,ragged-right]
709 \new Staff \relative c'' {
715 \once \override NoteColumn #'force-hshift = #0 <ees c>2
716 \once \override NoteColumn #'force-hshift = #0.5 des2
723 @node Explicitly instantiating voices
724 @subsection Explicitly instantiating voices
726 Voice contexts can also be created manually
727 inside a @code{<< >>} block to create polyphonic music, using
728 @code{\voiceOne} ... @code{\voiceFour} to indicate the required
729 directions of stems, slurs, etc.
731 Specifically, the construct @code{<< \\ >>} which we used in
732 the previous section:
735 << \upper \\ \lower >>
739 where @code{upper} and @code{lower} are user-defined variables
740 containing the music for the two voices, is equivalent to
744 \new Voice = "1" @{ \voiceOne \upper @}
745 \new Voice = "2" @{ \voiceTwo \lower @}
749 The @code{\voiceXXX} commands set the direction of stems, slurs,
750 ties, articulations, text annotations, augmentation dots of dotted
751 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
752 make these objects point upwards, while @code{\voiceTwo} and
753 @code{\voiceFour} make them point downwards. These commands also
754 generate a horizontal shift for each voice when this is required
755 to avoid clashes of note heads. The command @code{\oneVoice}
756 reverts the settings back to the normal values for a single voice.
758 Let us see in a simple example exactly what effect
759 @code{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on
760 markup, ties, slurs, and dynamics:
762 @lilypond[quote,ragged-right,verbatim]
764 c-"default" d8 ~ d e4 ( f g a ) b-> c \break
766 c,-"\\voiceOne" d8 ~ d e4 ( f g a ) b-> c \break
768 c,-"\\oneVoice" d8 ~ d e4 ( f g a ) b-> c \break
770 c,-"\\voiceTwo" d8 ~ d e4 ( f g a ) b-> c \break
774 An expression that appears directly inside a @code{<< >>} belongs
775 to the main voice. This is useful when extra voices appear while
776 the main voice is playing. Here is a more correct rendition of
777 the example from the previous section. The red diamond-shaped
778 notes demonstrate that the main melody is now in a single
779 voice context, permitting a phrasing slur to be drawn over them.
781 @lilypond[quote,ragged-right,verbatim]
782 \new Staff \relative c' {
784 c16^( d e f % These notes are monophonic
785 << % Start simultaneous section of three voices
786 { g4 f e | d2 e2) } % Continue the main voice in parallel
787 \new Voice { % Initiate second voice
788 \voiceTwo % Set stems, etc, down
789 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
791 \new Voice { % Initiate third voice
792 \voiceThree % Set stems, etc, up
799 @cindex nesting music expressions
800 @cindex nesting simultaneous constructs
802 More deeply nested polyphony constructs are possible, and if a
803 voice appears only briefly this might be a more natural way to
806 @lilypond[quote,ragged-right,verbatim]
807 \new Staff \relative c' {
827 This method of nesting new voices briefly is useful
828 when only small sections of the music
829 are polyphonic, but when the whole staff is largely polyphonic
830 it can be clearer to use multiple voices throughout, using
831 spacing notes to step over sections where the voice is silent,
834 @lilypond[quote,ragged-right,verbatim]
835 \new Staff \relative c' <<
836 \new Voice { % Initiate first voice
838 c16^( d e f g4 f e | d2 e2) |
840 \new Voice { % Initiate second voice
841 \voiceTwo % set stems, etc down
842 s4 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 |
844 \new Voice { % Initiate third voice
845 \voiceThree % set stems, etc up
852 @node Voices and vocals
853 @subsection Voices and vocals
855 Vocal music presents a special difficulty: we need to combine two
856 expressions -- notes and lyrics.
858 You have already seen the @code{\lyricsAdd@{@}} command, which
859 handles simple cases for you. However, this technique is
860 very limited. For most music, you must explicitly link the lyrics
861 to the notes with @code{\lyricsto@{@}}, using the name assigned
864 @lilypond[quote,verbatim,fragment]
866 \new Voice = "one" \relative c'' {
869 c4 b8. a16 g4. f8 e4 d c2
871 \new Lyrics \lyricsto "one" {
872 No more let sins and sor -- rows grow.
877 The automatic beaming which LilyPond uses by default works well
878 for instrumental music, but not so well for music with lyrics,
879 where beaming is either not required at all or is used to indicate
880 melismata in the lyrics. In the example above we use the command
881 @code{\autoBeamOff} to turn off the automatic beaming.
883 Let us reuse the earlier example from Judas Maccabæus to
884 illustrate this more flexible technique. We first recast
885 it to use variables so the music and lyrics can be separated
886 from the staff structure. We also introduce a choirstaff
887 bracket. The lyrics themselves must be introduced with
888 @code{\lyricmode} to ensure they are interpreted as lyrics
891 @lilypond[quote,verbatim]
892 global = { \time 6/8 \partial 8 \key f \major}
893 SopOneMusic = \relative c'' {
894 c8 | c([ bes)] a a([ g)] f | f'4. b, | c4.~ c4 }
895 SopTwoMusic = \relative c' {
896 r8 | r4. r4 c8 | a'([ g)] f f([ e)] d | e([ d)] c bes' }
897 SopOneLyrics = \lyricmode {
898 Let | flee -- cy flocks the | hills a -- dorn, __ }
899 SopTwoLyrics = \lyricmode {
900 Let | flee -- cy flocks the | hills a -- dorn, }
905 \new Voice = "SopOne" {
909 \new Lyrics \lyricsto "SopOne" {
914 \new Voice = "SopTwo" {
917 \new Lyrics \lyricsto "SopTwo" {
925 This is the basic structure of all vocal scores. More staves may
926 be added as required, more voices may be added to the staves,
927 more verses may be added to the lyrics,
928 and the variables containing the music can easily be placed
929 in separate files should they become too long.
931 Here is a final example of the first line of a hymn with four
932 verses, set for SATB. In this case the words for all four
935 @lilypond[quote,verbatim]
936 global = { \time 4/4 \partial 4 \key c \major}
937 SopMusic = \relative c' { c4 | e4. e8 g4 g | a a g }
938 AltoMusic = \relative c' { c4 | c4. c8 e4 e | f f e }
939 TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 }
940 BassMusic = \relative c { c4 | c4. c8 c4 c | f8 g a b c4 }
941 VerseOne = \lyricmode {
942 E -- | ter -- nal fa -- ther, | strong to save, }
943 VerseTwo = \lyricmode {
944 O | Christ, whose voice the | wa -- ters heard, }
945 VerseThree = \lyricmode {
946 O | Ho -- ly Spi -- rit, | who didst brood }
947 VerseFour = \lyricmode {
948 O | Tri -- ni -- ty of | love and pow'r }
954 \new Voice = "Sop" { \voiceOne \global \SopMusic }
955 \new Voice = "Alto" { \voiceTwo \AltoMusic }
956 \new Lyrics \lyricsto "Sop" { \VerseOne }
957 \new Lyrics \lyricsto "Sop" { \VerseTwo }
958 \new Lyrics \lyricsto "Sop" { \VerseThree }
959 \new Lyrics \lyricsto "Sop" { \VerseFour }
963 \new Voice = "Tenor" { \voiceOne \TenorMusic }
964 \new Voice = "Bass" { \voiceTwo \BassMusic }
970 @node Contexts and engravers
971 @section Contexts and engravers
973 Contexts and engravers have been mentioned informally
974 in earlier sections; we now must look at
975 these concepts in more detail, as they are important
976 in the fine-tuning of LilyPond output.
980 * Contexts explained::
981 * Creating contexts::
983 * Modifying contexts::
986 @node Contexts explained
987 @subsection Contexts explained
989 When music is printed, many notational elements which do not
990 appear explicitly in the input file must be added to the
991 output. For example, compare the input and output of the
994 @lilypond[quote,verbatim,relative=2,fragment]
998 The input is rather sparse, but in the output, bar lines,
999 accidentals, clef, and time signature have been added. When
1000 LilyPond @emph{interprets} the input the musical information
1001 is inspected in time order, similar to reading a score from left
1002 to right. While reading the input, the program remembers where
1003 measure boundaries are, and which pitches require explicit
1004 accidentals. This information must be held on several levels.
1005 For example, the effect of an accidental is limited
1006 to a single staff, while a bar line must be synchronized across
1009 Within LilyPond, these rules and bits of information are grouped
1010 in @emph{Contexts}. We have already met the @context{Voice}
1012 Others are the @context{Staff} and @context{Score} contexts.
1013 Contexts are hierarchical to reflect the heirarchical nature of
1015 For example: a @context{Staff} context can contain many
1016 @context{Voice} contexts, and a @context{Score} context can
1017 contain many @context{Staff} contexts.
1020 @image{context-example,5cm,,}
1023 Each context has the responsibility for enforcing some notation rules,
1024 creating some notation objects and maintaining the associated
1025 properties. For example, the @context{Voice} context may introduce an
1026 accidental and then the @context{Staff} context maintains the rule to
1027 show or suppress the accidental for the remainder of the measure.
1029 As another example, the synchronization of bar lines is by default
1030 handled in the @context{Score} context.
1031 However, in some music we may not want the bar lines to be
1032 synchronized -- consider a polymetric score in 4/4 and 3/4 time.
1033 In such cases, we must modify the default settings of the
1034 @context{Score} and @context{Staff} contexts.
1036 For very simple scores, contexts are created implicitly, and you need
1037 not be aware of them. For larger pieces, such as anything with more
1038 than one staff, they must be
1039 created explicitly to make sure that you get as many staves as you
1040 need, and that they are in the correct order. For typesetting pieces
1041 with specialized notation, it is usual to modify existing or
1042 even to define totally new contexts.
1044 In addition to the @context{Score,} @context{Staff} and
1045 @context{Voice} contexts there are contexts which fit between
1046 the score and staff levels to control staff groups, such as the
1047 @context{PianoStaff} and @context{ChoirStaff} contexts. There
1048 are also alternative staff and voice contexts, and contexts for
1049 lyrics, percussion, fret boards, figured bass, etc. A complete
1050 list is shown in the Notation Reference.
1053 The names of all context types are formed from one or more
1054 words, each word being capitalised and joined immediately to the
1055 preceding word with no hyphen or underscore, e.g.,
1056 @context{GregorianTranscriptionStaff}.
1058 @node Creating contexts
1059 @subsection Creating contexts
1061 There can be only one top level context, the @context{Score}
1062 context. This is created with the @code{\score} command,
1063 or, in simple scores, it is created automatically.
1065 For scores with only one voice and one staff, the
1066 @context{Voice} and @context{Staff} contexts may be left to be
1067 created automatically, but for more complex scores it is
1068 necessary to create them by hand.
1069 The simplest command that does this is @code{\new}.
1070 It is prepended to a music expression, for example
1073 @cindex new contexts
1074 @cindex Context, creating
1077 \new @var{type} @var{music expression}
1081 where @var{type} is a context name (like @code{Staff} or
1082 @code{Voice}). This command creates a new context, and starts
1083 interpreting the @var{music expression} within that context.
1085 Note that there is no @code{\new Score % Invalid!} command;
1086 the single top-level @context{Score} context is introduced
1087 with @code{\score}. This is because there can be only one
1088 @context{Score} context, whereas there may be multiple
1089 @context{Staff} and @context{Voice} contexts - each created
1092 So a practical application of @code{\new} is a score with many
1093 staves. Each part that should be on its own staff is preceded
1094 with @code{\new Staff}.
1096 @lilypond[quote,verbatim,relative=2,ragged-right,fragment]
1103 The @code{\new} command may also give a identifying name to the
1104 context to distinguish it from other contexts of the same type,
1107 \new @var{type} = @var{id} @var{music}
1110 Note the distinction between the name of the context type,
1111 @context{Staff}, @context{Voice}, etc, and
1112 the identifying name of a particular instance of that type,
1113 which can be any sequence of letters invented by the user.
1114 The identifying name is used to refer back to that particular
1115 instance of a context. We saw this in use in the section on
1116 lyrics in @ref{Voices and vocals}.
1120 @subsection Engravers
1122 Every mark on the printed output of a score produced by LilyPond
1123 is produced by an @code{Engraver}. Thus there is an engraver
1124 to print staves, one to print noteheads, one for stems, one for
1125 beams, etc, etc. In total there are over 120 such engravers!
1126 Fortunately, for most scores it is not necessary to know about
1127 more than a few, and for simple scores you do not need to know
1130 A musical score can be viewed heirarchically. At the top level
1131 is the whole score. This consists of one or more staves.
1132 Each staff contains one or more voices. As we have seen, there
1133 are contexts which correspond to each of these levels and it
1134 is in these contexts that the Engravers operate.
1136 Engravers such as the @code{Metronome_mark_engraver}, whose
1137 action and output applies to the score as a whole, live in
1138 the highest level context - the @context{Score} context. There
1139 can be only one of these engravers as there can be only one tempo
1140 at any particular point in the score.
1142 The @code{Clef_engraver} and @code{Key_engraver} are to be
1143 found in the Staff Context, as different staves may require
1144 different clefs and keys.
1146 The @code{Note_heads_engraver} and @code{Stem_engraver} live
1147 in a @context{Voice} context, the lowest level context of all.
1149 Each engraver processes the particular objects associated
1150 with its function, and contains the properties that relate
1151 to that function. These properties, like the properties
1152 associated with contexts, may be modified to change the
1153 operation of the engraver or the appearance of those elements
1154 in the printed score.
1156 Engravers all have compound names formed from words which
1157 describe their function. Just the first word is capitalised,
1158 and the remainder are joined to it with underscores. Thus
1159 the @code{Staff_symbol_engraver} is responsible for creating the
1160 lines of the staff, the @code{Clef_engraver} determines and sets
1161 the pitch reference point on the staff by drawing a clef symbol.
1163 Here are some of the most common engravers together with their
1164 function. You will see it is easy to guess the function from
1165 the name, or vice versa.
1167 @multitable @columnfractions .3 .7
1170 @item Accidental_engraver
1171 @tab Makes accidentals, cautionary and suggested accidentals
1176 @item Dynamic_engraver
1177 @tab Creates hairpins and dynamic texts
1179 @tab Creates the key signature
1180 @item Metronome_mark_engraver
1181 @tab Engraves metronome marking
1182 @item Note_heads_engraver
1183 @tab Engraves noteheads
1186 @item Staff_symbol_engraver
1187 @tab Engraves the five (by default) lines of the staff
1189 @tab Creates stems and single-stem tremulos
1192 We shall see later how the output of LilyPond can be changed
1193 by modifying the action of Engravers.
1196 @node Modifying contexts
1197 @subsection Modifying contexts
1200 * Changing context properties::
1201 * Adding and removing engravers::
1204 @node Changing context properties
1205 @subsubsection Changing context properties
1207 @cindex context properties
1211 Contexts are responsible for holding the values of a number of
1212 context @emph{properties}. Many of them can be changed to
1213 influence the interpretation of the input and so change the
1214 appearance of the output. They are changed by the
1215 @code{\set} command. This takes the form
1218 \set @emph{ContextName}.@emph{propertyName} = @emph{value}
1221 Where the @emph{ContextName} is usually @context{Score},
1222 @context{Staff} or @context{Voice}. It may be omitted,
1223 in which case @context{Voice} is assumed.
1225 The names of context properties consist of words joined
1226 together with no hyphens or underscores, all except the
1227 first having a capital letter. Here are a few examples
1228 of some commonly used ones. There are many more.
1230 @multitable @columnfractions .3 .2 .5
1231 @headitem propertyName
1236 @tab If true (##t), set extra natural sign before accidentals
1237 @item currentBarNumber
1239 @tab Set the current bar number
1242 @tab If true (##t), print slurs both above and below notes
1243 @item instrumentName
1245 @tab Set the name to be placed at the start of the staff
1248 @tab Increase or decrease the font size
1251 @tab Set the text to print before the start of a verse
1254 Before we can set any of these properties we need to know
1255 which context they operate in. Sometimes this is obvious,
1256 but occasionally it can be tricky. If the wrong context
1257 is specified, no error message is produced, but the expected
1258 action will not be taken. For example, the
1259 @code{instrumentName} clearly lives in the Staff context, since
1260 it is the staff that is named.
1261 In this example the first staff is labelled, but the second,
1262 Alto, staff is not, because we omitted the context name.
1264 @lilypond[quote,verbatim,ragged-right]
1266 \new Staff \relative c'' {
1267 \set Staff.instrumentName = "Soprano"
1270 \new Staff \relative c' {
1271 \set instrumentName = "Alto"
1277 Remember the default context name is Voice, so the second
1278 @code{\set} command set the property @emph{instrumentName} in the
1279 Voice context to @qq{Alto}, but as LilyPond does not look
1280 for any such property in the @context{Voice} context, no
1281 further action took place. No error message is logged in
1284 Similarly, if the property name is mis-spelt no error message
1285 is produced, and the expected action clearly is not performed.
1286 If fact, you can set any (fictitious) @q{property} using any
1287 name you like in any context that exists by using the
1288 @code{\set} command. But if the name is not
1289 known to LilyPond it will not cause any action to be taken.
1291 The @code{instrumentName} property will take effect only
1292 if it is set in the @context{Staff} context, but
1293 some properties can be set in more than one context.
1294 For example, the property @code{extraNatural} is by
1295 default set to ##t (true) for all staves.
1296 If it is set to ##f (false) in the @context{Staff} context
1297 it applies just to the accidentals on that staff.
1298 If it is set to false in the @context{Score} context
1299 it applies to all staves.
1301 So this sets @code{extraNatural} in one staff:
1303 @lilypond[quote,verbatim,ragged-right]
1305 \new Staff \relative c'' {
1308 \new Staff \relative c'' {
1309 \set Staff.extraNatural = ##f
1316 and this sets it in all staves:
1318 @lilypond[quote,verbatim,ragged-right]
1320 \new Staff \relative c'' {
1323 \new Staff \relative c'' {
1324 \set Score.extraNatural = ##f
1330 The value of every property set in this way can be reset
1331 to its original value with the @code{\unset} command
1333 The @code{\set} and @code{\unset} commands can appear anywhere
1334 in the input file and will take effect from the time they are
1335 encountered until the end of the score or until the property is
1336 @code{\set} or @code{\unset} again. Let's try changing the
1337 font size, which affects the size of the note heads (among
1338 other things) several times.
1340 @lilypond[quote,verbatim,ragged-right,relative=1,fragment]
1342 \set fontSize = #-4 % make noteheads smaller
1344 \set fontSize = #2.5 % make noteheads larger
1346 \unset fontSize % return to original size
1350 We have now seen how to set the values of several different
1351 types of property. Note that integers and numbers are alway
1352 preceded by a hash sign, @code{#}, while a true or false value
1353 is specified by ##t and ##f, with two hash signs. A text
1354 property should be enclosed in double quotation signs, as above,
1355 although we shall see later that text can actually be specified
1356 in a much more general way by using the very powerful
1357 @code{markup} command.
1362 Context properties may also be set at the time the context is
1363 created. Sometimes this is a clearer way of specifying a
1364 property value if it is to remain fixed for the duration of
1365 the context. When a context is created with a @code{\new}
1366 command it may be immediately followed by a
1367 @code{\with @{ .. @}} block in which the property values are
1368 set. For example, if we wish to suppress the printing of
1369 extra naturals for the duration of a staff we would write:
1371 @lilypond[quote,verbatim,ragged-right]
1380 In effect this overrides the default value of the property. It
1381 may still be changed dynamically using @code{\set} and
1384 @node Adding and removing engravers
1385 @subsubsection Adding and removing engravers
1387 @cindex Engravers, adding
1388 @cindex Engravers, removing
1393 We have seen that contexts each contain several engravers, each
1394 of which is responsible for producing a particular part of the
1395 output, like barlines, staves, note heads, stems, etc. If an
1396 engraver is removed from a context it can no longer produce its
1397 output. This is a crude way of modifying the output, but it
1398 can sometimes be useful.
1400 To remove an engraver we can use the @code{\with} command placed
1401 immediately after the context creation command, as in the
1405 illustration let's repeat an example from the previous
1406 section with the staff lines removed. Remember that the
1407 staff lines are produced by the Staff_symbol_engraver.
1409 @lilypond[quote,verbatim,ragged-right]
1411 \remove Staff_symbol_engraver
1415 \set fontSize = #-4 % make noteheads smaller
1417 \set fontSize = #2.5 % make noteheads larger
1419 \unset fontSize % return to original size
1424 @cindex ambitus engraver
1426 Engravers can also be added to contexts. The command
1427 to do this is @code{\consists @emph{Engraver_name}},
1428 placed inside a @code{\with} block. Some vocal scores
1429 have an @rglos{ambitus} placed at the beginning of a
1430 staff to indicate the range of notes in that staff.
1431 The ambitus is produced by the @code{Ambitus_engraver},
1432 which is not normally included in any context. If
1433 we add it to the @context{Voice} context it calculates
1434 the range from that voice only:
1436 @lilypond[quote,verbatim,ragged-right]
1439 \consists Ambitus_engraver
1454 but if we add the Ambitus engraver to the
1455 @context{Staff} context it calculates the range from all
1456 the notes in all the voices on that staff:
1458 @lilypond[quote,verbatim,ragged-right]
1460 \consists Ambitus_engraver
1477 @node Extending the templates
1478 @section Extending the templates
1480 You've read the tutorial, you know how to write music, you
1481 understand the fundamental concepts. But how can you
1482 get the staves that you want? Well, you can find lots of
1483 templates in Appendix A which may give you a start. But what
1484 if you want something that isn't covered there? Read on.
1487 * Soprano and cello::
1488 * Four-part SATB vocal score::
1489 * Building a score from scratch::
1492 @node Soprano and cello
1493 @subsection Soprano and cello
1495 Start off with the template that seems closest to what you want to end
1496 up with. Let's say that you want to write something for soprano and
1497 cello. In this case, we would start with @q{Notes and lyrics} (for the
1502 melody = \relative c' @{
1510 text = \lyricmode @{
1516 \new Voice = "one" @{
1520 \new Lyrics \lyricsto "one" \text
1527 Now we want to add a cello part. Let's look at the @q{Notes only} example:
1531 melody = \relative c' @{
1546 We don't need two @code{\version} commands. We'll need the @code{melody}
1547 section. We don't want two @code{\score} sections -- if we had two
1548 @code{\score}s, we'd get the two parts separately. We want them together,
1549 as a duet. Within the @code{\score} section, we don't need two
1550 @code{\layout} or @code{\midi}.
1552 If we simply cut and paste the @code{melody} section, we would end up with
1553 two @code{melody} sections. So let's rename them. We'll call the section
1554 for the soprano @code{sopranoMusic} and the section for the cello
1555 @code{celloMusic}. While we're doing this, let's rename @code{text}
1556 to be @code{sopranoLyrics}. Remember to rename both instances of all
1557 these names -- both the initial definition (the
1558 @code{melody = relative c' @{ } part) and the name's use (in the
1559 @code{\score} section).
1561 While we're doing this, let's change the cello part's staff -- celli
1562 normally use bass clef. We'll also give the cello some different
1567 sopranoMusic = \relative c' @{
1575 sopranoLyrics = \lyricmode @{
1579 celloMusic = \relative c @{
1589 \new Voice = "one" @{
1593 \new Lyrics \lyricsto "one" \sopranoLyrics
1600 This is looking promising, but the cello part won't appear in the
1601 score -- we haven't used it in the @code{\score} section. If we
1602 want the cello part to appear under the soprano part, we need to add
1605 \new Staff \celloMusic
1609 underneath the soprano stuff. We also need to add @code{<<} and
1610 @code{>>} around the music -- that tells LilyPond that there's
1611 more than one thing (in this case, @code{Staff}) happening at once. The
1612 @code{\score} looks like this now
1614 @c Indentation in this example is deliberately poor
1619 \new Voice = "one" @{
1623 \new Lyrics \lyricsto "one" \sopranoLyrics
1625 \new Staff \celloMusic
1633 This looks a bit messy; the indentation is messed up now. That is
1634 easily fixed. Here's the complete soprano and cello template.
1636 @lilypond[quote,verbatim,ragged-right]
1638 sopranoMusic = \relative c' {
1646 sopranoLyrics = \lyricmode {
1650 celloMusic = \relative c {
1661 \new Voice = "one" {
1665 \new Lyrics \lyricsto "one" \sopranoLyrics
1667 \new Staff \celloMusic
1675 @node Four-part SATB vocal score
1676 @subsection Four-part SATB vocal score
1678 Most vocal scores of music written for four-part mixed choir
1679 with orchestral accompaniment such as Mendelssohn's Elijah or
1680 Handel's Messiah have the choral music and words on four
1681 staves, one for each of SATB, with a piano reduction of the
1682 orchestral accompaniment underneath. Here's an example
1683 from Handel's Messiah:
1685 @c The following should appear as music without code
1686 @lilypond[quote,ragged-right]
1688 global = { \key d \major \time 4/4 }
1689 sopMusic = \relative c'' {
1691 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
1693 sopWords = \lyricmode {
1694 Wor -- thy is the lamb that was slain
1696 altoMusic = \relative a' {
1698 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
1700 altoWords = \sopWords
1701 tenorMusic = \relative c' {
1703 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
1705 tenorWords = \sopWords
1706 bassMusic = \relative c' {
1708 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
1710 bassWords = \sopWords
1711 upper = \relative a' {
1714 r4 <a d fis>2 <a e' a>4 |
1715 <d fis d'>4. <d fis d'>8 <a d a'>2 |
1716 <g cis g'>4 <a d fis> <a cis e>2 |
1718 lower = \relative c, {
1721 <d d'>4 <d d'>2 <cis cis'>4 |
1722 <b b'>4. <b' b'>8 <fis fis'>2 |
1723 <e e'>4 <d d'> <a' a'>2 |
1727 << % combine ChoirStaff and PianoStaff in parallel
1729 \new Staff = "sopranos" <<
1730 \set Staff.instrumentName = "Soprano"
1731 \new Voice = "sopranos" { \global \sopMusic }
1733 \new Lyrics \lyricsto "sopranos" { \sopWords }
1734 \new Staff = "altos" <<
1735 \set Staff.instrumentName = "Alto"
1736 \new Voice = "altos" { \global \altoMusic }
1738 \new Lyrics \lyricsto "altos" { \altoWords }
1739 \new Staff = "tenors" <<
1740 \set Staff.instrumentName = "Tenor"
1741 \new Voice = "tenors" { \global \tenorMusic }
1743 \new Lyrics \lyricsto "tenors" { \tenorWords }
1744 \new Staff = "basses" <<
1745 \set Staff.instrumentName = "Bass"
1746 \new Voice = "basses" { \global \bassMusic }
1748 \new Lyrics \lyricsto "basses" { \bassWords }
1752 \set PianoStaff.instrumentName = "Piano "
1753 \new Staff = "upper" \upper
1754 \new Staff = "lower" \lower
1760 None of the templates provides this layout exactly. The
1761 nearest is @q{SATB vocal score and automatic piano reduction},
1762 but we shall need to change the layout and add a piano
1763 accompaniment which is not derived automatically from the
1764 vocal parts. The variables holding the music and words for
1765 the vocal parts are fine, but we shall need to add variables for
1766 the piano reduction.
1768 The order in which the contexts appear in the ChoirStaff of
1769 the template do not correspond with the order in the vocal
1770 score shown above. We need to rearrange them so there are
1771 four staves with the words written directly underneath the
1772 notes for each part.
1773 All the voices should be @code{voiceOne}, which is
1774 the default, so the @code{\voiceXXX} commands can be removed.
1775 We also need to specify the tenor clef for the tenors.
1776 The way in which lyrics are specified has also been simplified
1777 as we have not yet encountered the method used in the template.
1778 We've also added the names of each staff.
1780 Doing this gives for our ChoirStaff:
1784 \new Staff = "sopranos" <<
1785 \set Staff.instrumentName = "Soprano"
1786 \new Voice = "sopranos" @{ \global \sopMusic @}
1788 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
1789 \new Staff = "altos" <<
1790 \set Staff.instrumentName = "Alto"
1791 \new Voice = "altos" @{ \global \altoMusic @}
1793 \new Lyrics \lyricsto "altos" @{ \altoWords @}
1794 \new Staff = "tenors" <<
1795 \set Staff.instrumentName = "Tenor"
1796 \new Voice = "tenors" @{ \global \tenorMusic @}
1798 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
1799 \new Staff = "basses" <<
1800 \set Staff.instrumentName = "Bass"
1801 \new Voice = "basses" @{ \global \bassMusic @}
1803 \new Lyrics \lyricsto "basses" @{ \bassWords @}
1807 Next we must work out the piano part. This is
1808 easy - we just pull out the piano part from the
1809 @q{Solo piano} template:
1813 \set PianoStaff.instrumentName = "Piano "
1814 \new Staff = "upper" \upper
1815 \new Staff = "lower" \lower
1819 and add the variable definitions for @code{upper}
1822 The ChoirStaff and PianoStaff must be combined
1823 using angle brackets as we want them to be
1824 stacked one above the other:
1827 << % combine ChoirStaff and PianoStaff one above the other
1829 \new Staff = "sopranos" <<
1830 \new Voice = "sopranos" @{ \global \sopMusic @}
1832 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
1833 \new Staff = "altos" <<
1834 \new Voice = "altos" @{ \global \altoMusic @}
1836 \new Lyrics \lyricsto "altos" @{ \altoWords @}
1837 \new Staff = "tenors" <<
1838 \clef "G_8" % tenor clef
1839 \new Voice = "tenors" @{ \global \tenorMusic @}
1841 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
1842 \new Staff = "basses" <<
1844 \new Voice = "basses" @{ \global \bassMusic @}
1846 \new Lyrics \lyricsto "basses" @{ bassWords @}
1850 \set PianoStaff.instrumentName = "Piano "
1851 \new Staff = "upper" \upper
1852 \new Staff = "lower" \lower
1857 Combining all these together and adding the music
1858 for the three bars of the example above gives:
1860 @lilypond[quote,verbatim,ragged-right]
1862 global = { \key d \major \time 4/4 }
1863 sopMusic = \relative c'' {
1865 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
1867 sopWords = \lyricmode {
1868 Wor -- thy is the lamb that was slain
1870 altoMusic = \relative a' {
1872 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
1874 altoWords = \sopWords
1875 tenorMusic = \relative c' {
1877 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
1879 tenorWords = \sopWords
1880 bassMusic = \relative c' {
1882 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
1884 bassWords = \sopWords
1885 upper = \relative a' {
1888 r4 <a d fis>2 <a e' a>4 |
1889 <d fis d'>4. <d fis d'>8 <a d a'>2 |
1890 <g cis g'>4 <a d fis> <a cis e>2 |
1892 lower = \relative c, {
1895 <d d'>4 <d d'>2 <cis cis'>4 |
1896 <b b'>4. <b' b'>8 <fis fis'>2 |
1897 <e e'>4 <d d'> <a' a'>2 |
1901 << % combine ChoirStaff and PianoStaff in parallel
1903 \new Staff = "sopranos" <<
1904 \set Staff.instrumentName = "Soprano"
1905 \new Voice = "sopranos" { \global \sopMusic }
1907 \new Lyrics \lyricsto "sopranos" { \sopWords }
1908 \new Staff = "altos" <<
1909 \set Staff.instrumentName = "Alto"
1910 \new Voice = "altos" { \global \altoMusic }
1912 \new Lyrics \lyricsto "altos" { \altoWords }
1913 \new Staff = "tenors" <<
1914 \set Staff.instrumentName = "Tenor"
1915 \new Voice = "tenors" { \global \tenorMusic }
1917 \new Lyrics \lyricsto "tenors" { \tenorWords }
1918 \new Staff = "basses" <<
1919 \set Staff.instrumentName = "Bass"
1920 \new Voice = "basses" { \global \bassMusic }
1922 \new Lyrics \lyricsto "basses" { \bassWords }
1926 \set PianoStaff.instrumentName = "Piano "
1927 \new Staff = "upper" \upper
1928 \new Staff = "lower" \lower
1935 @node Building a score from scratch
1936 @subsection Building a score from scratch
1938 After gaining some facility with writing LilyPond code you
1939 may find that it is easier to build a score from scratch
1940 rather than modifying one of the templates. You can also
1941 develop your own style this way to suit the sort of music you
1942 like. Let's see how to put together the score for an organ
1943 prelude as an example.
1945 We begin with a header section. Here go the title, name
1946 of composer, etc followed by the variable definitions
1947 and ending with the score block. Let's start with these and
1948 fill in the details later.
1950 We'll use the first two bars of Bach's prelude
1951 based on @emph{Jesu, meine Freude} which is set in two
1952 manuals and pedal organ. The top manual has two voices,
1953 the lower and pedal organ one each. So we need four
1954 music definitions and one to define the time signature
1960 title = "Jesu, meine Freude"
1961 composer = "J S Bach"
1963 TimeKey = @{ \time 4/4 \key c \minor @}
1964 ManualOneVoiceOneMusic = @{s1@}
1965 ManualOneVoiceTwoMusic = @{s1@}
1966 ManualTwoMusic = @{s1@}
1967 PedalOrganMusic = @{s1@}
1973 For now we've just used a spacer note, @code{s1},
1974 instead of the real music. We'll add that later.
1976 Next let's see what should go in the score block.
1977 We simply mirror the staff structure we want.
1978 Organ music is usually written on three staves,
1979 one for each manual and one for the pedals. The
1980 manual staves should be bracketed together so we
1981 need to use a PianoStaff for them. The first
1982 manual part needs two voices and the second manual
1987 \new Staff = "ManualOne" <<
1988 \new Voice @{ \ManualOneVoiceOneMusic @}
1989 \new Voice @{ \ManualOneVoiceTwoMusic @}
1990 >> % end ManualOne Staff context
1991 \new Staff = "ManualTwo" <<
1992 \new Voice @{ \ManualTwoMusic @}
1993 >> % end ManualTwo Staff context
1994 >> % end PianoStaff context
1997 Next we need to add a staff for the pedal organ.
1998 This goes underneath the PianoStaff, but it must
1999 be simultaneous with it, so we need angle brackets
2000 round the two. Missing these out would generate
2001 an error in the log file. It's a common mistake
2002 which you'll make sooner or later! Try copying
2003 the final example at the end of this section,
2004 remove these angle brackets, and compile it to
2005 see what errors it generates.
2008 << % PianoStaff and Pedal Staff must be simultaneous
2010 \new Staff = "ManualOne" <<
2011 \new Voice @{ \ManualOneVoiceOneMusic @}
2012 \new Voice @{ \ManualOneVoiceTwoMusic @}
2013 >> % end ManualOne Staff context
2014 \new Staff = "ManualTwo" <<
2015 \new Voice @{ \ManualTwoMusic @}
2016 >> % end ManualTwo Staff context
2017 >> % end PianoStaff context
2018 \new Staff = "PedalOrgan" <<
2019 \new Voice @{ \PedalOrganMusic @}
2024 It is not strictly necessary to use the simultaneous contruct
2025 @code{<< >>} for the manual two staff and the pedal organ staff,
2026 since they contain only one music expression, but it does no harm
2027 and always using angle brackets after @code{\new Staff} is a good
2028 habit to cultivate in case there are multiple voices.
2030 Let's add this structure to the score block, and adjust the
2031 indenting. We also add the appropriate clefs, ensure the
2032 second voice stems point down with @code{\voiceTwo} and
2033 enter the time signature and key to each staff using our
2034 predefined variable, @code{\TimeKey}.
2038 << % PianoStaff and Pedal Staff must be simultaneous
2040 \new Staff = "ManualOne" <<
2041 \TimeKey % set time signature and key
2043 \new Voice @{ \ManualOneVoiceOneMusic @}
2044 \new Voice @{ \voiceTwo \ManualOneVoiceTwoMusic @}
2045 >> % end ManualOne Staff context
2046 \new Staff = "ManualTwo" <<
2049 \new Voice @{ \ManualTwoMusic @}
2050 >> % end ManualTwo Staff context
2051 >> % end PianoStaff context
2052 \new Staff = "PedalOrgan" <<
2055 \new Voice @{ \PedalOrganMusic @}
2056 >> % end PedalOrgan Staff
2058 @} % end Score context
2061 That completes the structure. Any three-staff organ music
2062 will have a similar structure, although the number of voices
2063 may vary. All that remains now
2064 is to add the music, and combine all the parts together.
2066 @lilypond[quote,verbatim,ragged-right]
2069 title = "Jesu, meine Freude"
2070 composer = "J S Bach"
2072 TimeKey = { \time 4/4 \key c \minor }
2073 ManualOneVoiceOneMusic = \relative g' {
2074 g4 g f ees | d2 c2 |
2076 ManualOneVoiceTwoMusic = \relative c' {
2077 ees16 d ees8~ ees16 f ees s c8 d~ d c~ |
2078 c c4 b8 c8. g16 c b c d |
2080 ManualTwoMusic = \relative c' {
2081 c16 b c8~ c16 b c g a8 g~ g16 g aes ees |
2082 f ees f d g aes g f ees d e8~ ees16 f ees d |
2084 PedalOrganMusic = \relative c {
2085 r8 c16 d ees d ees8~ ees16 a, b g c b c8 |
2086 r16 g ees f g f g8 c,2 |
2090 << % PianoStaff and Pedal Staff must be simultaneous
2092 \new Staff = "ManualOne" <<
2093 \TimeKey % set time signature and key
2095 \new Voice { \ManualOneVoiceOneMusic }
2096 \new Voice { \voiceTwo \ManualOneVoiceTwoMusic }
2097 >> % end ManualOne Staff context
2098 \new Staff = "ManualTwo" <<
2101 \new Voice { \ManualTwoMusic }
2102 >> % end ManualTwo Staff context
2103 >> % end PianoStaff context
2104 \new Staff = "PedalOrgan" <<
2107 \new Voice { \PedalOrganMusic }
2108 >> % end PedalOrgan Staff
2110 } % end Score context
2113 @node Scores and parts
2114 @section Scores and parts
2116 TODO: this is really old stuff from the really old tutorial.
2117 Rewrite, fix, etc. Or maybe delete entirely. -gp
2118 Include section on tags -td
2119 and then move to section 5. Working ... -td
2121 In orchestral music, all notes are printed twice. Once in a part for
2122 the musicians, and once in a full score for the conductor. Variables can
2123 be used to avoid double work. The music is entered once, and stored in
2124 a variable. The contents of that variable is then used to generate
2125 both the part and the full score.
2127 It is convenient to define the notes in a special file. For example,
2128 suppose that the file @file{horn-music.ly} contains the following part
2129 of a horn/@/bassoon duo
2132 hornNotes = \relative c @{
2139 Then, an individual part is made by putting the following in a file
2142 \include "horn-music.ly"
2144 instrument = "Horn in F"
2148 \transpose f c' \hornNotes
2155 \include "horn-music.ly"
2159 substitutes the contents of @file{horn-music.ly} at this position in
2160 the file, so @code{hornNotes} is defined afterwards. The command
2161 @code{\transpose f@tie{}c'} indicates that the argument, being
2162 @code{\hornNotes}, should be transposed by a fifth upwards. Sounding
2163 @code{f} is denoted by notated @code{c'}, which corresponds with the
2164 tuning of a normal French Horn in@tie{}F. The transposition can be seen
2165 in the following output
2167 @lilypond[quote,ragged-right]
2168 \transpose f c' \relative c {
2174 In ensemble pieces, one of the voices often does not play for many
2175 measures. This is denoted by a special rest, the multi-measure
2176 rest. It is entered with a capital @code{R} followed by a duration
2177 (@code{1}@tie{}for a whole note, @code{2}@tie{}for a half note,
2178 etc.). By multiplying the
2179 duration, longer rests can be constructed. For example, this rest
2180 takes 3@tie{}measures in 2/4 time
2186 When printing the part, multi-rests
2187 must be condensed. This is done by setting a run-time variable
2190 \set Score.skipBars = ##t
2194 This command sets the property @code{skipBars} in the
2195 @code{Score} context to true (@code{##t}). Prepending the rest and
2196 this option to the music above, leads to the following result
2198 @lilypond[quote,ragged-right]
2199 \transpose f c' \relative c {
2201 \set Score.skipBars = ##t
2208 The score is made by combining all of the music together. Assuming
2209 that the other voice is in @code{bassoonNotes} in the file
2210 @file{bassoon-music.ly}, a score is made with
2213 \include "bassoon-music.ly"
2214 \include "horn-music.ly"
2217 \new Staff \hornNotes
2218 \new Staff \bassoonNotes
2225 @lilypond[quote,ragged-right]
2233 r4 d,8 f | gis4 c | b bes |
2234 a8 e f4 | g d | gis f