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.
220 \new Staff = "singer" <<
222 \new PianoStaff = piano <<
229 Remember that we use @code{<<} and @code{>>} to show simultaneous
230 music. And we definitely want to show the vocal part and piano
231 part at the same time, not one after the other! However, the
232 @code{<< .. >>} construct is not really necessary for the Singer
233 staff, as it contains only one music expression, but Staves often
234 do require simultaneous Voices within them, so using @code{<< .. >>}
235 rather than braces is a good habit to adopt. We'll add some real
236 music later; for now let's just put in some dummy notes and lyrics.
238 @lilypond[verbatim,quote,ragged-right]
241 \new Staff = "singer" <<
242 \new Voice = "vocal" { c'1 }
245 \new PianoStaff = "piano" <<
246 \new Staff = "upper" { c'1 }
247 \new Staff = "lower" { c'1 }
254 Now we have a lot more details. We have the singer's staff: it
255 contains a @code{Voice} (in LilyPond, this term refers to a set of
256 notes, not necessarily vocal notes -- for example, a violin
257 generally plays one voice) and some lyrics. We also have a piano
258 staff: it contains an upper staff (right hand) and a lower staff
261 At this stage, we could start filling in notes. Inside the curly
262 braces next to @code{\new Voice = vocal}, we could start writing
270 But if we did that, the @code{\score} section would get pretty
271 long, and it would be harder to understand what was happening. So
272 let's use variables instead. These were introduced at the end
273 of the previous section, remember? So, adding a few notes, we
274 now have a piece of real music:
276 @lilypond[verbatim,quote,ragged-right]
277 melody = \relative c'' { r4 d8\noBeam g, c r4 }
278 text = \lyricmode { And God said, }
279 upper = \relative c'' { <g d g,>2~ <g d g,> }
280 lower = \relative c { b2 e2 }
284 \new Staff = "singer" <<
285 \new Voice = "vocal" { \melody }
288 \new PianoStaff = "piano" <<
289 \new Staff = "upper" { \upper }
290 \new Staff = "lower" {
301 Be careful about the difference between notes, which are introduced
302 with @code{\relative}, and lyrics, which are introduced with
303 @code{\lyricmode}. These are essential to tell LilyPond
304 to interpret the following content as music and text
307 When writing (or reading) a @code{\score} section, just take it
308 slowly and carefully. Start with the outer layer, then work on
309 each smaller layer. It also really helps to be strict with
310 indentation -- make sure that each item on the same layer starts
311 on the same horizontal position in your text editor.
314 @node Nesting music expressions
315 @subsection Nesting music expressions
317 It is not essential to declare all staves at the beginning;
318 they may be introduced temporarily at any point. This is
319 particularly useful for creating ossia sections
320 (see @rglos{ossia}). Here is a simple example showing how
321 to introduce a new staff temporarily for the duration of
324 @lilypond[verbatim,quote,ragged-right]
341 Note that the size of the clef is the same as a clef printed
342 following a clef change -- slightly smaller than the clef
343 at the begining of the line. This is usual for clefs printed
344 in the middle of a line.
346 The ossia section may be placed above the staff
349 @lilypond[verbatim,quote,ragged-right]
357 alignAboveContext = "main" }
365 This example uses @code{\with}, which will be explained more
366 fully later. It is a means of modifying the default behaviour
367 of a single Staff. Here it says that the new staff should be
368 placed above the staff called @qq{main} instead of the default
369 position which is below.
371 Ossia are often written without clef and without
372 time signature and are usually in a smaller font.
373 These require further commands which
374 have not yet been introduced. See @ref{Size of objects}
376 @node On the un-nestedness of brackets and ties
377 @subsection On the un-nestedness of brackets and ties
379 You have already met a number of different types of bracket in
380 writing the input file to LilyPond. These obey different rules
381 which can be confusing at first. Before we explain the rules
382 let's first review the different types of bracket.
384 @c attempt to force this onto a new page
386 @multitable @columnfractions .3 .7
387 @headitem Bracket Type
389 @item @code{@{ .. @}}
390 @tab Encloses a sequential segment of music
392 @tab Encloses the notes of a chord
393 @item @code{<< .. >>}
394 @tab Encloses concurrent or simultaneous sections
396 @tab Marks the start and end of a slur
397 @item @code{\( .. \)}
398 @tab Marks the start and end of a phrase mark
400 @tab Marks the start and end of a manual beam
403 To these we should add other constructs which generate lines
404 between or across notes: ties (marked by a tilde, @code{~}),
405 tuplets written as @code{\times x/y @{..@}}, and grace notes
406 written as @code{\grace@{..@}}.
408 Outside LilyPond, the conventional use of brackets requires
409 the different types to be properly nested, like this,
410 @code{<< [ @{ ( .. ) @} ] >>}, with the closing brackets being
411 encountered in exactly the opposite order to the opening
412 brackets. This @strong{is} a requirement for the three types of
413 bracket described by the word @q{Encloses} in the table above --
414 they must nest properly.
415 However, the remaining brackets, described with the word
416 @q{Marks} in the table above together with ties and tuplets,
417 do @strong{not} have to nest
418 properly with any of the brackets. In fact, these are not
419 brackets in the sense that
420 they enclose something -- they are simply markers to indicate
421 where something starts and ends.
423 So, for example, a phrasing slur can start before a manually
424 inserted beam and end before the end of the beam -- not very
425 musical, perhaps, but possible:
427 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
428 { g8\( a b[ c b\) a] }
431 In general, different kinds of brackets, and those implied by
432 tuplets, ties and grace notes, may be mixed freely.
433 This example shows a beam extending into a tuplet (line 1),
434 a slur extending into a tuplet (line 2),
435 a beam and a slur extending into a tuplet, a tie crossing
436 two tuplets, and a phrasing slur extending out of a tuplet
439 @lilypond[quote,verbatim,fragment,ragged-right]
441 r16[ g16 \times 2/3 {r16 e'8] }
442 g16( a \times 2/3 {b d) e' }
443 g8[( a \times 2/3 {b d') e'~]}
444 \times 4/5 {e'32\( a b d' e'} a'4.\)
449 @node Voices contain music
450 @section Voices contain music
452 Singers need voices to sing, and so does LilyPond.
453 The actual music for all instruments in a score
454 is contained in Voices -- the most fundamental
455 of all LilyPond's concepts.
458 * I'm hearing Voices::
459 * Explicitly instantiating voices::
460 * Voices and vocals::
463 @node I'm hearing Voices
464 @subsection I'm hearing Voices
468 @cindex Voice context
470 The lowest, most fundamental or innermost layers in a LilyPond
471 score are called @q{Voice contexts} or just @q{Voices} for short.
472 Voices are sometimes called @q{layers} in other notation
475 In fact, a Voice layer or context is the only one which can
476 contain music. If a Voice context is not explicitly declared
477 one is created automatically, as we saw at the beginning of
478 this chapter. Some instruments such as an
479 Oboe can play only one note at a time. Music written for
480 such instruments is monophonic and requires just a single
481 voice. Instruments which can play more than one note at a
482 time like the piano will often require multiple voices to
483 encode the different concurrent notes and rhythms they are
486 A single voice can contain many notes in a chord, of course,
487 so when exactly are multiple voices needed? Look first at
488 this example of four chords:
490 @lilypond[quote,verbatim,fragment,ragged-right,relative=1]
492 <d g>4 <d fis> <d a'> <d g>
495 This can be expressed using just the single angle bracket chord
496 symbols, @code{< ... >}, and for this just a single voice is
497 needed. But suppose the F-sharp were actually an eighth-note
498 followed by an eighth-note G, a passing note on the way to the A?
499 Now we have two notes which start at the same time but have
500 different durations: the quarter-note D and the eighth-note
501 F-sharp. How are these to be coded? They cannot be written as
502 a chord because all the notes in a chord must have the same
503 duration. And they cannot be written as two separate notes
504 as they need to start at the same time. This is when two
507 Let us see how this is done in LilyPond input syntax.
512 The easiest way to enter fragments with more than one voice on a
513 staff is to enter each voice as a sequence (with @code{@{...@}}),
514 and combine them simultaneously with angle brackets, @code{<<...>>}.
515 The fragments must also be separated with double backward slashes,
516 @code{\\}, to place them in separate voices. Without these, the
517 notes would be entered into a single voice, which would usually
518 cause errors. This technique is particularly suited to pieces of
519 music which are largely monophonic with occasional short sections
522 Here's how we split the chords above into two voices and add both
523 the passing note and a slur:
525 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
527 % Voice "1" Voice "2"
528 << { g4 fis8( g) a4 g } \\ { d4 d d d } >> |
531 Notice how the stems of the second voice now point down.
533 Here's another simple example:
535 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
537 % Voice "1" Voice "2"
538 << { r4 g g4. a8 } \\ { d,2 d4 g } >> |
539 << { bes4 bes c bes } \\ { g4 g g8( a) g4 } >> |
540 << { a2. r4 } \\ { fis2. s4 } >> |
543 It is not necessary to use a separate @code{<< \\ >>} construct
544 for each bar. For music with few notes in each bar this layout
545 can help the legibility of the code, but if there are many
546 notes in each bar it may be better to split out each voice
547 separately, like this:
549 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
565 This example has just two voices, but the same contruct may be
566 used to encode three or more voices by adding more back-slash
569 The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
570 In each of these contexts, the vertical direction of slurs,
571 stems, ties, dynamics etc., is set appropriately.
573 @lilypond[quote,verbatim,fragment]
574 \new Staff \relative c' {
577 % Voice "1" Voice "2" Voice "3"
578 << { g4 f e } \\ { r8 e4 d c8 ~ } >> |
579 << { d2 e2 } \\ { c8 b16 a b8 g ~ g2 } \\ { s4 b4 c2 } >> |
583 These voices are all separate from the main voice that contains
584 the notes just outside the @code{<< .. >>} construct. Let's call
585 this the @emph{simultaneous construct}. Slurs and ties may only
586 connect notes within the same voice, so slurs and ties cannot go
587 into or out of a simultaneous construct. Conversely,
588 parallel voices from separate simultaneous constructs on the same
589 staff are the same voice. Other voice-related properties also
590 carry across simultaneous constructs. Here is the same example,
591 with different colors and note heads for each voice. Note that
592 changes in one voice do not affect other voices, but they do
593 persist in the same voice later. Note also that tied notes may be
594 split across the same voices in two constructs, shown here in the
597 @lilypond[quote,verbatim]
598 \new Staff \relative c' {
617 { c8 b16 a b8 g ~ g2 }
627 The commands @code{\voiceXXXStyle} are mainly intended for use in
628 educational documents such as this one. They modify the color
629 of the note head, the stem and the beams, and the style of the
630 note head, so that the voices may be easily distinguished.
631 Voice one is set to red diamonds, voice two to blue triangles,
632 voice three to green crossed circles, and voice four (not used
633 here) to magenta crosses. We shall see later how commands like
634 these may be created by the user.
635 See @ref{Visibility and color of objects}
636 TODO Add link to using variables for tweaks
638 Polyphony does not change the relationship of notes within a
639 @code{\relative @{ @}} block. Each note is still calculated
640 relative to the note immediately preceding it, or to the first
641 note of the preceding chord. So in
644 \relative c' @{ noteA << < noteB noteC > \\ noteD >> noteE @}
648 @code{noteB} is relative to @code{noteA} @*
649 @code{noteC} is relative to @code{noteB}, not @code{noteA}; @*
650 @code{noteD} is relative to @code{noteB}, not @code{noteA} or
652 @code{noteE} is relative to @code{noteD}, not @code{noteA}
654 An alternative way, which may be clearer if the notes in the
655 voices are widely separated, is to place a @code{\relative}
656 command at the start of each voice:
659 \relative c' @{ noteA ... @}
661 \relative c'' @{ < noteB noteC > ... @}
663 \relative g' @{ noteD ... @}
665 \relative c' @{ noteE ... @}
668 Let us finally analyse the voices in a more complex piece of
670 the notes from the first two bars of the second of Chopin's
671 Deux Nocturnes, Op 32. This example will be used at later
672 stages in this and the next chapter to illustrate several
673 techniques for producing notation, so please ignore for now
674 anything in the underlying code which looks mysterious and
675 concentrate just on the music and the voices -- the
676 complications will all be explained in later sections.
678 @c The following should appear as music without code
679 @lilypond[quote,ragged-right]
680 \new Staff \relative c'' {
689 % Ignore these for now - they are explained in Ch 4
690 \once \override NoteColumn #'force-hshift = #0
692 \once \override NoteColumn #'force-hshift = #0.5
700 The direction of the stems is often used to indicate the
701 continuity of two simultaneous melodic lines. Here the
702 stems of the highest notes are all pointing up and the
703 stems of the lower notes are all pointing down.
704 This is the first indication that more than one voice
707 But the real need for multiple voices arises when notes
708 which start at the same time have different durations.
709 Look at the notes which start at beat three in the first
710 bar. The A-flat is a dotted quarter note, the F is a
711 quarter note and the D-flat is a half note. These
712 cannot be written as a chord as all the notes in a chord
713 must have the same duration. Neither can they be written
714 as sequential notes, as they must start at the same time.
715 This section of the bar requires three voices, and the
716 normal practice would be to write the whole bar as three
717 voices, as shown below, where we have used different note heads
718 and colors for the three voices. Again, the code behind this
719 example will be explained later, so ignore anything you do
722 @c The following should appear as music without code
723 @c The three voice styles should be defined in -init
724 @lilypond[quote,ragged-right]
725 \new Staff \relative c'' {
736 \\ % No Voice three (we want stems down)
739 % Ignore these for now - they are explained in Ch 4
740 \once \override NoteColumn #'force-hshift = #0
742 \once \override NoteColumn #'force-hshift = #0.5
751 Let us try to encode this music from scratch. As we
752 shall see, this encounters some difficulties. We begin as
753 we have learnt, using the @code{<< \\ >>} construct to
754 enter the music of the first bar in three voices:
756 @lilypond[quote,verbatim,fragment,ragged-right]
757 \new Staff \relative c'' {
760 { c2 aes4. bes8 } \\ { aes2 f4 fes } \\ { <ees c>2 des2 }
769 The stem directions are automatically assigned with the
770 odd-numbered voices taking upward stems and the even-numbered
771 voices downward ones. The stems for voices 1 and 2 are right,
772 but the stems in voice 3 should go down in this particular piece
773 of music. We can correct this simply by missing out voice three
774 and placing the music in voice four:
776 @lilypond[quote,verbatim,fragment,ragged-right]
777 \new Staff \relative c'' {
783 \\ % Omit Voice three
792 and exposes a problem commonly encountered with multiple
793 voices: the stems of notes can collide with note heads
794 in other voices. In laying out the notes, LilyPond allows the
795 notes or chords from two voices to occupy the same vertical
796 note column provided the stems are in opposite directions, but
797 the notes from a third voice are displaced to avoid the stems
798 colliding. This often works well, but in this example the
799 notes of the lowest voice are clearly not well placed by default.
800 LilyPond provides several ways to adjust the horizontal placing
801 of notes. We are not quite ready yet to see how to correct this,
802 so we shall leave this problem until a later section
803 (see @ref{Fixing overlapping notation} )
805 @node Explicitly instantiating voices
806 @subsection Explicitly instantiating voices
810 @funindex \voiceThree
813 Voice contexts can also be created manually
814 inside a @code{<< >>} block to create polyphonic music, using
815 @code{\voiceOne} ... @code{\voiceFour} to indicate the required
816 directions of stems, slurs, etc. In longer scores this method
817 is clearer, as it permits the voices to be separated and to be
818 given more descriptive names.
820 Specifically, the construct @code{<< \\ >>} which we used in
821 the previous section:
826 << @{ e4 f g a @} \\ @{ c,4 d e f @} >>
836 \new Voice = "1" @{ \voiceOne \relative c' @{ e4 f g a @} @}
837 \new Voice = "2" @{ \voiceTwo \relative c' @{ c4 d e f @} @}
841 Both of the above would produce
843 @c The following example should not display the code
844 @lilypond[ragged-right,quote]
846 \new Voice = "1" { \voiceOne \relative c' { e4 f g a } }
847 \new Voice = "2" { \voiceTwo \relative c' { c4 d e f } }
851 The @code{\voiceXXX} commands set the direction of stems, slurs,
852 ties, articulations, text annotations, augmentation dots of dotted
853 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
854 make these objects point upwards, while @code{\voiceTwo} and
855 @code{\voiceFour} make them point downwards. These commands also
856 generate a horizontal shift for each voice when this is required
857 to avoid clashes of note heads. The command @code{\oneVoice}
858 reverts the settings back to the normal values for a single voice.
860 Let us see in some simple examples exactly what effect
861 @code{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on
862 markup, ties, slurs, and dynamics:
864 @lilypond[quote,ragged-right,verbatim]
866 % Default behaviour or behaviour after \oneVoice
867 c d8 ~ d e4 ( f g a ) b-> c
871 @lilypond[quote,ragged-right,verbatim]
874 c d8 ~ d e4 ( f g a ) b-> c
876 c, d8 ~ d e4 ( f g a ) b-> c
880 @lilypond[quote,ragged-right,verbatim]
883 c d8 ~ d e4 ( f g a ) b-> c
885 c, d8 ~ d e4 ( f g a ) b-> c
889 An expression that appears directly inside a @code{<< >>} belongs
890 to the main voice (but, note, @strong{not} in a @code{<< \\ >>}
891 construct). This is useful when extra voices appear while the
892 main voice is playing. Here is a more correct rendition of the
893 example from the previous section. The red diamond-shaped notes
894 demonstrate that the main melody is now in a single voice context,
895 permitting a phrasing slur to be drawn over them.
897 @lilypond[quote,ragged-right,verbatim]
898 \new Staff \relative c' {
900 % The following notes are monophonic
902 % Start simultaneous section of three voices
904 % Continue the main voice in parallel
906 % Initiate second voice
908 % Set stems, etc, down
910 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
912 % Initiate third voice
922 @cindex nesting music expressions
923 @cindex nesting simultaneous constructs
925 More deeply nested polyphony constructs are possible, and if a
926 voice appears only briefly this might be a more natural way to
929 @lilypond[quote,ragged-right,verbatim]
930 \new Staff \relative c' {
950 This method of nesting new voices briefly is useful
951 when only small sections of the music
952 are polyphonic, but when the whole staff is largely polyphonic
953 it can be clearer to use multiple voices throughout, using
954 spacing notes to step over sections where the voice is silent,
957 @lilypond[quote,ragged-right,verbatim]
958 \new Staff \relative c' <<
959 % Initiate first voice
962 c16^( d e f g4 f e | d2 e2) |
964 % Initiate second voice
966 % set stems, etc down
968 s4 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 |
970 % Initiate third voice
980 @cindex shift commands
986 Closely spaced notes in a chord, or notes occuring at the same
987 time in different voices, are arranged in two, occasionally more,
988 columns to prevent the note heads overlapping. These are called
989 note columns. There are separate columns for each voice, and
990 the currently specified voice-dependent shift is applied to the
991 note column if there would otherwise be a collision. This can
992 be seen in the example above. In bar 2 the C in voice two is
993 shifted to the right relative to the D in voice one, and in the
994 final chord the C in voice three is also shifted to the right
995 relative to the other notes.
997 The @code{\shiftOn}, @code{\shiftOnn}, @code{\shiftOnnn}, and
998 @code{\shiftOff} commands specify the degree to which notes and
999 chords of the voice should be shifted if a collision
1000 would otherwise occur. By default, the outer voices (normally
1001 voices one and two) have @code{\shiftOff} specified, while the
1002 inner voices (three and four) have @code{\shiftOn} specified.
1003 When a shift is applied, Voices one and three are shifted to
1004 the right and voices two and four to the left.
1006 @code{\shiftOnn} and @code{\shiftOnnn} define further shift
1007 levels which may be specified temporarily to resolve collisions
1008 in complex situations -- see @ref{Real music example}.
1010 A note column can contain just one note (or chord) from a voice
1011 with stems up and one note (or chord) from a voice with stems
1012 down. If notes from two voices which have their stems in the
1013 same direction are placed at the same position and both voices
1014 have no shift or the same shift specified, the error message
1015 @qq{Too many clashing note columns} will be produced.
1017 @node Voices and vocals
1018 @subsection Voices and vocals
1020 Vocal music presents a special difficulty: we need to combine two
1021 expressions -- notes and lyrics.
1023 You have already seen the @code{\addlyrics@{@}} command, which
1024 handles simple scores well. However, this technique is
1025 quite limited. For more complex music, you must introduce the
1026 lyrics in a @code{Lyrics} context using @code{\new Lyrics} and
1028 the lyrics to the notes with @code{\lyricsto@{@}}, using the
1029 name assigned to the Voice.
1031 @lilypond[quote,verbatim,fragment]
1033 \new Voice = "one" \relative c'' {
1036 c4 b8. a16 g4. f8 e4 d c2
1038 \new Lyrics \lyricsto "one" {
1039 No more let sins and sor -- rows grow.
1044 The automatic beaming which LilyPond uses by default works well
1045 for instrumental music, but not so well for music with lyrics,
1046 where beaming is either not required at all or is used to indicate
1047 melismata in the lyrics. In the example above we use the command
1048 @code{\autoBeamOff} to turn off the automatic beaming.
1050 Let us reuse the earlier example from Judas Maccabæus to
1051 illustrate this more flexible technique. We first recast
1052 it to use variables so the music and lyrics can be separated
1053 from the staff structure. We also introduce a ChoirStaff
1054 bracket. The lyrics themselves must be introduced with
1055 @code{\lyricmode} to ensure they are interpreted as lyrics
1058 @lilypond[quote,verbatim]
1059 global = { \time 6/8 \partial 8 \key f \major}
1060 SopOneMusic = \relative c'' {
1061 c8 | c([ bes)] a a([ g)] f | f'4. b, | c4.~ c4 }
1062 SopTwoMusic = \relative c' {
1063 r8 | r4. r4 c8 | a'([ g)] f f([ e)] d | e([ d)] c bes' }
1064 SopOneLyrics = \lyricmode {
1065 Let | flee -- cy flocks the | hills a -- dorn, __ }
1066 SopTwoLyrics = \lyricmode {
1067 Let | flee -- cy flocks the | hills a -- dorn, }
1072 \new Voice = "SopOne" {
1076 \new Lyrics \lyricsto "SopOne" {
1081 \new Voice = "SopTwo" {
1084 \new Lyrics \lyricsto "SopTwo" {
1092 This is the basic structure of all vocal scores. More staves may
1093 be added as required, more voices may be added to the staves,
1094 more verses may be added to the lyrics,
1095 and the variables containing the music can easily be placed
1096 in separate files should they become too long.
1098 Here is a final example of the first line of a hymn with four
1099 verses, set for SATB. In this case the words for all four
1102 @lilypond[quote,verbatim]
1103 TimeKey = { \time 4/4 \partial 4 \key c \major}
1104 SopMusic = \relative c' { c4 | e4. e8 g4 g | a a g }
1105 AltoMusic = \relative c' { c4 | c4. c8 e4 e | f f e }
1106 TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 }
1107 BassMusic = \relative c { c4 | c4. c8 c4 c | f8 g a b c4 }
1108 VerseOne = \lyricmode {
1109 E -- | ter -- nal fa -- ther, | strong to save, }
1110 VerseTwo = \lyricmode {
1111 O | Christ, whose voice the | wa -- ters heard, }
1112 VerseThree = \lyricmode {
1113 O | Ho -- ly Spi -- rit, | who didst brood }
1114 VerseFour = \lyricmode {
1115 O | Tri -- ni -- ty of | love and pow'r }
1121 \new Voice = "Sop" { \voiceOne \TimeKey \SopMusic }
1122 \new Voice = "Alto" { \voiceTwo \AltoMusic }
1123 \new Lyrics \lyricsto "Sop" { \VerseOne }
1124 \new Lyrics \lyricsto "Sop" { \VerseTwo }
1125 \new Lyrics \lyricsto "Sop" { \VerseThree }
1126 \new Lyrics \lyricsto "Sop" { \VerseFour }
1130 \new Voice = "Tenor" { \voiceOne \TenorMusic }
1131 \new Voice = "Bass" { \voiceTwo \BassMusic }
1137 @node Contexts and engravers
1138 @section Contexts and engravers
1140 Contexts and engravers have been mentioned informally
1141 in earlier sections; we now must look at
1142 these concepts in more detail, as they are important
1143 in the fine-tuning of LilyPond output.
1147 * Contexts explained::
1148 * Creating contexts::
1149 * Engravers explained::
1150 * Modifying context properties::
1151 * Adding and removing engravers::
1154 @node Contexts explained
1155 @subsection Contexts explained
1157 When music is printed, many notational elements which do not
1158 appear explicitly in the input file must be added to the
1159 output. For example, compare the input and output of the
1162 @lilypond[quote,verbatim,relative=2,fragment]
1166 The input is rather sparse, but in the output, bar lines,
1167 accidentals, clef, and time signature have been added. When
1168 LilyPond @emph{interprets} the input the musical information
1169 is inspected in time order, similar to reading a score from left
1170 to right. While reading the input, the program remembers where
1171 measure boundaries are, and which pitches require explicit
1172 accidentals. This information must be held on several levels.
1173 For example, the effect of an accidental is limited
1174 to a single staff, while a bar line must be synchronized across
1177 Within LilyPond, these rules and bits of information are grouped
1178 in @emph{Contexts}. We have already met the
1179 @code{Voice} context.
1180 Others are the @code{Staff} and @code{Score} contexts.
1181 Contexts are hierarchical to reflect the heirarchical nature of
1183 For example: a @code{Staff} context can contain many
1184 @code{Voice} contexts, and a @code{Score} context can
1185 contain many @code{Staff} contexts.
1188 @image{context-example,5cm,,}
1191 Each context has the responsibility for enforcing some notation rules,
1192 creating some notation objects and maintaining the associated
1193 properties. For example, the @code{Voice} context may introduce an
1194 accidental and then the @code{Staff} context maintains the rule to
1195 show or suppress the accidental for the remainder of the measure.
1197 As another example, the synchronization of bar lines is, by default,
1198 handled in the @code{Score} context.
1199 However, in some music we may not want the bar lines to be
1200 synchronized -- consider a polymetric score in 4/4 and 3/4 time.
1201 In such cases, we must modify the default settings of the
1202 @code{Score} and @code{Staff} contexts.
1204 For very simple scores, contexts are created implicitly, and you need
1205 not be aware of them. For larger pieces, such as anything with more
1206 than one staff, they must be
1207 created explicitly to make sure that you get as many staves as you
1208 need, and that they are in the correct order. For typesetting pieces
1209 with specialized notation, it is usual to modify existing, or
1210 even to define totally new, contexts.
1212 In addition to the @code{Score,} @code{Staff} and
1213 @code{Voice} contexts there are contexts which fit between
1214 the score and staff levels to control staff groups, such as the
1215 @code{PianoStaff} and @code{ChoirStaff} contexts. There
1216 are also alternative staff and voice contexts, and contexts for
1217 lyrics, percussion, fret boards, figured bass, etc. A complete
1218 list is shown in the Notation Reference.
1221 The names of all context types are formed from one or more
1222 words, each word being capitalised and joined immediately to the
1223 preceding word with no hyphen or underscore, e.g.,
1224 @code{GregorianTranscriptionStaff}.
1226 @node Creating contexts
1227 @subsection Creating contexts
1229 There can be only one top level context: the
1231 context. This is created with the @code{\score} command,
1232 or, in simple scores, it is created automatically.
1234 For scores with only one voice and one staff, the
1235 @code{Voice} and @code{Staff} contexts may be left to be
1236 created automatically, but for more complex scores it is
1237 necessary to create them by hand.
1238 The simplest command that does this is @code{\new}.
1239 It is prepended to a music expression, for example
1242 @cindex new contexts
1243 @cindex Context, creating
1246 \new @var{type} @var{music-expression}
1250 where @var{type} is a context name (like @code{Staff} or
1251 @code{Voice}). This command creates a new context, and starts
1252 interpreting the @var{music-expression} within that context.
1254 Note that there is no @code{\new Score} command;
1255 the single top-level @code{Score} context is introduced
1258 The @code{\new} command may also give a identifying name to the
1259 context to distinguish it from other contexts of the same type,
1262 \new @var{type} = @var{id} @var{music-expression}
1265 Note the distinction between the name of the context type,
1266 @code{Staff}, @code{Voice}, etc, and
1267 the identifying name of a particular instance of that type,
1268 which can be any sequence of letters invented by the user.
1269 The identifying name is used to refer back to that particular
1270 instance of a context. We saw this in use in the section on
1271 lyrics in @ref{Voices and vocals}.
1274 @node Engravers explained
1275 @subsection Engravers explained
1279 Every mark on the printed output of a score produced by LilyPond
1280 is produced by an @code{Engraver}. Thus there is an engraver
1281 to print staves, one to print note heads, one for stems, one for
1282 beams, etc, etc. In total there are over 120 such engravers!
1283 Fortunately, for most scores it is not necessary to know about
1284 more than a few, and for simple scores you do not need to know
1287 Engravers live and operate in Contexts.
1288 Engravers such as the @code{Metronome_mark_engraver}, whose
1289 action and output applies to the score as a whole, operate in
1290 the highest level context -- the @code{Score} context.
1292 The @code{Clef_engraver} and @code{Key_engraver} are to be
1293 found in every Staff Context, as different staves may require
1294 different clefs and keys.
1296 The @code{Note_heads_engraver} and @code{Stem_engraver} live
1297 in every @code{Voice} context, the lowest level context of all.
1299 Each engraver processes the particular objects associated
1300 with its function, and maintains the properties that relate
1301 to that function. These properties, like the properties
1302 associated with contexts, may be modified to change the
1303 operation of the engraver or the appearance of those elements
1304 in the printed score.
1306 Engravers all have compound names formed from words which
1307 describe their function. Just the first word is capitalised,
1308 and the remainder are joined to it with underscores. Thus
1309 the @code{Staff_symbol_engraver} is responsible for creating the
1310 lines of the staff, the @code{Clef_engraver} determines and sets
1311 the pitch reference point on the staff by drawing a clef symbol.
1313 Here are some of the most common engravers together with their
1314 function. You will see it is easy to guess the function from
1315 the name, or vice versa.
1317 @multitable @columnfractions .3 .7
1320 @item Accidental_engraver
1321 @tab Makes accidentals, cautionary and suggested accidentals
1326 @item Dynamic_engraver
1327 @tab Creates hairpins and dynamic texts
1329 @tab Creates the key signature
1330 @item Metronome_mark_engraver
1331 @tab Engraves metronome marking
1332 @item Note_heads_engraver
1333 @tab Engraves note heads
1336 @item Staff_symbol_engraver
1337 @tab Engraves the five (by default) lines of the staff
1339 @tab Creates stems and single-stem tremulos
1340 @item Time_signature_engraver
1341 @tab Creates time signatures
1346 We shall see later how the output of LilyPond can be changed
1347 by modifying the action of Engravers.
1350 @node Modifying context properties
1351 @subsection Modifying context properties
1353 @cindex context properties
1357 Contexts are responsible for holding the values of a number of
1358 context @emph{properties}. Many of them can be changed to
1359 influence the interpretation of the input and so change the
1360 appearance of the output. They are changed by the
1361 @code{\set} command. This takes the form
1364 \set @emph{ContextName}.@emph{propertyName} = #@emph{value}
1367 Where the @emph{ContextName} is usually @code{Score},
1368 @code{Staff} or @code{Voice}. It may be omitted,
1369 in which case @code{Voice} is assumed.
1371 The names of context properties consist of words joined
1372 together with no hyphens or underscores, all except the
1373 first having a capital letter. Here are a few examples
1374 of some commonly used ones. There are many more.
1376 @c attempt to force this onto a new page
1378 @multitable @columnfractions .25 .15 .45 .15
1379 @headitem propertyName
1385 @tab If true, set extra natural signs before accidentals
1386 @tab @code{#t}, @code{#f}
1387 @item currentBarNumber
1389 @tab Set the current bar number
1393 @tab If true, print slurs both above and below notes
1394 @tab @code{#t}, @code{#f}
1395 @item instrumentName
1397 @tab Set the name to be placed at the start of the staff
1398 @tab @code{"Cello I"}
1401 @tab Increase or decrease the font size
1405 @tab Set the text to print before the start of a verse
1410 where a Boolean is either True (@code{#t}) or False (@code{#f}),
1411 an Integer is a positive whole number, a Real is a positive
1412 or negative decimal number, and text is enclosed in double
1413 apostrophes. Note the occurrence of hash signs,
1414 (@code{#}), in two different places -- as part of the Boolean
1415 value before the @code{t} or @code{f}, and before @emph{value}
1416 in the @code{\set} statement. So when a Boolean is being
1417 entered you need to code two hash signs, e.g., @code{##t}.
1419 Before we can set any of these properties we need to know
1420 in which context they operate. Sometimes this is obvious,
1421 but occasionally it can be tricky. If the wrong context
1422 is specified, no error message is produced, but the expected
1423 action will not take place. For example, the
1424 @code{instrumentName} clearly lives in the Staff context, since
1425 it is the staff that is to be named.
1426 In this example the first staff is labelled, but not the second,
1427 because we omitted the context name.
1429 @lilypond[quote,verbatim,ragged-right]
1431 \new Staff \relative c'' {
1432 \set Staff.instrumentName = "Soprano"
1435 \new Staff \relative c' {
1436 \set instrumentName = "Alto" % Wrong!
1442 Remember the default context name is Voice, so the second
1443 @code{\set} command set the property @code{instrumentName} in the
1444 Voice context to @qq{Alto}, but as LilyPond does not look
1445 for any such property in the @code{Voice} context, no
1446 further action took place. This is not an error, and no error
1447 message is logged in the log file.
1449 Similarly, if the property name is mis-spelt no error message
1450 is produced, and clearly the expected action cannot be performed.
1451 If fact, you can set any (fictitious) @q{property} using any
1452 name you like in any context that exists by using the
1453 @code{\set} command. But if the name is not
1454 known to LilyPond it will not cause any action to be taken.
1455 This is one of the reasons why it is highly recommended to
1456 use a context-sensitive editor with syntax highlighting for
1457 editing LilyPond files, such as Vim, Jedit, ConTEXT or Emacs,
1458 since unknown property names will be highlighted differently.
1460 The @code{instrumentName} property will take effect only
1461 if it is set in the @code{Staff} context, but
1462 some properties can be set in more than one context.
1463 For example, the property @code{extraNatural} is by
1464 default set to ##t (true) for all staves.
1465 If it is set to ##f (false) in the @code{Staff} context
1466 it applies just to the accidentals on that staff.
1467 If it is set to false in the @code{Score} context
1468 it applies to all staves.
1470 So this turns off extra naturals in one staff:
1472 @lilypond[quote,verbatim,ragged-right]
1474 \new Staff \relative c'' {
1477 \new Staff \relative c'' {
1478 \set Staff.extraNatural = ##f
1485 and this turns them off in all staves:
1487 @lilypond[quote,verbatim,ragged-right]
1489 \new Staff \relative c'' {
1492 \new Staff \relative c'' {
1493 \set Score.extraNatural = ##f
1499 The value of every property set in this way can be reset
1500 to its original value with the @code{\unset} command.
1502 The @code{\set} and @code{\unset} commands can appear anywhere
1503 in the input file and will take effect from the time they are
1504 encountered until the end of the score or until the property is
1505 @code{\set} or @code{\unset} again. Let's try changing the
1506 font size, which affects the size of the note heads (among
1507 other things) several times.
1509 @lilypond[quote,verbatim,ragged-right,relative=1,fragment]
1511 % make note heads smaller
1514 % make note heads larger
1515 \set fontSize = #2.5
1517 % return to original size
1522 We have now seen how to set the values of several different
1523 types of property. Note that integers and numbers are alway
1524 preceded by a hash sign, @code{#}, while a true or false value
1525 is specified by ##t and ##f, with two hash signs. A text
1526 property should be enclosed in double quotation signs, as above,
1527 although we shall see later that text can actually be specified
1528 in a much more general way by using the very powerful
1529 @code{markup} command.
1534 Context properties may also be set at the time the context is
1535 created. Sometimes this is a clearer way of specifying a
1536 property value if it is to remain fixed for the duration of
1537 the context. When a context is created with a @code{\new}
1538 command it may be followed immediately by a
1539 @code{\with @{ .. @}} block in which the property values are
1540 set. For example, if we wish to suppress the printing of
1541 extra naturals for the duration of a staff we would write:
1544 \new Staff \with @{ extraNatural = ##f @}
1550 @lilypond[quote,verbatim,ragged-right]
1556 \new Staff \with { extraNatural = ##f }
1563 In effect this overrides the default value of the property. It
1564 may still be changed dynamically using @code{\set} and returned
1565 to its (new) default value with @code{\unset}.
1567 @node Adding and removing engravers
1568 @subsection Adding and removing engravers
1570 @cindex Engravers, adding
1571 @cindex Engravers, removing
1576 We have seen that contexts each contain several engravers, each
1577 of which is responsible for producing a particular part of the
1578 output, like bar lines, staves, note heads, stems, etc. If an
1579 engraver is removed from a context it can no longer produce its
1580 output. This is a crude way of modifying the output, but it
1581 can sometimes be useful.
1583 @unnumberedsubsubsec Changing a single context
1585 To remove an engraver from a single context we use the
1586 @code{\with} command placed immediately after the context creation
1587 command, as in the previous section.
1590 illustration let's repeat an example from the previous
1591 section with the staff lines removed. Remember that the
1592 staff lines are produced by the Staff_symbol_engraver.
1594 @lilypond[quote,verbatim,ragged-right]
1596 \remove Staff_symbol_engraver
1600 \set fontSize = #-4 % make note heads smaller
1602 \set fontSize = #2.5 % make note heads larger
1604 \unset fontSize % return to original size
1609 @cindex ambitus engraver
1611 Engravers can also be added to individual contexts.
1612 The command to do this is
1614 @code{\consists @emph{Engraver_name}},
1616 placed inside a @code{\with} block. Some vocal scores
1617 have an @rglos{ambitus} placed at the beginning of a
1618 staff to indicate the range of notes in that staff.
1619 The ambitus is produced by the @code{Ambitus_engraver},
1620 which is not normally included in any context. If
1621 we add it to the @code{Voice} context it calculates
1622 the range from that voice only:
1624 @lilypond[quote,verbatim,ragged-right]
1627 \consists Ambitus_engraver
1642 but if we add the Ambitus engraver to the
1643 @code{Staff} context it calculates the range from all
1644 the notes in all the voices on that staff:
1646 @lilypond[quote,verbatim,ragged-right]
1648 \consists Ambitus_engraver
1664 @unnumberedsubsubsec Changing all contexts of the same type
1666 The examples above show how to remove or add engravers to
1667 individual contexts. It is also possible to remove or add
1668 engravers to every context of a specific type by placing the
1669 commands in the appropriate context in a @code{\layout}
1670 block. For example, If we wanted to show ambiti for every
1671 staff in a four-staff score we could write
1673 @lilypond[quote,verbatim,ragged-right]
1677 \relative c'' { c a b g }
1680 \relative c' { c a b g }
1684 \relative c' { c a b g }
1688 \relative c { c a b g }
1694 \consists Ambitus_engraver
1701 The default values of context properties may also be set
1702 for all contexts of a particular type by including the
1703 @code{\set} command in a @code{\context} block in the
1706 @node Extending the templates
1707 @section Extending the templates
1709 You've read the tutorial, you know how to write music, you
1710 understand the fundamental concepts. But how can you
1711 get the staves that you want? Well, you can find lots of
1712 templates (see @ref{Templates}) which may give you a start.
1714 if you want something that isn't covered there? Read on.
1716 TODO Add links to templates after they have been moved to LSR
1719 * Soprano and cello::
1720 * Four-part SATB vocal score::
1721 * Building a score from scratch::
1724 @node Soprano and cello
1725 @subsection Soprano and cello
1727 Start off with the template that seems closest to what you want to end
1728 up with. Let's say that you want to write something for soprano and
1729 cello. In this case, we would start with @q{Notes and lyrics} (for the
1734 melody = \relative c' @{
1742 text = \lyricmode @{
1748 \new Voice = "one" @{
1752 \new Lyrics \lyricsto "one" \text
1759 Now we want to add a cello part. Let's look at the @q{Notes only} example:
1763 melody = \relative c' @{
1778 We don't need two @code{\version} commands. We'll need the @code{melody}
1779 section. We don't want two @code{\score} sections -- if we had two
1780 @code{\score}s, we'd get the two parts separately. We want them together,
1781 as a duet. Within the @code{\score} section, we don't need two
1782 @code{\layout} or @code{\midi}.
1784 If we simply cut and paste the @code{melody} section, we would end up with
1785 two @code{melody} sections. So let's rename them. We'll call the section
1786 for the soprano @code{sopranoMusic} and the section for the cello
1787 @code{celloMusic}. While we're doing this, let's rename @code{text}
1788 to be @code{sopranoLyrics}. Remember to rename both instances of all
1789 these names -- both the initial definition (the
1790 @code{melody = relative c' @{ } part) and the name's use (in the
1791 @code{\score} section).
1793 While we're doing this, let's change the cello part's staff -- celli
1794 normally use bass clef. We'll also give the cello some different
1799 sopranoMusic = \relative c' @{
1807 sopranoLyrics = \lyricmode @{
1811 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' {
1878 sopranoLyrics = \lyricmode {
1882 celloMusic = \relative c {
1893 \new Voice = "one" {
1897 \new Lyrics \lyricsto "one" \sopranoLyrics
1899 \new Staff \celloMusic
1907 @node Four-part SATB vocal score
1908 @subsection Four-part SATB vocal score
1910 Most vocal scores of music written for four-part mixed choir
1911 with orchestral accompaniment such as Mendelssohn's Elijah or
1912 Handel's Messiah have the choral music and words on four
1913 staves, one for each of SATB, with a piano reduction of the
1914 orchestral accompaniment underneath. Here's an example
1915 from Handel's Messiah:
1917 @c The following should appear as music without code
1918 @lilypond[quote,ragged-right]
1920 global = { \key d \major \time 4/4 }
1921 sopMusic = \relative c'' {
1923 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
1925 sopWords = \lyricmode {
1926 Wor -- thy is the lamb that was slain
1928 altoMusic = \relative a' {
1930 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
1932 altoWords = \sopWords
1933 tenorMusic = \relative c' {
1935 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
1937 tenorWords = \sopWords
1938 bassMusic = \relative c' {
1940 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
1942 bassWords = \sopWords
1943 upper = \relative a' {
1946 r4 <a d fis>2 <a e' a>4 |
1947 <d fis d'>4. <d fis d'>8 <a d a'>2 |
1948 <g cis g'>4 <a d fis> <a cis e>2 |
1950 lower = \relative c, {
1953 <d d'>4 <d d'>2 <cis cis'>4 |
1954 <b b'>4. <b' b'>8 <fis fis'>2 |
1955 <e e'>4 <d d'> <a' a'>2 |
1959 << % combine ChoirStaff and PianoStaff in parallel
1961 \new Staff = "sopranos" <<
1962 \set Staff.instrumentName = "Soprano"
1963 \new Voice = "sopranos" { \global \sopMusic }
1965 \new Lyrics \lyricsto "sopranos" { \sopWords }
1966 \new Staff = "altos" <<
1967 \set Staff.instrumentName = "Alto"
1968 \new Voice = "altos" { \global \altoMusic }
1970 \new Lyrics \lyricsto "altos" { \altoWords }
1971 \new Staff = "tenors" <<
1972 \set Staff.instrumentName = "Tenor"
1973 \new Voice = "tenors" { \global \tenorMusic }
1975 \new Lyrics \lyricsto "tenors" { \tenorWords }
1976 \new Staff = "basses" <<
1977 \set Staff.instrumentName = "Bass"
1978 \new Voice = "basses" { \global \bassMusic }
1980 \new Lyrics \lyricsto "basses" { \bassWords }
1984 \set PianoStaff.instrumentName = "Piano "
1985 \new Staff = "upper" \upper
1986 \new Staff = "lower" \lower
1992 None of the templates provides this layout exactly. The
1993 nearest is @q{SATB vocal score and automatic piano reduction},
1994 but we need to change the layout and add a piano
1995 accompaniment which is not derived automatically from the
1996 vocal parts. The variables holding the music and words for
1997 the vocal parts are fine, but we shall need to add variables for
1998 the piano reduction.
2000 The order in which the contexts appear in the ChoirStaff of
2001 the template do not correspond with the order in the vocal
2002 score shown above. We need to rearrange them so there are
2003 four staves with the words written directly underneath the
2004 notes for each part.
2005 All the voices should be @code{\voiceOne}, which is
2006 the default, so the @code{\voiceXXX} commands should be removed.
2007 We also need to specify the tenor clef for the tenors.
2008 The way in which lyrics are specified in the template has not yet
2009 been encountered so we need to use the method with which we are
2010 familiar. We should also add the names of each staff.
2012 Doing this gives for our ChoirStaff:
2016 \new Staff = "sopranos" <<
2017 \set Staff.instrumentName = "Soprano"
2018 \new Voice = "sopranos" @{ \global \sopMusic @}
2020 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
2021 \new Staff = "altos" <<
2022 \set Staff.instrumentName = "Alto"
2023 \new Voice = "altos" @{ \global \altoMusic @}
2025 \new Lyrics \lyricsto "altos" @{ \altoWords @}
2026 \new Staff = "tenors" <<
2027 \set Staff.instrumentName = "Tenor"
2028 \new Voice = "tenors" @{ \global \tenorMusic @}
2030 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
2031 \new Staff = "basses" <<
2032 \set Staff.instrumentName = "Bass"
2033 \new Voice = "basses" @{ \global \bassMusic @}
2035 \new Lyrics \lyricsto "basses" @{ \bassWords @}
2039 Next we must work out the piano part. This is
2040 easy - we just pull out the piano part from the
2041 @q{Solo piano} template:
2045 \set PianoStaff.instrumentName = "Piano "
2046 \new Staff = "upper" \upper
2047 \new Staff = "lower" \lower
2051 and add the variable definitions for @code{upper}
2054 The ChoirStaff and PianoStaff must be combined
2055 using angle brackets as we want them to be
2056 stacked one above the other:
2059 << % combine ChoirStaff and PianoStaff one above the other
2061 \new Staff = "sopranos" <<
2062 \new Voice = "sopranos" @{ \global \sopMusic @}
2064 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
2065 \new Staff = "altos" <<
2066 \new Voice = "altos" @{ \global \altoMusic @}
2068 \new Lyrics \lyricsto "altos" @{ \altoWords @}
2069 \new Staff = "tenors" <<
2070 \clef "G_8" % tenor clef
2071 \new Voice = "tenors" @{ \global \tenorMusic @}
2073 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
2074 \new Staff = "basses" <<
2076 \new Voice = "basses" @{ \global \bassMusic @}
2078 \new Lyrics \lyricsto "basses" @{ bassWords @}
2082 \set PianoStaff.instrumentName = "Piano "
2083 \new Staff = "upper" \upper
2084 \new Staff = "lower" \lower
2089 Combining all these together and adding the music
2090 for the three bars of the example above gives:
2092 @lilypond[quote,verbatim,ragged-right]
2094 global = { \key d \major \time 4/4 }
2095 sopMusic = \relative c'' {
2097 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
2099 sopWords = \lyricmode {
2100 Wor -- thy is the lamb that was slain
2102 altoMusic = \relative a' {
2104 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
2106 altoWords = \sopWords
2107 tenorMusic = \relative c' {
2109 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
2111 tenorWords = \sopWords
2112 bassMusic = \relative c' {
2114 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
2116 bassWords = \sopWords
2117 upper = \relative a' {
2120 r4 <a d fis>2 <a e' a>4 |
2121 <d fis d'>4. <d fis d'>8 <a d a'>2 |
2122 <g cis g'>4 <a d fis> <a cis e>2 |
2124 lower = \relative c, {
2127 <d d'>4 <d d'>2 <cis cis'>4 |
2128 <b b'>4. <b' b'>8 <fis fis'>2 |
2129 <e e'>4 <d d'> <a' a'>2 |
2133 << % combine ChoirStaff and PianoStaff in parallel
2135 \new Staff = "sopranos" <<
2136 \set Staff.instrumentName = "Soprano"
2137 \new Voice = "sopranos" { \global \sopMusic }
2139 \new Lyrics \lyricsto "sopranos" { \sopWords }
2140 \new Staff = "altos" <<
2141 \set Staff.instrumentName = "Alto"
2142 \new Voice = "altos" { \global \altoMusic }
2144 \new Lyrics \lyricsto "altos" { \altoWords }
2145 \new Staff = "tenors" <<
2146 \set Staff.instrumentName = "Tenor"
2147 \new Voice = "tenors" { \global \tenorMusic }
2149 \new Lyrics \lyricsto "tenors" { \tenorWords }
2150 \new Staff = "basses" <<
2151 \set Staff.instrumentName = "Bass"
2152 \new Voice = "basses" { \global \bassMusic }
2154 \new Lyrics \lyricsto "basses" { \bassWords }
2158 \set PianoStaff.instrumentName = "Piano "
2159 \new Staff = "upper" \upper
2160 \new Staff = "lower" \lower
2167 @node Building a score from scratch
2168 @subsection Building a score from scratch
2170 After gaining some facility with writing LilyPond code you
2171 may find that it is easier to build a score from scratch
2172 rather than modifying one of the templates. You can also
2173 develop your own style this way to suit the sort of music you
2174 like. Let's see how to put together the score for an organ
2175 prelude as an example.
2177 We begin with a header section. Here go the title, name
2178 of composer, etc, then come any variable definitions, and
2179 finally the score block. Let's start with these in outline
2180 and fill in the details later.
2182 We'll use the first two bars of Bach's prelude
2183 based on @emph{Jesu, meine Freude} which is written for two
2184 manuals and pedal organ. You can see these two bars of music
2185 at the bottom of this section. The top manual part has two voices,
2186 the lower and pedal organ one each. So we need four
2187 music definitions and one to define the time signature
2193 title = "Jesu, meine Freude"
2194 composer = "J S Bach"
2196 TimeKey = @{ \time 4/4 \key c \minor @}
2197 ManualOneVoiceOneMusic = @{s1@}
2198 ManualOneVoiceTwoMusic = @{s1@}
2199 ManualTwoMusic = @{s1@}
2200 PedalOrganMusic = @{s1@}
2206 For now we've just used a spacer note, @code{s1},
2207 instead of the real music. We'll add that later.
2209 Next let's see what should go in the score block.
2210 We simply mirror the staff structure we want.
2211 Organ music is usually written on three staves,
2212 one for each manual and one for the pedals. The
2213 manual staves should be bracketed together so we
2214 need to use a PianoStaff for them. The first
2215 manual part needs two voices and the second manual
2220 \new Staff = "ManualOne" <<
2221 \new Voice @{ \ManualOneVoiceOneMusic @}
2222 \new Voice @{ \ManualOneVoiceTwoMusic @}
2223 >> % end ManualOne Staff context
2224 \new Staff = "ManualTwo" <<
2225 \new Voice @{ \ManualTwoMusic @}
2226 >> % end ManualTwo Staff context
2227 >> % end PianoStaff context
2230 Next we need to add a staff for the pedal organ.
2231 This goes underneath the PianoStaff, but it must
2232 be simultaneous with it, so we need angle brackets
2233 round the two. Missing these out would generate
2234 an error in the log file. It's a common mistake
2235 which you'll make sooner or later! Try copying
2236 the final example at the end of this section,
2237 remove these angle brackets, and compile it to
2238 see what errors it generates.
2241 << % PianoStaff and Pedal Staff must be simultaneous
2243 \new Staff = "ManualOne" <<
2244 \new Voice @{ \ManualOneVoiceOneMusic @}
2245 \new Voice @{ \ManualOneVoiceTwoMusic @}
2246 >> % end ManualOne Staff context
2247 \new Staff = "ManualTwo" <<
2248 \new Voice @{ \ManualTwoMusic @}
2249 >> % end ManualTwo Staff context
2250 >> % end PianoStaff context
2251 \new Staff = "PedalOrgan" <<
2252 \new Voice @{ \PedalOrganMusic @}
2257 It is not strictly necessary to use the simultaneous construct
2258 @code{<< >>} for the manual two staff and the pedal organ staff,
2259 since they contain only one music expression, but it does no harm
2260 and always using angle brackets after @code{\new Staff} is a good
2261 habit to cultivate in case there are multiple voices.
2263 Let's add this structure to the score block, and adjust the
2264 indenting. We also add the appropriate clefs, ensure the
2265 second voice stems point down with @code{\voiceTwo} and
2266 enter the time signature and key to each staff using our
2267 predefined variable, @code{\TimeKey}.
2271 << % PianoStaff and Pedal Staff must be simultaneous
2273 \new Staff = "ManualOne" <<
2274 \TimeKey % set time signature and key
2276 \new Voice @{ \ManualOneVoiceOneMusic @}
2277 \new Voice @{ \voiceTwo \ManualOneVoiceTwoMusic @}
2278 >> % end ManualOne Staff context
2279 \new Staff = "ManualTwo" <<
2282 \new Voice @{ \ManualTwoMusic @}
2283 >> % end ManualTwo Staff context
2284 >> % end PianoStaff context
2285 \new Staff = "PedalOrgan" <<
2288 \new Voice @{ \PedalOrganMusic @}
2289 >> % end PedalOrgan Staff
2291 @} % end Score context
2294 That completes the structure. Any three-staff organ music
2295 will have a similar structure, although the number of voices
2296 may vary. All that remains now
2297 is to add the music, and combine all the parts together.
2299 @lilypond[quote,verbatim,ragged-right]
2302 title = "Jesu, meine Freude"
2303 composer = "J S Bach"
2305 TimeKey = { \time 4/4 \key c \minor }
2306 ManualOneVoiceOneMusic = \relative g' {
2307 g4 g f ees | d2 c2 |
2309 ManualOneVoiceTwoMusic = \relative c' {
2310 ees16 d ees8~ ees16 f ees s c8 d~ d c~ |
2311 c c4 b8 c8. g16 c b c d |
2313 ManualTwoMusic = \relative c' {
2314 c16 b c8~ c16 b c g a8 g~ g16 g aes ees |
2315 f ees f d g aes g f ees d e8~ ees16 f ees d |
2317 PedalOrganMusic = \relative c {
2318 r8 c16 d ees d ees8~ ees16 a, b g c b c8 |
2319 r16 g ees f g f g8 c,2 |
2323 << % PianoStaff and Pedal Staff must be simultaneous
2325 \new Staff = "ManualOne" <<
2326 \TimeKey % set time signature and key
2328 \new Voice { \ManualOneVoiceOneMusic }
2329 \new Voice { \voiceTwo \ManualOneVoiceTwoMusic }
2330 >> % end ManualOne Staff context
2331 \new Staff = "ManualTwo" <<
2334 \new Voice { \ManualTwoMusic }
2335 >> % end ManualTwo Staff context
2336 >> % end PianoStaff context
2337 \new Staff = "PedalOrgan" <<
2340 \new Voice { \PedalOrganMusic }
2341 >> % end PedalOrgan Staff
2343 } % end Score context