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.
153 Every @code{\book} block creates a separate output file (e.g., a
154 pdf file). If you haven't explicitly added one, LilyPond wraps
155 your entire input code in a @code{\book} block implicitly.
157 Every @code{\score} block is a separate chunk of music within a
160 Every @code{\layout} block affects the @code{\score} or
161 @code{\book} block in which it appears -- i.e., a @code{\layout}
162 block inside a @code{\score} block affects only that @code{\score}
163 block, but a @code{\layout} block outside of a @code{\score} block
164 (and thus in a @code{\book} block, either explicitly or
165 implicitly) will affect every @code{\score} in that @code{\book}.
167 Every @code{\context} block will affect the named context (e.g.,
168 @code{\StaffGroup}) throughout the block (@code{\score} or
169 @code{\book}) in which it appears.
171 For details see @ruser{Multiple scores in a book}.
175 Another great shorthand is the ability to define variables. All
176 the templates use this
179 melody = \relative c' @{
188 When LilyPond looks at this file, it takes the value of
189 @code{melody} (everything after the equals sign) and inserts it
190 whenever it sees @code{\melody}. There's nothing special about
191 the names -- it could be @code{melody}, @code{global},
193 @code{pianorighthand}, or @code{foofoobarbaz}. For more details,
194 see @ref{Saving typing with variables and functions}.
195 Remember that you can use almost any name you like as long
196 as it contains just alphabetic characters and is distinct from
197 LilyPond command names. The exact
198 limitations on variable names are detailed in
199 @ruser{File structure}.
205 For a complete definition of the input format, see
206 @ruser{File structure}.
208 @node Score is a (single) compound musical expression
209 @subsection Score is a (single) compound musical expression
211 @cindex Compound music expression
212 @cindex Music expression, compound
214 We saw the general organization of LilyPond input files in the
215 previous section, @ref{How LilyPond input files work}. But we seemed to
216 skip over the most important part: how do we figure out what to
217 write after @code{\score}?
219 We didn't skip over it at all. The big mystery is simply that
220 there @emph{is} no mystery. This line explains it all:
223 @emph{A @code{\score} block must begin with a compound music expression.}
227 You may find it useful to review
228 @ref{Music expressions explained}. In that section, we saw how to
229 build big music expressions from small pieces -- we started from
230 notes, then chords, etc. Now we're going to start from a big
231 music expression and work our way down.
235 @{ % this brace begins the overall compound music expression
237 @var{...insert the whole score of a Wagner opera in here...}
239 @} % this brace ends the overall compound music expression
244 A whole Wagner opera would easily double the length of this
245 manual, so let's just add a singer and piano. We don't need a
246 @code{GrandStaff} for this ensemble, which simply groups a number
247 of staves together with a brace at the left, so we shall remove
248 it. We @emph{do} need a singer and a piano, though.
253 \new Staff = "singer" <<
255 \new PianoStaff = piano <<
262 Remember that we use @code{<< ... >>} instead of
263 @code{@{ ... @}} to show simultaneous
264 music. And we definitely want to show the vocal part and piano
265 part at the same time, not one after the other! However, the
266 @code{<< ... >>} construct is not really necessary for the Singer
267 staff, as it contains only one music expression, but Staves often
268 do require simultaneous Voices within them, so using
270 rather than braces is a good habit to adopt. We'll add some real
271 music later; for now let's just put in some dummy notes and lyrics.
273 @lilypond[verbatim,quote,ragged-right]
276 \new Staff = "singer" <<
277 \new Voice = "vocal" { c'1 }
280 \new PianoStaff = "piano" <<
281 \new Staff = "upper" { c'1 }
282 \new Staff = "lower" { c'1 }
289 Now we have a lot more details. We have the singer's staff: it
290 contains a @code{Voice} (in LilyPond, this term refers to a set of
291 notes, not necessarily vocal notes -- for example, a violin
292 generally plays one voice) and some lyrics. We also have a piano
293 staff: it contains an upper staff (right hand) and a lower staff
296 At this stage, we could start filling in notes. Inside the curly
297 braces next to @code{\new Voice = vocal}, we could start writing
305 But if we did that, the @code{\score} section would get pretty
306 long, and it would be harder to understand what was happening. So
307 let's use variables instead. These were introduced at the end
308 of the previous section, remember? So, adding a few notes, we
309 now have a piece of real music:
311 @lilypond[verbatim,quote,ragged-right]
312 melody = \relative c'' { r4 d8\noBeam g, c4 r }
313 text = \lyricmode { And God said, }
314 upper = \relative c'' { <g d g,>2~ <g d g,> }
315 lower = \relative c { b2 e2 }
319 \new Staff = "singer" <<
320 \new Voice = "vocal" { \melody }
323 \new PianoStaff = "piano" <<
324 \new Staff = "upper" { \upper }
325 \new Staff = "lower" {
336 Be careful about the difference between notes, which are introduced
337 with @code{\relative}, and lyrics, which are introduced with
338 @code{\lyricmode}. These are essential to tell LilyPond
339 to interpret the following content as music and text
342 When writing (or reading) a @code{\score} section, just take it
343 slowly and carefully. Start with the outer layer, then work on
344 each smaller layer. It also really helps to be strict with
345 indentation -- make sure that each item on the same layer starts
346 on the same horizontal position in your text editor.
349 @node Nesting music expressions
350 @subsection Nesting music expressions
352 It is not essential to declare all staves at the beginning;
353 they may be introduced temporarily at any point. This is
354 particularly useful for creating ossia sections
355 (see @rglos{ossia}). Here is a simple example showing how
356 to introduce a new staff temporarily for the duration of
359 @lilypond[verbatim,quote,ragged-right]
376 Note that the size of the clef is the same as a clef printed
377 following a clef change -- slightly smaller than the clef
378 at the beginning of the line. This is usual for clefs printed
379 in the middle of a line.
381 The ossia section may be placed above the staff
384 @lilypond[verbatim,quote,ragged-right]
392 alignAboveContext = "main" }
400 This example uses @code{\with}, which will be explained more
401 fully later. It is a means of modifying the default behavior
402 of a single Staff. Here it says that the new staff should be
403 placed above the staff called @qq{main} instead of the default
404 position which is below.
406 Ossia are often written without clef and without
407 time signature and are usually in a smaller font.
408 These require further commands which
409 have not yet been introduced. See @ref{Size of objects}
411 @node On the un-nestedness of brackets and ties
412 @subsection On the un-nestedness of brackets and ties
414 You have already met a number of different types of bracket in
415 writing the input file to LilyPond. These obey different rules
416 which can be confusing at first. Before we explain the rules
417 let's first review the different types of bracket.
419 @c attempt to force this onto a new page
421 @multitable @columnfractions .3 .7
422 @headitem Bracket Type
424 @item @code{@{ .. @}}
425 @tab Encloses a sequential segment of music
427 @tab Encloses the notes of a chord
428 @item @code{<< .. >>}
429 @tab Encloses concurrent or simultaneous sections
431 @tab Marks the start and end of a slur
432 @item @code{\( .. \)}
433 @tab Marks the start and end of a phrase mark
435 @tab Marks the start and end of a manual beam
438 To these we should add other constructs which generate lines
439 between or across notes: ties (marked by a tilde, @code{~}),
440 tuplets written as @code{\times x/y @{..@}}, and grace notes
441 written as @code{\grace@{..@}}.
443 Outside LilyPond, the conventional use of brackets requires
444 the different types to be properly nested, like this,
445 @code{<< [ @{ ( .. ) @} ] >>}, with the closing brackets being
446 encountered in exactly the opposite order to the opening
447 brackets. This @strong{is} a requirement for the three types of
448 bracket described by the word @q{Encloses} in the table above --
449 they must nest properly.
450 However, the remaining brackets, described with the word
451 @q{Marks} in the table above together with ties and tuplets,
452 do @strong{not} have to nest
453 properly with any of the brackets. In fact, these are not
454 brackets in the sense that
455 they enclose something -- they are simply markers to indicate
456 where something starts and ends.
458 So, for example, a phrasing slur can start before a manually
459 inserted beam and end before the end of the beam -- not very
460 musical, perhaps, but possible:
462 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
463 { g8\( a b[ c b\) a] }
466 In general, different kinds of brackets, and those implied by
467 tuplets, ties and grace notes, may be mixed freely.
468 This example shows a beam extending into a tuplet (line 1),
469 a slur extending into a tuplet (line 2),
470 a beam and a slur extending into a tuplet, a tie crossing
471 two tuplets, and a phrasing slur extending out of a tuplet
474 @lilypond[quote,verbatim,fragment,ragged-right]
476 r16[ g16 \times 2/3 {r16 e'8] }
477 g16( a \times 2/3 {b d) e' }
478 g8[( a \times 2/3 {b d') e'~]}
479 \times 4/5 {e'32\( a b d' e'} a'4.\)
484 @node Voices contain music
485 @section Voices contain music
487 Singers need voices to sing, and so does LilyPond.
488 The actual music for all instruments in a score
489 is contained in Voices -- the most fundamental
490 of all LilyPond's concepts.
493 * I'm hearing Voices::
494 * Explicitly instantiating voices::
495 * Voices and vocals::
498 @node I'm hearing Voices
499 @subsection I'm hearing Voices
503 @cindex Voice context
505 The lowest, most fundamental or innermost layers in a LilyPond
506 score are called @q{Voice contexts} or just @q{Voices} for short.
507 Voices are sometimes called @q{layers} in other notation
510 In fact, a Voice layer or context is the only one which can
511 contain music. If a Voice context is not explicitly declared
512 one is created automatically, as we saw at the beginning of
513 this chapter. Some instruments such as an
514 Oboe can play only one note at a time. Music written for
515 such instruments is monophonic and requires just a single
516 voice. Instruments which can play more than one note at a
517 time like the piano will often require multiple voices to
518 encode the different concurrent notes and rhythms they are
521 A single voice can contain many notes in a chord, of course,
522 so when exactly are multiple voices needed? Look first at
523 this example of four chords:
525 @lilypond[quote,verbatim,fragment,ragged-right,relative=1]
527 <d g>4 <d fis> <d a'> <d g>
530 This can be expressed using just the single angle bracket chord
531 symbols, @code{< ... >}, and for this just a single voice is
532 needed. But suppose the F-sharp were actually an eighth-note
533 followed by an eighth-note G, a passing note on the way to the A?
534 Now we have two notes which start at the same time but have
535 different durations: the quarter-note D and the eighth-note
536 F-sharp. How are these to be coded? They cannot be written as
537 a chord because all the notes in a chord must have the same
538 duration. And they cannot be written as two separate notes
539 as they need to start at the same time. This is when two
542 Let us see how this is done in LilyPond input syntax.
547 The easiest way to enter fragments with more than one voice on a
548 staff is to enter each voice as a sequence (with @code{@{...@}}),
549 and combine them simultaneously with angle brackets, @code{<<...>>}.
550 The fragments must also be separated with double backward slashes,
551 @code{\\}, to place them in separate voices. Without these, the
552 notes would be entered into a single voice, which would usually
553 cause errors. This technique is particularly suited to pieces of
554 music which are largely monophonic with occasional short sections
557 Here's how we split the chords above into two voices and add both
558 the passing note and a slur:
560 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
562 % Voice "1" Voice "2"
563 << { g4 fis8( g) a4 g } \\ { d4 d d d } >> |
566 Notice how the stems of the second voice now point down.
568 Here's another simple example:
570 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
572 % Voice "1" Voice "2"
573 << { r4 g g4. a8 } \\ { d,2 d4 g } >> |
574 << { bes4 bes c bes } \\ { g4 g g8( a) g4 } >> |
575 << { a2. r4 } \\ { fis2. s4 } >> |
578 It is not necessary to use a separate @code{<< \\ >>} construct
579 for each bar. For music with few notes in each bar this layout
580 can help the legibility of the code, but if there are many
581 notes in each bar it may be better to split out each voice
582 separately, like this:
584 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
600 This example has just two voices, but the same construct may be
601 used to encode three or more voices by adding more back-slash
604 The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
605 In each of these contexts, the vertical direction of slurs,
606 stems, ties, dynamics etc., is set appropriately.
608 @lilypond[quote,verbatim,fragment]
609 \new Staff \relative c' {
612 % Voice "1" Voice "2" Voice "3"
613 << { g4 f e } \\ { r8 e4 d c8 ~ } >> |
614 << { d2 e2 } \\ { c8 b16 a b8 g ~ g2 } \\ { s4 b4 c2 } >> |
618 These voices are all separate from the main voice that contains
619 the notes just outside the @code{<< .. >>} construct. Let's call
620 this the @emph{simultaneous construct}. Slurs and ties may only
621 connect notes within the same voice, so slurs and ties cannot go
622 into or out of a simultaneous construct. Conversely,
623 parallel voices from separate simultaneous constructs on the same
624 staff are the same voice. Other voice-related properties also
625 carry across simultaneous constructs. Here is the same example,
626 with different colors and note heads for each voice. Note that
627 changes in one voice do not affect other voices, but they do
628 persist in the same voice later. Note also that tied notes may be
629 split across the same voices in two constructs, shown here in the
632 @lilypond[quote,verbatim]
633 \new Staff \relative c' {
652 { c8 b16 a b8 g ~ g2 }
662 The commands @code{\voiceXXXStyle} are mainly intended for use in
663 educational documents such as this one. They modify the color
664 of the note head, the stem and the beams, and the style of the
665 note head, so that the voices may be easily distinguished.
666 Voice one is set to red diamonds, voice two to blue triangles,
667 voice three to green crossed circles, and voice four (not used
668 here) to magenta crosses. We shall see later how commands like
669 these may be created by the user.
670 See @ref{Visibility and color of objects}
671 TODO Add link to using variables for tweaks
673 Polyphony does not change the relationship of notes within a
674 @code{\relative @{ @}} block. Each note is still calculated
675 relative to the note immediately preceding it, or to the first
676 note of the preceding chord. So in
679 \relative c' @{ noteA << < noteB noteC > \\ noteD >> noteE @}
683 @code{noteB} is relative to @code{noteA} @*
684 @code{noteC} is relative to @code{noteB}, not @code{noteA}; @*
685 @code{noteD} is relative to @code{noteB}, not @code{noteA} or
687 @code{noteE} is relative to @code{noteD}, not @code{noteA}
689 An alternative way, which may be clearer if the notes in the
690 voices are widely separated, is to place a @code{\relative}
691 command at the start of each voice:
694 \relative c' @{ noteA ... @}
696 \relative c'' @{ < noteB noteC > ... @}
698 \relative g' @{ noteD ... @}
700 \relative c' @{ noteE ... @}
703 Let us finally analyze the voices in a more complex piece of
705 the notes from the first two bars of the second of Chopin's
706 Deux Nocturnes, Op 32. This example will be used at later
707 stages in this and the next chapter to illustrate several
708 techniques for producing notation, so please ignore for now
709 anything in the underlying code which looks mysterious and
710 concentrate just on the music and the voices -- the
711 complications will all be explained in later sections.
713 @c The following should appear as music without code
714 @lilypond[quote,ragged-right]
715 \new Staff \relative c'' {
724 % Ignore these for now - they are explained in Ch 4
725 \once \override NoteColumn #'force-hshift = #0
727 \once \override NoteColumn #'force-hshift = #0.5
735 The direction of the stems is often used to indicate the
736 continuity of two simultaneous melodic lines. Here the
737 stems of the highest notes are all pointing up and the
738 stems of the lower notes are all pointing down.
739 This is the first indication that more than one voice
742 But the real need for multiple voices arises when notes
743 which start at the same time have different durations.
744 Look at the notes which start at beat three in the first
745 bar. The A-flat is a dotted quarter note, the F is a
746 quarter note and the D-flat is a half note. These
747 cannot be written as a chord as all the notes in a chord
748 must have the same duration. Neither can they be written
749 as sequential notes, as they must start at the same time.
750 This section of the bar requires three voices, and the
751 normal practice would be to write the whole bar as three
752 voices, as shown below, where we have used different note heads
753 and colors for the three voices. Again, the code behind this
754 example will be explained later, so ignore anything you do
757 @c The following should appear as music without code
758 @c The three voice styles should be defined in -init
759 @lilypond[quote,ragged-right]
760 \new Staff \relative c'' {
771 \\ % No Voice three (we want stems down)
774 % Ignore these for now - they are explained in Ch 4
775 \once \override NoteColumn #'force-hshift = #0
777 \once \override NoteColumn #'force-hshift = #0.5
786 Let us try to encode this music from scratch. As we
787 shall see, this encounters some difficulties. We begin as
788 we have learnt, using the @code{<< \\ >>} construct to
789 enter the music of the first bar in three voices:
791 @lilypond[quote,verbatim,fragment,ragged-right]
792 \new Staff \relative c'' {
795 { c2 aes4. bes8 } \\ { aes2 f4 fes } \\ { <ees c>2 des2 }
804 The stem directions are automatically assigned with the
805 odd-numbered voices taking upward stems and the even-numbered
806 voices downward ones. The stems for voices 1 and 2 are right,
807 but the stems in voice 3 should go down in this particular piece
808 of music. We can correct this simply by missing out voice three
809 and placing the music in voice four:
811 @lilypond[quote,verbatim,fragment,ragged-right]
812 \new Staff \relative c'' {
818 \\ % Omit Voice three
827 We see that this fixes the stem direction, but exposes a
828 problem sometimes encountered with multiple voices -- the
829 stems of the notes in one voice can collide with the note heads
830 in other voices. In laying out the notes, LilyPond allows the
831 notes or chords from two voices to occupy the same vertical
832 note column provided the stems are in opposite directions, but
833 the notes from the third and fourth voices are displaced to if
834 necessary to avoid the note heads
835 colliding. This usually works well, but in this example the
836 notes of the lowest voice are clearly not well placed by default.
837 LilyPond provides several ways to adjust the horizontal placing
838 of notes. We are not quite ready yet to see how to correct this,
839 so we shall leave this problem until a later section
840 (see the force-hshift property in @ref{Fixing overlapping
843 @node Explicitly instantiating voices
844 @subsection Explicitly instantiating voices
848 @funindex \voiceThree
851 Voice contexts can also be created manually
852 inside a @code{<< >>} block to create polyphonic music, using
853 @code{\voiceOne} ... @code{\voiceFour} to indicate the required
854 directions of stems, slurs, etc. In longer scores this method
855 is clearer, as it permits the voices to be separated and to be
856 given more descriptive names.
858 Specifically, the construct @code{<< \\ >>} which we used in
859 the previous section:
864 << @{ e4 f g a @} \\ @{ c,4 d e f @} >>
874 \new Voice = "1" @{ \voiceOne \relative c' @{ e4 f g a @} @}
875 \new Voice = "2" @{ \voiceTwo \relative c' @{ c4 d e f @} @}
879 Both of the above would produce
881 @c The following example should not display the code
882 @lilypond[ragged-right,quote]
884 \new Voice = "1" { \voiceOne \relative c' { e4 f g a } }
885 \new Voice = "2" { \voiceTwo \relative c' { c4 d e f } }
889 The @code{\voiceXXX} commands set the direction of stems, slurs,
890 ties, articulations, text annotations, augmentation dots of dotted
891 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
892 make these objects point upwards, while @code{\voiceTwo} and
893 @code{\voiceFour} make them point downwards. These commands also
894 generate a horizontal shift for each voice when this is required
895 to avoid clashes of note heads. The command @code{\oneVoice}
896 reverts the settings back to the normal values for a single voice.
898 Let us see in some simple examples exactly what effect
899 @code{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on
900 markup, ties, slurs, and dynamics:
902 @lilypond[quote,ragged-right,verbatim]
904 % Default behavior or behavior after \oneVoice
905 c d8 ~ d e4 ( f g a ) b-> c
909 @lilypond[quote,ragged-right,verbatim]
912 c d8 ~ d e4 ( f g a ) b-> c
914 c, d8 ~ d e4 ( f g a ) b-> c
918 @lilypond[quote,ragged-right,verbatim]
921 c d8 ~ d e4 ( f g a ) b-> c
923 c, d8 ~ d e4 ( f g a ) b-> c
927 An expression that appears directly inside a @code{<< >>} belongs
928 to the main voice (but, note, @strong{not} in a @code{<< \\ >>}
929 construct). This is useful when extra voices appear while the
930 main voice is playing. Here is a more correct rendition of the
931 example from the previous section. The red diamond-shaped notes
932 demonstrate that the main melody is now in a single voice context,
933 permitting a phrasing slur to be drawn over them.
935 @lilypond[quote,ragged-right,verbatim]
936 \new Staff \relative c' {
938 % The following notes are monophonic
940 % Start simultaneous section of three voices
942 % Continue the main voice in parallel
944 % Initiate second voice
946 % Set stems, etc, down
948 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
950 % Initiate third voice
960 @cindex nesting music expressions
961 @cindex nesting simultaneous constructs
963 More deeply nested polyphony constructs are possible, and if a
964 voice appears only briefly this might be a more natural way to
967 @lilypond[quote,ragged-right,verbatim]
968 \new Staff \relative c' {
988 This method of nesting new voices briefly is useful
989 when only small sections of the music
990 are polyphonic, but when the whole staff is largely polyphonic
991 it can be clearer to use multiple voices throughout, using
992 spacing notes to step over sections where the voice is silent,
995 @lilypond[quote,ragged-right,verbatim]
996 \new Staff \relative c' <<
997 % Initiate first voice
1000 c16^( d e f g4 f e | d2 e2) |
1002 % Initiate second voice
1004 % set stems, etc down
1006 s4 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 |
1008 % Initiate third voice
1018 @cindex shift commands
1022 @funindex \shiftOnnn
1024 Closely spaced notes in a chord, or notes occurring at the same
1025 time in different voices, are arranged in two, occasionally more,
1026 columns to prevent the note heads overlapping. These are called
1027 note columns. There are separate columns for each voice, and
1028 the currently specified voice-dependent shift is applied to the
1029 note column if there would otherwise be a collision. This can
1030 be seen in the example above. In bar 2 the C in voice two is
1031 shifted to the right relative to the D in voice one, and in the
1032 final chord the C in voice three is also shifted to the right
1033 relative to the other notes.
1035 The @code{\shiftOn}, @code{\shiftOnn}, @code{\shiftOnnn}, and
1036 @code{\shiftOff} commands specify the degree to which notes and
1037 chords of the voice should be shifted if a collision
1038 would otherwise occur. By default, the outer voices (normally
1039 voices one and two) have @code{\shiftOff} specified, while the
1040 inner voices (three and four) have @code{\shiftOn} specified.
1041 When a shift is applied, Voices one and three are shifted to
1042 the right and voices two and four to the left.
1044 @code{\shiftOnn} and @code{\shiftOnnn} define further shift
1045 levels which may be specified temporarily to resolve collisions
1046 in complex situations -- see @ref{Real music example}.
1048 A note column can contain just one note (or chord) from a voice
1049 with stems up and one note (or chord) from a voice with stems
1050 down. If notes from two voices which have their stems in the
1051 same direction are placed at the same position and both voices
1052 have no shift or the same shift specified, the error message
1053 @qq{Too many clashing note columns} will be produced.
1055 @node Voices and vocals
1056 @subsection Voices and vocals
1058 Vocal music presents a special difficulty: we need to combine two
1059 expressions -- notes and lyrics.
1061 You have already seen the @code{\addlyrics@{@}} command, which
1062 handles simple scores well. However, this technique is
1063 quite limited. For more complex music, you must introduce the
1064 lyrics in a @code{Lyrics} context using @code{\new Lyrics} and
1066 the lyrics to the notes with @code{\lyricsto@{@}}, using the
1067 name assigned to the Voice.
1069 @lilypond[quote,verbatim,fragment]
1071 \new Voice = "one" \relative c'' {
1074 c4 b8. a16 g4. f8 e4 d c2
1076 \new Lyrics \lyricsto "one" {
1077 No more let sins and sor -- rows grow.
1082 The automatic beaming which LilyPond uses by default works well
1083 for instrumental music, but not so well for music with lyrics,
1084 where beaming is either not required at all or is used to indicate
1085 melismata in the lyrics. In the example above we use the command
1086 @code{\autoBeamOff} to turn off the automatic beaming.
1088 Let us reuse the earlier example from Judas Maccabæus to
1089 illustrate this more flexible technique. We first recast
1090 it to use variables so the music and lyrics can be separated
1091 from the staff structure. We also introduce a ChoirStaff
1092 bracket. The lyrics themselves must be introduced with
1093 @code{\lyricmode} to ensure they are interpreted as lyrics
1096 @lilypond[quote,verbatim]
1097 global = { \time 6/8 \partial 8 \key f \major}
1098 SopOneMusic = \relative c'' {
1099 c8 | c([ bes)] a a([ g)] f | f'4. b, | c4.~ c4 }
1100 SopTwoMusic = \relative c' {
1101 r8 | r4. r4 c8 | a'([ g)] f f([ e)] d | e([ d)] c bes' }
1102 SopOneLyrics = \lyricmode {
1103 Let | flee -- cy flocks the | hills a -- dorn, __ }
1104 SopTwoLyrics = \lyricmode {
1105 Let | flee -- cy flocks the | hills a -- dorn, }
1110 \new Voice = "SopOne" {
1114 \new Lyrics \lyricsto "SopOne" {
1119 \new Voice = "SopTwo" {
1123 \new Lyrics \lyricsto "SopTwo" {
1131 This is the basic structure of all vocal scores. More staves may
1132 be added as required, more voices may be added to the staves,
1133 more verses may be added to the lyrics,
1134 and the variables containing the music can easily be placed
1135 in separate files should they become too long.
1137 Here is a example of the first line of a hymn with four
1138 verses, set for SATB. In this case the words for all four
1141 @lilypond[quote,verbatim]
1142 TimeKey = { \time 4/4 \partial 4 \key c \major}
1143 SopMusic = \relative c' { c4 | e4. e8 g4 g | a a g }
1144 AltoMusic = \relative c' { c4 | c4. c8 e4 e | f f e }
1145 TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 }
1146 BassMusic = \relative c { c4 | c4. c8 c4 c | f8 g a b c4 }
1147 VerseOne = \lyricmode {
1148 E -- | ter -- nal fa -- ther, | strong to save, }
1149 VerseTwo = \lyricmode {
1150 O | Christ, whose voice the | wa -- ters heard, }
1151 VerseThree = \lyricmode {
1152 O | Ho -- ly Spi -- rit, | who didst brood }
1153 VerseFour = \lyricmode {
1154 O | Tri -- ni -- ty of | love and pow'r }
1160 \new Voice = "Sop" { \voiceOne \TimeKey \SopMusic }
1161 \new Voice = "Alto" { \voiceTwo \AltoMusic }
1162 \new Lyrics \lyricsto "Sop" { \VerseOne }
1163 \new Lyrics \lyricsto "Sop" { \VerseTwo }
1164 \new Lyrics \lyricsto "Sop" { \VerseThree }
1165 \new Lyrics \lyricsto "Sop" { \VerseFour }
1169 \new Voice = "Tenor" { \voiceOne \TimeKey \TenorMusic }
1170 \new Voice = "Bass" { \voiceTwo \BassMusic }
1176 We end with an example to show how we might code a solo verse which
1177 continues into a two-part refrain in two staves. The
1178 positioning of the sequential and simultaneous sections to achieve
1179 this within a single score is quite tricky, so follow the
1180 explanation carefully!
1182 Let's start with a score block containing a @code{ChoirStaff}, as
1183 we would like the brace to appear at the start of the chorus.
1184 Normally you would need angle brackets after @code{\new ChoirStaff}
1185 to bring in all the staves in parallel, but here we want to
1186 defer the parallelism during the solo so we use braces, although
1187 angle brackets here wouldn't hurt. Inside the @code{ChoirStaff} we
1188 want first the staff which will contain the verse. This must
1189 contain notes and lyrics in parallel, so here we need angle
1190 brackets around the @code{\new Voice} and @code{\new Lyrics} to
1191 start them at the same time:
1193 @lilypond[quote,verbatim,ragged-right]
1194 versenotes = \relative c'' {
1197 \time 3/4 g g g b b b
1199 versewords = \lyricmode {
1200 One two three four five six
1205 \new Voice = "verse" {
1208 \new Lyrics \lyricsto verse {
1216 That gives the verse line.
1218 Now we want to continue with refrainA on the same staff while a
1219 second staff is introduced in parallel with it for refrainB, so
1220 this is a parallel section which must be positioned immediately
1221 following the @code{\break} in the verse Voice. Yes, @emph{within}
1222 the verse Voice! Here's that parallel section. More staves
1223 could be introduced here in the same way.
1228 \new Lyrics \lyricsto verse @{
1232 \new Voice = "refrainB" @{
1235 \new Lyrics \lyricsto "refrainB" @{
1242 Here's the final result with two staves in the chorus showing
1243 how the parallel section is positioned within the verse Voice:
1245 @lilypond[quote,verbatim, ragged-right]
1246 versenotes = \relative c'' {
1249 \time 3/4 g g g b b b
1251 refrainnotesA = \relative c'' {
1255 refrainnotesB = \relative c {
1260 versewords = \lyricmode {
1261 One two three four five six
1263 refrainwordsA = \lyricmode {
1266 refrainwordsB = \lyricmode {
1272 \context Voice = "verse" {
1276 \new Lyrics \lyricsto "verse" {
1280 \new Voice = "refrainB" {
1283 \new Lyrics \lyricsto "refrainB" {
1289 \new Lyrics \lyricsto "verse" {
1297 @cindex book, example of using
1300 However, although this is an interesting and useful exercise to
1301 help you to understand how sequential and simultaneous blocks work,
1302 in practice one would perhaps choose to code this as two
1303 @code{\score} blocks within an implicit @code{\book} block, as
1306 @lilypond[quote,verbatim,ragged-right]
1307 versenotes = \relative c'' {
1310 \time 3/4 g g g b b b
1312 refrainnotesA = \relative c'' {
1316 refrainnotesB = \relative c {
1321 versewords = \lyricmode {
1322 One two three four five six
1324 refrainwordsA = \lyricmode {
1327 refrainwordsB = \lyricmode {
1332 \new Voice = "verse" {
1335 \new Lyrics \lyricsto "verse" {
1344 \new Voice = "refrainA" {
1347 \new Lyrics \lyricsto "refrainA" {
1352 \new Voice = "refrainB" {
1355 \new Lyrics \lyricsto "refrainB" {
1363 @node Contexts and engravers
1364 @section Contexts and engravers
1366 Contexts and engravers have been mentioned informally
1367 in earlier sections; we now must look at
1368 these concepts in more detail, as they are important
1369 in the fine-tuning of LilyPond output.
1373 * Contexts explained::
1374 * Creating contexts::
1375 * Engravers explained::
1376 * Modifying context properties::
1377 * Adding and removing engravers::
1380 @node Contexts explained
1381 @subsection Contexts explained
1383 When music is printed, many notational elements which do not
1384 appear explicitly in the input file must be added to the
1385 output. For example, compare the input and output of the
1388 @lilypond[quote,verbatim,relative=2,fragment]
1392 The input is rather sparse, but in the output, bar lines,
1393 accidentals, clef, and time signature have been added. When
1394 LilyPond @emph{interprets} the input the musical information
1395 is inspected in time order, similar to reading a score from left
1396 to right. While reading the input, the program remembers where
1397 measure boundaries are, and which pitches require explicit
1398 accidentals. This information must be held on several levels.
1399 For example, the effect of an accidental is limited
1400 to a single staff, while a bar line must be synchronized across
1403 Within LilyPond, these rules and bits of information are grouped
1404 in @emph{Contexts}. We have already met the
1405 @code{Voice} context.
1406 Others are the @code{Staff} and @code{Score} contexts.
1407 Contexts are hierarchical to reflect the hierarchical nature of
1409 For example: a @code{Staff} context can contain many
1410 @code{Voice} contexts, and a @code{Score} context can
1411 contain many @code{Staff} contexts.
1414 @sourceimage{context-example,5cm,,}
1417 Each context has the responsibility for enforcing some notation rules,
1418 creating some notation objects and maintaining the associated
1419 properties. For example, the @code{Voice} context may introduce an
1420 accidental and then the @code{Staff} context maintains the rule to
1421 show or suppress the accidental for the remainder of the measure.
1423 As another example, the synchronization of bar lines is, by default,
1424 handled in the @code{Score} context.
1425 However, in some music we may not want the bar lines to be
1426 synchronized -- consider a polymetric score in 4/4 and 3/4 time.
1427 In such cases, we must modify the default settings of the
1428 @code{Score} and @code{Staff} contexts.
1430 For very simple scores, contexts are created implicitly, and you need
1431 not be aware of them. For larger pieces, such as anything with more
1432 than one staff, they must be
1433 created explicitly to make sure that you get as many staves as you
1434 need, and that they are in the correct order. For typesetting pieces
1435 with specialized notation, it is usual to modify existing, or
1436 even to define totally new, contexts.
1438 In addition to the @code{Score,} @code{Staff} and
1439 @code{Voice} contexts there are contexts which fit between
1440 the score and staff levels to control staff groups, such as the
1441 @code{PianoStaff} and @code{ChoirStaff} contexts. There
1442 are also alternative staff and voice contexts, and contexts for
1443 lyrics, percussion, fret boards, figured bass, etc.
1445 The names of all context types are formed from one or more
1446 words, each word being capitalized and joined immediately to the
1447 preceding word with no hyphen or underscore, e.g.,
1448 @code{GregorianTranscriptionStaff}.
1450 @node Creating contexts
1451 @subsection Creating contexts
1453 There can be only one top level context: the
1455 context. This is created with the @code{\score} command,
1456 or, in simple scores, it is created automatically.
1458 For scores with only one voice and one staff, the
1459 @code{Voice} and @code{Staff} contexts may be left to be
1460 created automatically, but for more complex scores it is
1461 necessary to create them by hand.
1462 The simplest command that does this is @code{\new}.
1463 It is prepended to a music expression, for example
1466 @cindex new contexts
1467 @cindex Context, creating
1470 \new @var{type} @var{music-expression}
1474 where @var{type} is a context name (like @code{Staff} or
1475 @code{Voice}). This command creates a new context, and starts
1476 interpreting the @var{music-expression} within that context.
1478 Note that there is no @code{\new Score} command;
1479 the single top-level @code{Score} context is introduced
1482 The @code{\new} command may also give a identifying name to the
1483 context to distinguish it from other contexts of the same type,
1486 \new @var{type} = @var{id} @var{music-expression}
1489 Note the distinction between the name of the context type,
1490 @code{Staff}, @code{Voice}, etc, and
1491 the identifying name of a particular instance of that type,
1492 which can be any sequence of letters invented by the user.
1493 The identifying name is used to refer back to that particular
1494 instance of a context. We saw this in use in the section on
1495 lyrics in @ref{Voices and vocals}.
1498 @node Engravers explained
1499 @subsection Engravers explained
1503 Every mark on the printed output of a score produced by LilyPond
1504 is produced by an @code{Engraver}. Thus there is an engraver
1505 to print staves, one to print note heads, one for stems, one for
1506 beams, etc, etc. In total there are over 120 such engravers!
1507 Fortunately, for most scores it is not necessary to know about
1508 more than a few, and for simple scores you do not need to know
1511 Engravers live and operate in Contexts.
1512 Engravers such as the @code{Metronome_mark_engraver}, whose
1513 action and output applies to the score as a whole, operate in
1514 the highest level context -- the @code{Score} context.
1516 The @code{Clef_engraver} and @code{Key_engraver} are to be
1517 found in every Staff Context, as different staves may require
1518 different clefs and keys.
1520 The @code{Note_heads_engraver} and @code{Stem_engraver} live
1521 in every @code{Voice} context, the lowest level context of all.
1523 Each engraver processes the particular objects associated
1524 with its function, and maintains the properties that relate
1525 to that function. These properties, like the properties
1526 associated with contexts, may be modified to change the
1527 operation of the engraver or the appearance of those elements
1528 in the printed score.
1530 Engravers all have compound names formed from words which
1531 describe their function. Just the first word is capitalized,
1532 and the remainder are joined to it with underscores. Thus
1533 the @code{Staff_symbol_engraver} is responsible for creating the
1534 lines of the staff, the @code{Clef_engraver} determines and sets
1535 the pitch reference point on the staff by drawing a clef symbol.
1537 Here are some of the most common engravers together with their
1538 function. You will see it is easy to guess the function from
1539 the name, or vice versa.
1541 @multitable @columnfractions .3 .7
1544 @item Accidental_engraver
1545 @tab Makes accidentals, cautionary and suggested accidentals
1550 @item Dynamic_engraver
1551 @tab Creates hairpins and dynamic texts
1553 @tab Creates the key signature
1554 @item Metronome_mark_engraver
1555 @tab Engraves metronome marking
1556 @item Note_heads_engraver
1557 @tab Engraves note heads
1560 @item Staff_symbol_engraver
1561 @tab Engraves the five (by default) lines of the staff
1563 @tab Creates stems and single-stem tremolos
1564 @item Time_signature_engraver
1565 @tab Creates time signatures
1570 We shall see later how the output of LilyPond can be changed
1571 by modifying the action of Engravers.
1574 @node Modifying context properties
1575 @subsection Modifying context properties
1577 @cindex context properties
1581 Contexts are responsible for holding the values of a number of
1582 context @emph{properties}. Many of them can be changed to
1583 influence the interpretation of the input and so change the
1584 appearance of the output. They are changed by the
1585 @code{\set} command. This takes the form
1588 \set @emph{ContextName}.@emph{propertyName} = #@emph{value}
1591 Where the @emph{ContextName} is usually @code{Score},
1592 @code{Staff} or @code{Voice}. It may be omitted,
1593 in which case @code{Voice} is assumed.
1595 The names of context properties consist of words joined
1596 together with no hyphens or underscores, all except the
1597 first having a capital letter. Here are a few examples
1598 of some commonly used ones. There are many more.
1600 @c attempt to force this onto a new page
1602 @multitable @columnfractions .25 .15 .45 .15
1603 @headitem propertyName
1609 @tab If true, set extra natural signs before accidentals
1610 @tab @code{#t}, @code{#f}
1611 @item currentBarNumber
1613 @tab Set the current bar number
1617 @tab If true, print slurs both above and below notes
1618 @tab @code{#t}, @code{#f}
1619 @item instrumentName
1621 @tab Set the name to be placed at the start of the staff
1622 @tab @code{"Cello I"}
1625 @tab Increase or decrease the font size
1629 @tab Set the text to print before the start of a verse
1634 where a Boolean is either True (@code{#t}) or False (@code{#f}),
1635 an Integer is a positive whole number, a Real is a positive
1636 or negative decimal number, and text is enclosed in double
1637 apostrophes. Note the occurrence of hash signs,
1638 (@code{#}), in two different places -- as part of the Boolean
1639 value before the @code{t} or @code{f}, and before @emph{value}
1640 in the @code{\set} statement. So when a Boolean is being
1641 entered you need to code two hash signs, e.g., @code{##t}.
1643 Before we can set any of these properties we need to know
1644 in which context they operate. Sometimes this is obvious,
1645 but occasionally it can be tricky. If the wrong context
1646 is specified, no error message is produced, but the expected
1647 action will not take place. For example, the
1648 @code{instrumentName} clearly lives in the Staff context, since
1649 it is the staff that is to be named.
1650 In this example the first staff is labelled, but not the second,
1651 because we omitted the context name.
1653 @lilypond[quote,verbatim,ragged-right]
1655 \new Staff \relative c'' {
1656 \set Staff.instrumentName = #"Soprano"
1659 \new Staff \relative c' {
1660 \set instrumentName = #"Alto" % Wrong!
1666 Remember the default context name is Voice, so the second
1667 @code{\set} command set the property @code{instrumentName} in the
1668 Voice context to @qq{Alto}, but as LilyPond does not look
1669 for any such property in the @code{Voice} context, no
1670 further action took place. This is not an error, and no error
1671 message is logged in the log file.
1673 Similarly, if the property name is mis-spelt no error message
1674 is produced, and clearly the expected action cannot be performed.
1675 If fact, you can set any (fictitious) @q{property} using any
1676 name you like in any context that exists by using the
1677 @code{\set} command. But if the name is not
1678 known to LilyPond it will not cause any action to be taken.
1679 This is one of the reasons why it is highly recommended to
1680 use a context-sensitive editor with syntax highlighting for
1681 editing LilyPond input files, such as Vim, Jedit, ConTEXT or Emacs,
1682 since unknown property names will be highlighted differently.
1684 The @code{instrumentName} property will take effect only
1685 if it is set in the @code{Staff} context, but
1686 some properties can be set in more than one context.
1687 For example, the property @code{extraNatural} is by
1688 default set to ##t (true) for all staves.
1689 If it is set to ##f (false) in one particular @code{Staff}
1690 context it applies just to the accidentals on that staff.
1691 If it is set to false in the @code{Score} context
1692 it applies to all staves.
1694 So this turns off extra naturals in one staff:
1696 @lilypond[quote,verbatim,ragged-right]
1698 \new Staff \relative c'' {
1701 \new Staff \relative c'' {
1702 \set Staff.extraNatural = ##f
1709 and this turns them off in all staves:
1711 @lilypond[quote,verbatim,ragged-right]
1713 \new Staff \relative c'' {
1716 \new Staff \relative c'' {
1717 \set Score.extraNatural = ##f
1723 The value of every property set in this way can be reset
1724 to its original value with the @code{\unset} command.
1726 The @code{\set} and @code{\unset} commands can appear anywhere
1727 in the input file and will take effect from the time they are
1728 encountered until the end of the score or until the property is
1729 @code{\set} or @code{\unset} again. Let's try changing the
1730 font size, which affects the size of the note heads (among
1731 other things) several times. The change is from the default
1732 value, not the current value.
1734 @lilypond[quote,verbatim,ragged-right,relative=1,fragment]
1736 % make note heads smaller
1739 % make note heads larger
1740 \set fontSize = #2.5
1742 % return to original size
1747 We have now seen how to set the values of several different
1748 types of property. Note that integers and numbers are alway
1749 preceded by a hash sign, @code{#}, while a true or false value
1750 is specified by ##t and ##f, with two hash signs. A text
1751 property should be enclosed in double quotation signs, as above,
1752 although we shall see later that text can actually be specified
1753 in a much more general way by using the very powerful
1754 @code{markup} command.
1759 Context properties may also be set at the time the context is
1760 created. Sometimes this is a clearer way of specifying a
1761 property value if it is to remain fixed for the duration of
1762 the context. When a context is created with a @code{\new}
1763 command it may be followed immediately by a
1764 @code{\with @{ .. @}} block in which the property values are
1765 set. For example, if we wish to suppress the printing of
1766 extra naturals for the duration of a staff we would write:
1769 \new Staff \with @{ extraNatural = ##f @}
1775 @lilypond[quote,verbatim,ragged-right]
1781 \new Staff \with { extraNatural = ##f }
1788 In effect this overrides the default value of the property. It
1789 may still be changed dynamically using @code{\set} and returned
1790 to its (new) default value with @code{\unset}.
1792 @node Adding and removing engravers
1793 @subsection Adding and removing engravers
1795 @cindex Engravers, adding
1796 @cindex Engravers, removing
1801 We have seen that contexts each contain several engravers, each
1802 of which is responsible for producing a particular part of the
1803 output, like bar lines, staves, note heads, stems, etc. If an
1804 engraver is removed from a context it can no longer produce its
1805 output. This is a crude way of modifying the output, but it
1806 can sometimes be useful.
1808 @subsubheading Changing a single context
1810 To remove an engraver from a single context we use the
1811 @code{\with} command placed immediately after the context creation
1812 command, as in the previous section.
1815 illustration let's repeat an example from the previous
1816 section with the staff lines removed. Remember that the
1817 staff lines are produced by the Staff_symbol_engraver.
1819 @lilypond[quote,verbatim,ragged-right]
1821 \remove Staff_symbol_engraver
1825 \set fontSize = #-4 % make note heads smaller
1827 \set fontSize = #2.5 % make note heads larger
1829 \unset fontSize % return to original size
1834 @cindex ambitus engraver
1836 Engravers can also be added to individual contexts.
1837 The command to do this is
1839 @code{\consists @emph{Engraver_name}},
1841 placed inside a @code{\with} block. Some vocal scores
1842 have an @rglos{ambitus} placed at the beginning of a
1843 staff to indicate the range of notes in that staff.
1844 The ambitus is produced by the @code{Ambitus_engraver},
1845 which is not normally included in any context. If
1846 we add it to the @code{Voice} context it calculates
1847 the range from that voice only:
1849 @lilypond[quote,verbatim,ragged-right]
1852 \consists Ambitus_engraver
1867 but if we add the Ambitus engraver to the
1868 @code{Staff} context it calculates the range from all
1869 the notes in all the voices on that staff:
1871 @lilypond[quote,verbatim,ragged-right]
1873 \consists Ambitus_engraver
1889 @subsubheading Changing all contexts of the same type
1891 The examples above show how to remove or add engravers to
1892 individual contexts. It is also possible to remove or add
1893 engravers to every context of a specific type by placing the
1894 commands in the appropriate context in a @code{\layout}
1895 block. For example, if we wanted to show an ambitus for every
1896 staff in a four-staff score we could write
1898 @lilypond[quote,verbatim,ragged-right]
1902 \relative c'' { c a b g }
1905 \relative c' { c a b g }
1909 \relative c' { c a b g }
1913 \relative c { c a b g }
1919 \consists Ambitus_engraver
1926 The default values of context properties may also be set
1927 for all contexts of a particular type by including the
1928 @code{\set} command in a @code{\context} block in the
1931 @node Extending the templates
1932 @section Extending the templates
1934 You've read the tutorial, you know how to write music, you
1935 understand the fundamental concepts. But how can you
1936 get the staves that you want? Well, you can find lots of
1937 templates (see @ref{Templates}) which may give you a start.
1939 if you want something that isn't covered there? Read on.
1941 TODO Add links to templates after they have been moved to LSR
1944 * Soprano and cello::
1945 * Four-part SATB vocal score::
1946 * Building a score from scratch::
1949 @node Soprano and cello
1950 @subsection Soprano and cello
1952 Start off with the template that seems closest to what you want to end
1953 up with. Let's say that you want to write something for soprano and
1954 cello. In this case, we would start with @q{Notes and lyrics} (for the
1958 \version @w{"@version{}"}
1959 melody = \relative c' @{
1966 text = \lyricmode @{
1972 \new Voice = "one" @{
1976 \new Lyrics \lyricsto "one" \text
1983 Now we want to add a cello part. Let's look at the @q{Notes only} example:
1986 \version @w{"@version{}"}
1987 melody = \relative c' @{
2001 We don't need two @code{\version} commands. We'll need the
2002 @code{melody} section. We don't want two @code{\score} sections
2003 -- if we had two @code{\score}s, we'd get the two parts separately.
2004 We want them together, as a duet. Within the @code{\score}
2005 section, we don't need two @code{\layout} or @code{\midi}.
2007 If we simply cut and paste the @code{melody} section, we would
2008 end up with two @code{melody} definitions. This would not generate
2009 an error, but the second one would be used for both melodies.
2010 So let's rename them to make them distinct. We'll call the
2011 section for the soprano @code{sopranoMusic} and the section for
2012 the cello @code{celloMusic}. While we're doing this, let's rename
2013 @code{text} to be @code{sopranoLyrics}. Remember to rename both
2014 instances of all these names -- both the initial definition (the
2015 @code{melody = \relative c' @{ } part) and the name's use (in the
2016 @code{\score} section).
2018 While we're doing this, let's change the cello part's staff --
2019 celli normally use bass clef. We'll also give the cello some
2023 \version @w{"@version{}"}
2024 sopranoMusic = \relative c' @{
2031 sopranoLyrics = \lyricmode @{
2035 celloMusic = \relative c @{
2044 \new Voice = "one" @{
2048 \new Lyrics \lyricsto "one" \sopranoLyrics
2055 This is looking promising, but the cello part won't appear in the
2056 score -- we haven't used it in the @code{\score} section. If we
2057 want the cello part to appear under the soprano part, we need to add
2060 \new Staff \celloMusic
2064 underneath the soprano stuff. We also need to add @code{<<} and
2065 @code{>>} around the music -- that tells LilyPond that there's
2066 more than one thing (in this case, two @code{Staves}) happening
2067 at once. The @code{\score} looks like this now
2069 @c Indentation in this example is deliberately poor
2074 \new Voice = "one" @{
2078 \new Lyrics \lyricsto "one" \sopranoLyrics
2080 \new Staff \celloMusic
2088 This looks a bit messy; the indentation is messed up now. That is
2089 easily fixed. Here's the complete soprano and cello template.
2091 @lilypond[quote,verbatim,ragged-right,addversion]
2092 sopranoMusic = \relative c' {
2099 sopranoLyrics = \lyricmode {
2103 celloMusic = \relative c {
2113 \new Voice = "one" {
2117 \new Lyrics \lyricsto "one" \sopranoLyrics
2119 \new Staff \celloMusic
2127 @node Four-part SATB vocal score
2128 @subsection Four-part SATB vocal score
2130 Most vocal scores of music written for four-part mixed choir
2131 with orchestral accompaniment such as Mendelssohn's Elijah or
2132 Handel's Messiah have the choral music and words on four
2133 staves, one for each of SATB, with a piano reduction of the
2134 orchestral accompaniment underneath. Here's an example
2135 from Handel's Messiah:
2137 @c The following should appear as music without code
2138 @lilypond[quote,ragged-right]
2139 global = { \key d \major \time 4/4 }
2140 sopMusic = \relative c'' {
2142 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
2144 sopWords = \lyricmode {
2145 Wor -- thy is the lamb that was slain
2147 altoMusic = \relative a' {
2149 r4 a2 a4 | fis4. fis8 a2 | g4 fis e2 |
2151 altoWords = \sopWords
2152 tenorMusic = \relative c' {
2154 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
2156 tenorWords = \sopWords
2157 bassMusic = \relative c' {
2159 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
2161 bassWords = \sopWords
2162 upper = \relative a' {
2165 r4 <a d fis>2 <a e' a>4 |
2166 <d fis d'>4. <d fis d'>8 <a d a'>2 |
2167 <g cis g'>4 <a d fis> <a cis e>2 |
2169 lower = \relative c, {
2172 <d d'>4 <d d'>2 <cis cis'>4 |
2173 <b b'>4. <b' b'>8 <fis fis'>2 |
2174 <e e'>4 <d d'> <a' a'>2 |
2178 << % combine ChoirStaff and PianoStaff in parallel
2180 \new Staff = "sopranos" <<
2181 \set Staff.instrumentName = "Soprano"
2182 \new Voice = "sopranos" { \global \sopMusic }
2184 \new Lyrics \lyricsto "sopranos" { \sopWords }
2185 \new Staff = "altos" <<
2186 \set Staff.instrumentName = "Alto"
2187 \new Voice = "altos" { \global \altoMusic }
2189 \new Lyrics \lyricsto "altos" { \altoWords }
2190 \new Staff = "tenors" <<
2191 \set Staff.instrumentName = "Tenor"
2192 \new Voice = "tenors" { \global \tenorMusic }
2194 \new Lyrics \lyricsto "tenors" { \tenorWords }
2195 \new Staff = "basses" <<
2196 \set Staff.instrumentName = "Bass"
2197 \new Voice = "basses" { \global \bassMusic }
2199 \new Lyrics \lyricsto "basses" { \bassWords }
2203 \set PianoStaff.instrumentName = "Piano "
2204 \new Staff = "upper" \upper
2205 \new Staff = "lower" \lower
2211 None of the templates provides this layout exactly. The
2212 nearest is @q{SATB vocal score and automatic piano reduction},
2213 but we need to change the layout and add a piano
2214 accompaniment which is not derived automatically from the
2215 vocal parts. The variables holding the music and words for
2216 the vocal parts are fine, but we shall need to add variables for
2217 the piano reduction.
2219 The order in which the contexts appear in the ChoirStaff of
2220 the template do not correspond with the order in the vocal
2221 score shown above. We need to rearrange them so there are
2222 four staves with the words written directly underneath the
2223 notes for each part.
2224 All the voices should be @code{\voiceOne}, which is
2225 the default, so the @code{\voiceXXX} commands should be removed.
2226 We also need to specify the tenor clef for the tenors.
2227 The way in which lyrics are specified in the template has not yet
2228 been encountered so we need to use the method with which we are
2229 familiar. We should also add the names of each staff.
2231 Doing this gives for our ChoirStaff:
2235 \new Staff = "sopranos" <<
2236 \set Staff.instrumentName = "Soprano"
2237 \new Voice = "sopranos" @{ \global \sopMusic @}
2239 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
2240 \new Staff = "altos" <<
2241 \set Staff.instrumentName = "Alto"
2242 \new Voice = "altos" @{ \global \altoMusic @}
2244 \new Lyrics \lyricsto "altos" @{ \altoWords @}
2245 \new Staff = "tenors" <<
2246 \set Staff.instrumentName = "Tenor"
2247 \new Voice = "tenors" @{ \global \tenorMusic @}
2249 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
2250 \new Staff = "basses" <<
2251 \set Staff.instrumentName = "Bass"
2252 \new Voice = "basses" @{ \global \bassMusic @}
2254 \new Lyrics \lyricsto "basses" @{ \bassWords @}
2258 Next we must work out the piano part. This is
2259 easy - we just pull out the piano part from the
2260 @q{Solo piano} template:
2264 \set PianoStaff.instrumentName = "Piano "
2265 \new Staff = "upper" \upper
2266 \new Staff = "lower" \lower
2270 and add the variable definitions for @code{upper}
2273 The ChoirStaff and PianoStaff must be combined
2274 using angle brackets as we want them to be
2275 stacked one above the other:
2278 << % combine ChoirStaff and PianoStaff one above the other
2280 \new Staff = "sopranos" <<
2281 \new Voice = "sopranos" @{ \global \sopMusic @}
2283 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
2284 \new Staff = "altos" <<
2285 \new Voice = "altos" @{ \global \altoMusic @}
2287 \new Lyrics \lyricsto "altos" @{ \altoWords @}
2288 \new Staff = "tenors" <<
2289 \clef "G_8" % tenor clef
2290 \new Voice = "tenors" @{ \global \tenorMusic @}
2292 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
2293 \new Staff = "basses" <<
2295 \new Voice = "basses" @{ \global \bassMusic @}
2297 \new Lyrics \lyricsto "basses" @{ \bassWords @}
2301 \set PianoStaff.instrumentName = "Piano "
2302 \new Staff = "upper" \upper
2303 \new Staff = "lower" \lower
2308 Combining all these together and adding the music
2309 for the three bars of the example above gives:
2311 @lilypond[quote,verbatim,ragged-right,addversion]
2312 global = { \key d \major \time 4/4 }
2313 sopMusic = \relative c'' {
2315 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
2317 sopWords = \lyricmode {
2318 Wor -- thy is the lamb that was slain
2320 altoMusic = \relative a' {
2322 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
2324 altoWords = \sopWords
2325 tenorMusic = \relative c' {
2327 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
2329 tenorWords = \sopWords
2330 bassMusic = \relative c' {
2332 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
2334 bassWords = \sopWords
2335 upper = \relative a' {
2338 r4 <a d fis>2 <a e' a>4 |
2339 <d fis d'>4. <d fis d'>8 <a d a'>2 |
2340 <g cis g'>4 <a d fis> <a cis e>2 |
2342 lower = \relative c, {
2345 <d d'>4 <d d'>2 <cis cis'>4 |
2346 <b b'>4. <b' b'>8 <fis fis'>2 |
2347 <e e'>4 <d d'> <a' a'>2 |
2351 << % combine ChoirStaff and PianoStaff in parallel
2353 \new Staff = "sopranos" <<
2354 \set Staff.instrumentName = "Soprano"
2355 \new Voice = "sopranos" { \global \sopMusic }
2357 \new Lyrics \lyricsto "sopranos" { \sopWords }
2358 \new Staff = "altos" <<
2359 \set Staff.instrumentName = "Alto"
2360 \new Voice = "altos" { \global \altoMusic }
2362 \new Lyrics \lyricsto "altos" { \altoWords }
2363 \new Staff = "tenors" <<
2364 \set Staff.instrumentName = "Tenor"
2365 \new Voice = "tenors" { \global \tenorMusic }
2367 \new Lyrics \lyricsto "tenors" { \tenorWords }
2368 \new Staff = "basses" <<
2369 \set Staff.instrumentName = "Bass"
2370 \new Voice = "basses" { \global \bassMusic }
2372 \new Lyrics \lyricsto "basses" { \bassWords }
2376 \set PianoStaff.instrumentName = "Piano "
2377 \new Staff = "upper" \upper
2378 \new Staff = "lower" \lower
2385 @node Building a score from scratch
2386 @subsection Building a score from scratch
2388 After gaining some facility with writing LilyPond code you
2389 may find that it is easier to build a score from scratch
2390 rather than modifying one of the templates. You can also
2391 develop your own style this way to suit the sort of music you
2392 like. Let's see how to put together the score for an organ
2393 prelude as an example.
2395 We begin with a header section. Here go the title, name
2396 of composer, etc, then come any variable definitions, and
2397 finally the score block. Let's start with these in outline
2398 and fill in the details later.
2400 We'll use the first two bars of Bach's prelude
2401 based on @emph{Jesu, meine Freude} which is written for two
2402 manuals and pedal organ. You can see these two bars of music
2403 at the bottom of this section. The top manual part has two voices,
2404 the lower and pedal organ one each. So we need four
2405 music definitions and one to define the time signature
2409 \version @w{"@version{}"}
2411 title = "Jesu, meine Freude"
2412 composer = "J S Bach"
2414 TimeKey = @{ \time 4/4 \key c \minor @}
2415 ManualOneVoiceOneMusic = @{s1@}
2416 ManualOneVoiceTwoMusic = @{s1@}
2417 ManualTwoMusic = @{s1@}
2418 PedalOrganMusic = @{s1@}
2424 For now we've just used a spacer note, @code{s1},
2425 instead of the real music. We'll add that later.
2427 Next let's see what should go in the score block.
2428 We simply mirror the staff structure we want.
2429 Organ music is usually written on three staves,
2430 one for each manual and one for the pedals. The
2431 manual staves should be bracketed together so we
2432 need to use a PianoStaff for them. The first
2433 manual part needs two voices and the second manual
2438 \new Staff = "ManualOne" <<
2439 \new Voice @{ \ManualOneVoiceOneMusic @}
2440 \new Voice @{ \ManualOneVoiceTwoMusic @}
2441 >> % end ManualOne Staff context
2442 \new Staff = "ManualTwo" <<
2443 \new Voice @{ \ManualTwoMusic @}
2444 >> % end ManualTwo Staff context
2445 >> % end PianoStaff context
2448 Next we need to add a staff for the pedal organ.
2449 This goes underneath the PianoStaff, but it must
2450 be simultaneous with it, so we need angle brackets
2451 round the two. Missing these out would generate
2452 an error in the log file. It's a common mistake
2453 which you'll make sooner or later! Try copying
2454 the final example at the end of this section,
2455 remove these angle brackets, and compile it to
2456 see what errors it generates.
2459 << % PianoStaff and Pedal Staff must be simultaneous
2461 \new Staff = "ManualOne" <<
2462 \new Voice @{ \ManualOneVoiceOneMusic @}
2463 \new Voice @{ \ManualOneVoiceTwoMusic @}
2464 >> % end ManualOne Staff context
2465 \new Staff = "ManualTwo" <<
2466 \new Voice @{ \ManualTwoMusic @}
2467 >> % end ManualTwo Staff context
2468 >> % end PianoStaff context
2469 \new Staff = "PedalOrgan" <<
2470 \new Voice @{ \PedalOrganMusic @}
2475 It is not strictly necessary to use the simultaneous construct
2476 @code{<< >>} for the manual two staff and the pedal organ staff,
2477 since they contain only one music expression, but it does no harm
2478 and always using angle brackets after @code{\new Staff} is a good
2479 habit to cultivate in case there are multiple voices.
2481 Let's add this structure to the score block, and adjust the
2482 indenting. We also add the appropriate clefs, ensure the
2483 second voice stems point down with @code{\voiceTwo} and
2484 enter the time signature and key to each staff using our
2485 predefined variable, @code{\TimeKey}.
2489 << % PianoStaff and Pedal Staff must be simultaneous
2491 \new Staff = "ManualOne" <<
2492 \TimeKey % set time signature and key
2494 \new Voice @{ \ManualOneVoiceOneMusic @}
2495 \new Voice @{ \voiceTwo \ManualOneVoiceTwoMusic @}
2496 >> % end ManualOne Staff context
2497 \new Staff = "ManualTwo" <<
2500 \new Voice @{ \ManualTwoMusic @}
2501 >> % end ManualTwo Staff context
2502 >> % end PianoStaff context
2503 \new Staff = "PedalOrgan" <<
2506 \new Voice @{ \PedalOrganMusic @}
2507 >> % end PedalOrgan Staff
2509 @} % end Score context
2512 That completes the structure. Any three-staff organ music
2513 will have a similar structure, although the number of voices
2514 may vary. All that remains now
2515 is to add the music, and combine all the parts together.
2517 @lilypond[quote,verbatim,ragged-right,addversion]
2519 title = "Jesu, meine Freude"
2520 composer = "J S Bach"
2522 TimeKey = { \time 4/4 \key c \minor }
2523 ManualOneVoiceOneMusic = \relative g' {
2524 g4 g f ees | d2 c2 |
2526 ManualOneVoiceTwoMusic = \relative c' {
2527 ees16 d ees8~ ees16 f ees s c8 d~ d c~ |
2528 c c4 b8 c8. g16 c b c d |
2530 ManualTwoMusic = \relative c' {
2531 c16 b c8~ c16 b c g a8 g~ g16 g aes ees |
2532 f ees f d g aes g f ees d e8~ ees16 f ees d |
2534 PedalOrganMusic = \relative c {
2535 r8 c16 d ees d ees8~ ees16 a, b g c b c8 |
2536 r16 g ees f g f g8 c,2 |
2540 << % PianoStaff and Pedal Staff must be simultaneous
2542 \new Staff = "ManualOne" <<
2543 \TimeKey % set time signature and key
2545 \new Voice { \ManualOneVoiceOneMusic }
2546 \new Voice { \voiceTwo \ManualOneVoiceTwoMusic }
2547 >> % end ManualOne Staff context
2548 \new Staff = "ManualTwo" <<
2551 \new Voice { \ManualTwoMusic }
2552 >> % end ManualTwo Staff context
2553 >> % end PianoStaff context
2554 \new Staff = "PedalOrgan" <<
2557 \new Voice { \PedalOrganMusic }
2558 >> % end PedalOrgan Staff
2560 } % end Score context