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 has 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 immediately after the @code{\score} command.
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} block can contain other
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} command. 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} block 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.
220 \new Staff = "singer" <<
222 \new PianoStaff = piano <<
229 Remember that we use @code{<< ... >>} instead of
230 @code{@{ ... @}} to show simultaneous
231 music. And we definitely want to show the vocal part and piano
232 part at the same time, not one after the other! However, the
233 @code{<< ... >>} construct is not really necessary for the Singer
234 staff, as it contains only one music expression, but Staves often
235 do require simultaneous Voices within them, so using
237 rather than braces is a good habit to adopt. We'll add some real
238 music later; for now let's just put in some dummy notes and lyrics.
240 @lilypond[verbatim,quote,ragged-right]
243 \new Staff = "singer" <<
244 \new Voice = "vocal" { c'1 }
247 \new PianoStaff = "piano" <<
248 \new Staff = "upper" { c'1 }
249 \new Staff = "lower" { c'1 }
256 Now we have a lot more details. We have the singer's staff: it
257 contains a @code{Voice} (in LilyPond, this term refers to a set of
258 notes, not necessarily vocal notes -- for example, a violin
259 generally plays one voice) and some lyrics. We also have a piano
260 staff: it contains an upper staff (right hand) and a lower staff
263 At this stage, we could start filling in notes. Inside the curly
264 braces next to @code{\new Voice = vocal}, we could start writing
272 But if we did that, the @code{\score} section would get pretty
273 long, and it would be harder to understand what was happening. So
274 let's use variables instead. These were introduced at the end
275 of the previous section, remember? So, adding a few notes, we
276 now have a piece of real music:
278 @lilypond[verbatim,quote,ragged-right]
279 melody = \relative c'' { r4 d8\noBeam g, c4 r }
280 text = \lyricmode { And God said, }
281 upper = \relative c'' { <g d g,>2~ <g d g,> }
282 lower = \relative c { b2 e2 }
286 \new Staff = "singer" <<
287 \new Voice = "vocal" { \melody }
290 \new PianoStaff = "piano" <<
291 \new Staff = "upper" { \upper }
292 \new Staff = "lower" {
303 Be careful about the difference between notes, which are introduced
304 with @code{\relative}, and lyrics, which are introduced with
305 @code{\lyricmode}. These are essential to tell LilyPond
306 to interpret the following content as music and text
309 When writing (or reading) a @code{\score} section, just take it
310 slowly and carefully. Start with the outer layer, then work on
311 each smaller layer. It also really helps to be strict with
312 indentation -- make sure that each item on the same layer starts
313 on the same horizontal position in your text editor.
316 @node Nesting music expressions
317 @subsection Nesting music expressions
319 It is not essential to declare all staves at the beginning;
320 they may be introduced temporarily at any point. This is
321 particularly useful for creating ossia sections
322 (see @rglos{ossia}). Here is a simple example showing how
323 to introduce a new staff temporarily for the duration of
326 @lilypond[verbatim,quote,ragged-right]
343 Note that the size of the clef is the same as a clef printed
344 following a clef change -- slightly smaller than the clef
345 at the begining of the line. This is usual for clefs printed
346 in the middle of a line.
348 The ossia section may be placed above the staff
351 @lilypond[verbatim,quote,ragged-right]
359 alignAboveContext = "main" }
367 This example uses @code{\with}, which will be explained more
368 fully later. It is a means of modifying the default behaviour
369 of a single Staff. Here it says that the new staff should be
370 placed above the staff called @qq{main} instead of the default
371 position which is below.
373 Ossia are often written without clef and without
374 time signature and are usually in a smaller font.
375 These require further commands which
376 have not yet been introduced. See @ref{Size of objects}
378 @node On the un-nestedness of brackets and ties
379 @subsection On the un-nestedness of brackets and ties
381 You have already met a number of different types of bracket in
382 writing the input file to LilyPond. These obey different rules
383 which can be confusing at first. Before we explain the rules
384 let's first review the different types of bracket.
386 @c attempt to force this onto a new page
388 @multitable @columnfractions .3 .7
389 @headitem Bracket Type
391 @item @code{@{ .. @}}
392 @tab Encloses a sequential segment of music
394 @tab Encloses the notes of a chord
395 @item @code{<< .. >>}
396 @tab Encloses concurrent or simultaneous sections
398 @tab Marks the start and end of a slur
399 @item @code{\( .. \)}
400 @tab Marks the start and end of a phrase mark
402 @tab Marks the start and end of a manual beam
405 To these we should add other constructs which generate lines
406 between or across notes: ties (marked by a tilde, @code{~}),
407 tuplets written as @code{\times x/y @{..@}}, and grace notes
408 written as @code{\grace@{..@}}.
410 Outside LilyPond, the conventional use of brackets requires
411 the different types to be properly nested, like this,
412 @code{<< [ @{ ( .. ) @} ] >>}, with the closing brackets being
413 encountered in exactly the opposite order to the opening
414 brackets. This @strong{is} a requirement for the three types of
415 bracket described by the word @q{Encloses} in the table above --
416 they must nest properly.
417 However, the remaining brackets, described with the word
418 @q{Marks} in the table above together with ties and tuplets,
419 do @strong{not} have to nest
420 properly with any of the brackets. In fact, these are not
421 brackets in the sense that
422 they enclose something -- they are simply markers to indicate
423 where something starts and ends.
425 So, for example, a phrasing slur can start before a manually
426 inserted beam and end before the end of the beam -- not very
427 musical, perhaps, but possible:
429 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
430 { g8\( a b[ c b\) a] }
433 In general, different kinds of brackets, and those implied by
434 tuplets, ties and grace notes, may be mixed freely.
435 This example shows a beam extending into a tuplet (line 1),
436 a slur extending into a tuplet (line 2),
437 a beam and a slur extending into a tuplet, a tie crossing
438 two tuplets, and a phrasing slur extending out of a tuplet
441 @lilypond[quote,verbatim,fragment,ragged-right]
443 r16[ g16 \times 2/3 {r16 e'8] }
444 g16( a \times 2/3 {b d) e' }
445 g8[( a \times 2/3 {b d') e'~]}
446 \times 4/5 {e'32\( a b d' e'} a'4.\)
451 @node Voices contain music
452 @section Voices contain music
454 Singers need voices to sing, and so does LilyPond.
455 The actual music for all instruments in a score
456 is contained in Voices -- the most fundamental
457 of all LilyPond's concepts.
460 * I'm hearing Voices::
461 * Explicitly instantiating voices::
462 * Voices and vocals::
465 @node I'm hearing Voices
466 @subsection I'm hearing Voices
470 @cindex Voice context
472 The lowest, most fundamental or innermost layers in a LilyPond
473 score are called @q{Voice contexts} or just @q{Voices} for short.
474 Voices are sometimes called @q{layers} in other notation
477 In fact, a Voice layer or context is the only one which can
478 contain music. If a Voice context is not explicitly declared
479 one is created automatically, as we saw at the beginning of
480 this chapter. Some instruments such as an
481 Oboe can play only one note at a time. Music written for
482 such instruments is monophonic and requires just a single
483 voice. Instruments which can play more than one note at a
484 time like the piano will often require multiple voices to
485 encode the different concurrent notes and rhythms they are
488 A single voice can contain many notes in a chord, of course,
489 so when exactly are multiple voices needed? Look first at
490 this example of four chords:
492 @lilypond[quote,verbatim,fragment,ragged-right,relative=1]
494 <d g>4 <d fis> <d a'> <d g>
497 This can be expressed using just the single angle bracket chord
498 symbols, @code{< ... >}, and for this just a single voice is
499 needed. But suppose the F-sharp were actually an eighth-note
500 followed by an eighth-note G, a passing note on the way to the A?
501 Now we have two notes which start at the same time but have
502 different durations: the quarter-note D and the eighth-note
503 F-sharp. How are these to be coded? They cannot be written as
504 a chord because all the notes in a chord must have the same
505 duration. And they cannot be written as two separate notes
506 as they need to start at the same time. This is when two
509 Let us see how this is done in LilyPond input syntax.
514 The easiest way to enter fragments with more than one voice on a
515 staff is to enter each voice as a sequence (with @code{@{...@}}),
516 and combine them simultaneously with angle brackets, @code{<<...>>}.
517 The fragments must also be separated with double backward slashes,
518 @code{\\}, to place them in separate voices. Without these, the
519 notes would be entered into a single voice, which would usually
520 cause errors. This technique is particularly suited to pieces of
521 music which are largely monophonic with occasional short sections
524 Here's how we split the chords above into two voices and add both
525 the passing note and a slur:
527 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
529 % Voice "1" Voice "2"
530 << { g4 fis8( g) a4 g } \\ { d4 d d d } >> |
533 Notice how the stems of the second voice now point down.
535 Here's another simple example:
537 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
539 % Voice "1" Voice "2"
540 << { r4 g g4. a8 } \\ { d,2 d4 g } >> |
541 << { bes4 bes c bes } \\ { g4 g g8( a) g4 } >> |
542 << { a2. r4 } \\ { fis2. s4 } >> |
545 It is not necessary to use a separate @code{<< \\ >>} construct
546 for each bar. For music with few notes in each bar this layout
547 can help the legibility of the code, but if there are many
548 notes in each bar it may be better to split out each voice
549 separately, like this:
551 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
567 This example has just two voices, but the same contruct may be
568 used to encode three or more voices by adding more back-slash
571 The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
572 In each of these contexts, the vertical direction of slurs,
573 stems, ties, dynamics etc., is set appropriately.
575 @lilypond[quote,verbatim,fragment]
576 \new Staff \relative c' {
579 % Voice "1" Voice "2" Voice "3"
580 << { g4 f e } \\ { r8 e4 d c8 ~ } >> |
581 << { d2 e2 } \\ { c8 b16 a b8 g ~ g2 } \\ { s4 b4 c2 } >> |
585 These voices are all separate from the main voice that contains
586 the notes just outside the @code{<< .. >>} construct. Let's call
587 this the @emph{simultaneous construct}. Slurs and ties may only
588 connect notes within the same voice, so slurs and ties cannot go
589 into or out of a simultaneous construct. Conversely,
590 parallel voices from separate simultaneous constructs on the same
591 staff are the same voice. Other voice-related properties also
592 carry across simultaneous constructs. Here is the same example,
593 with different colors and note heads for each voice. Note that
594 changes in one voice do not affect other voices, but they do
595 persist in the same voice later. Note also that tied notes may be
596 split across the same voices in two constructs, shown here in the
599 @lilypond[quote,verbatim]
600 \new Staff \relative c' {
619 { c8 b16 a b8 g ~ g2 }
629 The commands @code{\voiceXXXStyle} are mainly intended for use in
630 educational documents such as this one. They modify the color
631 of the note head, the stem and the beams, and the style of the
632 note head, so that the voices may be easily distinguished.
633 Voice one is set to red diamonds, voice two to blue triangles,
634 voice three to green crossed circles, and voice four (not used
635 here) to magenta crosses. We shall see later how commands like
636 these may be created by the user.
637 See @ref{Visibility and color of objects}
638 TODO Add link to using variables for tweaks
640 Polyphony does not change the relationship of notes within a
641 @code{\relative @{ @}} block. Each note is still calculated
642 relative to the note immediately preceding it, or to the first
643 note of the preceding chord. So in
646 \relative c' @{ noteA << < noteB noteC > \\ noteD >> noteE @}
650 @code{noteB} is relative to @code{noteA} @*
651 @code{noteC} is relative to @code{noteB}, not @code{noteA}; @*
652 @code{noteD} is relative to @code{noteB}, not @code{noteA} or
654 @code{noteE} is relative to @code{noteD}, not @code{noteA}
656 An alternative way, which may be clearer if the notes in the
657 voices are widely separated, is to place a @code{\relative}
658 command at the start of each voice:
661 \relative c' @{ noteA ... @}
663 \relative c'' @{ < noteB noteC > ... @}
665 \relative g' @{ noteD ... @}
667 \relative c' @{ noteE ... @}
670 Let us finally analyse the voices in a more complex piece of
672 the notes from the first two bars of the second of Chopin's
673 Deux Nocturnes, Op 32. This example will be used at later
674 stages in this and the next chapter to illustrate several
675 techniques for producing notation, so please ignore for now
676 anything in the underlying code which looks mysterious and
677 concentrate just on the music and the voices -- the
678 complications will all be explained in later sections.
680 @c The following should appear as music without code
681 @lilypond[quote,ragged-right]
682 \new Staff \relative c'' {
691 % Ignore these for now - they are explained in Ch 4
692 \once \override NoteColumn #'force-hshift = #0
694 \once \override NoteColumn #'force-hshift = #0.5
702 The direction of the stems is often used to indicate the
703 continuity of two simultaneous melodic lines. Here the
704 stems of the highest notes are all pointing up and the
705 stems of the lower notes are all pointing down.
706 This is the first indication that more than one voice
709 But the real need for multiple voices arises when notes
710 which start at the same time have different durations.
711 Look at the notes which start at beat three in the first
712 bar. The A-flat is a dotted quarter note, the F is a
713 quarter note and the D-flat is a half note. These
714 cannot be written as a chord as all the notes in a chord
715 must have the same duration. Neither can they be written
716 as sequential notes, as they must start at the same time.
717 This section of the bar requires three voices, and the
718 normal practice would be to write the whole bar as three
719 voices, as shown below, where we have used different note heads
720 and colors for the three voices. Again, the code behind this
721 example will be explained later, so ignore anything you do
724 @c The following should appear as music without code
725 @c The three voice styles should be defined in -init
726 @lilypond[quote,ragged-right]
727 \new Staff \relative c'' {
738 \\ % No Voice three (we want stems down)
741 % Ignore these for now - they are explained in Ch 4
742 \once \override NoteColumn #'force-hshift = #0
744 \once \override NoteColumn #'force-hshift = #0.5
753 Let us try to encode this music from scratch. As we
754 shall see, this encounters some difficulties. We begin as
755 we have learnt, using the @code{<< \\ >>} construct to
756 enter the music of the first bar in three voices:
758 @lilypond[quote,verbatim,fragment,ragged-right]
759 \new Staff \relative c'' {
762 { c2 aes4. bes8 } \\ { aes2 f4 fes } \\ { <ees c>2 des2 }
771 The stem directions are automatically assigned with the
772 odd-numbered voices taking upward stems and the even-numbered
773 voices downward ones. The stems for voices 1 and 2 are right,
774 but the stems in voice 3 should go down in this particular piece
775 of music. We can correct this simply by missing out voice three
776 and placing the music in voice four:
778 @lilypond[quote,verbatim,fragment,ragged-right]
779 \new Staff \relative c'' {
785 \\ % Omit Voice three
794 We see that this fixes the stem direction, but exposes a
795 problem sometimes encountered with multiple voices -- the
796 stems of the notes in one voice can collide with the note heads
797 in other voices. In laying out the notes, LilyPond allows the
798 notes or chords from two voices to occupy the same vertical
799 note column provided the stems are in opposite directions, but
800 the notes from the third and fourth voices are displaced to if
801 necessary to avoid the note heads
802 colliding. This usually works well, but in this example the
803 notes of the lowest voice are clearly not well placed by default.
804 LilyPond provides several ways to adjust the horizontal placing
805 of notes. We are not quite ready yet to see how to correct this,
806 so we shall leave this problem until a later section
807 (see the force-hshift property in @ref{Fixing overlapping
810 @node Explicitly instantiating voices
811 @subsection Explicitly instantiating voices
815 @funindex \voiceThree
818 Voice contexts can also be created manually
819 inside a @code{<< >>} block to create polyphonic music, using
820 @code{\voiceOne} ... @code{\voiceFour} to indicate the required
821 directions of stems, slurs, etc. In longer scores this method
822 is clearer, as it permits the voices to be separated and to be
823 given more descriptive names.
825 Specifically, the construct @code{<< \\ >>} which we used in
826 the previous section:
831 << @{ e4 f g a @} \\ @{ c,4 d e f @} >>
841 \new Voice = "1" @{ \voiceOne \relative c' @{ e4 f g a @} @}
842 \new Voice = "2" @{ \voiceTwo \relative c' @{ c4 d e f @} @}
846 Both of the above would produce
848 @c The following example should not display the code
849 @lilypond[ragged-right,quote]
851 \new Voice = "1" { \voiceOne \relative c' { e4 f g a } }
852 \new Voice = "2" { \voiceTwo \relative c' { c4 d e f } }
856 The @code{\voiceXXX} commands set the direction of stems, slurs,
857 ties, articulations, text annotations, augmentation dots of dotted
858 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
859 make these objects point upwards, while @code{\voiceTwo} and
860 @code{\voiceFour} make them point downwards. These commands also
861 generate a horizontal shift for each voice when this is required
862 to avoid clashes of note heads. The command @code{\oneVoice}
863 reverts the settings back to the normal values for a single voice.
865 Let us see in some simple examples exactly what effect
866 @code{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on
867 markup, ties, slurs, and dynamics:
869 @lilypond[quote,ragged-right,verbatim]
871 % Default behaviour or behaviour after \oneVoice
872 c d8 ~ d e4 ( f g a ) b-> c
876 @lilypond[quote,ragged-right,verbatim]
879 c d8 ~ d e4 ( f g a ) b-> c
881 c, d8 ~ d e4 ( f g a ) b-> c
885 @lilypond[quote,ragged-right,verbatim]
888 c d8 ~ d e4 ( f g a ) b-> c
890 c, d8 ~ d e4 ( f g a ) b-> c
894 An expression that appears directly inside a @code{<< >>} belongs
895 to the main voice (but, note, @strong{not} in a @code{<< \\ >>}
896 construct). This is useful when extra voices appear while the
897 main voice is playing. Here is a more correct rendition of the
898 example from the previous section. The red diamond-shaped notes
899 demonstrate that the main melody is now in a single voice context,
900 permitting a phrasing slur to be drawn over them.
902 @lilypond[quote,ragged-right,verbatim]
903 \new Staff \relative c' {
905 % The following notes are monophonic
907 % Start simultaneous section of three voices
909 % Continue the main voice in parallel
911 % Initiate second voice
913 % Set stems, etc, down
915 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
917 % Initiate third voice
927 @cindex nesting music expressions
928 @cindex nesting simultaneous constructs
930 More deeply nested polyphony constructs are possible, and if a
931 voice appears only briefly this might be a more natural way to
934 @lilypond[quote,ragged-right,verbatim]
935 \new Staff \relative c' {
955 This method of nesting new voices briefly is useful
956 when only small sections of the music
957 are polyphonic, but when the whole staff is largely polyphonic
958 it can be clearer to use multiple voices throughout, using
959 spacing notes to step over sections where the voice is silent,
962 @lilypond[quote,ragged-right,verbatim]
963 \new Staff \relative c' <<
964 % Initiate first voice
967 c16^( d e f g4 f e | d2 e2) |
969 % Initiate second voice
971 % set stems, etc down
973 s4 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 |
975 % Initiate third voice
985 @cindex shift commands
991 Closely spaced notes in a chord, or notes occuring at the same
992 time in different voices, are arranged in two, occasionally more,
993 columns to prevent the note heads overlapping. These are called
994 note columns. There are separate columns for each voice, and
995 the currently specified voice-dependent shift is applied to the
996 note column if there would otherwise be a collision. This can
997 be seen in the example above. In bar 2 the C in voice two is
998 shifted to the right relative to the D in voice one, and in the
999 final chord the C in voice three is also shifted to the right
1000 relative to the other notes.
1002 The @code{\shiftOn}, @code{\shiftOnn}, @code{\shiftOnnn}, and
1003 @code{\shiftOff} commands specify the degree to which notes and
1004 chords of the voice should be shifted if a collision
1005 would otherwise occur. By default, the outer voices (normally
1006 voices one and two) have @code{\shiftOff} specified, while the
1007 inner voices (three and four) have @code{\shiftOn} specified.
1008 When a shift is applied, Voices one and three are shifted to
1009 the right and voices two and four to the left.
1011 @code{\shiftOnn} and @code{\shiftOnnn} define further shift
1012 levels which may be specified temporarily to resolve collisions
1013 in complex situations -- see @ref{Real music example}.
1015 A note column can contain just one note (or chord) from a voice
1016 with stems up and one note (or chord) from a voice with stems
1017 down. If notes from two voices which have their stems in the
1018 same direction are placed at the same position and both voices
1019 have no shift or the same shift specified, the error message
1020 @qq{Too many clashing note columns} will be produced.
1022 @node Voices and vocals
1023 @subsection Voices and vocals
1025 Vocal music presents a special difficulty: we need to combine two
1026 expressions -- notes and lyrics.
1028 You have already seen the @code{\addlyrics@{@}} command, which
1029 handles simple scores well. However, this technique is
1030 quite limited. For more complex music, you must introduce the
1031 lyrics in a @code{Lyrics} context using @code{\new Lyrics} and
1033 the lyrics to the notes with @code{\lyricsto@{@}}, using the
1034 name assigned to the Voice.
1036 @lilypond[quote,verbatim,fragment]
1038 \new Voice = "one" \relative c'' {
1041 c4 b8. a16 g4. f8 e4 d c2
1043 \new Lyrics \lyricsto "one" {
1044 No more let sins and sor -- rows grow.
1049 The automatic beaming which LilyPond uses by default works well
1050 for instrumental music, but not so well for music with lyrics,
1051 where beaming is either not required at all or is used to indicate
1052 melismata in the lyrics. In the example above we use the command
1053 @code{\autoBeamOff} to turn off the automatic beaming.
1055 Let us reuse the earlier example from Judas Maccabæus to
1056 illustrate this more flexible technique. We first recast
1057 it to use variables so the music and lyrics can be separated
1058 from the staff structure. We also introduce a ChoirStaff
1059 bracket. The lyrics themselves must be introduced with
1060 @code{\lyricmode} to ensure they are interpreted as lyrics
1063 @lilypond[quote,verbatim]
1064 global = { \time 6/8 \partial 8 \key f \major}
1065 SopOneMusic = \relative c'' {
1066 c8 | c([ bes)] a a([ g)] f | f'4. b, | c4.~ c4 }
1067 SopTwoMusic = \relative c' {
1068 r8 | r4. r4 c8 | a'([ g)] f f([ e)] d | e([ d)] c bes' }
1069 SopOneLyrics = \lyricmode {
1070 Let | flee -- cy flocks the | hills a -- dorn, __ }
1071 SopTwoLyrics = \lyricmode {
1072 Let | flee -- cy flocks the | hills a -- dorn, }
1077 \new Voice = "SopOne" {
1081 \new Lyrics \lyricsto "SopOne" {
1086 \new Voice = "SopTwo" {
1089 \new Lyrics \lyricsto "SopTwo" {
1097 This is the basic structure of all vocal scores. More staves may
1098 be added as required, more voices may be added to the staves,
1099 more verses may be added to the lyrics,
1100 and the variables containing the music can easily be placed
1101 in separate files should they become too long.
1103 Here is a final example of the first line of a hymn with four
1104 verses, set for SATB. In this case the words for all four
1107 @lilypond[quote,verbatim]
1108 TimeKey = { \time 4/4 \partial 4 \key c \major}
1109 SopMusic = \relative c' { c4 | e4. e8 g4 g | a a g }
1110 AltoMusic = \relative c' { c4 | c4. c8 e4 e | f f e }
1111 TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 }
1112 BassMusic = \relative c { c4 | c4. c8 c4 c | f8 g a b c4 }
1113 VerseOne = \lyricmode {
1114 E -- | ter -- nal fa -- ther, | strong to save, }
1115 VerseTwo = \lyricmode {
1116 O | Christ, whose voice the | wa -- ters heard, }
1117 VerseThree = \lyricmode {
1118 O | Ho -- ly Spi -- rit, | who didst brood }
1119 VerseFour = \lyricmode {
1120 O | Tri -- ni -- ty of | love and pow'r }
1126 \new Voice = "Sop" { \voiceOne \TimeKey \SopMusic }
1127 \new Voice = "Alto" { \voiceTwo \AltoMusic }
1128 \new Lyrics \lyricsto "Sop" { \VerseOne }
1129 \new Lyrics \lyricsto "Sop" { \VerseTwo }
1130 \new Lyrics \lyricsto "Sop" { \VerseThree }
1131 \new Lyrics \lyricsto "Sop" { \VerseFour }
1135 \new Voice = "Tenor" { \voiceOne \TenorMusic }
1136 \new Voice = "Bass" { \voiceTwo \BassMusic }
1142 @node Contexts and engravers
1143 @section Contexts and engravers
1145 Contexts and engravers have been mentioned informally
1146 in earlier sections; we now must look at
1147 these concepts in more detail, as they are important
1148 in the fine-tuning of LilyPond output.
1152 * Contexts explained::
1153 * Creating contexts::
1154 * Engravers explained::
1155 * Modifying context properties::
1156 * Adding and removing engravers::
1159 @node Contexts explained
1160 @subsection Contexts explained
1162 When music is printed, many notational elements which do not
1163 appear explicitly in the input file must be added to the
1164 output. For example, compare the input and output of the
1167 @lilypond[quote,verbatim,relative=2,fragment]
1171 The input is rather sparse, but in the output, bar lines,
1172 accidentals, clef, and time signature have been added. When
1173 LilyPond @emph{interprets} the input the musical information
1174 is inspected in time order, similar to reading a score from left
1175 to right. While reading the input, the program remembers where
1176 measure boundaries are, and which pitches require explicit
1177 accidentals. This information must be held on several levels.
1178 For example, the effect of an accidental is limited
1179 to a single staff, while a bar line must be synchronized across
1182 Within LilyPond, these rules and bits of information are grouped
1183 in @emph{Contexts}. We have already met the
1184 @code{Voice} context.
1185 Others are the @code{Staff} and @code{Score} contexts.
1186 Contexts are hierarchical to reflect the heirarchical nature of
1188 For example: a @code{Staff} context can contain many
1189 @code{Voice} contexts, and a @code{Score} context can
1190 contain many @code{Staff} contexts.
1193 @image{context-example,5cm,,}
1196 Each context has the responsibility for enforcing some notation rules,
1197 creating some notation objects and maintaining the associated
1198 properties. For example, the @code{Voice} context may introduce an
1199 accidental and then the @code{Staff} context maintains the rule to
1200 show or suppress the accidental for the remainder of the measure.
1202 As another example, the synchronization of bar lines is, by default,
1203 handled in the @code{Score} context.
1204 However, in some music we may not want the bar lines to be
1205 synchronized -- consider a polymetric score in 4/4 and 3/4 time.
1206 In such cases, we must modify the default settings of the
1207 @code{Score} and @code{Staff} contexts.
1209 For very simple scores, contexts are created implicitly, and you need
1210 not be aware of them. For larger pieces, such as anything with more
1211 than one staff, they must be
1212 created explicitly to make sure that you get as many staves as you
1213 need, and that they are in the correct order. For typesetting pieces
1214 with specialized notation, it is usual to modify existing, or
1215 even to define totally new, contexts.
1217 In addition to the @code{Score,} @code{Staff} and
1218 @code{Voice} contexts there are contexts which fit between
1219 the score and staff levels to control staff groups, such as the
1220 @code{PianoStaff} and @code{ChoirStaff} contexts. There
1221 are also alternative staff and voice contexts, and contexts for
1222 lyrics, percussion, fret boards, figured bass, etc.
1224 The names of all context types are formed from one or more
1225 words, each word being capitalised and joined immediately to the
1226 preceding word with no hyphen or underscore, e.g.,
1227 @code{GregorianTranscriptionStaff}.
1229 @node Creating contexts
1230 @subsection Creating contexts
1232 There can be only one top level context: the
1234 context. This is created with the @code{\score} command,
1235 or, in simple scores, it is created automatically.
1237 For scores with only one voice and one staff, the
1238 @code{Voice} and @code{Staff} contexts may be left to be
1239 created automatically, but for more complex scores it is
1240 necessary to create them by hand.
1241 The simplest command that does this is @code{\new}.
1242 It is prepended to a music expression, for example
1245 @cindex new contexts
1246 @cindex Context, creating
1249 \new @var{type} @var{music-expression}
1253 where @var{type} is a context name (like @code{Staff} or
1254 @code{Voice}). This command creates a new context, and starts
1255 interpreting the @var{music-expression} within that context.
1257 Note that there is no @code{\new Score} command;
1258 the single top-level @code{Score} context is introduced
1261 The @code{\new} command may also give a identifying name to the
1262 context to distinguish it from other contexts of the same type,
1265 \new @var{type} = @var{id} @var{music-expression}
1268 Note the distinction between the name of the context type,
1269 @code{Staff}, @code{Voice}, etc, and
1270 the identifying name of a particular instance of that type,
1271 which can be any sequence of letters invented by the user.
1272 The identifying name is used to refer back to that particular
1273 instance of a context. We saw this in use in the section on
1274 lyrics in @ref{Voices and vocals}.
1277 @node Engravers explained
1278 @subsection Engravers explained
1282 Every mark on the printed output of a score produced by LilyPond
1283 is produced by an @code{Engraver}. Thus there is an engraver
1284 to print staves, one to print note heads, one for stems, one for
1285 beams, etc, etc. In total there are over 120 such engravers!
1286 Fortunately, for most scores it is not necessary to know about
1287 more than a few, and for simple scores you do not need to know
1290 Engravers live and operate in Contexts.
1291 Engravers such as the @code{Metronome_mark_engraver}, whose
1292 action and output applies to the score as a whole, operate in
1293 the highest level context -- the @code{Score} context.
1295 The @code{Clef_engraver} and @code{Key_engraver} are to be
1296 found in every Staff Context, as different staves may require
1297 different clefs and keys.
1299 The @code{Note_heads_engraver} and @code{Stem_engraver} live
1300 in every @code{Voice} context, the lowest level context of all.
1302 Each engraver processes the particular objects associated
1303 with its function, and maintains the properties that relate
1304 to that function. These properties, like the properties
1305 associated with contexts, may be modified to change the
1306 operation of the engraver or the appearance of those elements
1307 in the printed score.
1309 Engravers all have compound names formed from words which
1310 describe their function. Just the first word is capitalised,
1311 and the remainder are joined to it with underscores. Thus
1312 the @code{Staff_symbol_engraver} is responsible for creating the
1313 lines of the staff, the @code{Clef_engraver} determines and sets
1314 the pitch reference point on the staff by drawing a clef symbol.
1316 Here are some of the most common engravers together with their
1317 function. You will see it is easy to guess the function from
1318 the name, or vice versa.
1320 @multitable @columnfractions .3 .7
1323 @item Accidental_engraver
1324 @tab Makes accidentals, cautionary and suggested accidentals
1329 @item Dynamic_engraver
1330 @tab Creates hairpins and dynamic texts
1332 @tab Creates the key signature
1333 @item Metronome_mark_engraver
1334 @tab Engraves metronome marking
1335 @item Note_heads_engraver
1336 @tab Engraves note heads
1339 @item Staff_symbol_engraver
1340 @tab Engraves the five (by default) lines of the staff
1342 @tab Creates stems and single-stem tremulos
1343 @item Time_signature_engraver
1344 @tab Creates time signatures
1349 We shall see later how the output of LilyPond can be changed
1350 by modifying the action of Engravers.
1353 @node Modifying context properties
1354 @subsection Modifying context properties
1356 @cindex context properties
1360 Contexts are responsible for holding the values of a number of
1361 context @emph{properties}. Many of them can be changed to
1362 influence the interpretation of the input and so change the
1363 appearance of the output. They are changed by the
1364 @code{\set} command. This takes the form
1367 \set @emph{ContextName}.@emph{propertyName} = #@emph{value}
1370 Where the @emph{ContextName} is usually @code{Score},
1371 @code{Staff} or @code{Voice}. It may be omitted,
1372 in which case @code{Voice} is assumed.
1374 The names of context properties consist of words joined
1375 together with no hyphens or underscores, all except the
1376 first having a capital letter. Here are a few examples
1377 of some commonly used ones. There are many more.
1379 @c attempt to force this onto a new page
1381 @multitable @columnfractions .25 .15 .45 .15
1382 @headitem propertyName
1388 @tab If true, set extra natural signs before accidentals
1389 @tab @code{#t}, @code{#f}
1390 @item currentBarNumber
1392 @tab Set the current bar number
1396 @tab If true, print slurs both above and below notes
1397 @tab @code{#t}, @code{#f}
1398 @item instrumentName
1400 @tab Set the name to be placed at the start of the staff
1401 @tab @code{"Cello I"}
1404 @tab Increase or decrease the font size
1408 @tab Set the text to print before the start of a verse
1413 where a Boolean is either True (@code{#t}) or False (@code{#f}),
1414 an Integer is a positive whole number, a Real is a positive
1415 or negative decimal number, and text is enclosed in double
1416 apostrophes. Note the occurrence of hash signs,
1417 (@code{#}), in two different places -- as part of the Boolean
1418 value before the @code{t} or @code{f}, and before @emph{value}
1419 in the @code{\set} statement. So when a Boolean is being
1420 entered you need to code two hash signs, e.g., @code{##t}.
1422 Before we can set any of these properties we need to know
1423 in which context they operate. Sometimes this is obvious,
1424 but occasionally it can be tricky. If the wrong context
1425 is specified, no error message is produced, but the expected
1426 action will not take place. For example, the
1427 @code{instrumentName} clearly lives in the Staff context, since
1428 it is the staff that is to be named.
1429 In this example the first staff is labelled, but not the second,
1430 because we omitted the context name.
1432 @lilypond[quote,verbatim,ragged-right]
1434 \new Staff \relative c'' {
1435 \set Staff.instrumentName = "Soprano"
1438 \new Staff \relative c' {
1439 \set instrumentName = "Alto" % Wrong!
1445 Remember the default context name is Voice, so the second
1446 @code{\set} command set the property @code{instrumentName} in the
1447 Voice context to @qq{Alto}, but as LilyPond does not look
1448 for any such property in the @code{Voice} context, no
1449 further action took place. This is not an error, and no error
1450 message is logged in the log file.
1452 Similarly, if the property name is mis-spelt no error message
1453 is produced, and clearly the expected action cannot be performed.
1454 If fact, you can set any (fictitious) @q{property} using any
1455 name you like in any context that exists by using the
1456 @code{\set} command. But if the name is not
1457 known to LilyPond it will not cause any action to be taken.
1458 This is one of the reasons why it is highly recommended to
1459 use a context-sensitive editor with syntax highlighting for
1460 editing LilyPond files, such as Vim, Jedit, ConTEXT or Emacs,
1461 since unknown property names will be highlighted differently.
1463 The @code{instrumentName} property will take effect only
1464 if it is set in the @code{Staff} context, but
1465 some properties can be set in more than one context.
1466 For example, the property @code{extraNatural} is by
1467 default set to ##t (true) for all staves.
1468 If it is set to ##f (false) in one particular @code{Staff}
1469 context it applies just to the accidentals on that staff.
1470 If it is set to false in the @code{Score} context
1471 it applies to all staves.
1473 So this turns off extra naturals in one staff:
1475 @lilypond[quote,verbatim,ragged-right]
1477 \new Staff \relative c'' {
1480 \new Staff \relative c'' {
1481 \set Staff.extraNatural = ##f
1488 and this turns them off in all staves:
1490 @lilypond[quote,verbatim,ragged-right]
1492 \new Staff \relative c'' {
1495 \new Staff \relative c'' {
1496 \set Score.extraNatural = ##f
1502 The value of every property set in this way can be reset
1503 to its original value with the @code{\unset} command.
1505 The @code{\set} and @code{\unset} commands can appear anywhere
1506 in the input file and will take effect from the time they are
1507 encountered until the end of the score or until the property is
1508 @code{\set} or @code{\unset} again. Let's try changing the
1509 font size, which affects the size of the note heads (among
1510 other things) several times. The change is from the default
1511 value, not the current value.
1513 @lilypond[quote,verbatim,ragged-right,relative=1,fragment]
1515 % make note heads smaller
1518 % make note heads larger
1519 \set fontSize = #2.5
1521 % return to original size
1526 We have now seen how to set the values of several different
1527 types of property. Note that integers and numbers are alway
1528 preceded by a hash sign, @code{#}, while a true or false value
1529 is specified by ##t and ##f, with two hash signs. A text
1530 property should be enclosed in double quotation signs, as above,
1531 although we shall see later that text can actually be specified
1532 in a much more general way by using the very powerful
1533 @code{markup} command.
1538 Context properties may also be set at the time the context is
1539 created. Sometimes this is a clearer way of specifying a
1540 property value if it is to remain fixed for the duration of
1541 the context. When a context is created with a @code{\new}
1542 command it may be followed immediately by a
1543 @code{\with @{ .. @}} block in which the property values are
1544 set. For example, if we wish to suppress the printing of
1545 extra naturals for the duration of a staff we would write:
1548 \new Staff \with @{ extraNatural = ##f @}
1554 @lilypond[quote,verbatim,ragged-right]
1560 \new Staff \with { extraNatural = ##f }
1567 In effect this overrides the default value of the property. It
1568 may still be changed dynamically using @code{\set} and returned
1569 to its (new) default value with @code{\unset}.
1571 @node Adding and removing engravers
1572 @subsection Adding and removing engravers
1574 @cindex Engravers, adding
1575 @cindex Engravers, removing
1580 We have seen that contexts each contain several engravers, each
1581 of which is responsible for producing a particular part of the
1582 output, like bar lines, staves, note heads, stems, etc. If an
1583 engraver is removed from a context it can no longer produce its
1584 output. This is a crude way of modifying the output, but it
1585 can sometimes be useful.
1587 @unnumberedsubsubsec Changing a single context
1589 To remove an engraver from a single context we use the
1590 @code{\with} command placed immediately after the context creation
1591 command, as in the previous section.
1594 illustration let's repeat an example from the previous
1595 section with the staff lines removed. Remember that the
1596 staff lines are produced by the Staff_symbol_engraver.
1598 @lilypond[quote,verbatim,ragged-right]
1600 \remove Staff_symbol_engraver
1604 \set fontSize = #-4 % make note heads smaller
1606 \set fontSize = #2.5 % make note heads larger
1608 \unset fontSize % return to original size
1613 @cindex ambitus engraver
1615 Engravers can also be added to individual contexts.
1616 The command to do this is
1618 @code{\consists @emph{Engraver_name}},
1620 placed inside a @code{\with} block. Some vocal scores
1621 have an @rglos{ambitus} placed at the beginning of a
1622 staff to indicate the range of notes in that staff.
1623 The ambitus is produced by the @code{Ambitus_engraver},
1624 which is not normally included in any context. If
1625 we add it to the @code{Voice} context it calculates
1626 the range from that voice only:
1628 @lilypond[quote,verbatim,ragged-right]
1631 \consists Ambitus_engraver
1646 but if we add the Ambitus engraver to the
1647 @code{Staff} context it calculates the range from all
1648 the notes in all the voices on that staff:
1650 @lilypond[quote,verbatim,ragged-right]
1652 \consists Ambitus_engraver
1668 @unnumberedsubsubsec Changing all contexts of the same type
1670 The examples above show how to remove or add engravers to
1671 individual contexts. It is also possible to remove or add
1672 engravers to every context of a specific type by placing the
1673 commands in the appropriate context in a @code{\layout}
1674 block. For example, If we wanted to show ambiti for every
1675 staff in a four-staff score we could write
1677 @lilypond[quote,verbatim,ragged-right]
1681 \relative c'' { c a b g }
1684 \relative c' { c a b g }
1688 \relative c' { c a b g }
1692 \relative c { c a b g }
1698 \consists Ambitus_engraver
1705 The default values of context properties may also be set
1706 for all contexts of a particular type by including the
1707 @code{\set} command in a @code{\context} block in the
1710 @node Extending the templates
1711 @section Extending the templates
1713 You've read the tutorial, you know how to write music, you
1714 understand the fundamental concepts. But how can you
1715 get the staves that you want? Well, you can find lots of
1716 templates (see @ref{Templates}) which may give you a start.
1718 if you want something that isn't covered there? Read on.
1720 TODO Add links to templates after they have been moved to LSR
1723 * Soprano and cello::
1724 * Four-part SATB vocal score::
1725 * Building a score from scratch::
1728 @node Soprano and cello
1729 @subsection Soprano and cello
1731 Start off with the template that seems closest to what you want to end
1732 up with. Let's say that you want to write something for soprano and
1733 cello. In this case, we would start with @q{Notes and lyrics} (for the
1738 melody = \relative c' @{
1745 text = \lyricmode @{
1751 \new Voice = "one" @{
1755 \new Lyrics \lyricsto "one" \text
1762 Now we want to add a cello part. Let's look at the @q{Notes only} example:
1766 melody = \relative c' @{
1780 We don't need two @code{\version} commands. We'll need the @code{melody}
1781 section. We don't want two @code{\score} sections -- if we had two
1782 @code{\score}s, we'd get the two parts separately. We want them together,
1783 as a duet. Within the @code{\score} section, we don't need two
1784 @code{\layout} or @code{\midi}.
1786 If we simply cut and paste the @code{melody} section, we would end up with
1787 two @code{melody} sections. So let's rename them. We'll call the section
1788 for the soprano @code{sopranoMusic} and the section for the cello
1789 @code{celloMusic}. While we're doing this, let's rename @code{text}
1790 to be @code{sopranoLyrics}. Remember to rename both instances of all
1791 these names -- both the initial definition (the
1792 @code{melody = \relative c' @{ } part) and the name's use (in the
1793 @code{\score} section).
1795 While we're doing this, let's change the cello part's staff -- celli
1796 normally use bass clef. We'll also give the cello some different
1801 sopranoMusic = \relative c' @{
1808 sopranoLyrics = \lyricmode @{
1812 celloMusic = \relative c @{
1821 \new Voice = "one" @{
1825 \new Lyrics \lyricsto "one" \sopranoLyrics
1832 This is looking promising, but the cello part won't appear in the
1833 score -- we haven't used it in the @code{\score} section. If we
1834 want the cello part to appear under the soprano part, we need to add
1837 \new Staff \celloMusic
1841 underneath the soprano stuff. We also need to add @code{<<} and
1842 @code{>>} around the music -- that tells LilyPond that there's
1843 more than one thing (in this case, two @code{Staves}) happening
1844 at once. The @code{\score} looks like this now
1846 @c Indentation in this example is deliberately poor
1851 \new Voice = "one" @{
1855 \new Lyrics \lyricsto "one" \sopranoLyrics
1857 \new Staff \celloMusic
1865 This looks a bit messy; the indentation is messed up now. That is
1866 easily fixed. Here's the complete soprano and cello template.
1868 @lilypond[quote,verbatim,ragged-right]
1870 sopranoMusic = \relative c' {
1877 sopranoLyrics = \lyricmode {
1881 celloMusic = \relative c {
1891 \new Voice = "one" {
1895 \new Lyrics \lyricsto "one" \sopranoLyrics
1897 \new Staff \celloMusic
1905 @node Four-part SATB vocal score
1906 @subsection Four-part SATB vocal score
1908 Most vocal scores of music written for four-part mixed choir
1909 with orchestral accompaniment such as Mendelssohn's Elijah or
1910 Handel's Messiah have the choral music and words on four
1911 staves, one for each of SATB, with a piano reduction of the
1912 orchestral accompaniment underneath. Here's an example
1913 from Handel's Messiah:
1915 @c The following should appear as music without code
1916 @lilypond[quote,ragged-right]
1918 global = { \key d \major \time 4/4 }
1919 sopMusic = \relative c'' {
1921 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
1923 sopWords = \lyricmode {
1924 Wor -- thy is the lamb that was slain
1926 altoMusic = \relative a' {
1928 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
1930 altoWords = \sopWords
1931 tenorMusic = \relative c' {
1933 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
1935 tenorWords = \sopWords
1936 bassMusic = \relative c' {
1938 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
1940 bassWords = \sopWords
1941 upper = \relative a' {
1944 r4 <a d fis>2 <a e' a>4 |
1945 <d fis d'>4. <d fis d'>8 <a d a'>2 |
1946 <g cis g'>4 <a d fis> <a cis e>2 |
1948 lower = \relative c, {
1951 <d d'>4 <d d'>2 <cis cis'>4 |
1952 <b b'>4. <b' b'>8 <fis fis'>2 |
1953 <e e'>4 <d d'> <a' a'>2 |
1957 << % combine ChoirStaff and PianoStaff in parallel
1959 \new Staff = "sopranos" <<
1960 \set Staff.instrumentName = "Soprano"
1961 \new Voice = "sopranos" { \global \sopMusic }
1963 \new Lyrics \lyricsto "sopranos" { \sopWords }
1964 \new Staff = "altos" <<
1965 \set Staff.instrumentName = "Alto"
1966 \new Voice = "altos" { \global \altoMusic }
1968 \new Lyrics \lyricsto "altos" { \altoWords }
1969 \new Staff = "tenors" <<
1970 \set Staff.instrumentName = "Tenor"
1971 \new Voice = "tenors" { \global \tenorMusic }
1973 \new Lyrics \lyricsto "tenors" { \tenorWords }
1974 \new Staff = "basses" <<
1975 \set Staff.instrumentName = "Bass"
1976 \new Voice = "basses" { \global \bassMusic }
1978 \new Lyrics \lyricsto "basses" { \bassWords }
1982 \set PianoStaff.instrumentName = "Piano "
1983 \new Staff = "upper" \upper
1984 \new Staff = "lower" \lower
1990 None of the templates provides this layout exactly. The
1991 nearest is @q{SATB vocal score and automatic piano reduction},
1992 but we need to change the layout and add a piano
1993 accompaniment which is not derived automatically from the
1994 vocal parts. The variables holding the music and words for
1995 the vocal parts are fine, but we shall need to add variables for
1996 the piano reduction.
1998 The order in which the contexts appear in the ChoirStaff of
1999 the template do not correspond with the order in the vocal
2000 score shown above. We need to rearrange them so there are
2001 four staves with the words written directly underneath the
2002 notes for each part.
2003 All the voices should be @code{\voiceOne}, which is
2004 the default, so the @code{\voiceXXX} commands should be removed.
2005 We also need to specify the tenor clef for the tenors.
2006 The way in which lyrics are specified in the template has not yet
2007 been encountered so we need to use the method with which we are
2008 familiar. We should also add the names of each staff.
2010 Doing this gives for our ChoirStaff:
2014 \new Staff = "sopranos" <<
2015 \set Staff.instrumentName = "Soprano"
2016 \new Voice = "sopranos" @{ \global \sopMusic @}
2018 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
2019 \new Staff = "altos" <<
2020 \set Staff.instrumentName = "Alto"
2021 \new Voice = "altos" @{ \global \altoMusic @}
2023 \new Lyrics \lyricsto "altos" @{ \altoWords @}
2024 \new Staff = "tenors" <<
2025 \set Staff.instrumentName = "Tenor"
2026 \new Voice = "tenors" @{ \global \tenorMusic @}
2028 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
2029 \new Staff = "basses" <<
2030 \set Staff.instrumentName = "Bass"
2031 \new Voice = "basses" @{ \global \bassMusic @}
2033 \new Lyrics \lyricsto "basses" @{ \bassWords @}
2037 Next we must work out the piano part. This is
2038 easy - we just pull out the piano part from the
2039 @q{Solo piano} template:
2043 \set PianoStaff.instrumentName = "Piano "
2044 \new Staff = "upper" \upper
2045 \new Staff = "lower" \lower
2049 and add the variable definitions for @code{upper}
2052 The ChoirStaff and PianoStaff must be combined
2053 using angle brackets as we want them to be
2054 stacked one above the other:
2057 << % combine ChoirStaff and PianoStaff one above the other
2059 \new Staff = "sopranos" <<
2060 \new Voice = "sopranos" @{ \global \sopMusic @}
2062 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
2063 \new Staff = "altos" <<
2064 \new Voice = "altos" @{ \global \altoMusic @}
2066 \new Lyrics \lyricsto "altos" @{ \altoWords @}
2067 \new Staff = "tenors" <<
2068 \clef "G_8" % tenor clef
2069 \new Voice = "tenors" @{ \global \tenorMusic @}
2071 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
2072 \new Staff = "basses" <<
2074 \new Voice = "basses" @{ \global \bassMusic @}
2076 \new Lyrics \lyricsto "basses" @{ bassWords @}
2080 \set PianoStaff.instrumentName = "Piano "
2081 \new Staff = "upper" \upper
2082 \new Staff = "lower" \lower
2087 Combining all these together and adding the music
2088 for the three bars of the example above gives:
2090 @lilypond[quote,verbatim,ragged-right]
2092 global = { \key d \major \time 4/4 }
2093 sopMusic = \relative c'' {
2095 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
2097 sopWords = \lyricmode {
2098 Wor -- thy is the lamb that was slain
2100 altoMusic = \relative a' {
2102 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
2104 altoWords = \sopWords
2105 tenorMusic = \relative c' {
2107 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
2109 tenorWords = \sopWords
2110 bassMusic = \relative c' {
2112 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
2114 bassWords = \sopWords
2115 upper = \relative a' {
2118 r4 <a d fis>2 <a e' a>4 |
2119 <d fis d'>4. <d fis d'>8 <a d a'>2 |
2120 <g cis g'>4 <a d fis> <a cis e>2 |
2122 lower = \relative c, {
2125 <d d'>4 <d d'>2 <cis cis'>4 |
2126 <b b'>4. <b' b'>8 <fis fis'>2 |
2127 <e e'>4 <d d'> <a' a'>2 |
2131 << % combine ChoirStaff and PianoStaff in parallel
2133 \new Staff = "sopranos" <<
2134 \set Staff.instrumentName = "Soprano"
2135 \new Voice = "sopranos" { \global \sopMusic }
2137 \new Lyrics \lyricsto "sopranos" { \sopWords }
2138 \new Staff = "altos" <<
2139 \set Staff.instrumentName = "Alto"
2140 \new Voice = "altos" { \global \altoMusic }
2142 \new Lyrics \lyricsto "altos" { \altoWords }
2143 \new Staff = "tenors" <<
2144 \set Staff.instrumentName = "Tenor"
2145 \new Voice = "tenors" { \global \tenorMusic }
2147 \new Lyrics \lyricsto "tenors" { \tenorWords }
2148 \new Staff = "basses" <<
2149 \set Staff.instrumentName = "Bass"
2150 \new Voice = "basses" { \global \bassMusic }
2152 \new Lyrics \lyricsto "basses" { \bassWords }
2156 \set PianoStaff.instrumentName = "Piano "
2157 \new Staff = "upper" \upper
2158 \new Staff = "lower" \lower
2165 @node Building a score from scratch
2166 @subsection Building a score from scratch
2168 After gaining some facility with writing LilyPond code you
2169 may find that it is easier to build a score from scratch
2170 rather than modifying one of the templates. You can also
2171 develop your own style this way to suit the sort of music you
2172 like. Let's see how to put together the score for an organ
2173 prelude as an example.
2175 We begin with a header section. Here go the title, name
2176 of composer, etc, then come any variable definitions, and
2177 finally the score block. Let's start with these in outline
2178 and fill in the details later.
2180 We'll use the first two bars of Bach's prelude
2181 based on @emph{Jesu, meine Freude} which is written for two
2182 manuals and pedal organ. You can see these two bars of music
2183 at the bottom of this section. The top manual part has two voices,
2184 the lower and pedal organ one each. So we need four
2185 music definitions and one to define the time signature
2191 title = "Jesu, meine Freude"
2192 composer = "J S Bach"
2194 TimeKey = @{ \time 4/4 \key c \minor @}
2195 ManualOneVoiceOneMusic = @{s1@}
2196 ManualOneVoiceTwoMusic = @{s1@}
2197 ManualTwoMusic = @{s1@}
2198 PedalOrganMusic = @{s1@}
2204 For now we've just used a spacer note, @code{s1},
2205 instead of the real music. We'll add that later.
2207 Next let's see what should go in the score block.
2208 We simply mirror the staff structure we want.
2209 Organ music is usually written on three staves,
2210 one for each manual and one for the pedals. The
2211 manual staves should be bracketed together so we
2212 need to use a PianoStaff for them. The first
2213 manual part needs two voices and the second manual
2218 \new Staff = "ManualOne" <<
2219 \new Voice @{ \ManualOneVoiceOneMusic @}
2220 \new Voice @{ \ManualOneVoiceTwoMusic @}
2221 >> % end ManualOne Staff context
2222 \new Staff = "ManualTwo" <<
2223 \new Voice @{ \ManualTwoMusic @}
2224 >> % end ManualTwo Staff context
2225 >> % end PianoStaff context
2228 Next we need to add a staff for the pedal organ.
2229 This goes underneath the PianoStaff, but it must
2230 be simultaneous with it, so we need angle brackets
2231 round the two. Missing these out would generate
2232 an error in the log file. It's a common mistake
2233 which you'll make sooner or later! Try copying
2234 the final example at the end of this section,
2235 remove these angle brackets, and compile it to
2236 see what errors it generates.
2239 << % PianoStaff and Pedal Staff must be simultaneous
2241 \new Staff = "ManualOne" <<
2242 \new Voice @{ \ManualOneVoiceOneMusic @}
2243 \new Voice @{ \ManualOneVoiceTwoMusic @}
2244 >> % end ManualOne Staff context
2245 \new Staff = "ManualTwo" <<
2246 \new Voice @{ \ManualTwoMusic @}
2247 >> % end ManualTwo Staff context
2248 >> % end PianoStaff context
2249 \new Staff = "PedalOrgan" <<
2250 \new Voice @{ \PedalOrganMusic @}
2255 It is not strictly necessary to use the simultaneous construct
2256 @code{<< >>} for the manual two staff and the pedal organ staff,
2257 since they contain only one music expression, but it does no harm
2258 and always using angle brackets after @code{\new Staff} is a good
2259 habit to cultivate in case there are multiple voices.
2261 Let's add this structure to the score block, and adjust the
2262 indenting. We also add the appropriate clefs, ensure the
2263 second voice stems point down with @code{\voiceTwo} and
2264 enter the time signature and key to each staff using our
2265 predefined variable, @code{\TimeKey}.
2269 << % PianoStaff and Pedal Staff must be simultaneous
2271 \new Staff = "ManualOne" <<
2272 \TimeKey % set time signature and key
2274 \new Voice @{ \ManualOneVoiceOneMusic @}
2275 \new Voice @{ \voiceTwo \ManualOneVoiceTwoMusic @}
2276 >> % end ManualOne Staff context
2277 \new Staff = "ManualTwo" <<
2280 \new Voice @{ \ManualTwoMusic @}
2281 >> % end ManualTwo Staff context
2282 >> % end PianoStaff context
2283 \new Staff = "PedalOrgan" <<
2286 \new Voice @{ \PedalOrganMusic @}
2287 >> % end PedalOrgan Staff
2289 @} % end Score context
2292 That completes the structure. Any three-staff organ music
2293 will have a similar structure, although the number of voices
2294 may vary. All that remains now
2295 is to add the music, and combine all the parts together.
2297 @lilypond[quote,verbatim,ragged-right]
2300 title = "Jesu, meine Freude"
2301 composer = "J S Bach"
2303 TimeKey = { \time 4/4 \key c \minor }
2304 ManualOneVoiceOneMusic = \relative g' {
2305 g4 g f ees | d2 c2 |
2307 ManualOneVoiceTwoMusic = \relative c' {
2308 ees16 d ees8~ ees16 f ees s c8 d~ d c~ |
2309 c c4 b8 c8. g16 c b c d |
2311 ManualTwoMusic = \relative c' {
2312 c16 b c8~ c16 b c g a8 g~ g16 g aes ees |
2313 f ees f d g aes g f ees d e8~ ees16 f ees d |
2315 PedalOrganMusic = \relative c {
2316 r8 c16 d ees d ees8~ ees16 a, b g c b c8 |
2317 r16 g ees f g f g8 c,2 |
2321 << % PianoStaff and Pedal Staff must be simultaneous
2323 \new Staff = "ManualOne" <<
2324 \TimeKey % set time signature and key
2326 \new Voice { \ManualOneVoiceOneMusic }
2327 \new Voice { \voiceTwo \ManualOneVoiceTwoMusic }
2328 >> % end ManualOne Staff context
2329 \new Staff = "ManualTwo" <<
2332 \new Voice { \ManualTwoMusic }
2333 >> % end ManualTwo Staff context
2334 >> % end PianoStaff context
2335 \new Staff = "PedalOrgan" <<
2338 \new Voice { \PedalOrganMusic }
2339 >> % end PedalOrgan Staff
2341 } % end Score context