1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond-learning.tely
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
12 @node Fundamental concepts
13 @chapter Fundamental concepts
15 You've seen in the Tutorial how to produce beautifully printed
16 music from a simple text file. This section introduces the
17 concepts and techniques required to produce equally beautiful
18 but more complex scores.
21 * How LilyPond input files work::
22 * Voices contain music::
23 * Contexts and engravers::
24 * Extending the templates::
28 @node How LilyPond input files work
29 @section How LilyPond input files work
31 The LilyPond input format is quite free-form, giving experienced
32 users a lot of flexibility to structure their files however they
33 wish. But this flexibility can make things confusing for new
34 users. This section will explain some of this structure, but may
35 gloss over some details in favor of simplicity. For a complete
36 description of the input format, see @ruser{File structure}.
39 * Introduction to the LilyPond file structure::
40 * Score is a (single) compound musical expression::
41 * Nesting music expressions::
42 * On the un-nestedness of brackets and ties::
45 @node Introduction to the LilyPond file structure
46 @subsection Introduction to the LilyPond file structure
48 A basic example of a LilyPond input file is
51 \version @w{"@version{}"}
53 @var{...compound music expression...} % all the music goes here!
61 There are many variations of this basic pattern, but this
62 example serves as a useful starting place.
64 Up to this point none of the examples you have seen has used a
65 @code{\score@{@}} command. This is because LilyPond automatically
66 adds the extra commands which are needed when you give it simple
67 input. LilyPond treats input like this:
76 as shorthand for this:
93 In other words, if the input contains a single music expression,
94 LilyPond will interpret the file as though the music expression
95 was wrapped up inside the commands shown above. For now, though,
96 let us return to the first example and examine the @code{\score}
97 command, leaving the others to default.
99 A @code{\score} block must always contain just one music
101 this must appear immediately after the @code{\score} command.
102 Remember that a music expression could be anything from a single
103 note to a huge compound expression like
108 @var{...insert the whole score of a Wagner opera in here...}
114 Since everything is inside @code{@{ ... @}}, it counts
115 as one music expression.
117 As we saw previously, the @code{\score} block can contain other
130 Some people put some of those commands outside the @code{\score}
131 block -- for example, @code{\header} is often placed above the
132 @code{\score} command. That's just another shorthand that LilyPond
135 Two more commands you have not previously seen are
136 @code{\layout @{ @}} and @code{\midi @{@}}. If these appear as
137 shown they will cause LilyPond to produce a printed output and a
138 MIDI output respectively. They are described fully in the
139 Notation Reference -- @ruser{Score layout} and
140 @ruser{Creating MIDI files}.
142 You may code multiple @code{\score} blocks. Each will be
143 treated as a separate score, but they will be all combined into
144 a single output file. A @code{\book} command is not necessary
145 -- one will be implicitly created. However, if you would like
146 separate output files from one @code{.ly} file then the
147 @code{\book} command should be used to separate the different
148 sections: each @code{\book} block will produce a
149 separate output file. For details see @ruser{Multiple scores
154 Another great shorthand is the ability to define variables. All
155 the templates use this
158 melody = \relative c' @{
167 When LilyPond looks at this file, it takes the value of
168 @code{melody} (everything after the equals sign) and inserts it
169 whenever it sees @code{\melody}. There's nothing special about
170 the names -- it could be @code{melody}, @code{global},
172 @code{pianorighthand}, or @code{foofoobarbaz}. For more details,
173 see @ref{Saving typing with variables and functions}.
174 Remember that you can use almost any name you like as long
175 as it contains just alphabetic characters and is distinct from
176 LilyPond command names. The exact
177 limitations on variable names are detailed in
178 @ruser{File structure}.
184 For a complete definition of the input format, see
185 @ruser{File structure}.
187 @node Score is a (single) compound musical expression
188 @subsection Score is a (single) compound musical expression
190 @cindex Compound music expression
191 @cindex Music expression, compound
193 We saw the general organization of LilyPond input files in the
194 previous section, @ref{How LilyPond input files work}. But we seemed to
195 skip over the most important part: how do we figure out what to
196 write after @code{\score}?
198 We didn't skip over it at all. The big mystery is simply that
199 there @emph{is} no mystery. This line explains it all:
202 @emph{A @code{\score} block must begin with a compound music expression.}
206 You may find it useful to review
207 @ref{Music expressions explained}. In that section, we saw how to
208 build big music expressions from small pieces -- we started from
209 notes, then chords, etc. Now we're going to start from a big
210 music expression and work our way down.
214 @{ % this brace begins the overall compound music expression
216 @var{...insert the whole score of a Wagner opera in here...}
218 @} % this brace ends the overall compound music expression
223 A whole Wagner opera would easily double the length of this
224 manual, so let's just add a singer and piano. We don't need a
225 @code{GrandStaff} for this ensemble, which simply groups a number
226 of staves together with a brace at the left, so we shall remove
227 it. We @emph{do} need a singer and a piano, though.
232 \new Staff = "singer" <<
234 \new PianoStaff = piano <<
241 Remember that we use @code{<< ... >>} instead of
242 @code{@{ ... @}} to show simultaneous
243 music. And we definitely want to show the vocal part and piano
244 part at the same time, not one after the other! However, the
245 @code{<< ... >>} construct is not really necessary for the Singer
246 staff, as it contains only one music expression, but Staves often
247 do require simultaneous Voices within them, so using
249 rather than braces is a good habit to adopt. We'll add some real
250 music later; for now let's just put in some dummy notes and lyrics.
252 @lilypond[verbatim,quote,ragged-right]
255 \new Staff = "singer" <<
256 \new Voice = "vocal" { c'1 }
259 \new PianoStaff = "piano" <<
260 \new Staff = "upper" { c'1 }
261 \new Staff = "lower" { c'1 }
268 Now we have a lot more details. We have the singer's staff: it
269 contains a @code{Voice} (in LilyPond, this term refers to a set of
270 notes, not necessarily vocal notes -- for example, a violin
271 generally plays one voice) and some lyrics. We also have a piano
272 staff: it contains an upper staff (right hand) and a lower staff
275 At this stage, we could start filling in notes. Inside the curly
276 braces next to @code{\new Voice = vocal}, we could start writing
284 But if we did that, the @code{\score} section would get pretty
285 long, and it would be harder to understand what was happening. So
286 let's use variables instead. These were introduced at the end
287 of the previous section, remember? So, adding a few notes, we
288 now have a piece of real music:
290 @lilypond[verbatim,quote,ragged-right]
291 melody = \relative c'' { r4 d8\noBeam g, c4 r }
292 text = \lyricmode { And God said, }
293 upper = \relative c'' { <g d g,>2~ <g d g,> }
294 lower = \relative c { b2 e2 }
298 \new Staff = "singer" <<
299 \new Voice = "vocal" { \melody }
302 \new PianoStaff = "piano" <<
303 \new Staff = "upper" { \upper }
304 \new Staff = "lower" {
315 Be careful about the difference between notes, which are introduced
316 with @code{\relative}, and lyrics, which are introduced with
317 @code{\lyricmode}. These are essential to tell LilyPond
318 to interpret the following content as music and text
321 When writing (or reading) a @code{\score} section, just take it
322 slowly and carefully. Start with the outer layer, then work on
323 each smaller layer. It also really helps to be strict with
324 indentation -- make sure that each item on the same layer starts
325 on the same horizontal position in your text editor.
328 @node Nesting music expressions
329 @subsection Nesting music expressions
331 It is not essential to declare all staves at the beginning;
332 they may be introduced temporarily at any point. This is
333 particularly useful for creating ossia sections
334 (see @rglos{ossia}). Here is a simple example showing how
335 to introduce a new staff temporarily for the duration of
338 @lilypond[verbatim,quote,ragged-right]
355 Note that the size of the clef is the same as a clef printed
356 following a clef change -- slightly smaller than the clef
357 at the beginning of the line. This is usual for clefs printed
358 in the middle of a line.
360 The ossia section may be placed above the staff
363 @lilypond[verbatim,quote,ragged-right]
371 alignAboveContext = "main" }
379 This example uses @code{\with}, which will be explained more
380 fully later. It is a means of modifying the default behavior
381 of a single Staff. Here it says that the new staff should be
382 placed above the staff called @qq{main} instead of the default
383 position which is below.
385 Ossia are often written without clef and without
386 time signature and are usually in a smaller font.
387 These require further commands which
388 have not yet been introduced. See @ref{Size of objects}
390 @node On the un-nestedness of brackets and ties
391 @subsection On the un-nestedness of brackets and ties
393 You have already met a number of different types of bracket in
394 writing the input file to LilyPond. These obey different rules
395 which can be confusing at first. Before we explain the rules
396 let's first review the different types of bracket.
398 @c attempt to force this onto a new page
400 @multitable @columnfractions .3 .7
401 @headitem Bracket Type
403 @item @code{@{ .. @}}
404 @tab Encloses a sequential segment of music
406 @tab Encloses the notes of a chord
407 @item @code{<< .. >>}
408 @tab Encloses concurrent or simultaneous sections
410 @tab Marks the start and end of a slur
411 @item @code{\( .. \)}
412 @tab Marks the start and end of a phrase mark
414 @tab Marks the start and end of a manual beam
417 To these we should add other constructs which generate lines
418 between or across notes: ties (marked by a tilde, @code{~}),
419 tuplets written as @code{\times x/y @{..@}}, and grace notes
420 written as @code{\grace@{..@}}.
422 Outside LilyPond, the conventional use of brackets requires
423 the different types to be properly nested, like this,
424 @code{<< [ @{ ( .. ) @} ] >>}, with the closing brackets being
425 encountered in exactly the opposite order to the opening
426 brackets. This @strong{is} a requirement for the three types of
427 bracket described by the word @q{Encloses} in the table above --
428 they must nest properly.
429 However, the remaining brackets, described with the word
430 @q{Marks} in the table above together with ties and tuplets,
431 do @strong{not} have to nest
432 properly with any of the brackets. In fact, these are not
433 brackets in the sense that
434 they enclose something -- they are simply markers to indicate
435 where something starts and ends.
437 So, for example, a phrasing slur can start before a manually
438 inserted beam and end before the end of the beam -- not very
439 musical, perhaps, but possible:
441 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
442 { g8\( a b[ c b\) a] }
445 In general, different kinds of brackets, and those implied by
446 tuplets, ties and grace notes, may be mixed freely.
447 This example shows a beam extending into a tuplet (line 1),
448 a slur extending into a tuplet (line 2),
449 a beam and a slur extending into a tuplet, a tie crossing
450 two tuplets, and a phrasing slur extending out of a tuplet
453 @lilypond[quote,verbatim,fragment,ragged-right]
455 r16[ g16 \times 2/3 {r16 e'8] }
456 g16( a \times 2/3 {b d) e' }
457 g8[( a \times 2/3 {b d') e'~]}
458 \times 4/5 {e'32\( a b d' e'} a'4.\)
463 @node Voices contain music
464 @section Voices contain music
466 Singers need voices to sing, and so does LilyPond.
467 The actual music for all instruments in a score
468 is contained in Voices -- the most fundamental
469 of all LilyPond's concepts.
472 * I'm hearing Voices::
473 * Explicitly instantiating voices::
474 * Voices and vocals::
477 @node I'm hearing Voices
478 @subsection I'm hearing Voices
482 @cindex Voice context
484 The lowest, most fundamental or innermost layers in a LilyPond
485 score are called @q{Voice contexts} or just @q{Voices} for short.
486 Voices are sometimes called @q{layers} in other notation
489 In fact, a Voice layer or context is the only one which can
490 contain music. If a Voice context is not explicitly declared
491 one is created automatically, as we saw at the beginning of
492 this chapter. Some instruments such as an
493 Oboe can play only one note at a time. Music written for
494 such instruments is monophonic and requires just a single
495 voice. Instruments which can play more than one note at a
496 time like the piano will often require multiple voices to
497 encode the different concurrent notes and rhythms they are
500 A single voice can contain many notes in a chord, of course,
501 so when exactly are multiple voices needed? Look first at
502 this example of four chords:
504 @lilypond[quote,verbatim,fragment,ragged-right,relative=1]
506 <d g>4 <d fis> <d a'> <d g>
509 This can be expressed using just the single angle bracket chord
510 symbols, @code{< ... >}, and for this just a single voice is
511 needed. But suppose the F-sharp were actually an eighth-note
512 followed by an eighth-note G, a passing note on the way to the A?
513 Now we have two notes which start at the same time but have
514 different durations: the quarter-note D and the eighth-note
515 F-sharp. How are these to be coded? They cannot be written as
516 a chord because all the notes in a chord must have the same
517 duration. And they cannot be written as two separate notes
518 as they need to start at the same time. This is when two
521 Let us see how this is done in LilyPond input syntax.
526 The easiest way to enter fragments with more than one voice on a
527 staff is to enter each voice as a sequence (with @code{@{...@}}),
528 and combine them simultaneously with angle brackets, @code{<<...>>}.
529 The fragments must also be separated with double backward slashes,
530 @code{\\}, to place them in separate voices. Without these, the
531 notes would be entered into a single voice, which would usually
532 cause errors. This technique is particularly suited to pieces of
533 music which are largely monophonic with occasional short sections
536 Here's how we split the chords above into two voices and add both
537 the passing note and a slur:
539 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
541 % Voice "1" Voice "2"
542 << { g4 fis8( g) a4 g } \\ { d4 d d d } >> |
545 Notice how the stems of the second voice now point down.
547 Here's another simple example:
549 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
551 % Voice "1" Voice "2"
552 << { r4 g g4. a8 } \\ { d,2 d4 g } >> |
553 << { bes4 bes c bes } \\ { g4 g g8( a) g4 } >> |
554 << { a2. r4 } \\ { fis2. s4 } >> |
557 It is not necessary to use a separate @code{<< \\ >>} construct
558 for each bar. For music with few notes in each bar this layout
559 can help the legibility of the code, but if there are many
560 notes in each bar it may be better to split out each voice
561 separately, like this:
563 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
579 This example has just two voices, but the same construct may be
580 used to encode three or more voices by adding more back-slash
583 The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
584 In each of these contexts, the vertical direction of slurs,
585 stems, ties, dynamics etc., is set appropriately.
587 @lilypond[quote,verbatim,fragment]
588 \new Staff \relative c' {
591 % Voice "1" Voice "2" Voice "3"
592 << { g4 f e } \\ { r8 e4 d c8 ~ } >> |
593 << { d2 e2 } \\ { c8 b16 a b8 g ~ g2 } \\ { s4 b4 c2 } >> |
597 These voices are all separate from the main voice that contains
598 the notes just outside the @code{<< .. >>} construct. Let's call
599 this the @emph{simultaneous construct}. Slurs and ties may only
600 connect notes within the same voice, so slurs and ties cannot go
601 into or out of a simultaneous construct. Conversely,
602 parallel voices from separate simultaneous constructs on the same
603 staff are the same voice. Other voice-related properties also
604 carry across simultaneous constructs. Here is the same example,
605 with different colors and note heads for each voice. Note that
606 changes in one voice do not affect other voices, but they do
607 persist in the same voice later. Note also that tied notes may be
608 split across the same voices in two constructs, shown here in the
611 @lilypond[quote,verbatim]
612 \new Staff \relative c' {
631 { c8 b16 a b8 g ~ g2 }
641 The commands @code{\voiceXXXStyle} are mainly intended for use in
642 educational documents such as this one. They modify the color
643 of the note head, the stem and the beams, and the style of the
644 note head, so that the voices may be easily distinguished.
645 Voice one is set to red diamonds, voice two to blue triangles,
646 voice three to green crossed circles, and voice four (not used
647 here) to magenta crosses. We shall see later how commands like
648 these may be created by the user.
649 See @ref{Visibility and color of objects}
650 TODO Add link to using variables for tweaks
652 Polyphony does not change the relationship of notes within a
653 @code{\relative @{ @}} block. Each note is still calculated
654 relative to the note immediately preceding it, or to the first
655 note of the preceding chord. So in
658 \relative c' @{ noteA << < noteB noteC > \\ noteD >> noteE @}
662 @code{noteB} is relative to @code{noteA} @*
663 @code{noteC} is relative to @code{noteB}, not @code{noteA}; @*
664 @code{noteD} is relative to @code{noteB}, not @code{noteA} or
666 @code{noteE} is relative to @code{noteD}, not @code{noteA}
668 An alternative way, which may be clearer if the notes in the
669 voices are widely separated, is to place a @code{\relative}
670 command at the start of each voice:
673 \relative c' @{ noteA ... @}
675 \relative c'' @{ < noteB noteC > ... @}
677 \relative g' @{ noteD ... @}
679 \relative c' @{ noteE ... @}
682 Let us finally analyze the voices in a more complex piece of
684 the notes from the first two bars of the second of Chopin's
685 Deux Nocturnes, Op 32. This example will be used at later
686 stages in this and the next chapter to illustrate several
687 techniques for producing notation, so please ignore for now
688 anything in the underlying code which looks mysterious and
689 concentrate just on the music and the voices -- the
690 complications will all be explained in later sections.
692 @c The following should appear as music without code
693 @lilypond[quote,ragged-right]
694 \new Staff \relative c'' {
703 % Ignore these for now - they are explained in Ch 4
704 \once \override NoteColumn #'force-hshift = #0
706 \once \override NoteColumn #'force-hshift = #0.5
714 The direction of the stems is often used to indicate the
715 continuity of two simultaneous melodic lines. Here the
716 stems of the highest notes are all pointing up and the
717 stems of the lower notes are all pointing down.
718 This is the first indication that more than one voice
721 But the real need for multiple voices arises when notes
722 which start at the same time have different durations.
723 Look at the notes which start at beat three in the first
724 bar. The A-flat is a dotted quarter note, the F is a
725 quarter note and the D-flat is a half note. These
726 cannot be written as a chord as all the notes in a chord
727 must have the same duration. Neither can they be written
728 as sequential notes, as they must start at the same time.
729 This section of the bar requires three voices, and the
730 normal practice would be to write the whole bar as three
731 voices, as shown below, where we have used different note heads
732 and colors for the three voices. Again, the code behind this
733 example will be explained later, so ignore anything you do
736 @c The following should appear as music without code
737 @c The three voice styles should be defined in -init
738 @lilypond[quote,ragged-right]
739 \new Staff \relative c'' {
750 \\ % No Voice three (we want stems down)
753 % Ignore these for now - they are explained in Ch 4
754 \once \override NoteColumn #'force-hshift = #0
756 \once \override NoteColumn #'force-hshift = #0.5
765 Let us try to encode this music from scratch. As we
766 shall see, this encounters some difficulties. We begin as
767 we have learnt, using the @code{<< \\ >>} construct to
768 enter the music of the first bar in three voices:
770 @lilypond[quote,verbatim,fragment,ragged-right]
771 \new Staff \relative c'' {
774 { c2 aes4. bes8 } \\ { aes2 f4 fes } \\ { <ees c>2 des2 }
783 The stem directions are automatically assigned with the
784 odd-numbered voices taking upward stems and the even-numbered
785 voices downward ones. The stems for voices 1 and 2 are right,
786 but the stems in voice 3 should go down in this particular piece
787 of music. We can correct this simply by missing out voice three
788 and placing the music in voice four:
790 @lilypond[quote,verbatim,fragment,ragged-right]
791 \new Staff \relative c'' {
797 \\ % Omit Voice three
806 We see that this fixes the stem direction, but exposes a
807 problem sometimes encountered with multiple voices -- the
808 stems of the notes in one voice can collide with the note heads
809 in other voices. In laying out the notes, LilyPond allows the
810 notes or chords from two voices to occupy the same vertical
811 note column provided the stems are in opposite directions, but
812 the notes from the third and fourth voices are displaced to if
813 necessary to avoid the note heads
814 colliding. This usually works well, but in this example the
815 notes of the lowest voice are clearly not well placed by default.
816 LilyPond provides several ways to adjust the horizontal placing
817 of notes. We are not quite ready yet to see how to correct this,
818 so we shall leave this problem until a later section
819 (see the force-hshift property in @ref{Fixing overlapping
822 @node Explicitly instantiating voices
823 @subsection Explicitly instantiating voices
827 @funindex \voiceThree
830 Voice contexts can also be created manually
831 inside a @code{<< >>} block to create polyphonic music, using
832 @code{\voiceOne} ... @code{\voiceFour} to indicate the required
833 directions of stems, slurs, etc. In longer scores this method
834 is clearer, as it permits the voices to be separated and to be
835 given more descriptive names.
837 Specifically, the construct @code{<< \\ >>} which we used in
838 the previous section:
843 << @{ e4 f g a @} \\ @{ c,4 d e f @} >>
853 \new Voice = "1" @{ \voiceOne \relative c' @{ e4 f g a @} @}
854 \new Voice = "2" @{ \voiceTwo \relative c' @{ c4 d e f @} @}
858 Both of the above would produce
860 @c The following example should not display the code
861 @lilypond[ragged-right,quote]
863 \new Voice = "1" { \voiceOne \relative c' { e4 f g a } }
864 \new Voice = "2" { \voiceTwo \relative c' { c4 d e f } }
868 The @code{\voiceXXX} commands set the direction of stems, slurs,
869 ties, articulations, text annotations, augmentation dots of dotted
870 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
871 make these objects point upwards, while @code{\voiceTwo} and
872 @code{\voiceFour} make them point downwards. These commands also
873 generate a horizontal shift for each voice when this is required
874 to avoid clashes of note heads. The command @code{\oneVoice}
875 reverts the settings back to the normal values for a single voice.
877 Let us see in some simple examples exactly what effect
878 @code{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on
879 markup, ties, slurs, and dynamics:
881 @lilypond[quote,ragged-right,verbatim]
883 % Default behavior or behavior after \oneVoice
884 c d8 ~ d e4 ( f g a ) b-> c
888 @lilypond[quote,ragged-right,verbatim]
891 c d8 ~ d e4 ( f g a ) b-> c
893 c, d8 ~ d e4 ( f g a ) b-> c
897 @lilypond[quote,ragged-right,verbatim]
900 c d8 ~ d e4 ( f g a ) b-> c
902 c, d8 ~ d e4 ( f g a ) b-> c
906 An expression that appears directly inside a @code{<< >>} belongs
907 to the main voice (but, note, @strong{not} in a @code{<< \\ >>}
908 construct). This is useful when extra voices appear while the
909 main voice is playing. Here is a more correct rendition of the
910 example from the previous section. The red diamond-shaped notes
911 demonstrate that the main melody is now in a single voice context,
912 permitting a phrasing slur to be drawn over them.
914 @lilypond[quote,ragged-right,verbatim]
915 \new Staff \relative c' {
917 % The following notes are monophonic
919 % Start simultaneous section of three voices
921 % Continue the main voice in parallel
923 % Initiate second voice
925 % Set stems, etc, down
927 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
929 % Initiate third voice
939 @cindex nesting music expressions
940 @cindex nesting simultaneous constructs
942 More deeply nested polyphony constructs are possible, and if a
943 voice appears only briefly this might be a more natural way to
946 @lilypond[quote,ragged-right,verbatim]
947 \new Staff \relative c' {
967 This method of nesting new voices briefly is useful
968 when only small sections of the music
969 are polyphonic, but when the whole staff is largely polyphonic
970 it can be clearer to use multiple voices throughout, using
971 spacing notes to step over sections where the voice is silent,
974 @lilypond[quote,ragged-right,verbatim]
975 \new Staff \relative c' <<
976 % Initiate first voice
979 c16^( d e f g4 f e | d2 e2) |
981 % Initiate second voice
983 % set stems, etc down
985 s4 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 |
987 % Initiate third voice
997 @cindex shift commands
1001 @funindex \shiftOnnn
1003 Closely spaced notes in a chord, or notes occurring at the same
1004 time in different voices, are arranged in two, occasionally more,
1005 columns to prevent the note heads overlapping. These are called
1006 note columns. There are separate columns for each voice, and
1007 the currently specified voice-dependent shift is applied to the
1008 note column if there would otherwise be a collision. This can
1009 be seen in the example above. In bar 2 the C in voice two is
1010 shifted to the right relative to the D in voice one, and in the
1011 final chord the C in voice three is also shifted to the right
1012 relative to the other notes.
1014 The @code{\shiftOn}, @code{\shiftOnn}, @code{\shiftOnnn}, and
1015 @code{\shiftOff} commands specify the degree to which notes and
1016 chords of the voice should be shifted if a collision
1017 would otherwise occur. By default, the outer voices (normally
1018 voices one and two) have @code{\shiftOff} specified, while the
1019 inner voices (three and four) have @code{\shiftOn} specified.
1020 When a shift is applied, Voices one and three are shifted to
1021 the right and voices two and four to the left.
1023 @code{\shiftOnn} and @code{\shiftOnnn} define further shift
1024 levels which may be specified temporarily to resolve collisions
1025 in complex situations -- see @ref{Real music example}.
1027 A note column can contain just one note (or chord) from a voice
1028 with stems up and one note (or chord) from a voice with stems
1029 down. If notes from two voices which have their stems in the
1030 same direction are placed at the same position and both voices
1031 have no shift or the same shift specified, the error message
1032 @qq{Too many clashing note columns} will be produced.
1034 @node Voices and vocals
1035 @subsection Voices and vocals
1037 Vocal music presents a special difficulty: we need to combine two
1038 expressions -- notes and lyrics.
1040 You have already seen the @code{\addlyrics@{@}} command, which
1041 handles simple scores well. However, this technique is
1042 quite limited. For more complex music, you must introduce the
1043 lyrics in a @code{Lyrics} context using @code{\new Lyrics} and
1045 the lyrics to the notes with @code{\lyricsto@{@}}, using the
1046 name assigned to the Voice.
1048 @lilypond[quote,verbatim,fragment]
1050 \new Voice = "one" \relative c'' {
1053 c4 b8. a16 g4. f8 e4 d c2
1055 \new Lyrics \lyricsto "one" {
1056 No more let sins and sor -- rows grow.
1061 The automatic beaming which LilyPond uses by default works well
1062 for instrumental music, but not so well for music with lyrics,
1063 where beaming is either not required at all or is used to indicate
1064 melismata in the lyrics. In the example above we use the command
1065 @code{\autoBeamOff} to turn off the automatic beaming.
1067 Let us reuse the earlier example from Judas Maccabæus to
1068 illustrate this more flexible technique. We first recast
1069 it to use variables so the music and lyrics can be separated
1070 from the staff structure. We also introduce a ChoirStaff
1071 bracket. The lyrics themselves must be introduced with
1072 @code{\lyricmode} to ensure they are interpreted as lyrics
1075 @lilypond[quote,verbatim]
1076 global = { \time 6/8 \partial 8 \key f \major}
1077 SopOneMusic = \relative c'' {
1078 c8 | c([ bes)] a a([ g)] f | f'4. b, | c4.~ c4 }
1079 SopTwoMusic = \relative c' {
1080 r8 | r4. r4 c8 | a'([ g)] f f([ e)] d | e([ d)] c bes' }
1081 SopOneLyrics = \lyricmode {
1082 Let | flee -- cy flocks the | hills a -- dorn, __ }
1083 SopTwoLyrics = \lyricmode {
1084 Let | flee -- cy flocks the | hills a -- dorn, }
1089 \new Voice = "SopOne" {
1093 \new Lyrics \lyricsto "SopOne" {
1098 \new Voice = "SopTwo" {
1102 \new Lyrics \lyricsto "SopTwo" {
1110 This is the basic structure of all vocal scores. More staves may
1111 be added as required, more voices may be added to the staves,
1112 more verses may be added to the lyrics,
1113 and the variables containing the music can easily be placed
1114 in separate files should they become too long.
1116 Here is a final example of the first line of a hymn with four
1117 verses, set for SATB. In this case the words for all four
1120 @lilypond[quote,verbatim]
1121 TimeKey = { \time 4/4 \partial 4 \key c \major}
1122 SopMusic = \relative c' { c4 | e4. e8 g4 g | a a g }
1123 AltoMusic = \relative c' { c4 | c4. c8 e4 e | f f e }
1124 TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 }
1125 BassMusic = \relative c { c4 | c4. c8 c4 c | f8 g a b c4 }
1126 VerseOne = \lyricmode {
1127 E -- | ter -- nal fa -- ther, | strong to save, }
1128 VerseTwo = \lyricmode {
1129 O | Christ, whose voice the | wa -- ters heard, }
1130 VerseThree = \lyricmode {
1131 O | Ho -- ly Spi -- rit, | who didst brood }
1132 VerseFour = \lyricmode {
1133 O | Tri -- ni -- ty of | love and pow'r }
1139 \new Voice = "Sop" { \voiceOne \TimeKey \SopMusic }
1140 \new Voice = "Alto" { \voiceTwo \AltoMusic }
1141 \new Lyrics \lyricsto "Sop" { \VerseOne }
1142 \new Lyrics \lyricsto "Sop" { \VerseTwo }
1143 \new Lyrics \lyricsto "Sop" { \VerseThree }
1144 \new Lyrics \lyricsto "Sop" { \VerseFour }
1148 \new Voice = "Tenor" { \voiceOne \TimeKey \TenorMusic }
1149 \new Voice = "Bass" { \voiceTwo \BassMusic }
1155 @node Contexts and engravers
1156 @section Contexts and engravers
1158 Contexts and engravers have been mentioned informally
1159 in earlier sections; we now must look at
1160 these concepts in more detail, as they are important
1161 in the fine-tuning of LilyPond output.
1165 * Contexts explained::
1166 * Creating contexts::
1167 * Engravers explained::
1168 * Modifying context properties::
1169 * Adding and removing engravers::
1172 @node Contexts explained
1173 @subsection Contexts explained
1175 When music is printed, many notational elements which do not
1176 appear explicitly in the input file must be added to the
1177 output. For example, compare the input and output of the
1180 @lilypond[quote,verbatim,relative=2,fragment]
1184 The input is rather sparse, but in the output, bar lines,
1185 accidentals, clef, and time signature have been added. When
1186 LilyPond @emph{interprets} the input the musical information
1187 is inspected in time order, similar to reading a score from left
1188 to right. While reading the input, the program remembers where
1189 measure boundaries are, and which pitches require explicit
1190 accidentals. This information must be held on several levels.
1191 For example, the effect of an accidental is limited
1192 to a single staff, while a bar line must be synchronized across
1195 Within LilyPond, these rules and bits of information are grouped
1196 in @emph{Contexts}. We have already met the
1197 @code{Voice} context.
1198 Others are the @code{Staff} and @code{Score} contexts.
1199 Contexts are hierarchical to reflect the hierarchical nature of
1201 For example: a @code{Staff} context can contain many
1202 @code{Voice} contexts, and a @code{Score} context can
1203 contain many @code{Staff} contexts.
1206 @sourceimage{context-example,5cm,,}
1209 Each context has the responsibility for enforcing some notation rules,
1210 creating some notation objects and maintaining the associated
1211 properties. For example, the @code{Voice} context may introduce an
1212 accidental and then the @code{Staff} context maintains the rule to
1213 show or suppress the accidental for the remainder of the measure.
1215 As another example, the synchronization of bar lines is, by default,
1216 handled in the @code{Score} context.
1217 However, in some music we may not want the bar lines to be
1218 synchronized -- consider a polymetric score in 4/4 and 3/4 time.
1219 In such cases, we must modify the default settings of the
1220 @code{Score} and @code{Staff} contexts.
1222 For very simple scores, contexts are created implicitly, and you need
1223 not be aware of them. For larger pieces, such as anything with more
1224 than one staff, they must be
1225 created explicitly to make sure that you get as many staves as you
1226 need, and that they are in the correct order. For typesetting pieces
1227 with specialized notation, it is usual to modify existing, or
1228 even to define totally new, contexts.
1230 In addition to the @code{Score,} @code{Staff} and
1231 @code{Voice} contexts there are contexts which fit between
1232 the score and staff levels to control staff groups, such as the
1233 @code{PianoStaff} and @code{ChoirStaff} contexts. There
1234 are also alternative staff and voice contexts, and contexts for
1235 lyrics, percussion, fret boards, figured bass, etc.
1237 The names of all context types are formed from one or more
1238 words, each word being capitalized and joined immediately to the
1239 preceding word with no hyphen or underscore, e.g.,
1240 @code{GregorianTranscriptionStaff}.
1242 @node Creating contexts
1243 @subsection Creating contexts
1245 There can be only one top level context: the
1247 context. This is created with the @code{\score} command,
1248 or, in simple scores, it is created automatically.
1250 For scores with only one voice and one staff, the
1251 @code{Voice} and @code{Staff} contexts may be left to be
1252 created automatically, but for more complex scores it is
1253 necessary to create them by hand.
1254 The simplest command that does this is @code{\new}.
1255 It is prepended to a music expression, for example
1258 @cindex new contexts
1259 @cindex Context, creating
1262 \new @var{type} @var{music-expression}
1266 where @var{type} is a context name (like @code{Staff} or
1267 @code{Voice}). This command creates a new context, and starts
1268 interpreting the @var{music-expression} within that context.
1270 Note that there is no @code{\new Score} command;
1271 the single top-level @code{Score} context is introduced
1274 The @code{\new} command may also give a identifying name to the
1275 context to distinguish it from other contexts of the same type,
1278 \new @var{type} = @var{id} @var{music-expression}
1281 Note the distinction between the name of the context type,
1282 @code{Staff}, @code{Voice}, etc, and
1283 the identifying name of a particular instance of that type,
1284 which can be any sequence of letters invented by the user.
1285 The identifying name is used to refer back to that particular
1286 instance of a context. We saw this in use in the section on
1287 lyrics in @ref{Voices and vocals}.
1290 @node Engravers explained
1291 @subsection Engravers explained
1295 Every mark on the printed output of a score produced by LilyPond
1296 is produced by an @code{Engraver}. Thus there is an engraver
1297 to print staves, one to print note heads, one for stems, one for
1298 beams, etc, etc. In total there are over 120 such engravers!
1299 Fortunately, for most scores it is not necessary to know about
1300 more than a few, and for simple scores you do not need to know
1303 Engravers live and operate in Contexts.
1304 Engravers such as the @code{Metronome_mark_engraver}, whose
1305 action and output applies to the score as a whole, operate in
1306 the highest level context -- the @code{Score} context.
1308 The @code{Clef_engraver} and @code{Key_engraver} are to be
1309 found in every Staff Context, as different staves may require
1310 different clefs and keys.
1312 The @code{Note_heads_engraver} and @code{Stem_engraver} live
1313 in every @code{Voice} context, the lowest level context of all.
1315 Each engraver processes the particular objects associated
1316 with its function, and maintains the properties that relate
1317 to that function. These properties, like the properties
1318 associated with contexts, may be modified to change the
1319 operation of the engraver or the appearance of those elements
1320 in the printed score.
1322 Engravers all have compound names formed from words which
1323 describe their function. Just the first word is capitalized,
1324 and the remainder are joined to it with underscores. Thus
1325 the @code{Staff_symbol_engraver} is responsible for creating the
1326 lines of the staff, the @code{Clef_engraver} determines and sets
1327 the pitch reference point on the staff by drawing a clef symbol.
1329 Here are some of the most common engravers together with their
1330 function. You will see it is easy to guess the function from
1331 the name, or vice versa.
1333 @multitable @columnfractions .3 .7
1336 @item Accidental_engraver
1337 @tab Makes accidentals, cautionary and suggested accidentals
1342 @item Dynamic_engraver
1343 @tab Creates hairpins and dynamic texts
1345 @tab Creates the key signature
1346 @item Metronome_mark_engraver
1347 @tab Engraves metronome marking
1348 @item Note_heads_engraver
1349 @tab Engraves note heads
1352 @item Staff_symbol_engraver
1353 @tab Engraves the five (by default) lines of the staff
1355 @tab Creates stems and single-stem tremolos
1356 @item Time_signature_engraver
1357 @tab Creates time signatures
1362 We shall see later how the output of LilyPond can be changed
1363 by modifying the action of Engravers.
1366 @node Modifying context properties
1367 @subsection Modifying context properties
1369 @cindex context properties
1373 Contexts are responsible for holding the values of a number of
1374 context @emph{properties}. Many of them can be changed to
1375 influence the interpretation of the input and so change the
1376 appearance of the output. They are changed by the
1377 @code{\set} command. This takes the form
1380 \set @emph{ContextName}.@emph{propertyName} = #@emph{value}
1383 Where the @emph{ContextName} is usually @code{Score},
1384 @code{Staff} or @code{Voice}. It may be omitted,
1385 in which case @code{Voice} is assumed.
1387 The names of context properties consist of words joined
1388 together with no hyphens or underscores, all except the
1389 first having a capital letter. Here are a few examples
1390 of some commonly used ones. There are many more.
1392 @c attempt to force this onto a new page
1394 @multitable @columnfractions .25 .15 .45 .15
1395 @headitem propertyName
1401 @tab If true, set extra natural signs before accidentals
1402 @tab @code{#t}, @code{#f}
1403 @item currentBarNumber
1405 @tab Set the current bar number
1409 @tab If true, print slurs both above and below notes
1410 @tab @code{#t}, @code{#f}
1411 @item instrumentName
1413 @tab Set the name to be placed at the start of the staff
1414 @tab @code{"Cello I"}
1417 @tab Increase or decrease the font size
1421 @tab Set the text to print before the start of a verse
1426 where a Boolean is either True (@code{#t}) or False (@code{#f}),
1427 an Integer is a positive whole number, a Real is a positive
1428 or negative decimal number, and text is enclosed in double
1429 apostrophes. Note the occurrence of hash signs,
1430 (@code{#}), in two different places -- as part of the Boolean
1431 value before the @code{t} or @code{f}, and before @emph{value}
1432 in the @code{\set} statement. So when a Boolean is being
1433 entered you need to code two hash signs, e.g., @code{##t}.
1435 Before we can set any of these properties we need to know
1436 in which context they operate. Sometimes this is obvious,
1437 but occasionally it can be tricky. If the wrong context
1438 is specified, no error message is produced, but the expected
1439 action will not take place. For example, the
1440 @code{instrumentName} clearly lives in the Staff context, since
1441 it is the staff that is to be named.
1442 In this example the first staff is labelled, but not the second,
1443 because we omitted the context name.
1445 @lilypond[quote,verbatim,ragged-right]
1447 \new Staff \relative c'' {
1448 \set Staff.instrumentName = #"Soprano"
1451 \new Staff \relative c' {
1452 \set instrumentName = #"Alto" % Wrong!
1458 Remember the default context name is Voice, so the second
1459 @code{\set} command set the property @code{instrumentName} in the
1460 Voice context to @qq{Alto}, but as LilyPond does not look
1461 for any such property in the @code{Voice} context, no
1462 further action took place. This is not an error, and no error
1463 message is logged in the log file.
1465 Similarly, if the property name is mis-spelt no error message
1466 is produced, and clearly the expected action cannot be performed.
1467 If fact, you can set any (fictitious) @q{property} using any
1468 name you like in any context that exists by using the
1469 @code{\set} command. But if the name is not
1470 known to LilyPond it will not cause any action to be taken.
1471 This is one of the reasons why it is highly recommended to
1472 use a context-sensitive editor with syntax highlighting for
1473 editing LilyPond input files, such as Vim, Jedit, ConTEXT or Emacs,
1474 since unknown property names will be highlighted differently.
1476 The @code{instrumentName} property will take effect only
1477 if it is set in the @code{Staff} context, but
1478 some properties can be set in more than one context.
1479 For example, the property @code{extraNatural} is by
1480 default set to ##t (true) for all staves.
1481 If it is set to ##f (false) in one particular @code{Staff}
1482 context it applies just to the accidentals on that staff.
1483 If it is set to false in the @code{Score} context
1484 it applies to all staves.
1486 So this turns off extra naturals in one staff:
1488 @lilypond[quote,verbatim,ragged-right]
1490 \new Staff \relative c'' {
1493 \new Staff \relative c'' {
1494 \set Staff.extraNatural = ##f
1501 and this turns them off in all staves:
1503 @lilypond[quote,verbatim,ragged-right]
1505 \new Staff \relative c'' {
1508 \new Staff \relative c'' {
1509 \set Score.extraNatural = ##f
1515 The value of every property set in this way can be reset
1516 to its original value with the @code{\unset} command.
1518 The @code{\set} and @code{\unset} commands can appear anywhere
1519 in the input file and will take effect from the time they are
1520 encountered until the end of the score or until the property is
1521 @code{\set} or @code{\unset} again. Let's try changing the
1522 font size, which affects the size of the note heads (among
1523 other things) several times. The change is from the default
1524 value, not the current value.
1526 @lilypond[quote,verbatim,ragged-right,relative=1,fragment]
1528 % make note heads smaller
1531 % make note heads larger
1532 \set fontSize = #2.5
1534 % return to original size
1539 We have now seen how to set the values of several different
1540 types of property. Note that integers and numbers are alway
1541 preceded by a hash sign, @code{#}, while a true or false value
1542 is specified by ##t and ##f, with two hash signs. A text
1543 property should be enclosed in double quotation signs, as above,
1544 although we shall see later that text can actually be specified
1545 in a much more general way by using the very powerful
1546 @code{markup} command.
1551 Context properties may also be set at the time the context is
1552 created. Sometimes this is a clearer way of specifying a
1553 property value if it is to remain fixed for the duration of
1554 the context. When a context is created with a @code{\new}
1555 command it may be followed immediately by a
1556 @code{\with @{ .. @}} block in which the property values are
1557 set. For example, if we wish to suppress the printing of
1558 extra naturals for the duration of a staff we would write:
1561 \new Staff \with @{ extraNatural = ##f @}
1567 @lilypond[quote,verbatim,ragged-right]
1573 \new Staff \with { extraNatural = ##f }
1580 In effect this overrides the default value of the property. It
1581 may still be changed dynamically using @code{\set} and returned
1582 to its (new) default value with @code{\unset}.
1584 @node Adding and removing engravers
1585 @subsection Adding and removing engravers
1587 @cindex Engravers, adding
1588 @cindex Engravers, removing
1593 We have seen that contexts each contain several engravers, each
1594 of which is responsible for producing a particular part of the
1595 output, like bar lines, staves, note heads, stems, etc. If an
1596 engraver is removed from a context it can no longer produce its
1597 output. This is a crude way of modifying the output, but it
1598 can sometimes be useful.
1600 @subsubheading Changing a single context
1602 To remove an engraver from a single context we use the
1603 @code{\with} command placed immediately after the context creation
1604 command, as in the previous section.
1607 illustration let's repeat an example from the previous
1608 section with the staff lines removed. Remember that the
1609 staff lines are produced by the Staff_symbol_engraver.
1611 @lilypond[quote,verbatim,ragged-right]
1613 \remove Staff_symbol_engraver
1617 \set fontSize = #-4 % make note heads smaller
1619 \set fontSize = #2.5 % make note heads larger
1621 \unset fontSize % return to original size
1626 @cindex ambitus engraver
1628 Engravers can also be added to individual contexts.
1629 The command to do this is
1631 @code{\consists @emph{Engraver_name}},
1633 placed inside a @code{\with} block. Some vocal scores
1634 have an @rglos{ambitus} placed at the beginning of a
1635 staff to indicate the range of notes in that staff.
1636 The ambitus is produced by the @code{Ambitus_engraver},
1637 which is not normally included in any context. If
1638 we add it to the @code{Voice} context it calculates
1639 the range from that voice only:
1641 @lilypond[quote,verbatim,ragged-right]
1644 \consists Ambitus_engraver
1659 but if we add the Ambitus engraver to the
1660 @code{Staff} context it calculates the range from all
1661 the notes in all the voices on that staff:
1663 @lilypond[quote,verbatim,ragged-right]
1665 \consists Ambitus_engraver
1681 @subsubheading Changing all contexts of the same type
1683 The examples above show how to remove or add engravers to
1684 individual contexts. It is also possible to remove or add
1685 engravers to every context of a specific type by placing the
1686 commands in the appropriate context in a @code{\layout}
1687 block. For example, if we wanted to show an ambitus for every
1688 staff in a four-staff score we could write
1690 @lilypond[quote,verbatim,ragged-right]
1694 \relative c'' { c a b g }
1697 \relative c' { c a b g }
1701 \relative c' { c a b g }
1705 \relative c { c a b g }
1711 \consists Ambitus_engraver
1718 The default values of context properties may also be set
1719 for all contexts of a particular type by including the
1720 @code{\set} command in a @code{\context} block in the
1723 @node Extending the templates
1724 @section Extending the templates
1726 You've read the tutorial, you know how to write music, you
1727 understand the fundamental concepts. But how can you
1728 get the staves that you want? Well, you can find lots of
1729 templates (see @ref{Templates}) which may give you a start.
1731 if you want something that isn't covered there? Read on.
1733 TODO Add links to templates after they have been moved to LSR
1736 * Soprano and cello::
1737 * Four-part SATB vocal score::
1738 * Building a score from scratch::
1741 @node Soprano and cello
1742 @subsection Soprano and cello
1744 Start off with the template that seems closest to what you want to end
1745 up with. Let's say that you want to write something for soprano and
1746 cello. In this case, we would start with @q{Notes and lyrics} (for the
1750 \version @w{"@version{}"}
1751 melody = \relative c' @{
1758 text = \lyricmode @{
1764 \new Voice = "one" @{
1768 \new Lyrics \lyricsto "one" \text
1775 Now we want to add a cello part. Let's look at the @q{Notes only} example:
1778 \version @w{"@version{}"}
1779 melody = \relative c' @{
1793 We don't need two @code{\version} commands. We'll need the
1794 @code{melody} section. We don't want two @code{\score} sections
1795 -- if we had two @code{\score}s, we'd get the two parts separately.
1796 We want them together, as a duet. Within the @code{\score}
1797 section, we don't need two @code{\layout} or @code{\midi}.
1799 If we simply cut and paste the @code{melody} section, we would
1800 end up with two @code{melody} definitions. This would not generate
1801 an error, but the second one would be used for both melodies.
1802 So let's rename them to make them distinct. We'll call the
1803 section for the soprano @code{sopranoMusic} and the section for
1804 the cello @code{celloMusic}. While we're doing this, let's rename
1805 @code{text} to be @code{sopranoLyrics}. Remember to rename both
1806 instances of all these names -- both the initial definition (the
1807 @code{melody = \relative c' @{ } part) and the name's use (in the
1808 @code{\score} section).
1810 While we're doing this, let's change the cello part's staff --
1811 celli normally use bass clef. We'll also give the cello some
1815 \version @w{"@version{}"}
1816 sopranoMusic = \relative c' @{
1823 sopranoLyrics = \lyricmode @{
1827 celloMusic = \relative c @{
1836 \new Voice = "one" @{
1840 \new Lyrics \lyricsto "one" \sopranoLyrics
1847 This is looking promising, but the cello part won't appear in the
1848 score -- we haven't used it in the @code{\score} section. If we
1849 want the cello part to appear under the soprano part, we need to add
1852 \new Staff \celloMusic
1856 underneath the soprano stuff. We also need to add @code{<<} and
1857 @code{>>} around the music -- that tells LilyPond that there's
1858 more than one thing (in this case, two @code{Staves}) happening
1859 at once. The @code{\score} looks like this now
1861 @c Indentation in this example is deliberately poor
1866 \new Voice = "one" @{
1870 \new Lyrics \lyricsto "one" \sopranoLyrics
1872 \new Staff \celloMusic
1880 This looks a bit messy; the indentation is messed up now. That is
1881 easily fixed. Here's the complete soprano and cello template.
1883 @lilypond[quote,verbatim,ragged-right,addversion]
1884 sopranoMusic = \relative c' {
1891 sopranoLyrics = \lyricmode {
1895 celloMusic = \relative c {
1905 \new Voice = "one" {
1909 \new Lyrics \lyricsto "one" \sopranoLyrics
1911 \new Staff \celloMusic
1919 @node Four-part SATB vocal score
1920 @subsection Four-part SATB vocal score
1922 Most vocal scores of music written for four-part mixed choir
1923 with orchestral accompaniment such as Mendelssohn's Elijah or
1924 Handel's Messiah have the choral music and words on four
1925 staves, one for each of SATB, with a piano reduction of the
1926 orchestral accompaniment underneath. Here's an example
1927 from Handel's Messiah:
1929 @c The following should appear as music without code
1930 @lilypond[quote,ragged-right]
1931 global = { \key d \major \time 4/4 }
1932 sopMusic = \relative c'' {
1934 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
1936 sopWords = \lyricmode {
1937 Wor -- thy is the lamb that was slain
1939 altoMusic = \relative a' {
1941 r4 a2 a4 | fis4. fis8 a2 | g4 fis e2 |
1943 altoWords = \sopWords
1944 tenorMusic = \relative c' {
1946 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
1948 tenorWords = \sopWords
1949 bassMusic = \relative c' {
1951 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
1953 bassWords = \sopWords
1954 upper = \relative a' {
1957 r4 <a d fis>2 <a e' a>4 |
1958 <d fis d'>4. <d fis d'>8 <a d a'>2 |
1959 <g cis g'>4 <a d fis> <a cis e>2 |
1961 lower = \relative c, {
1964 <d d'>4 <d d'>2 <cis cis'>4 |
1965 <b b'>4. <b' b'>8 <fis fis'>2 |
1966 <e e'>4 <d d'> <a' a'>2 |
1970 << % combine ChoirStaff and PianoStaff in parallel
1972 \new Staff = "sopranos" <<
1973 \set Staff.instrumentName = "Soprano"
1974 \new Voice = "sopranos" { \global \sopMusic }
1976 \new Lyrics \lyricsto "sopranos" { \sopWords }
1977 \new Staff = "altos" <<
1978 \set Staff.instrumentName = "Alto"
1979 \new Voice = "altos" { \global \altoMusic }
1981 \new Lyrics \lyricsto "altos" { \altoWords }
1982 \new Staff = "tenors" <<
1983 \set Staff.instrumentName = "Tenor"
1984 \new Voice = "tenors" { \global \tenorMusic }
1986 \new Lyrics \lyricsto "tenors" { \tenorWords }
1987 \new Staff = "basses" <<
1988 \set Staff.instrumentName = "Bass"
1989 \new Voice = "basses" { \global \bassMusic }
1991 \new Lyrics \lyricsto "basses" { \bassWords }
1995 \set PianoStaff.instrumentName = "Piano "
1996 \new Staff = "upper" \upper
1997 \new Staff = "lower" \lower
2003 None of the templates provides this layout exactly. The
2004 nearest is @q{SATB vocal score and automatic piano reduction},
2005 but we need to change the layout and add a piano
2006 accompaniment which is not derived automatically from the
2007 vocal parts. The variables holding the music and words for
2008 the vocal parts are fine, but we shall need to add variables for
2009 the piano reduction.
2011 The order in which the contexts appear in the ChoirStaff of
2012 the template do not correspond with the order in the vocal
2013 score shown above. We need to rearrange them so there are
2014 four staves with the words written directly underneath the
2015 notes for each part.
2016 All the voices should be @code{\voiceOne}, which is
2017 the default, so the @code{\voiceXXX} commands should be removed.
2018 We also need to specify the tenor clef for the tenors.
2019 The way in which lyrics are specified in the template has not yet
2020 been encountered so we need to use the method with which we are
2021 familiar. We should also add the names of each staff.
2023 Doing this gives for our ChoirStaff:
2027 \new Staff = "sopranos" <<
2028 \set Staff.instrumentName = "Soprano"
2029 \new Voice = "sopranos" @{ \global \sopMusic @}
2031 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
2032 \new Staff = "altos" <<
2033 \set Staff.instrumentName = "Alto"
2034 \new Voice = "altos" @{ \global \altoMusic @}
2036 \new Lyrics \lyricsto "altos" @{ \altoWords @}
2037 \new Staff = "tenors" <<
2038 \set Staff.instrumentName = "Tenor"
2039 \new Voice = "tenors" @{ \global \tenorMusic @}
2041 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
2042 \new Staff = "basses" <<
2043 \set Staff.instrumentName = "Bass"
2044 \new Voice = "basses" @{ \global \bassMusic @}
2046 \new Lyrics \lyricsto "basses" @{ \bassWords @}
2050 Next we must work out the piano part. This is
2051 easy - we just pull out the piano part from the
2052 @q{Solo piano} template:
2056 \set PianoStaff.instrumentName = "Piano "
2057 \new Staff = "upper" \upper
2058 \new Staff = "lower" \lower
2062 and add the variable definitions for @code{upper}
2065 The ChoirStaff and PianoStaff must be combined
2066 using angle brackets as we want them to be
2067 stacked one above the other:
2070 << % combine ChoirStaff and PianoStaff one above the other
2072 \new Staff = "sopranos" <<
2073 \new Voice = "sopranos" @{ \global \sopMusic @}
2075 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
2076 \new Staff = "altos" <<
2077 \new Voice = "altos" @{ \global \altoMusic @}
2079 \new Lyrics \lyricsto "altos" @{ \altoWords @}
2080 \new Staff = "tenors" <<
2081 \clef "G_8" % tenor clef
2082 \new Voice = "tenors" @{ \global \tenorMusic @}
2084 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
2085 \new Staff = "basses" <<
2087 \new Voice = "basses" @{ \global \bassMusic @}
2089 \new Lyrics \lyricsto "basses" @{ \bassWords @}
2093 \set PianoStaff.instrumentName = "Piano "
2094 \new Staff = "upper" \upper
2095 \new Staff = "lower" \lower
2100 Combining all these together and adding the music
2101 for the three bars of the example above gives:
2103 @lilypond[quote,verbatim,ragged-right,addversion]
2104 global = { \key d \major \time 4/4 }
2105 sopMusic = \relative c'' {
2107 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
2109 sopWords = \lyricmode {
2110 Wor -- thy is the lamb that was slain
2112 altoMusic = \relative a' {
2114 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
2116 altoWords = \sopWords
2117 tenorMusic = \relative c' {
2119 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
2121 tenorWords = \sopWords
2122 bassMusic = \relative c' {
2124 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
2126 bassWords = \sopWords
2127 upper = \relative a' {
2130 r4 <a d fis>2 <a e' a>4 |
2131 <d fis d'>4. <d fis d'>8 <a d a'>2 |
2132 <g cis g'>4 <a d fis> <a cis e>2 |
2134 lower = \relative c, {
2137 <d d'>4 <d d'>2 <cis cis'>4 |
2138 <b b'>4. <b' b'>8 <fis fis'>2 |
2139 <e e'>4 <d d'> <a' a'>2 |
2143 << % combine ChoirStaff and PianoStaff in parallel
2145 \new Staff = "sopranos" <<
2146 \set Staff.instrumentName = "Soprano"
2147 \new Voice = "sopranos" { \global \sopMusic }
2149 \new Lyrics \lyricsto "sopranos" { \sopWords }
2150 \new Staff = "altos" <<
2151 \set Staff.instrumentName = "Alto"
2152 \new Voice = "altos" { \global \altoMusic }
2154 \new Lyrics \lyricsto "altos" { \altoWords }
2155 \new Staff = "tenors" <<
2156 \set Staff.instrumentName = "Tenor"
2157 \new Voice = "tenors" { \global \tenorMusic }
2159 \new Lyrics \lyricsto "tenors" { \tenorWords }
2160 \new Staff = "basses" <<
2161 \set Staff.instrumentName = "Bass"
2162 \new Voice = "basses" { \global \bassMusic }
2164 \new Lyrics \lyricsto "basses" { \bassWords }
2168 \set PianoStaff.instrumentName = "Piano "
2169 \new Staff = "upper" \upper
2170 \new Staff = "lower" \lower
2177 @node Building a score from scratch
2178 @subsection Building a score from scratch
2180 After gaining some facility with writing LilyPond code you
2181 may find that it is easier to build a score from scratch
2182 rather than modifying one of the templates. You can also
2183 develop your own style this way to suit the sort of music you
2184 like. Let's see how to put together the score for an organ
2185 prelude as an example.
2187 We begin with a header section. Here go the title, name
2188 of composer, etc, then come any variable definitions, and
2189 finally the score block. Let's start with these in outline
2190 and fill in the details later.
2192 We'll use the first two bars of Bach's prelude
2193 based on @emph{Jesu, meine Freude} which is written for two
2194 manuals and pedal organ. You can see these two bars of music
2195 at the bottom of this section. The top manual part has two voices,
2196 the lower and pedal organ one each. So we need four
2197 music definitions and one to define the time signature
2201 \version @w{"@version{}"}
2203 title = "Jesu, meine Freude"
2204 composer = "J S Bach"
2206 TimeKey = @{ \time 4/4 \key c \minor @}
2207 ManualOneVoiceOneMusic = @{s1@}
2208 ManualOneVoiceTwoMusic = @{s1@}
2209 ManualTwoMusic = @{s1@}
2210 PedalOrganMusic = @{s1@}
2216 For now we've just used a spacer note, @code{s1},
2217 instead of the real music. We'll add that later.
2219 Next let's see what should go in the score block.
2220 We simply mirror the staff structure we want.
2221 Organ music is usually written on three staves,
2222 one for each manual and one for the pedals. The
2223 manual staves should be bracketed together so we
2224 need to use a PianoStaff for them. The first
2225 manual part needs two voices and the second manual
2230 \new Staff = "ManualOne" <<
2231 \new Voice @{ \ManualOneVoiceOneMusic @}
2232 \new Voice @{ \ManualOneVoiceTwoMusic @}
2233 >> % end ManualOne Staff context
2234 \new Staff = "ManualTwo" <<
2235 \new Voice @{ \ManualTwoMusic @}
2236 >> % end ManualTwo Staff context
2237 >> % end PianoStaff context
2240 Next we need to add a staff for the pedal organ.
2241 This goes underneath the PianoStaff, but it must
2242 be simultaneous with it, so we need angle brackets
2243 round the two. Missing these out would generate
2244 an error in the log file. It's a common mistake
2245 which you'll make sooner or later! Try copying
2246 the final example at the end of this section,
2247 remove these angle brackets, and compile it to
2248 see what errors it generates.
2251 << % PianoStaff and Pedal Staff must be simultaneous
2253 \new Staff = "ManualOne" <<
2254 \new Voice @{ \ManualOneVoiceOneMusic @}
2255 \new Voice @{ \ManualOneVoiceTwoMusic @}
2256 >> % end ManualOne Staff context
2257 \new Staff = "ManualTwo" <<
2258 \new Voice @{ \ManualTwoMusic @}
2259 >> % end ManualTwo Staff context
2260 >> % end PianoStaff context
2261 \new Staff = "PedalOrgan" <<
2262 \new Voice @{ \PedalOrganMusic @}
2267 It is not strictly necessary to use the simultaneous construct
2268 @code{<< >>} for the manual two staff and the pedal organ staff,
2269 since they contain only one music expression, but it does no harm
2270 and always using angle brackets after @code{\new Staff} is a good
2271 habit to cultivate in case there are multiple voices.
2273 Let's add this structure to the score block, and adjust the
2274 indenting. We also add the appropriate clefs, ensure the
2275 second voice stems point down with @code{\voiceTwo} and
2276 enter the time signature and key to each staff using our
2277 predefined variable, @code{\TimeKey}.
2281 << % PianoStaff and Pedal Staff must be simultaneous
2283 \new Staff = "ManualOne" <<
2284 \TimeKey % set time signature and key
2286 \new Voice @{ \ManualOneVoiceOneMusic @}
2287 \new Voice @{ \voiceTwo \ManualOneVoiceTwoMusic @}
2288 >> % end ManualOne Staff context
2289 \new Staff = "ManualTwo" <<
2292 \new Voice @{ \ManualTwoMusic @}
2293 >> % end ManualTwo Staff context
2294 >> % end PianoStaff context
2295 \new Staff = "PedalOrgan" <<
2298 \new Voice @{ \PedalOrganMusic @}
2299 >> % end PedalOrgan Staff
2301 @} % end Score context
2304 That completes the structure. Any three-staff organ music
2305 will have a similar structure, although the number of voices
2306 may vary. All that remains now
2307 is to add the music, and combine all the parts together.
2309 @lilypond[quote,verbatim,ragged-right,addversion]
2311 title = "Jesu, meine Freude"
2312 composer = "J S Bach"
2314 TimeKey = { \time 4/4 \key c \minor }
2315 ManualOneVoiceOneMusic = \relative g' {
2316 g4 g f ees | d2 c2 |
2318 ManualOneVoiceTwoMusic = \relative c' {
2319 ees16 d ees8~ ees16 f ees s c8 d~ d c~ |
2320 c c4 b8 c8. g16 c b c d |
2322 ManualTwoMusic = \relative c' {
2323 c16 b c8~ c16 b c g a8 g~ g16 g aes ees |
2324 f ees f d g aes g f ees d e8~ ees16 f ees d |
2326 PedalOrganMusic = \relative c {
2327 r8 c16 d ees d ees8~ ees16 a, b g c b c8 |
2328 r16 g ees f g f g8 c,2 |
2332 << % PianoStaff and Pedal Staff must be simultaneous
2334 \new Staff = "ManualOne" <<
2335 \TimeKey % set time signature and key
2337 \new Voice { \ManualOneVoiceOneMusic }
2338 \new Voice { \voiceTwo \ManualOneVoiceTwoMusic }
2339 >> % end ManualOne Staff context
2340 \new Staff = "ManualTwo" <<
2343 \new Voice { \ManualTwoMusic }
2344 >> % end ManualTwo Staff context
2345 >> % end PianoStaff context
2346 \new Staff = "PedalOrgan" <<
2349 \new Voice { \PedalOrganMusic }
2350 >> % end PedalOrgan Staff
2352 } % end Score context