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
7 You've seen in the Tutorial how to produce beautifully printed
8 music from a simple text file. This section introduces the
9 concepts and techniques required to produce equally beautiful
10 but more complex scores.
13 * How LilyPond files work::
14 * Voices contain music::
15 * Contexts and engravers::
16 * Extending the templates::
20 @node How LilyPond files work
21 @section How LilyPond files work
23 The LilyPond input format is quite free-form, giving experienced
24 users a lot of flexibility to structure their files however they
25 wish. But this flexibility can make things confusing for new
26 users. This section will explain some of this structure, but may
27 gloss over some details in favor of simplicity. For a complete
28 description of the input format, see @ruser{File structure}.
31 * Introduction to the LilyPond file structure::
32 * Score is a (single) compound musical expression::
33 * Nesting music expressions::
34 * On the un-nestedness of brackets and ties::
37 @node Introduction to the LilyPond file structure
38 @subsection Introduction to the LilyPond file structure
40 A basic example of a lilypond input file is
45 @var{...compound music expression...} % all the music goes here!
53 There are many variations of this basic pattern, but this
54 example serves as a useful starting place.
56 Up to this point none of the examples you have seen have used a
57 @code{\score@{@}} command. This is because LilyPond automatically
58 adds the extra commands which are needed when you give it simple
59 input. LilyPond treats input like this:
68 as shorthand for this:
85 In other words, if the input contains a single music expression,
86 LilyPond will interpret the file as though the music expression
87 was wrapped up inside the commands shown above. For now, though,
88 let us return to the first example and examine the @code{\score}
89 command, leaving the others to default.
91 A @code{\score} block must always contain just one music
93 this must appear first within the @code{\score @{..@}} block.
94 Remember that a music expression could be anything from a single
95 note to a huge compound expression like
100 @var{...insert the whole score of a Wagner opera in here...}
106 Since everything is inside @code{@{ ... @}}, it counts
107 as one music expression.
109 As we saw previously, the @code{\score} can contain other things,
122 Some people put some of those commands outside the @code{\score}
123 block -- for example, @code{\header} is often placed above the
124 @code{\score}. That's just another shorthand that LilyPond
127 Two more commands you have not previously seen are
128 @code{\layout @{ @}} and @code{\midi @{@}}. If these appear as
129 shown they will cause LilyPond to produce a printed output and a
130 MIDI output respectively. They are described fully in the
131 Notation Reference -- @ruser{Score layout} and
132 @ruser{Creating MIDI files}.
134 The @code{\book} command allows
135 several @code{\score} blocks to be combined into one output.
136 If there are several @code{\book} blocks each one produces a
137 separate output file. For details see @ruser{Multiple scores
142 Another great shorthand is the ability to define variables. All
143 the templates use this
146 melody = \relative c' @{
155 When LilyPond looks at this file, it takes the value of
156 @code{melody} (everything after the equals sign) and inserts it
157 whenever it sees @code{\melody}. There's nothing special about
158 the names -- it could be @code{melody}, @code{global},
160 @code{pianorighthand}, or @code{foofoobarbaz}. For more details,
161 see @ref{Saving typing with variables and functions}.
162 Remember that you can use almost any name you like as long
163 as it contains just alphabetic characters and is distinct from
164 LilyPond command names. The exact
165 limitations on variable names are detailed in
166 @ruser{File structure}.
172 For a complete definition of the input format, see
173 @ruser{File structure}.
175 @node Score is a (single) compound musical expression
176 @subsection Score is a (single) compound musical expression
178 @cindex Compound music expression
179 @cindex Music expression, compound
181 We saw the general organization of LilyPond input files in the
182 previous section, @ref{How LilyPond files work}. But we seemed to
183 skip over the most important part: how do we figure out what to
184 write after @code{\score}?
186 We didn't skip over it at all. The big mystery is simply that
187 there @emph{is} no mystery. This line explains it all:
190 @emph{A @code{\score} must begin with a compound music expression.}
194 You may find it useful to review
195 @ref{Music expressions explained}. In that section, we saw how to
196 build big music expressions from small pieces -- we started from
197 notes, then chords, etc. Now we're going to start from a big
198 music expression and work our way down.
202 @{ % this brace begins the overall compound music expression
204 @var{...insert the whole score of a Wagner opera in here...}
206 @} % this brace ends the overall compound music expression
211 A whole Wagner opera would easily double the length of this
212 manual, so let's just add a singer and piano. We don't need a
213 @code{GrandStaff} for this ensemble, which simply groups a number
214 of staves together with a brace at the left, so we shall remove
215 it. We @emph{do} need a singer and a piano, though.
221 \new Staff = "singer" <<
223 \new PianoStaff = piano <<
231 Remember that we use @code{<<} and @code{>>} to show simultaneous
232 music. And we definitely want to show the vocal part and piano
233 part at the same time, not one after the other! However, the
234 @code{<< .. >>} construct is not really necessary for the Singer
235 staff, as it contains only one music expression, but Staves often
236 do require simultaneous Voices within them, so using @code{<< .. >>}
237 rather than braces is a good habit to adopt.
243 \new Staff = "singer" <<
244 \new Voice = "vocal" @{ @}
247 \new PianoStaff = "piano" <<
248 \new Staff = "upper" @{ @}
249 \new Staff = "lower" @{ @}
257 Now we have a lot more details. We have the singer's staff: it
258 contains a @code{Voice} (in LilyPond, this term refers to a set of
259 notes, not necessarily vocal notes -- for example, a violin
260 generally plays one voice) and some lyrics. We also have a piano
261 staff: it contains an upper staff (right hand) and a lower staff
264 At this stage, we could start filling in notes. Inside the curly
265 braces next to @code{\new Voice = vocal}, we could start writing
273 But if we did that, the @code{\score} section would get pretty
274 long, and it would be harder to understand what was happening. So
275 let's use variables instead.
278 melody = \relative c'' @{ @}
279 text = \lyricmode @{ @}
280 upper = \relative c'' @{ @}
281 lower = \relative c @{ @}
285 \new Staff = "singer" <<
286 \new Voice = "vocal" @{ \melody @}
287 \addlyrics @{ \text @}
289 \new PianoStaff = "piano" <<
290 \new Staff = "upper" @{ \upper @}
291 \new Staff = "lower" @{ \lower @}
299 Be careful about the difference between notes, which are introduced
300 with @code{\relative}, and lyrics, which are introduced with
301 @code{\lyricmode}. These are essential to tell LilyPond
302 to interpret the following content as music and text
305 When writing (or reading) a @code{\score} section, just take it
306 slowly and carefully. Start with the outer layer, then work on
307 each smaller layer. It also really helps to be strict with
308 indentation -- make sure that each item on the same layer starts
309 on the same horizontal position in your text editor.
312 @node Nesting music expressions
313 @subsection Nesting music expressions
315 It is not essential to declare all staves at the beginning;
316 they may be introduced temporarily at any point. This is
317 particularly useful for creating ossia sections
318 (see @rglos{ossia}). Here is a simple example showing how
319 to introduce a new staff temporarily for the duration of
322 @lilypond[verbatim,quote,ragged-right]
339 Note that the size of the clef is the same as a clef printed
340 following a clef change -- slightly smaller than the clef
341 at the begining of the line. This is usual for clefs printed
342 in the middle of a line.
344 The ossia section may be placed above the staff
347 @lilypond[verbatim,quote,ragged-right]
355 alignAboveContext = "main" }
363 This example uses @code{\with}, which will be explained more
364 fully later. It is a means of modifying the default behaviour
365 of a Staff. Here it says that the new staff should be placed
366 above the staff called @qq{main} instead of the default position
369 Ossia are often written without clef and without
370 time signature and are usually in a smaller font.
371 These require further commands which
372 have not yet been introduced. See @ref{Size of objects}
374 @node On the un-nestedness of brackets and ties
375 @subsection On the un-nestedness of brackets and ties
377 You have already met a number of different types of bracket in
378 writing the input file to LilyPond. These obey different rules
379 which can be confusing at first. Before we explain the rules
380 let's first review the different types of bracket.
382 @c attempt to force this onto a new page
384 @multitable @columnfractions .3 .7
385 @headitem Bracket Type
387 @item @code{@{ .. @}}
388 @tab Encloses a sequential segment of music
390 @tab Encloses the notes of a chord
391 @item @code{<< .. >>}
392 @tab Encloses concurrent or simultaneous sections
394 @tab Marks the start and end of a slur
395 @item @code{\( .. \)}
396 @tab Marks the start and end of a phrase mark
398 @tab Marks the start and end of a manual beam
401 To these we should add other constructs which generate lines
402 between or across notes: ties (marked by a tilde, @code{~}),
403 tuplets written as @code{\times x/y @{..@}}, and grace notes
404 written as @code{\grace@{..@}}.
406 Outside LilyPond, the conventional use of brackets requires
407 the different types to be properly nested, like this,
408 @code{<< [ @{ ( .. ) @} ] >>}, with the closing brackets being
409 encountered in exactly the opposite order to the opening
410 brackets. This @strong{is} a requirement for the three types of
411 bracket described by the word @q{Encloses} in the table above --
412 they must nest properly.
413 However, the remaining brackets, described with the word
414 @q{Marks} in the table above together with ties and tuplets,
415 do @strong{not} have to nest
416 properly with any of the brackets. In fact, these are not
417 brackets in the sense that
418 they enclose something -- they are simply markers to indicate
419 where something starts and ends.
421 So, for example, a phrasing slur can start before a manually
422 inserted beam and end before the end of the beam -- not very
423 musical, perhaps, but possible:
425 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
426 { g8\( a b[ c b\) a] }
429 In general, different kinds of brackets, and those implied by
430 tuplets, ties and grace notes, may be mixed freely.
431 This example shows a beam extending into a tuplet (line 1),
432 a slur extending into a tuplet (line 2),
433 a beam and a slur extending into a tuplet, a tie crossing
434 two tuplets, and a phrasing slur extending out of a tuplet
437 @lilypond[quote,verbatim,fragment,ragged-right]
439 r16[ g16 \times 2/3 {r16 e'8] }
440 g16( a \times 2/3 {b d) e' }
441 g8[( a \times 2/3 {b d') e'~]}
442 \times 4/5 {e'32\( a b d' e'} a'4.\)
447 @node Voices contain music
448 @section Voices contain music
450 Singers need voices to sing, and so does LilyPond.
451 The actual music for all instruments in a score
452 is contained in Voices -- the most fundamental
453 of all LilyPond's concepts.
456 * I'm hearing Voices::
457 * Explicitly instantiating voices::
458 * Voices and vocals::
461 @node I'm hearing Voices
462 @subsection I'm hearing Voices
466 @cindex Voice context
468 The lowest, most fundamental or innermost layers in a LilyPond
469 score are called @q{Voice contexts} or just @q{Voices} for short.
470 Voices are sometimes called @q{layers} in other notation
473 In fact, a Voice layer or context is the only one which can
474 contain music. If a Voice context is not explicitly declared
475 one is created automatically, as we saw at the beginning of
476 this chapter. Some instruments such as an
477 Oboe can play only one note at a time. Music written for
478 such instruments is monophonic and requires just a single
479 voice. Instruments which can play more than one note at a
480 time like the piano will often require multiple voices to
481 encode the different concurrent notes and rhythms they are
484 A single voice can contain many notes in a chord, of course,
485 so when exactly are multiple voices needed?
486 Let us analyse a short piece of music to see how many voices
487 are required. Here are the notes from the first two bars
488 of the second of Chopin's Deux Nocturnes, Op 32.
490 @c The following should appear as music without code
491 @lilypond[quote,ragged-right]
492 \new Staff \relative c'' {
500 \once \override NoteColumn #'force-hshift = #0 <ees c>2
501 \once \override NoteColumn #'force-hshift = #0.5 des2 }
507 The direction of the stems is often used to indicate the
508 continuity of two simultaneous melodic lines. Here the
509 stems of the highest notes are all pointing up and the
510 stems of the lower notes are all pointing down.
511 This is the first indication that more than one voice
514 But the real need for multiple voices arises when notes
515 which start at the same time have different durations.
516 Look at the notes which start at beat three in the first
517 bar. The a-flat is a dotted quarter note, the f is a
518 quarter note and the d-flat is a half note. These
519 cannot be written as a chord as all the notes in a chord
520 must have the same duration. Neither can they be written
521 as sequential notes, as they must start at the same time.
522 This section of the bar requires three voices, and the
523 normal practice would be to write the whole bar as three
524 voices, as shown here, where we have used different note heads
525 and colors for the three voices.
527 @c The following should appear as music without code
528 @c The three voice styles should be defined in -init
529 @lilypond[quote,ragged-right]
530 \new Staff \relative c'' {
541 \once \override NoteColumn #'force-hshift = #0 <ees c>2
542 \once \override NoteColumn #'force-hshift = #0.5 des2 }
548 Let us see how this is done.
552 The easiest way to enter fragments with more than one voice on a
553 staff is to enter each voice as a sequence (with @code{@{...@}}),
554 and combine them simultaneously with angle brackets, @code{<<...>>}.
555 The fragments must also be separated with double backward slashes,
556 @code{\\}, to place them in separate voices. Without these, the
557 notes would be entered into a single voice, which would usually
558 cause errors. This technique is particularly suited to pieces of
559 music which are largely monophonic with occasional short sections
560 of polyphony. Here's a simple example:
562 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
564 % Voice "1" Voice "2"
565 << { r4 g g4. a8 } \\ { d,2 d4 g } >> |
566 << { bes4 bes c bes } \\ { g4 g g8( a) g4 } >> |
567 << { a2. r4 } \\ { fis2. s4 } >>
570 It is not necessary to use a separate @code{<< \\ >>} construct
571 for each bar. For music with few notes in each bar this layout
572 can help the legibility of the code, but if there are many
573 notes in each bar it may be better to split out each voice
574 separately, like this:
576 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
592 This example has just two voices, but the same contruct may be
593 used to encode three or more voices by adding more back-slash
596 The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
597 In each of these contexts, the vertical direction of slurs,
598 stems, ties, dynamics etc., is set appropriately.
600 @lilypond[quote,verbatim,fragment]
601 \new Staff \relative c' {
604 % Voice "1" Voice "2" Voice "3"
605 << { g4 f e } \\ { r8 e4 d c8 ~ } >> |
606 << { d2 e2 } \\ { c8 b16 a b8 g ~ g2 } \\ { s4 b4 c2 } >> |
610 These voices are all separate from the main voice that contains
611 the notes just outside the @code{<< .. >>} construct. Let's call
612 this the @emph{simultaneous construct}. Slurs and ties may only
613 connect notes within the same voice, so slurs and ties cannot go
614 into or out of a simultaneous construct. Conversely,
615 parallel voices from separate simultaneous constructs on the same
616 staff are the same voice. Other voice-related properties also
617 carry across simultaneous constructs. Here is the same example,
618 with different colors and note heads for each voice. Note that
619 changes in one Voice do not affect other voices, but they do
620 persist in the same Voice later. Note also that tied notes may be
621 split across the same voices in two constructs, shown here in the
624 @lilypond[quote,verbatim]
625 \new Staff \relative c' {
640 { d2 e2 } % Voice 1 continues
642 { c8 b16 a b8 g ~ g2 } % Voice 2 continues
652 The commands @code{\voiceXXXStyle} are mainly intended for use in
653 educational documents such as this one. They modify the color
654 of the note head, the stem and the beams, and the style of the
655 note head, so that the voices may be easily distinguished.
656 Voice one is set to red diamonds, voice two to blue triangles,
657 voice three to green crossed circles, and voice four (not used
658 here) to magenta crosses. We shall see later how commands like
659 these may be created by the user.
660 See @ref{Visibility and color of objects}
661 TODO Add link to using variables for tweaks
663 Polyphony does not change the relationship of notes within a
664 @code{\relative @{ @}} block. Each note is still calculated
665 relative to the note immediately preceding it, or to the first
666 note of the preceding chord. So in
669 \relative c' @{ noteA << < noteB noteC > \\ noteD >> noteE @}
673 @code{noteB} is relative to @code{noteA} @*
674 @code{noteC} is relative to @code{noteB}, not @code{noteA}; @*
675 @code{noteD} is relative to @code{noteB}, not @code{noteA} or
677 @code{noteE} is relative to @code{noteD}, not @code{noteA}
679 We are now in a position to return to the first example from
680 the Chopin Nocturne to see how this might be encoded. As we
681 shall see, this encounters some difficulties. We begin as
682 we have learnt, using the @code{<< \\ >>} construct to
683 enter the music of the first bar in three voices:
685 @lilypond[quote,verbatim,fragment,ragged-right]
686 \new Staff \relative c'' {
689 { c2 aes4. bes8 } \\ { aes2 f4 fes } \\ { <ees c>2 des2 }
699 @funindex \voiceThree
702 The stem directions are automatically assigned with the
703 odd-numbered voices taking upward stems and the even-numbered
704 voices downward ones. The stems for voices 1 and 2 are right,
705 but the stems in voice 3 should go down in this particular piece
706 of music. We can correct this
707 by telling LilyPond that this third voice is really a fourth
708 voice, with stems going down, using the @code{\voiceFour}
709 command. There are also corresponding @code{\voiceOne},
710 @code{\voiceTwo}, and @code{\voiceThree}
711 commands. This results in the following:
713 @lilypond[quote,verbatim,fragment,ragged-right]
714 \new Staff \relative c'' {
719 { \voiceFour <ees c>2 des2 }
726 and exposes a problem commonly encountered with multiple
727 voices: the stems of notes can collide with note heads
728 in other voices. In laying out the notes, LilyPond allows the
729 notes or chords from two voices to occupy the same vertical
730 note column provided the stems are in opposite directions, but
731 the notes from a third voice are displaced to avoid the stems
732 colliding. This often works well, but in this example the
733 notes of the third voice are clearly not well placed by default.
734 LilyPond provides several ways to adjust the horizontal placing
735 of notes. We are not quite ready yet to see how to correct this,
736 so we shall leave this problem until a later section
737 (see @ref{Fixing overlapping notation} )
739 @node Explicitly instantiating voices
740 @subsection Explicitly instantiating voices
742 Voice contexts can also be created manually
743 inside a @code{<< >>} block to create polyphonic music, using
744 @code{\voiceOne} ... @code{\voiceFour} to indicate the required
745 directions of stems, slurs, etc. In longer scores this method
746 is clearer, as it permits the voices to be separated and to be
747 given more descriptive names.
749 Specifically, the construct @code{<< \\ >>} which we used in
750 the previous section:
755 << @{ e4 f g a @} \\ @{ c,4 d e f @} >>
765 \new Voice = "1" @{ \voiceOne \relative c' @{ e4 f g a @} @}
766 \new Voice = "2" @{ \voiceTwo \relative c' @{ c4 d e f @} @}
770 Both of the above would produce
772 @c The following example should not display the code
773 FIXME: weird compiling bug! Leave for gp.
774 @c @lilypond{ragged-right,quote]
776 @c % << { e4 f g a } \\ { c,4 d e f } >>
780 The @code{\voiceXXX} commands set the direction of stems, slurs,
781 ties, articulations, text annotations, augmentation dots of dotted
782 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
783 make these objects point upwards, while @code{\voiceTwo} and
784 @code{\voiceFour} make them point downwards. These commands also
785 generate a horizontal shift for each voice when this is required
786 to avoid clashes of note heads. The command @code{\oneVoice}
787 reverts the settings back to the normal values for a single voice.
789 Let us see in some simple examples exactly what effect
790 @code{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on
791 markup, ties, slurs, and dynamics:
793 @lilypond[quote,ragged-right,verbatim]
795 % Default behaviour or behaviour after \oneVoice
796 c d8 ~ d e4 ( f g a ) b-> c
800 @lilypond[quote,ragged-right,verbatim]
803 c d8 ~ d e4 ( f g a ) b-> c
805 c, d8 ~ d e4 ( f g a ) b-> c
809 @lilypond[quote,ragged-right,verbatim]
812 c d8 ~ d e4 ( f g a ) b-> c
814 c, d8 ~ d e4 ( f g a ) b-> c
818 An expression that appears directly inside a @code{<< >>} belongs
819 to the main voice (but, note, @strong{not} in a @code{<< \\ >>}
820 construct). This is useful when extra voices appear while the
821 main voice is playing. Here is a more correct rendition of the
822 example from the previous section. The red diamond-shaped notes
823 demonstrate that the main melody is now in a single voice context,
824 permitting a phrasing slur to be drawn over them.
826 @lilypond[quote,ragged-right,verbatim]
827 \new Staff \relative c' {
829 % The following notes are monophonic
831 % Start simultaneous section of three voices
833 % Continue the main voice in parallel
835 % Initiate second voice
837 % Set stems, etc, down
839 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
841 % Initiate third voice
851 @cindex nesting music expressions
852 @cindex nesting simultaneous constructs
854 More deeply nested polyphony constructs are possible, and if a
855 voice appears only briefly this might be a more natural way to
858 @lilypond[quote,ragged-right,verbatim]
859 \new Staff \relative c' {
879 This method of nesting new voices briefly is useful
880 when only small sections of the music
881 are polyphonic, but when the whole staff is largely polyphonic
882 it can be clearer to use multiple voices throughout, using
883 spacing notes to step over sections where the voice is silent,
886 @lilypond[quote,ragged-right,verbatim]
887 \new Staff \relative c' <<
888 % Initiate first voice
891 c16^( d e f g4 f e | d2 e2) |
893 % Initiate second voice
895 % set stems, etc down
897 s4 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 |
899 % Initiate third voice
909 @cindex shift commands
915 Closely spaced notes in a chord, or notes occuring at the same
916 time in different voices, are arranged in two, occasionally more,
917 columns to prevent the note heads overlapping. These are called
918 note columns. There are separate columns for each voice, and
919 the currently specified voice-dependent shift is applied to the
920 note column if there would otherwise be a collision. This can
921 be seen in the example above. In bar 2 the C in voice two is
922 shifted to the right relative to the D in voice one, and in the
923 final chord the C in voice three is also shifted to the right
924 relative to the other notes.
926 The @code{\shiftOn}, @code{\shiftOnn}, @code{\shiftOnnn}, and
927 @code{\shiftOff} commands specify the degree to which notes and
928 chords of the voice should be shifted if a collision
929 would otherwise occur. By default, the outer voices (normally
930 voices one and two) have @code{\shiftOff} specified, while the
931 inner voices (three and four) have @code{\shiftOn} specified.
932 When a shift is applied, Voices one and three are shifted to
933 the right and voices two and four to the left.
935 @code{\shiftOnn} and @code{\shiftOnnn} define further shift
936 levels which may be specified temporarily to resolve collisions
937 in complex situations -- see @ref{Real music example}.
939 A note column can contain just one note (or chord) from a voice
940 with stems up and one note (or chord) from a voice with stems
941 down. If notes from two voices which have their stems in the
942 same direction are placed at the same position and both voices
943 have no shift or the same shift specified, the error message
944 @qq{Too many clashing note columns} will be produced.
946 @node Voices and vocals
947 @subsection Voices and vocals
949 Vocal music presents a special difficulty: we need to combine two
950 expressions -- notes and lyrics.
952 You have already seen the @code{\addlyrics@{@}} command, which
953 handles simple scores well. However, this technique is
954 quite limited. For more complex music, you must introduce the
955 lyrics in a @code{Lyrics} context using @code{\new Lyrics} and
957 the lyrics to the notes with @code{\lyricsto@{@}}, using the
958 name assigned to the Voice.
960 @lilypond[quote,verbatim,fragment]
962 \new Voice = "one" \relative c'' {
965 c4 b8. a16 g4. f8 e4 d c2
967 \new Lyrics \lyricsto "one" {
968 No more let sins and sor -- rows grow.
973 The automatic beaming which LilyPond uses by default works well
974 for instrumental music, but not so well for music with lyrics,
975 where beaming is either not required at all or is used to indicate
976 melismata in the lyrics. In the example above we use the command
977 @code{\autoBeamOff} to turn off the automatic beaming.
979 Let us reuse the earlier example from Judas Maccabæus to
980 illustrate this more flexible technique. We first recast
981 it to use variables so the music and lyrics can be separated
982 from the staff structure. We also introduce a ChoirStaff
983 bracket. The lyrics themselves must be introduced with
984 @code{\lyricmode} to ensure they are interpreted as lyrics
987 @lilypond[quote,verbatim]
988 global = { \time 6/8 \partial 8 \key f \major}
989 SopOneMusic = \relative c'' {
990 c8 | c([ bes)] a a([ g)] f | f'4. b, | c4.~ c4 }
991 SopTwoMusic = \relative c' {
992 r8 | r4. r4 c8 | a'([ g)] f f([ e)] d | e([ d)] c bes' }
993 SopOneLyrics = \lyricmode {
994 Let | flee -- cy flocks the | hills a -- dorn, __ }
995 SopTwoLyrics = \lyricmode {
996 Let | flee -- cy flocks the | hills a -- dorn, }
1001 \new Voice = "SopOne" {
1005 \new Lyrics \lyricsto "SopOne" {
1010 \new Voice = "SopTwo" {
1013 \new Lyrics \lyricsto "SopTwo" {
1021 This is the basic structure of all vocal scores. More staves may
1022 be added as required, more voices may be added to the staves,
1023 more verses may be added to the lyrics,
1024 and the variables containing the music can easily be placed
1025 in separate files should they become too long.
1027 Here is a final example of the first line of a hymn with four
1028 verses, set for SATB. In this case the words for all four
1031 @lilypond[quote,verbatim]
1032 TimeKey = { \time 4/4 \partial 4 \key c \major}
1033 SopMusic = \relative c' { c4 | e4. e8 g4 g | a a g }
1034 AltoMusic = \relative c' { c4 | c4. c8 e4 e | f f e }
1035 TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 }
1036 BassMusic = \relative c { c4 | c4. c8 c4 c | f8 g a b c4 }
1037 VerseOne = \lyricmode {
1038 E -- | ter -- nal fa -- ther, | strong to save, }
1039 VerseTwo = \lyricmode {
1040 O | Christ, whose voice the | wa -- ters heard, }
1041 VerseThree = \lyricmode {
1042 O | Ho -- ly Spi -- rit, | who didst brood }
1043 VerseFour = \lyricmode {
1044 O | Tri -- ni -- ty of | love and pow'r }
1050 \new Voice = "Sop" { \voiceOne \TimeKey \SopMusic }
1051 \new Voice = "Alto" { \voiceTwo \AltoMusic }
1052 \new Lyrics \lyricsto "Sop" { \VerseOne }
1053 \new Lyrics \lyricsto "Sop" { \VerseTwo }
1054 \new Lyrics \lyricsto "Sop" { \VerseThree }
1055 \new Lyrics \lyricsto "Sop" { \VerseFour }
1059 \new Voice = "Tenor" { \voiceOne \TenorMusic }
1060 \new Voice = "Bass" { \voiceTwo \BassMusic }
1066 @node Contexts and engravers
1067 @section Contexts and engravers
1069 Contexts and engravers have been mentioned informally
1070 in earlier sections; we now must look at
1071 these concepts in more detail, as they are important
1072 in the fine-tuning of LilyPond output.
1076 * Contexts explained::
1077 * Creating contexts::
1078 * Engravers explained::
1079 * Modifying context properties::
1080 * Adding and removing engravers::
1083 @node Contexts explained
1084 @subsection Contexts explained
1086 When music is printed, many notational elements which do not
1087 appear explicitly in the input file must be added to the
1088 output. For example, compare the input and output of the
1091 @lilypond[quote,verbatim,relative=2,fragment]
1095 The input is rather sparse, but in the output, bar lines,
1096 accidentals, clef, and time signature have been added. When
1097 LilyPond @emph{interprets} the input the musical information
1098 is inspected in time order, similar to reading a score from left
1099 to right. While reading the input, the program remembers where
1100 measure boundaries are, and which pitches require explicit
1101 accidentals. This information must be held on several levels.
1102 For example, the effect of an accidental is limited
1103 to a single staff, while a bar line must be synchronized across
1106 Within LilyPond, these rules and bits of information are grouped
1107 in @emph{Contexts}. We have already met the
1108 @code{Voice} context.
1109 Others are the @code{Staff} and @code{Score} contexts.
1110 Contexts are hierarchical to reflect the heirarchical nature of
1112 For example: a @code{Staff} context can contain many
1113 @code{Voice} contexts, and a @code{Score} context can
1114 contain many @code{Staff} contexts.
1117 @image{context-example,5cm,,}
1120 Each context has the responsibility for enforcing some notation rules,
1121 creating some notation objects and maintaining the associated
1122 properties. For example, the @code{Voice} context may introduce an
1123 accidental and then the @code{Staff} context maintains the rule to
1124 show or suppress the accidental for the remainder of the measure.
1126 As another example, the synchronization of bar lines is, by default,
1127 handled in the @code{Score} context.
1128 However, in some music we may not want the bar lines to be
1129 synchronized -- consider a polymetric score in 4/4 and 3/4 time.
1130 In such cases, we must modify the default settings of the
1131 @code{Score} and @code{Staff} contexts.
1133 For very simple scores, contexts are created implicitly, and you need
1134 not be aware of them. For larger pieces, such as anything with more
1135 than one staff, they must be
1136 created explicitly to make sure that you get as many staves as you
1137 need, and that they are in the correct order. For typesetting pieces
1138 with specialized notation, it is usual to modify existing, or
1139 even to define totally new, contexts.
1141 In addition to the @code{Score,} @code{Staff} and
1142 @code{Voice} contexts there are contexts which fit between
1143 the score and staff levels to control staff groups, such as the
1144 @code{PianoStaff} and @code{ChoirStaff} contexts. There
1145 are also alternative staff and voice contexts, and contexts for
1146 lyrics, percussion, fret boards, figured bass, etc. A complete
1147 list is shown in the Notation Reference.
1150 The names of all context types are formed from one or more
1151 words, each word being capitalised and joined immediately to the
1152 preceding word with no hyphen or underscore, e.g.,
1153 @code{GregorianTranscriptionStaff}.
1155 @node Creating contexts
1156 @subsection Creating contexts
1158 There can be only one top level context: the
1160 context. This is created with the @code{\score} command,
1161 or, in simple scores, it is created automatically.
1163 For scores with only one voice and one staff, the
1164 @code{Voice} and @code{Staff} contexts may be left to be
1165 created automatically, but for more complex scores it is
1166 necessary to create them by hand.
1167 The simplest command that does this is @code{\new}.
1168 It is prepended to a music expression, for example
1171 @cindex new contexts
1172 @cindex Context, creating
1175 \new @var{type} @var{music-expression}
1179 where @var{type} is a context name (like @code{Staff} or
1180 @code{Voice}). This command creates a new context, and starts
1181 interpreting the @var{music-expression} within that context.
1183 Note that there is no @code{\new Score} command;
1184 the single top-level @code{Score} context is introduced
1187 The @code{\new} command may also give a identifying name to the
1188 context to distinguish it from other contexts of the same type,
1191 \new @var{type} = @var{id} @var{music-expression}
1194 Note the distinction between the name of the context type,
1195 @code{Staff}, @code{Voice}, etc, and
1196 the identifying name of a particular instance of that type,
1197 which can be any sequence of letters invented by the user.
1198 The identifying name is used to refer back to that particular
1199 instance of a context. We saw this in use in the section on
1200 lyrics in @ref{Voices and vocals}.
1203 @node Engravers explained
1204 @subsection Engravers explained
1208 Every mark on the printed output of a score produced by LilyPond
1209 is produced by an @code{Engraver}. Thus there is an engraver
1210 to print staves, one to print note heads, one for stems, one for
1211 beams, etc, etc. In total there are over 120 such engravers!
1212 Fortunately, for most scores it is not necessary to know about
1213 more than a few, and for simple scores you do not need to know
1216 Engravers live and operate in Contexts.
1217 Engravers such as the @code{Metronome_mark_engraver}, whose
1218 action and output applies to the score as a whole, operate in
1219 the highest level context -- the @code{Score} context.
1221 The @code{Clef_engraver} and @code{Key_engraver} are to be
1222 found in every Staff Context, as different staves may require
1223 different clefs and keys.
1225 The @code{Note_heads_engraver} and @code{Stem_engraver} live
1226 in every @code{Voice} context, the lowest level context of all.
1228 Each engraver processes the particular objects associated
1229 with its function, and maintains the properties that relate
1230 to that function. These properties, like the properties
1231 associated with contexts, may be modified to change the
1232 operation of the engraver or the appearance of those elements
1233 in the printed score.
1235 Engravers all have compound names formed from words which
1236 describe their function. Just the first word is capitalised,
1237 and the remainder are joined to it with underscores. Thus
1238 the @code{Staff_symbol_engraver} is responsible for creating the
1239 lines of the staff, the @code{Clef_engraver} determines and sets
1240 the pitch reference point on the staff by drawing a clef symbol.
1242 Here are some of the most common engravers together with their
1243 function. You will see it is easy to guess the function from
1244 the name, or vice versa.
1246 @multitable @columnfractions .3 .7
1249 @item Accidental_engraver
1250 @tab Makes accidentals, cautionary and suggested accidentals
1255 @item Dynamic_engraver
1256 @tab Creates hairpins and dynamic texts
1258 @tab Creates the key signature
1259 @item Metronome_mark_engraver
1260 @tab Engraves metronome marking
1261 @item Note_heads_engraver
1262 @tab Engraves note heads
1265 @item Staff_symbol_engraver
1266 @tab Engraves the five (by default) lines of the staff
1268 @tab Creates stems and single-stem tremulos
1269 @item Time_signature_engraver
1270 @tab Creates time signatures
1275 We shall see later how the output of LilyPond can be changed
1276 by modifying the action of Engravers.
1279 @node Modifying context properties
1280 @subsection Modifying context properties
1282 @cindex context properties
1286 Contexts are responsible for holding the values of a number of
1287 context @emph{properties}. Many of them can be changed to
1288 influence the interpretation of the input and so change the
1289 appearance of the output. They are changed by the
1290 @code{\set} command. This takes the form
1293 \set @emph{ContextName}.@emph{propertyName} = #@emph{value}
1296 Where the @emph{ContextName} is usually @code{Score},
1297 @code{Staff} or @code{Voice}. It may be omitted,
1298 in which case @code{Voice} is assumed.
1300 The names of context properties consist of words joined
1301 together with no hyphens or underscores, all except the
1302 first having a capital letter. Here are a few examples
1303 of some commonly used ones. There are many more.
1305 @c attempt to force this onto a new page
1307 @multitable @columnfractions .25 .15 .45 .15
1308 @headitem propertyName
1314 @tab If true, set extra natural signs before accidentals
1315 @tab @code{#t}, @code{#f}
1316 @item currentBarNumber
1318 @tab Set the current bar number
1322 @tab If true, print slurs both above and below notes
1323 @tab @code{#t}, @code{#f}
1324 @item instrumentName
1326 @tab Set the name to be placed at the start of the staff
1327 @tab @code{"Cello I"}
1330 @tab Increase or decrease the font size
1334 @tab Set the text to print before the start of a verse
1339 where a Boolean is either True (@code{#t}) or False (@code{#f}),
1340 an Integer is a positive whole number, a Real is a positive
1341 or negative decimal number, and text is enclosed in double
1342 apostrophes. Note the occurrence of hash signs,
1343 (@code{#}), in two different places -- as part of the Boolean
1344 value before the @code{t} or @code{f}, and before @emph{value}
1345 in the @code{\set} statement. So when a Boolean is being
1346 entered you need to code two hash signs, e.g., @code{##t}.
1348 Before we can set any of these properties we need to know
1349 in which context they operate. Sometimes this is obvious,
1350 but occasionally it can be tricky. If the wrong context
1351 is specified, no error message is produced, but the expected
1352 action will not take place. For example, the
1353 @code{instrumentName} clearly lives in the Staff context, since
1354 it is the staff that is to be named.
1355 In this example the first staff is labelled, but not the second,
1356 because we omitted the context name.
1358 @lilypond[quote,verbatim,ragged-right]
1360 \new Staff \relative c'' {
1361 \set Staff.instrumentName = "Soprano"
1364 \new Staff \relative c' {
1365 \set instrumentName = "Alto" % Wrong!
1371 Remember the default context name is Voice, so the second
1372 @code{\set} command set the property @code{instrumentName} in the
1373 Voice context to @qq{Alto}, but as LilyPond does not look
1374 for any such property in the @code{Voice} context, no
1375 further action took place. This is not an error, and no error
1376 message is logged in the log file.
1378 Similarly, if the property name is mis-spelt no error message
1379 is produced, and clearly the expected action cannot be performed.
1380 If fact, you can set any (fictitious) @q{property} using any
1381 name you like in any context that exists by using the
1382 @code{\set} command. But if the name is not
1383 known to LilyPond it will not cause any action to be taken.
1384 This is one of the reasons why it is highly recommended to
1385 use a context-sensitive editor with syntax highlighting for
1386 editing LilyPond files, such as Vim, Jedit, ConTEXT or Emacs,
1387 since unknown property names will be highlighted differently.
1389 The @code{instrumentName} property will take effect only
1390 if it is set in the @code{Staff} context, but
1391 some properties can be set in more than one context.
1392 For example, the property @code{extraNatural} is by
1393 default set to ##t (true) for all staves.
1394 If it is set to ##f (false) in the @code{Staff} context
1395 it applies just to the accidentals on that staff.
1396 If it is set to false in the @code{Score} context
1397 it applies to all staves.
1399 So this turns off extra naturals in one staff:
1401 @lilypond[quote,verbatim,ragged-right]
1403 \new Staff \relative c'' {
1406 \new Staff \relative c'' {
1407 \set Staff.extraNatural = ##f
1414 and this turns them off in all staves:
1416 @lilypond[quote,verbatim,ragged-right]
1418 \new Staff \relative c'' {
1421 \new Staff \relative c'' {
1422 \set Score.extraNatural = ##f
1428 The value of every property set in this way can be reset
1429 to its original value with the @code{\unset} command.
1431 The @code{\set} and @code{\unset} commands can appear anywhere
1432 in the input file and will take effect from the time they are
1433 encountered until the end of the score or until the property is
1434 @code{\set} or @code{\unset} again. Let's try changing the
1435 font size, which affects the size of the note heads (among
1436 other things) several times.
1438 @lilypond[quote,verbatim,ragged-right,relative=1,fragment]
1440 % make note heads smaller
1443 % make note heads larger
1444 \set fontSize = #2.5
1446 % return to original size
1451 We have now seen how to set the values of several different
1452 types of property. Note that integers and numbers are alway
1453 preceded by a hash sign, @code{#}, while a true or false value
1454 is specified by ##t and ##f, with two hash signs. A text
1455 property should be enclosed in double quotation signs, as above,
1456 although we shall see later that text can actually be specified
1457 in a much more general way by using the very powerful
1458 @code{markup} command.
1463 Context properties may also be set at the time the context is
1464 created. Sometimes this is a clearer way of specifying a
1465 property value if it is to remain fixed for the duration of
1466 the context. When a context is created with a @code{\new}
1467 command it may be immediately followed by a
1468 @code{\with @{ .. @}} block in which the property values are
1469 set. For example, if we wish to suppress the printing of
1470 extra naturals for the duration of a staff we would write:
1472 @lilypond[quote,verbatim,ragged-right]
1481 In effect this overrides the default value of the property. It
1482 may still be changed dynamically using @code{\set} and returned
1483 to its (new) default value with @code{\unset}.
1485 @node Adding and removing engravers
1486 @subsection Adding and removing engravers
1488 @cindex Engravers, adding
1489 @cindex Engravers, removing
1494 We have seen that contexts each contain several engravers, each
1495 of which is responsible for producing a particular part of the
1496 output, like barlines, staves, note heads, stems, etc. If an
1497 engraver is removed from a context it can no longer produce its
1498 output. This is a crude way of modifying the output, but it
1499 can sometimes be useful.
1501 To remove an engraver we can use the @code{\with} command placed
1502 immediately after the context creation command, as in the
1506 illustration let's repeat an example from the previous
1507 section with the staff lines removed. Remember that the
1508 staff lines are produced by the Staff_symbol_engraver.
1510 @lilypond[quote,verbatim,ragged-right]
1512 \remove Staff_symbol_engraver
1516 \set fontSize = #-4 % make note heads smaller
1518 \set fontSize = #2.5 % make note heads larger
1520 \unset fontSize % return to original size
1525 @cindex ambitus engraver
1527 Engravers can also be added to contexts. The command
1530 @code{\consists @emph{Engraver_name}},
1532 placed inside a @code{\with} block. Some vocal scores
1533 have an @rglos{ambitus} placed at the beginning of a
1534 staff to indicate the range of notes in that staff.
1535 The ambitus is produced by the @code{Ambitus_engraver},
1536 which is not normally included in any context. If
1537 we add it to the @code{Voice} context it calculates
1538 the range from that voice only:
1540 @lilypond[quote,verbatim,ragged-right]
1543 \consists Ambitus_engraver
1558 but if we add the Ambitus engraver to the
1559 @code{Staff} context it calculates the range from all
1560 the notes in all the voices on that staff:
1562 @lilypond[quote,verbatim,ragged-right]
1564 \consists Ambitus_engraver
1581 @node Extending the templates
1582 @section Extending the templates
1584 You've read the tutorial, you know how to write music, you
1585 understand the fundamental concepts. But how can you
1586 get the staves that you want? Well, you can find lots of
1587 templates (see @ref{Templates}) which may give you a start.
1589 if you want something that isn't covered there? Read on.
1591 TODO Add links to templates after they have been moved to LSR
1594 * Soprano and cello::
1595 * Four-part SATB vocal score::
1596 * Building a score from scratch::
1599 @node Soprano and cello
1600 @subsection Soprano and cello
1602 Start off with the template that seems closest to what you want to end
1603 up with. Let's say that you want to write something for soprano and
1604 cello. In this case, we would start with @q{Notes and lyrics} (for the
1609 melody = \relative c' @{
1617 text = \lyricmode @{
1623 \new Voice = "one" @{
1627 \new Lyrics \lyricsto "one" \text
1634 Now we want to add a cello part. Let's look at the @q{Notes only} example:
1638 melody = \relative c' @{
1653 We don't need two @code{\version} commands. We'll need the @code{melody}
1654 section. We don't want two @code{\score} sections -- if we had two
1655 @code{\score}s, we'd get the two parts separately. We want them together,
1656 as a duet. Within the @code{\score} section, we don't need two
1657 @code{\layout} or @code{\midi}.
1659 If we simply cut and paste the @code{melody} section, we would end up with
1660 two @code{melody} sections. So let's rename them. We'll call the section
1661 for the soprano @code{sopranoMusic} and the section for the cello
1662 @code{celloMusic}. While we're doing this, let's rename @code{text}
1663 to be @code{sopranoLyrics}. Remember to rename both instances of all
1664 these names -- both the initial definition (the
1665 @code{melody = relative c' @{ } part) and the name's use (in the
1666 @code{\score} section).
1668 While we're doing this, let's change the cello part's staff -- celli
1669 normally use bass clef. We'll also give the cello some different
1674 sopranoMusic = \relative c' @{
1682 sopranoLyrics = \lyricmode @{
1686 celloMusic = \relative c @{
1696 \new Voice = "one" @{
1700 \new Lyrics \lyricsto "one" \sopranoLyrics
1707 This is looking promising, but the cello part won't appear in the
1708 score -- we haven't used it in the @code{\score} section. If we
1709 want the cello part to appear under the soprano part, we need to add
1712 \new Staff \celloMusic
1716 underneath the soprano stuff. We also need to add @code{<<} and
1717 @code{>>} around the music -- that tells LilyPond that there's
1718 more than one thing (in this case, two @code{Staves}) happening
1719 at once. The @code{\score} looks like this now
1721 @c Indentation in this example is deliberately poor
1726 \new Voice = "one" @{
1730 \new Lyrics \lyricsto "one" \sopranoLyrics
1732 \new Staff \celloMusic
1740 This looks a bit messy; the indentation is messed up now. That is
1741 easily fixed. Here's the complete soprano and cello template.
1743 @lilypond[quote,verbatim,ragged-right]
1745 sopranoMusic = \relative c' {
1753 sopranoLyrics = \lyricmode {
1757 celloMusic = \relative c {
1768 \new Voice = "one" {
1772 \new Lyrics \lyricsto "one" \sopranoLyrics
1774 \new Staff \celloMusic
1782 @node Four-part SATB vocal score
1783 @subsection Four-part SATB vocal score
1785 Most vocal scores of music written for four-part mixed choir
1786 with orchestral accompaniment such as Mendelssohn's Elijah or
1787 Handel's Messiah have the choral music and words on four
1788 staves, one for each of SATB, with a piano reduction of the
1789 orchestral accompaniment underneath. Here's an example
1790 from Handel's Messiah:
1792 @c The following should appear as music without code
1793 @lilypond[quote,ragged-right]
1795 global = { \key d \major \time 4/4 }
1796 sopMusic = \relative c'' {
1798 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
1800 sopWords = \lyricmode {
1801 Wor -- thy is the lamb that was slain
1803 altoMusic = \relative a' {
1805 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
1807 altoWords = \sopWords
1808 tenorMusic = \relative c' {
1810 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
1812 tenorWords = \sopWords
1813 bassMusic = \relative c' {
1815 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
1817 bassWords = \sopWords
1818 upper = \relative a' {
1821 r4 <a d fis>2 <a e' a>4 |
1822 <d fis d'>4. <d fis d'>8 <a d a'>2 |
1823 <g cis g'>4 <a d fis> <a cis e>2 |
1825 lower = \relative c, {
1828 <d d'>4 <d d'>2 <cis cis'>4 |
1829 <b b'>4. <b' b'>8 <fis fis'>2 |
1830 <e e'>4 <d d'> <a' a'>2 |
1834 << % combine ChoirStaff and PianoStaff in parallel
1836 \new Staff = "sopranos" <<
1837 \set Staff.instrumentName = "Soprano"
1838 \new Voice = "sopranos" { \global \sopMusic }
1840 \new Lyrics \lyricsto "sopranos" { \sopWords }
1841 \new Staff = "altos" <<
1842 \set Staff.instrumentName = "Alto"
1843 \new Voice = "altos" { \global \altoMusic }
1845 \new Lyrics \lyricsto "altos" { \altoWords }
1846 \new Staff = "tenors" <<
1847 \set Staff.instrumentName = "Tenor"
1848 \new Voice = "tenors" { \global \tenorMusic }
1850 \new Lyrics \lyricsto "tenors" { \tenorWords }
1851 \new Staff = "basses" <<
1852 \set Staff.instrumentName = "Bass"
1853 \new Voice = "basses" { \global \bassMusic }
1855 \new Lyrics \lyricsto "basses" { \bassWords }
1859 \set PianoStaff.instrumentName = "Piano "
1860 \new Staff = "upper" \upper
1861 \new Staff = "lower" \lower
1867 None of the templates provides this layout exactly. The
1868 nearest is @q{SATB vocal score and automatic piano reduction},
1869 but we need to change the layout and add a piano
1870 accompaniment which is not derived automatically from the
1871 vocal parts. The variables holding the music and words for
1872 the vocal parts are fine, but we shall need to add variables for
1873 the piano reduction.
1875 The order in which the contexts appear in the ChoirStaff of
1876 the template do not correspond with the order in the vocal
1877 score shown above. We need to rearrange them so there are
1878 four staves with the words written directly underneath the
1879 notes for each part.
1880 All the voices should be @code{\voiceOne}, which is
1881 the default, so the @code{\voiceXXX} commands should be removed.
1882 We also need to specify the tenor clef for the tenors.
1883 The way in which lyrics are specified in the template has not yet
1884 been encountered so we need to use the method with which we are
1885 familiar. We should also add the names of each staff.
1887 Doing this gives for our ChoirStaff:
1891 \new Staff = "sopranos" <<
1892 \set Staff.instrumentName = "Soprano"
1893 \new Voice = "sopranos" @{ \global \sopMusic @}
1895 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
1896 \new Staff = "altos" <<
1897 \set Staff.instrumentName = "Alto"
1898 \new Voice = "altos" @{ \global \altoMusic @}
1900 \new Lyrics \lyricsto "altos" @{ \altoWords @}
1901 \new Staff = "tenors" <<
1902 \set Staff.instrumentName = "Tenor"
1903 \new Voice = "tenors" @{ \global \tenorMusic @}
1905 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
1906 \new Staff = "basses" <<
1907 \set Staff.instrumentName = "Bass"
1908 \new Voice = "basses" @{ \global \bassMusic @}
1910 \new Lyrics \lyricsto "basses" @{ \bassWords @}
1914 Next we must work out the piano part. This is
1915 easy - we just pull out the piano part from the
1916 @q{Solo piano} template:
1920 \set PianoStaff.instrumentName = "Piano "
1921 \new Staff = "upper" \upper
1922 \new Staff = "lower" \lower
1926 and add the variable definitions for @code{upper}
1929 The ChoirStaff and PianoStaff must be combined
1930 using angle brackets as we want them to be
1931 stacked one above the other:
1934 << % combine ChoirStaff and PianoStaff one above the other
1936 \new Staff = "sopranos" <<
1937 \new Voice = "sopranos" @{ \global \sopMusic @}
1939 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
1940 \new Staff = "altos" <<
1941 \new Voice = "altos" @{ \global \altoMusic @}
1943 \new Lyrics \lyricsto "altos" @{ \altoWords @}
1944 \new Staff = "tenors" <<
1945 \clef "G_8" % tenor clef
1946 \new Voice = "tenors" @{ \global \tenorMusic @}
1948 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
1949 \new Staff = "basses" <<
1951 \new Voice = "basses" @{ \global \bassMusic @}
1953 \new Lyrics \lyricsto "basses" @{ bassWords @}
1957 \set PianoStaff.instrumentName = "Piano "
1958 \new Staff = "upper" \upper
1959 \new Staff = "lower" \lower
1964 Combining all these together and adding the music
1965 for the three bars of the example above gives:
1967 @lilypond[quote,verbatim,ragged-right]
1969 global = { \key d \major \time 4/4 }
1970 sopMusic = \relative c'' {
1972 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
1974 sopWords = \lyricmode {
1975 Wor -- thy is the lamb that was slain
1977 altoMusic = \relative a' {
1979 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
1981 altoWords = \sopWords
1982 tenorMusic = \relative c' {
1984 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
1986 tenorWords = \sopWords
1987 bassMusic = \relative c' {
1989 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
1991 bassWords = \sopWords
1992 upper = \relative a' {
1995 r4 <a d fis>2 <a e' a>4 |
1996 <d fis d'>4. <d fis d'>8 <a d a'>2 |
1997 <g cis g'>4 <a d fis> <a cis e>2 |
1999 lower = \relative c, {
2002 <d d'>4 <d d'>2 <cis cis'>4 |
2003 <b b'>4. <b' b'>8 <fis fis'>2 |
2004 <e e'>4 <d d'> <a' a'>2 |
2008 << % combine ChoirStaff and PianoStaff in parallel
2010 \new Staff = "sopranos" <<
2011 \set Staff.instrumentName = "Soprano"
2012 \new Voice = "sopranos" { \global \sopMusic }
2014 \new Lyrics \lyricsto "sopranos" { \sopWords }
2015 \new Staff = "altos" <<
2016 \set Staff.instrumentName = "Alto"
2017 \new Voice = "altos" { \global \altoMusic }
2019 \new Lyrics \lyricsto "altos" { \altoWords }
2020 \new Staff = "tenors" <<
2021 \set Staff.instrumentName = "Tenor"
2022 \new Voice = "tenors" { \global \tenorMusic }
2024 \new Lyrics \lyricsto "tenors" { \tenorWords }
2025 \new Staff = "basses" <<
2026 \set Staff.instrumentName = "Bass"
2027 \new Voice = "basses" { \global \bassMusic }
2029 \new Lyrics \lyricsto "basses" { \bassWords }
2033 \set PianoStaff.instrumentName = "Piano "
2034 \new Staff = "upper" \upper
2035 \new Staff = "lower" \lower
2042 @node Building a score from scratch
2043 @subsection Building a score from scratch
2045 After gaining some facility with writing LilyPond code you
2046 may find that it is easier to build a score from scratch
2047 rather than modifying one of the templates. You can also
2048 develop your own style this way to suit the sort of music you
2049 like. Let's see how to put together the score for an organ
2050 prelude as an example.
2052 We begin with a header section. Here go the title, name
2053 of composer, etc, then come any variable definitions, and
2054 finally the score block. Let's start with these in outline
2055 and fill in the details later.
2057 We'll use the first two bars of Bach's prelude
2058 based on @emph{Jesu, meine Freude} which is written for two
2059 manuals and pedal organ. You can see these two bars of music
2060 at the bottom of this section. The top manual part has two voices,
2061 the lower and pedal organ one each. So we need four
2062 music definitions and one to define the time signature
2068 title = "Jesu, meine Freude"
2069 composer = "J S Bach"
2071 TimeKey = @{ \time 4/4 \key c \minor @}
2072 ManualOneVoiceOneMusic = @{s1@}
2073 ManualOneVoiceTwoMusic = @{s1@}
2074 ManualTwoMusic = @{s1@}
2075 PedalOrganMusic = @{s1@}
2081 For now we've just used a spacer note, @code{s1},
2082 instead of the real music. We'll add that later.
2084 Next let's see what should go in the score block.
2085 We simply mirror the staff structure we want.
2086 Organ music is usually written on three staves,
2087 one for each manual and one for the pedals. The
2088 manual staves should be bracketed together so we
2089 need to use a PianoStaff for them. The first
2090 manual part needs two voices and the second manual
2095 \new Staff = "ManualOne" <<
2096 \new Voice @{ \ManualOneVoiceOneMusic @}
2097 \new Voice @{ \ManualOneVoiceTwoMusic @}
2098 >> % end ManualOne Staff context
2099 \new Staff = "ManualTwo" <<
2100 \new Voice @{ \ManualTwoMusic @}
2101 >> % end ManualTwo Staff context
2102 >> % end PianoStaff context
2105 Next we need to add a staff for the pedal organ.
2106 This goes underneath the PianoStaff, but it must
2107 be simultaneous with it, so we need angle brackets
2108 round the two. Missing these out would generate
2109 an error in the log file. It's a common mistake
2110 which you'll make sooner or later! Try copying
2111 the final example at the end of this section,
2112 remove these angle brackets, and compile it to
2113 see what errors it generates.
2116 << % PianoStaff and Pedal Staff must be simultaneous
2118 \new Staff = "ManualOne" <<
2119 \new Voice @{ \ManualOneVoiceOneMusic @}
2120 \new Voice @{ \ManualOneVoiceTwoMusic @}
2121 >> % end ManualOne Staff context
2122 \new Staff = "ManualTwo" <<
2123 \new Voice @{ \ManualTwoMusic @}
2124 >> % end ManualTwo Staff context
2125 >> % end PianoStaff context
2126 \new Staff = "PedalOrgan" <<
2127 \new Voice @{ \PedalOrganMusic @}
2132 It is not strictly necessary to use the simultaneous construct
2133 @code{<< >>} for the manual two staff and the pedal organ staff,
2134 since they contain only one music expression, but it does no harm
2135 and always using angle brackets after @code{\new Staff} is a good
2136 habit to cultivate in case there are multiple voices.
2138 Let's add this structure to the score block, and adjust the
2139 indenting. We also add the appropriate clefs, ensure the
2140 second voice stems point down with @code{\voiceTwo} and
2141 enter the time signature and key to each staff using our
2142 predefined variable, @code{\TimeKey}.
2146 << % PianoStaff and Pedal Staff must be simultaneous
2148 \new Staff = "ManualOne" <<
2149 \TimeKey % set time signature and key
2151 \new Voice @{ \ManualOneVoiceOneMusic @}
2152 \new Voice @{ \voiceTwo \ManualOneVoiceTwoMusic @}
2153 >> % end ManualOne Staff context
2154 \new Staff = "ManualTwo" <<
2157 \new Voice @{ \ManualTwoMusic @}
2158 >> % end ManualTwo Staff context
2159 >> % end PianoStaff context
2160 \new Staff = "PedalOrgan" <<
2163 \new Voice @{ \PedalOrganMusic @}
2164 >> % end PedalOrgan Staff
2166 @} % end Score context
2169 That completes the structure. Any three-staff organ music
2170 will have a similar structure, although the number of voices
2171 may vary. All that remains now
2172 is to add the music, and combine all the parts together.
2174 @lilypond[quote,verbatim,ragged-right]
2177 title = "Jesu, meine Freude"
2178 composer = "J S Bach"
2180 TimeKey = { \time 4/4 \key c \minor }
2181 ManualOneVoiceOneMusic = \relative g' {
2182 g4 g f ees | d2 c2 |
2184 ManualOneVoiceTwoMusic = \relative c' {
2185 ees16 d ees8~ ees16 f ees s c8 d~ d c~ |
2186 c c4 b8 c8. g16 c b c d |
2188 ManualTwoMusic = \relative c' {
2189 c16 b c8~ c16 b c g a8 g~ g16 g aes ees |
2190 f ees f d g aes g f ees d e8~ ees16 f ees d |
2192 PedalOrganMusic = \relative c {
2193 r8 c16 d ees d ees8~ ees16 a, b g c b c8 |
2194 r16 g ees f g f g8 c,2 |
2198 << % PianoStaff and Pedal Staff must be simultaneous
2200 \new Staff = "ManualOne" <<
2201 \TimeKey % set time signature and key
2203 \new Voice { \ManualOneVoiceOneMusic }
2204 \new Voice { \voiceTwo \ManualOneVoiceTwoMusic }
2205 >> % end ManualOne Staff context
2206 \new Staff = "ManualTwo" <<
2209 \new Voice { \ManualTwoMusic }
2210 >> % end ManualTwo Staff context
2211 >> % end PianoStaff context
2212 \new Staff = "PedalOrgan" <<
2215 \new Voice { \PedalOrganMusic }
2216 >> % end PedalOrgan Staff
2218 } % end Score context