1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond-learning.tely
4 @node Fundamental concepts
5 @chapter Fundamental concepts
7 You've seen in the Tutorial how to produce beautifully printed
8 music from a simple text file. This section introduces the
9 concepts and techniques required to produce equally beautiful
10 but more complex scores.
13 * How LilyPond files work::
14 * Voices contain music::
15 * Contexts and engravers::
16 * Extending the templates::
20 @node How LilyPond files work
21 @section How LilyPond files work
23 The LilyPond input format is quite free-form, giving experienced
24 users a lot of flexibility to structure their files however they
25 wish. But this flexibility can make things confusing for new
26 users. This section will explain some of this structure, but may
27 gloss over some details in favor of simplicity. For a complete
28 description of the input format, see @ruser{File structure}.
31 * Introduction to the LilyPond file structure::
32 * Score is a (single) compound musical expression::
33 * Nesting music expressions::
34 * On the un-nestedness of brackets and ties::
37 @node Introduction to the LilyPond file structure
38 @subsection Introduction to the LilyPond file structure
40 A basic example of a lilypond input file is
43 \version @w{"@version{}"}
45 @var{...compound music expression...} % all the music goes here!
53 There are many variations of this basic pattern, but this
54 example serves as a useful starting place.
56 Up to this point none of the examples you have seen has used a
57 @code{\score@{@}} command. This is because LilyPond automatically
58 adds the extra commands which are needed when you give it simple
59 input. LilyPond treats input like this:
68 as shorthand for this:
85 In other words, if the input contains a single music expression,
86 LilyPond will interpret the file as though the music expression
87 was wrapped up inside the commands shown above. For now, though,
88 let us return to the first example and examine the @code{\score}
89 command, leaving the others to default.
91 A @code{\score} block must always contain just one music
93 this must appear immediately after the @code{\score} command.
94 Remember that a music expression could be anything from a single
95 note to a huge compound expression like
100 @var{...insert the whole score of a Wagner opera in here...}
106 Since everything is inside @code{@{ ... @}}, it counts
107 as one music expression.
109 As we saw previously, the @code{\score} block can contain other
122 Some people put some of those commands outside the @code{\score}
123 block -- for example, @code{\header} is often placed above the
124 @code{\score} command. That's just another shorthand that LilyPond
127 Two more commands you have not previously seen are
128 @code{\layout @{ @}} and @code{\midi @{@}}. If these appear as
129 shown they will cause LilyPond to produce a printed output and a
130 MIDI output respectively. They are described fully in the
131 Notation Reference -- @ruser{Score layout} and
132 @ruser{Creating MIDI files}.
134 You may code multiple @code{\score} blocks. Each will be
135 treated as a separate score, but they will be all combined into
136 a single output file. A @code{\book} command is not necessary
137 -- one will be implicitly created. However, if you would like
138 separate output files from one @code{.ly} file then the
139 @code{\book} command should be used to separate the different
140 sections: each @code{\book} block will produce a
141 separate output file. For details see @ruser{Multiple scores
146 Another great shorthand is the ability to define variables. All
147 the templates use this
150 melody = \relative c' @{
159 When LilyPond looks at this file, it takes the value of
160 @code{melody} (everything after the equals sign) and inserts it
161 whenever it sees @code{\melody}. There's nothing special about
162 the names -- it could be @code{melody}, @code{global},
164 @code{pianorighthand}, or @code{foofoobarbaz}. For more details,
165 see @ref{Saving typing with variables and functions}.
166 Remember that you can use almost any name you like as long
167 as it contains just alphabetic characters and is distinct from
168 LilyPond command names. The exact
169 limitations on variable names are detailed in
170 @ruser{File structure}.
176 For a complete definition of the input format, see
177 @ruser{File structure}.
179 @node Score is a (single) compound musical expression
180 @subsection Score is a (single) compound musical expression
182 @cindex Compound music expression
183 @cindex Music expression, compound
185 We saw the general organization of LilyPond input files in the
186 previous section, @ref{How LilyPond files work}. But we seemed to
187 skip over the most important part: how do we figure out what to
188 write after @code{\score}?
190 We didn't skip over it at all. The big mystery is simply that
191 there @emph{is} no mystery. This line explains it all:
194 @emph{A @code{\score} block must begin with a compound music expression.}
198 You may find it useful to review
199 @ref{Music expressions explained}. In that section, we saw how to
200 build big music expressions from small pieces -- we started from
201 notes, then chords, etc. Now we're going to start from a big
202 music expression and work our way down.
206 @{ % this brace begins the overall compound music expression
208 @var{...insert the whole score of a Wagner opera in here...}
210 @} % this brace ends the overall compound music expression
215 A whole Wagner opera would easily double the length of this
216 manual, so let's just add a singer and piano. We don't need a
217 @code{GrandStaff} for this ensemble, which simply groups a number
218 of staves together with a brace at the left, so we shall remove
219 it. We @emph{do} need a singer and a piano, though.
224 \new Staff = "singer" <<
226 \new PianoStaff = piano <<
233 Remember that we use @code{<< ... >>} instead of
234 @code{@{ ... @}} to show simultaneous
235 music. And we definitely want to show the vocal part and piano
236 part at the same time, not one after the other! However, the
237 @code{<< ... >>} construct is not really necessary for the Singer
238 staff, as it contains only one music expression, but Staves often
239 do require simultaneous Voices within them, so using
241 rather than braces is a good habit to adopt. We'll add some real
242 music later; for now let's just put in some dummy notes and lyrics.
244 @lilypond[verbatim,quote,ragged-right]
247 \new Staff = "singer" <<
248 \new Voice = "vocal" { c'1 }
251 \new PianoStaff = "piano" <<
252 \new Staff = "upper" { c'1 }
253 \new Staff = "lower" { c'1 }
260 Now we have a lot more details. We have the singer's staff: it
261 contains a @code{Voice} (in LilyPond, this term refers to a set of
262 notes, not necessarily vocal notes -- for example, a violin
263 generally plays one voice) and some lyrics. We also have a piano
264 staff: it contains an upper staff (right hand) and a lower staff
267 At this stage, we could start filling in notes. Inside the curly
268 braces next to @code{\new Voice = vocal}, we could start writing
276 But if we did that, the @code{\score} section would get pretty
277 long, and it would be harder to understand what was happening. So
278 let's use variables instead. These were introduced at the end
279 of the previous section, remember? So, adding a few notes, we
280 now have a piece of real music:
282 @lilypond[verbatim,quote,ragged-right]
283 melody = \relative c'' { r4 d8\noBeam g, c4 r }
284 text = \lyricmode { And God said, }
285 upper = \relative c'' { <g d g,>2~ <g d g,> }
286 lower = \relative c { b2 e2 }
290 \new Staff = "singer" <<
291 \new Voice = "vocal" { \melody }
294 \new PianoStaff = "piano" <<
295 \new Staff = "upper" { \upper }
296 \new Staff = "lower" {
307 Be careful about the difference between notes, which are introduced
308 with @code{\relative}, and lyrics, which are introduced with
309 @code{\lyricmode}. These are essential to tell LilyPond
310 to interpret the following content as music and text
313 When writing (or reading) a @code{\score} section, just take it
314 slowly and carefully. Start with the outer layer, then work on
315 each smaller layer. It also really helps to be strict with
316 indentation -- make sure that each item on the same layer starts
317 on the same horizontal position in your text editor.
320 @node Nesting music expressions
321 @subsection Nesting music expressions
323 It is not essential to declare all staves at the beginning;
324 they may be introduced temporarily at any point. This is
325 particularly useful for creating ossia sections
326 (see @rglos{ossia}). Here is a simple example showing how
327 to introduce a new staff temporarily for the duration of
330 @lilypond[verbatim,quote,ragged-right]
347 Note that the size of the clef is the same as a clef printed
348 following a clef change -- slightly smaller than the clef
349 at the begining of the line. This is usual for clefs printed
350 in the middle of a line.
352 The ossia section may be placed above the staff
355 @lilypond[verbatim,quote,ragged-right]
363 alignAboveContext = "main" }
371 This example uses @code{\with}, which will be explained more
372 fully later. It is a means of modifying the default behaviour
373 of a single Staff. Here it says that the new staff should be
374 placed above the staff called @qq{main} instead of the default
375 position which is below.
377 Ossia are often written without clef and without
378 time signature and are usually in a smaller font.
379 These require further commands which
380 have not yet been introduced. See @ref{Size of objects}
382 @node On the un-nestedness of brackets and ties
383 @subsection On the un-nestedness of brackets and ties
385 You have already met a number of different types of bracket in
386 writing the input file to LilyPond. These obey different rules
387 which can be confusing at first. Before we explain the rules
388 let's first review the different types of bracket.
390 @c attempt to force this onto a new page
392 @multitable @columnfractions .3 .7
393 @headitem Bracket Type
395 @item @code{@{ .. @}}
396 @tab Encloses a sequential segment of music
398 @tab Encloses the notes of a chord
399 @item @code{<< .. >>}
400 @tab Encloses concurrent or simultaneous sections
402 @tab Marks the start and end of a slur
403 @item @code{\( .. \)}
404 @tab Marks the start and end of a phrase mark
406 @tab Marks the start and end of a manual beam
409 To these we should add other constructs which generate lines
410 between or across notes: ties (marked by a tilde, @code{~}),
411 tuplets written as @code{\times x/y @{..@}}, and grace notes
412 written as @code{\grace@{..@}}.
414 Outside LilyPond, the conventional use of brackets requires
415 the different types to be properly nested, like this,
416 @code{<< [ @{ ( .. ) @} ] >>}, with the closing brackets being
417 encountered in exactly the opposite order to the opening
418 brackets. This @strong{is} a requirement for the three types of
419 bracket described by the word @q{Encloses} in the table above --
420 they must nest properly.
421 However, the remaining brackets, described with the word
422 @q{Marks} in the table above together with ties and tuplets,
423 do @strong{not} have to nest
424 properly with any of the brackets. In fact, these are not
425 brackets in the sense that
426 they enclose something -- they are simply markers to indicate
427 where something starts and ends.
429 So, for example, a phrasing slur can start before a manually
430 inserted beam and end before the end of the beam -- not very
431 musical, perhaps, but possible:
433 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
434 { g8\( a b[ c b\) a] }
437 In general, different kinds of brackets, and those implied by
438 tuplets, ties and grace notes, may be mixed freely.
439 This example shows a beam extending into a tuplet (line 1),
440 a slur extending into a tuplet (line 2),
441 a beam and a slur extending into a tuplet, a tie crossing
442 two tuplets, and a phrasing slur extending out of a tuplet
445 @lilypond[quote,verbatim,fragment,ragged-right]
447 r16[ g16 \times 2/3 {r16 e'8] }
448 g16( a \times 2/3 {b d) e' }
449 g8[( a \times 2/3 {b d') e'~]}
450 \times 4/5 {e'32\( a b d' e'} a'4.\)
455 @node Voices contain music
456 @section Voices contain music
458 Singers need voices to sing, and so does LilyPond.
459 The actual music for all instruments in a score
460 is contained in Voices -- the most fundamental
461 of all LilyPond's concepts.
464 * I'm hearing Voices::
465 * Explicitly instantiating voices::
466 * Voices and vocals::
469 @node I'm hearing Voices
470 @subsection I'm hearing Voices
474 @cindex Voice context
476 The lowest, most fundamental or innermost layers in a LilyPond
477 score are called @q{Voice contexts} or just @q{Voices} for short.
478 Voices are sometimes called @q{layers} in other notation
481 In fact, a Voice layer or context is the only one which can
482 contain music. If a Voice context is not explicitly declared
483 one is created automatically, as we saw at the beginning of
484 this chapter. Some instruments such as an
485 Oboe can play only one note at a time. Music written for
486 such instruments is monophonic and requires just a single
487 voice. Instruments which can play more than one note at a
488 time like the piano will often require multiple voices to
489 encode the different concurrent notes and rhythms they are
492 A single voice can contain many notes in a chord, of course,
493 so when exactly are multiple voices needed? Look first at
494 this example of four chords:
496 @lilypond[quote,verbatim,fragment,ragged-right,relative=1]
498 <d g>4 <d fis> <d a'> <d g>
501 This can be expressed using just the single angle bracket chord
502 symbols, @code{< ... >}, and for this just a single voice is
503 needed. But suppose the F-sharp were actually an eighth-note
504 followed by an eighth-note G, a passing note on the way to the A?
505 Now we have two notes which start at the same time but have
506 different durations: the quarter-note D and the eighth-note
507 F-sharp. How are these to be coded? They cannot be written as
508 a chord because all the notes in a chord must have the same
509 duration. And they cannot be written as two separate notes
510 as they need to start at the same time. This is when two
513 Let us see how this is done in LilyPond input syntax.
518 The easiest way to enter fragments with more than one voice on a
519 staff is to enter each voice as a sequence (with @code{@{...@}}),
520 and combine them simultaneously with angle brackets, @code{<<...>>}.
521 The fragments must also be separated with double backward slashes,
522 @code{\\}, to place them in separate voices. Without these, the
523 notes would be entered into a single voice, which would usually
524 cause errors. This technique is particularly suited to pieces of
525 music which are largely monophonic with occasional short sections
528 Here's how we split the chords above into two voices and add both
529 the passing note and a slur:
531 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
533 % Voice "1" Voice "2"
534 << { g4 fis8( g) a4 g } \\ { d4 d d d } >> |
537 Notice how the stems of the second voice now point down.
539 Here's another simple example:
541 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
543 % Voice "1" Voice "2"
544 << { r4 g g4. a8 } \\ { d,2 d4 g } >> |
545 << { bes4 bes c bes } \\ { g4 g g8( a) g4 } >> |
546 << { a2. r4 } \\ { fis2. s4 } >> |
549 It is not necessary to use a separate @code{<< \\ >>} construct
550 for each bar. For music with few notes in each bar this layout
551 can help the legibility of the code, but if there are many
552 notes in each bar it may be better to split out each voice
553 separately, like this:
555 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
571 This example has just two voices, but the same contruct may be
572 used to encode three or more voices by adding more back-slash
575 The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
576 In each of these contexts, the vertical direction of slurs,
577 stems, ties, dynamics etc., is set appropriately.
579 @lilypond[quote,verbatim,fragment]
580 \new Staff \relative c' {
583 % Voice "1" Voice "2" Voice "3"
584 << { g4 f e } \\ { r8 e4 d c8 ~ } >> |
585 << { d2 e2 } \\ { c8 b16 a b8 g ~ g2 } \\ { s4 b4 c2 } >> |
589 These voices are all separate from the main voice that contains
590 the notes just outside the @code{<< .. >>} construct. Let's call
591 this the @emph{simultaneous construct}. Slurs and ties may only
592 connect notes within the same voice, so slurs and ties cannot go
593 into or out of a simultaneous construct. Conversely,
594 parallel voices from separate simultaneous constructs on the same
595 staff are the same voice. Other voice-related properties also
596 carry across simultaneous constructs. Here is the same example,
597 with different colors and note heads for each voice. Note that
598 changes in one voice do not affect other voices, but they do
599 persist in the same voice later. Note also that tied notes may be
600 split across the same voices in two constructs, shown here in the
603 @lilypond[quote,verbatim]
604 \new Staff \relative c' {
623 { c8 b16 a b8 g ~ g2 }
633 The commands @code{\voiceXXXStyle} are mainly intended for use in
634 educational documents such as this one. They modify the color
635 of the note head, the stem and the beams, and the style of the
636 note head, so that the voices may be easily distinguished.
637 Voice one is set to red diamonds, voice two to blue triangles,
638 voice three to green crossed circles, and voice four (not used
639 here) to magenta crosses. We shall see later how commands like
640 these may be created by the user.
641 See @ref{Visibility and color of objects}
642 TODO Add link to using variables for tweaks
644 Polyphony does not change the relationship of notes within a
645 @code{\relative @{ @}} block. Each note is still calculated
646 relative to the note immediately preceding it, or to the first
647 note of the preceding chord. So in
650 \relative c' @{ noteA << < noteB noteC > \\ noteD >> noteE @}
654 @code{noteB} is relative to @code{noteA} @*
655 @code{noteC} is relative to @code{noteB}, not @code{noteA}; @*
656 @code{noteD} is relative to @code{noteB}, not @code{noteA} or
658 @code{noteE} is relative to @code{noteD}, not @code{noteA}
660 An alternative way, which may be clearer if the notes in the
661 voices are widely separated, is to place a @code{\relative}
662 command at the start of each voice:
665 \relative c' @{ noteA ... @}
667 \relative c'' @{ < noteB noteC > ... @}
669 \relative g' @{ noteD ... @}
671 \relative c' @{ noteE ... @}
674 Let us finally analyse the voices in a more complex piece of
676 the notes from the first two bars of the second of Chopin's
677 Deux Nocturnes, Op 32. This example will be used at later
678 stages in this and the next chapter to illustrate several
679 techniques for producing notation, so please ignore for now
680 anything in the underlying code which looks mysterious and
681 concentrate just on the music and the voices -- the
682 complications will all be explained in later sections.
684 @c The following should appear as music without code
685 @lilypond[quote,ragged-right]
686 \new Staff \relative c'' {
695 % Ignore these for now - they are explained in Ch 4
696 \once \override NoteColumn #'force-hshift = #0
698 \once \override NoteColumn #'force-hshift = #0.5
706 The direction of the stems is often used to indicate the
707 continuity of two simultaneous melodic lines. Here the
708 stems of the highest notes are all pointing up and the
709 stems of the lower notes are all pointing down.
710 This is the first indication that more than one voice
713 But the real need for multiple voices arises when notes
714 which start at the same time have different durations.
715 Look at the notes which start at beat three in the first
716 bar. The A-flat is a dotted quarter note, the F is a
717 quarter note and the D-flat is a half note. These
718 cannot be written as a chord as all the notes in a chord
719 must have the same duration. Neither can they be written
720 as sequential notes, as they must start at the same time.
721 This section of the bar requires three voices, and the
722 normal practice would be to write the whole bar as three
723 voices, as shown below, where we have used different note heads
724 and colors for the three voices. Again, the code behind this
725 example will be explained later, so ignore anything you do
728 @c The following should appear as music without code
729 @c The three voice styles should be defined in -init
730 @lilypond[quote,ragged-right]
731 \new Staff \relative c'' {
742 \\ % No Voice three (we want stems down)
745 % Ignore these for now - they are explained in Ch 4
746 \once \override NoteColumn #'force-hshift = #0
748 \once \override NoteColumn #'force-hshift = #0.5
757 Let us try to encode this music from scratch. As we
758 shall see, this encounters some difficulties. We begin as
759 we have learnt, using the @code{<< \\ >>} construct to
760 enter the music of the first bar in three voices:
762 @lilypond[quote,verbatim,fragment,ragged-right]
763 \new Staff \relative c'' {
766 { c2 aes4. bes8 } \\ { aes2 f4 fes } \\ { <ees c>2 des2 }
775 The stem directions are automatically assigned with the
776 odd-numbered voices taking upward stems and the even-numbered
777 voices downward ones. The stems for voices 1 and 2 are right,
778 but the stems in voice 3 should go down in this particular piece
779 of music. We can correct this simply by missing out voice three
780 and placing the music in voice four:
782 @lilypond[quote,verbatim,fragment,ragged-right]
783 \new Staff \relative c'' {
789 \\ % Omit Voice three
798 We see that this fixes the stem direction, but exposes a
799 problem sometimes encountered with multiple voices -- the
800 stems of the notes in one voice can collide with the note heads
801 in other voices. In laying out the notes, LilyPond allows the
802 notes or chords from two voices to occupy the same vertical
803 note column provided the stems are in opposite directions, but
804 the notes from the third and fourth voices are displaced to if
805 necessary to avoid the note heads
806 colliding. This usually works well, but in this example the
807 notes of the lowest voice are clearly not well placed by default.
808 LilyPond provides several ways to adjust the horizontal placing
809 of notes. We are not quite ready yet to see how to correct this,
810 so we shall leave this problem until a later section
811 (see the force-hshift property in @ref{Fixing overlapping
814 @node Explicitly instantiating voices
815 @subsection Explicitly instantiating voices
819 @funindex \voiceThree
822 Voice contexts can also be created manually
823 inside a @code{<< >>} block to create polyphonic music, using
824 @code{\voiceOne} ... @code{\voiceFour} to indicate the required
825 directions of stems, slurs, etc. In longer scores this method
826 is clearer, as it permits the voices to be separated and to be
827 given more descriptive names.
829 Specifically, the construct @code{<< \\ >>} which we used in
830 the previous section:
835 << @{ e4 f g a @} \\ @{ c,4 d e f @} >>
845 \new Voice = "1" @{ \voiceOne \relative c' @{ e4 f g a @} @}
846 \new Voice = "2" @{ \voiceTwo \relative c' @{ c4 d e f @} @}
850 Both of the above would produce
852 @c The following example should not display the code
853 @lilypond[ragged-right,quote]
855 \new Voice = "1" { \voiceOne \relative c' { e4 f g a } }
856 \new Voice = "2" { \voiceTwo \relative c' { c4 d e f } }
860 The @code{\voiceXXX} commands set the direction of stems, slurs,
861 ties, articulations, text annotations, augmentation dots of dotted
862 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
863 make these objects point upwards, while @code{\voiceTwo} and
864 @code{\voiceFour} make them point downwards. These commands also
865 generate a horizontal shift for each voice when this is required
866 to avoid clashes of note heads. The command @code{\oneVoice}
867 reverts the settings back to the normal values for a single voice.
869 Let us see in some simple examples exactly what effect
870 @code{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on
871 markup, ties, slurs, and dynamics:
873 @lilypond[quote,ragged-right,verbatim]
875 % Default behaviour or behaviour after \oneVoice
876 c d8 ~ d e4 ( f g a ) b-> c
880 @lilypond[quote,ragged-right,verbatim]
883 c d8 ~ d e4 ( f g a ) b-> c
885 c, d8 ~ d e4 ( f g a ) b-> c
889 @lilypond[quote,ragged-right,verbatim]
892 c d8 ~ d e4 ( f g a ) b-> c
894 c, d8 ~ d e4 ( f g a ) b-> c
898 An expression that appears directly inside a @code{<< >>} belongs
899 to the main voice (but, note, @strong{not} in a @code{<< \\ >>}
900 construct). This is useful when extra voices appear while the
901 main voice is playing. Here is a more correct rendition of the
902 example from the previous section. The red diamond-shaped notes
903 demonstrate that the main melody is now in a single voice context,
904 permitting a phrasing slur to be drawn over them.
906 @lilypond[quote,ragged-right,verbatim]
907 \new Staff \relative c' {
909 % The following notes are monophonic
911 % Start simultaneous section of three voices
913 % Continue the main voice in parallel
915 % Initiate second voice
917 % Set stems, etc, down
919 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
921 % Initiate third voice
931 @cindex nesting music expressions
932 @cindex nesting simultaneous constructs
934 More deeply nested polyphony constructs are possible, and if a
935 voice appears only briefly this might be a more natural way to
938 @lilypond[quote,ragged-right,verbatim]
939 \new Staff \relative c' {
959 This method of nesting new voices briefly is useful
960 when only small sections of the music
961 are polyphonic, but when the whole staff is largely polyphonic
962 it can be clearer to use multiple voices throughout, using
963 spacing notes to step over sections where the voice is silent,
966 @lilypond[quote,ragged-right,verbatim]
967 \new Staff \relative c' <<
968 % Initiate first voice
971 c16^( d e f g4 f e | d2 e2) |
973 % Initiate second voice
975 % set stems, etc down
977 s4 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 |
979 % Initiate third voice
989 @cindex shift commands
995 Closely spaced notes in a chord, or notes occuring at the same
996 time in different voices, are arranged in two, occasionally more,
997 columns to prevent the note heads overlapping. These are called
998 note columns. There are separate columns for each voice, and
999 the currently specified voice-dependent shift is applied to the
1000 note column if there would otherwise be a collision. This can
1001 be seen in the example above. In bar 2 the C in voice two is
1002 shifted to the right relative to the D in voice one, and in the
1003 final chord the C in voice three is also shifted to the right
1004 relative to the other notes.
1006 The @code{\shiftOn}, @code{\shiftOnn}, @code{\shiftOnnn}, and
1007 @code{\shiftOff} commands specify the degree to which notes and
1008 chords of the voice should be shifted if a collision
1009 would otherwise occur. By default, the outer voices (normally
1010 voices one and two) have @code{\shiftOff} specified, while the
1011 inner voices (three and four) have @code{\shiftOn} specified.
1012 When a shift is applied, Voices one and three are shifted to
1013 the right and voices two and four to the left.
1015 @code{\shiftOnn} and @code{\shiftOnnn} define further shift
1016 levels which may be specified temporarily to resolve collisions
1017 in complex situations -- see @ref{Real music example}.
1019 A note column can contain just one note (or chord) from a voice
1020 with stems up and one note (or chord) from a voice with stems
1021 down. If notes from two voices which have their stems in the
1022 same direction are placed at the same position and both voices
1023 have no shift or the same shift specified, the error message
1024 @qq{Too many clashing note columns} will be produced.
1026 @node Voices and vocals
1027 @subsection Voices and vocals
1029 Vocal music presents a special difficulty: we need to combine two
1030 expressions -- notes and lyrics.
1032 You have already seen the @code{\addlyrics@{@}} command, which
1033 handles simple scores well. However, this technique is
1034 quite limited. For more complex music, you must introduce the
1035 lyrics in a @code{Lyrics} context using @code{\new Lyrics} and
1037 the lyrics to the notes with @code{\lyricsto@{@}}, using the
1038 name assigned to the Voice.
1040 @lilypond[quote,verbatim,fragment]
1042 \new Voice = "one" \relative c'' {
1045 c4 b8. a16 g4. f8 e4 d c2
1047 \new Lyrics \lyricsto "one" {
1048 No more let sins and sor -- rows grow.
1053 The automatic beaming which LilyPond uses by default works well
1054 for instrumental music, but not so well for music with lyrics,
1055 where beaming is either not required at all or is used to indicate
1056 melismata in the lyrics. In the example above we use the command
1057 @code{\autoBeamOff} to turn off the automatic beaming.
1059 Let us reuse the earlier example from Judas Maccabæus to
1060 illustrate this more flexible technique. We first recast
1061 it to use variables so the music and lyrics can be separated
1062 from the staff structure. We also introduce a ChoirStaff
1063 bracket. The lyrics themselves must be introduced with
1064 @code{\lyricmode} to ensure they are interpreted as lyrics
1067 @lilypond[quote,verbatim]
1068 global = { \time 6/8 \partial 8 \key f \major}
1069 SopOneMusic = \relative c'' {
1070 c8 | c([ bes)] a a([ g)] f | f'4. b, | c4.~ c4 }
1071 SopTwoMusic = \relative c' {
1072 r8 | r4. r4 c8 | a'([ g)] f f([ e)] d | e([ d)] c bes' }
1073 SopOneLyrics = \lyricmode {
1074 Let | flee -- cy flocks the | hills a -- dorn, __ }
1075 SopTwoLyrics = \lyricmode {
1076 Let | flee -- cy flocks the | hills a -- dorn, }
1081 \new Voice = "SopOne" {
1085 \new Lyrics \lyricsto "SopOne" {
1090 \new Voice = "SopTwo" {
1094 \new Lyrics \lyricsto "SopTwo" {
1102 This is the basic structure of all vocal scores. More staves may
1103 be added as required, more voices may be added to the staves,
1104 more verses may be added to the lyrics,
1105 and the variables containing the music can easily be placed
1106 in separate files should they become too long.
1108 Here is a final example of the first line of a hymn with four
1109 verses, set for SATB. In this case the words for all four
1112 @lilypond[quote,verbatim]
1113 TimeKey = { \time 4/4 \partial 4 \key c \major}
1114 SopMusic = \relative c' { c4 | e4. e8 g4 g | a a g }
1115 AltoMusic = \relative c' { c4 | c4. c8 e4 e | f f e }
1116 TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 }
1117 BassMusic = \relative c { c4 | c4. c8 c4 c | f8 g a b c4 }
1118 VerseOne = \lyricmode {
1119 E -- | ter -- nal fa -- ther, | strong to save, }
1120 VerseTwo = \lyricmode {
1121 O | Christ, whose voice the | wa -- ters heard, }
1122 VerseThree = \lyricmode {
1123 O | Ho -- ly Spi -- rit, | who didst brood }
1124 VerseFour = \lyricmode {
1125 O | Tri -- ni -- ty of | love and pow'r }
1131 \new Voice = "Sop" { \voiceOne \TimeKey \SopMusic }
1132 \new Voice = "Alto" { \voiceTwo \AltoMusic }
1133 \new Lyrics \lyricsto "Sop" { \VerseOne }
1134 \new Lyrics \lyricsto "Sop" { \VerseTwo }
1135 \new Lyrics \lyricsto "Sop" { \VerseThree }
1136 \new Lyrics \lyricsto "Sop" { \VerseFour }
1140 \new Voice = "Tenor" { \voiceOne \TimeKey \TenorMusic }
1141 \new Voice = "Bass" { \voiceTwo \BassMusic }
1147 @node Contexts and engravers
1148 @section Contexts and engravers
1150 Contexts and engravers have been mentioned informally
1151 in earlier sections; we now must look at
1152 these concepts in more detail, as they are important
1153 in the fine-tuning of LilyPond output.
1157 * Contexts explained::
1158 * Creating contexts::
1159 * Engravers explained::
1160 * Modifying context properties::
1161 * Adding and removing engravers::
1164 @node Contexts explained
1165 @subsection Contexts explained
1167 When music is printed, many notational elements which do not
1168 appear explicitly in the input file must be added to the
1169 output. For example, compare the input and output of the
1172 @lilypond[quote,verbatim,relative=2,fragment]
1176 The input is rather sparse, but in the output, bar lines,
1177 accidentals, clef, and time signature have been added. When
1178 LilyPond @emph{interprets} the input the musical information
1179 is inspected in time order, similar to reading a score from left
1180 to right. While reading the input, the program remembers where
1181 measure boundaries are, and which pitches require explicit
1182 accidentals. This information must be held on several levels.
1183 For example, the effect of an accidental is limited
1184 to a single staff, while a bar line must be synchronized across
1187 Within LilyPond, these rules and bits of information are grouped
1188 in @emph{Contexts}. We have already met the
1189 @code{Voice} context.
1190 Others are the @code{Staff} and @code{Score} contexts.
1191 Contexts are hierarchical to reflect the heirarchical nature of
1193 For example: a @code{Staff} context can contain many
1194 @code{Voice} contexts, and a @code{Score} context can
1195 contain many @code{Staff} contexts.
1198 @sourceimage{context-example,5cm,,}
1201 Each context has the responsibility for enforcing some notation rules,
1202 creating some notation objects and maintaining the associated
1203 properties. For example, the @code{Voice} context may introduce an
1204 accidental and then the @code{Staff} context maintains the rule to
1205 show or suppress the accidental for the remainder of the measure.
1207 As another example, the synchronization of bar lines is, by default,
1208 handled in the @code{Score} context.
1209 However, in some music we may not want the bar lines to be
1210 synchronized -- consider a polymetric score in 4/4 and 3/4 time.
1211 In such cases, we must modify the default settings of the
1212 @code{Score} and @code{Staff} contexts.
1214 For very simple scores, contexts are created implicitly, and you need
1215 not be aware of them. For larger pieces, such as anything with more
1216 than one staff, they must be
1217 created explicitly to make sure that you get as many staves as you
1218 need, and that they are in the correct order. For typesetting pieces
1219 with specialized notation, it is usual to modify existing, or
1220 even to define totally new, contexts.
1222 In addition to the @code{Score,} @code{Staff} and
1223 @code{Voice} contexts there are contexts which fit between
1224 the score and staff levels to control staff groups, such as the
1225 @code{PianoStaff} and @code{ChoirStaff} contexts. There
1226 are also alternative staff and voice contexts, and contexts for
1227 lyrics, percussion, fret boards, figured bass, etc.
1229 The names of all context types are formed from one or more
1230 words, each word being capitalised and joined immediately to the
1231 preceding word with no hyphen or underscore, e.g.,
1232 @code{GregorianTranscriptionStaff}.
1234 @node Creating contexts
1235 @subsection Creating contexts
1237 There can be only one top level context: the
1239 context. This is created with the @code{\score} command,
1240 or, in simple scores, it is created automatically.
1242 For scores with only one voice and one staff, the
1243 @code{Voice} and @code{Staff} contexts may be left to be
1244 created automatically, but for more complex scores it is
1245 necessary to create them by hand.
1246 The simplest command that does this is @code{\new}.
1247 It is prepended to a music expression, for example
1250 @cindex new contexts
1251 @cindex Context, creating
1254 \new @var{type} @var{music-expression}
1258 where @var{type} is a context name (like @code{Staff} or
1259 @code{Voice}). This command creates a new context, and starts
1260 interpreting the @var{music-expression} within that context.
1262 Note that there is no @code{\new Score} command;
1263 the single top-level @code{Score} context is introduced
1266 The @code{\new} command may also give a identifying name to the
1267 context to distinguish it from other contexts of the same type,
1270 \new @var{type} = @var{id} @var{music-expression}
1273 Note the distinction between the name of the context type,
1274 @code{Staff}, @code{Voice}, etc, and
1275 the identifying name of a particular instance of that type,
1276 which can be any sequence of letters invented by the user.
1277 The identifying name is used to refer back to that particular
1278 instance of a context. We saw this in use in the section on
1279 lyrics in @ref{Voices and vocals}.
1282 @node Engravers explained
1283 @subsection Engravers explained
1287 Every mark on the printed output of a score produced by LilyPond
1288 is produced by an @code{Engraver}. Thus there is an engraver
1289 to print staves, one to print note heads, one for stems, one for
1290 beams, etc, etc. In total there are over 120 such engravers!
1291 Fortunately, for most scores it is not necessary to know about
1292 more than a few, and for simple scores you do not need to know
1295 Engravers live and operate in Contexts.
1296 Engravers such as the @code{Metronome_mark_engraver}, whose
1297 action and output applies to the score as a whole, operate in
1298 the highest level context -- the @code{Score} context.
1300 The @code{Clef_engraver} and @code{Key_engraver} are to be
1301 found in every Staff Context, as different staves may require
1302 different clefs and keys.
1304 The @code{Note_heads_engraver} and @code{Stem_engraver} live
1305 in every @code{Voice} context, the lowest level context of all.
1307 Each engraver processes the particular objects associated
1308 with its function, and maintains the properties that relate
1309 to that function. These properties, like the properties
1310 associated with contexts, may be modified to change the
1311 operation of the engraver or the appearance of those elements
1312 in the printed score.
1314 Engravers all have compound names formed from words which
1315 describe their function. Just the first word is capitalised,
1316 and the remainder are joined to it with underscores. Thus
1317 the @code{Staff_symbol_engraver} is responsible for creating the
1318 lines of the staff, the @code{Clef_engraver} determines and sets
1319 the pitch reference point on the staff by drawing a clef symbol.
1321 Here are some of the most common engravers together with their
1322 function. You will see it is easy to guess the function from
1323 the name, or vice versa.
1325 @multitable @columnfractions .3 .7
1328 @item Accidental_engraver
1329 @tab Makes accidentals, cautionary and suggested accidentals
1334 @item Dynamic_engraver
1335 @tab Creates hairpins and dynamic texts
1337 @tab Creates the key signature
1338 @item Metronome_mark_engraver
1339 @tab Engraves metronome marking
1340 @item Note_heads_engraver
1341 @tab Engraves note heads
1344 @item Staff_symbol_engraver
1345 @tab Engraves the five (by default) lines of the staff
1347 @tab Creates stems and single-stem tremulos
1348 @item Time_signature_engraver
1349 @tab Creates time signatures
1354 We shall see later how the output of LilyPond can be changed
1355 by modifying the action of Engravers.
1358 @node Modifying context properties
1359 @subsection Modifying context properties
1361 @cindex context properties
1365 Contexts are responsible for holding the values of a number of
1366 context @emph{properties}. Many of them can be changed to
1367 influence the interpretation of the input and so change the
1368 appearance of the output. They are changed by the
1369 @code{\set} command. This takes the form
1372 \set @emph{ContextName}.@emph{propertyName} = #@emph{value}
1375 Where the @emph{ContextName} is usually @code{Score},
1376 @code{Staff} or @code{Voice}. It may be omitted,
1377 in which case @code{Voice} is assumed.
1379 The names of context properties consist of words joined
1380 together with no hyphens or underscores, all except the
1381 first having a capital letter. Here are a few examples
1382 of some commonly used ones. There are many more.
1384 @c attempt to force this onto a new page
1386 @multitable @columnfractions .25 .15 .45 .15
1387 @headitem propertyName
1393 @tab If true, set extra natural signs before accidentals
1394 @tab @code{#t}, @code{#f}
1395 @item currentBarNumber
1397 @tab Set the current bar number
1401 @tab If true, print slurs both above and below notes
1402 @tab @code{#t}, @code{#f}
1403 @item instrumentName
1405 @tab Set the name to be placed at the start of the staff
1406 @tab @code{"Cello I"}
1409 @tab Increase or decrease the font size
1413 @tab Set the text to print before the start of a verse
1418 where a Boolean is either True (@code{#t}) or False (@code{#f}),
1419 an Integer is a positive whole number, a Real is a positive
1420 or negative decimal number, and text is enclosed in double
1421 apostrophes. Note the occurrence of hash signs,
1422 (@code{#}), in two different places -- as part of the Boolean
1423 value before the @code{t} or @code{f}, and before @emph{value}
1424 in the @code{\set} statement. So when a Boolean is being
1425 entered you need to code two hash signs, e.g., @code{##t}.
1427 Before we can set any of these properties we need to know
1428 in which context they operate. Sometimes this is obvious,
1429 but occasionally it can be tricky. If the wrong context
1430 is specified, no error message is produced, but the expected
1431 action will not take place. For example, the
1432 @code{instrumentName} clearly lives in the Staff context, since
1433 it is the staff that is to be named.
1434 In this example the first staff is labelled, but not the second,
1435 because we omitted the context name.
1437 @lilypond[quote,verbatim,ragged-right]
1439 \new Staff \relative c'' {
1440 \set Staff.instrumentName = #"Soprano"
1443 \new Staff \relative c' {
1444 \set instrumentName = #"Alto" % Wrong!
1450 Remember the default context name is Voice, so the second
1451 @code{\set} command set the property @code{instrumentName} in the
1452 Voice context to @qq{Alto}, but as LilyPond does not look
1453 for any such property in the @code{Voice} context, no
1454 further action took place. This is not an error, and no error
1455 message is logged in the log file.
1457 Similarly, if the property name is mis-spelt no error message
1458 is produced, and clearly the expected action cannot be performed.
1459 If fact, you can set any (fictitious) @q{property} using any
1460 name you like in any context that exists by using the
1461 @code{\set} command. But if the name is not
1462 known to LilyPond it will not cause any action to be taken.
1463 This is one of the reasons why it is highly recommended to
1464 use a context-sensitive editor with syntax highlighting for
1465 editing LilyPond files, such as Vim, Jedit, ConTEXT or Emacs,
1466 since unknown property names will be highlighted differently.
1468 The @code{instrumentName} property will take effect only
1469 if it is set in the @code{Staff} context, but
1470 some properties can be set in more than one context.
1471 For example, the property @code{extraNatural} is by
1472 default set to ##t (true) for all staves.
1473 If it is set to ##f (false) in one particular @code{Staff}
1474 context it applies just to the accidentals on that staff.
1475 If it is set to false in the @code{Score} context
1476 it applies to all staves.
1478 So this turns off extra naturals in one staff:
1480 @lilypond[quote,verbatim,ragged-right]
1482 \new Staff \relative c'' {
1485 \new Staff \relative c'' {
1486 \set Staff.extraNatural = ##f
1493 and this turns them off in all staves:
1495 @lilypond[quote,verbatim,ragged-right]
1497 \new Staff \relative c'' {
1500 \new Staff \relative c'' {
1501 \set Score.extraNatural = ##f
1507 The value of every property set in this way can be reset
1508 to its original value with the @code{\unset} command.
1510 The @code{\set} and @code{\unset} commands can appear anywhere
1511 in the input file and will take effect from the time they are
1512 encountered until the end of the score or until the property is
1513 @code{\set} or @code{\unset} again. Let's try changing the
1514 font size, which affects the size of the note heads (among
1515 other things) several times. The change is from the default
1516 value, not the current value.
1518 @lilypond[quote,verbatim,ragged-right,relative=1,fragment]
1520 % make note heads smaller
1523 % make note heads larger
1524 \set fontSize = #2.5
1526 % return to original size
1531 We have now seen how to set the values of several different
1532 types of property. Note that integers and numbers are alway
1533 preceded by a hash sign, @code{#}, while a true or false value
1534 is specified by ##t and ##f, with two hash signs. A text
1535 property should be enclosed in double quotation signs, as above,
1536 although we shall see later that text can actually be specified
1537 in a much more general way by using the very powerful
1538 @code{markup} command.
1543 Context properties may also be set at the time the context is
1544 created. Sometimes this is a clearer way of specifying a
1545 property value if it is to remain fixed for the duration of
1546 the context. When a context is created with a @code{\new}
1547 command it may be followed immediately by a
1548 @code{\with @{ .. @}} block in which the property values are
1549 set. For example, if we wish to suppress the printing of
1550 extra naturals for the duration of a staff we would write:
1553 \new Staff \with @{ extraNatural = ##f @}
1559 @lilypond[quote,verbatim,ragged-right]
1565 \new Staff \with { extraNatural = ##f }
1572 In effect this overrides the default value of the property. It
1573 may still be changed dynamically using @code{\set} and returned
1574 to its (new) default value with @code{\unset}.
1576 @node Adding and removing engravers
1577 @subsection Adding and removing engravers
1579 @cindex Engravers, adding
1580 @cindex Engravers, removing
1585 We have seen that contexts each contain several engravers, each
1586 of which is responsible for producing a particular part of the
1587 output, like bar lines, staves, note heads, stems, etc. If an
1588 engraver is removed from a context it can no longer produce its
1589 output. This is a crude way of modifying the output, but it
1590 can sometimes be useful.
1592 @subsubheading Changing a single context
1594 To remove an engraver from a single context we use the
1595 @code{\with} command placed immediately after the context creation
1596 command, as in the previous section.
1599 illustration let's repeat an example from the previous
1600 section with the staff lines removed. Remember that the
1601 staff lines are produced by the Staff_symbol_engraver.
1603 @lilypond[quote,verbatim,ragged-right]
1605 \remove Staff_symbol_engraver
1609 \set fontSize = #-4 % make note heads smaller
1611 \set fontSize = #2.5 % make note heads larger
1613 \unset fontSize % return to original size
1618 @cindex ambitus engraver
1620 Engravers can also be added to individual contexts.
1621 The command to do this is
1623 @code{\consists @emph{Engraver_name}},
1625 placed inside a @code{\with} block. Some vocal scores
1626 have an @rglos{ambitus} placed at the beginning of a
1627 staff to indicate the range of notes in that staff.
1628 The ambitus is produced by the @code{Ambitus_engraver},
1629 which is not normally included in any context. If
1630 we add it to the @code{Voice} context it calculates
1631 the range from that voice only:
1633 @lilypond[quote,verbatim,ragged-right]
1636 \consists Ambitus_engraver
1651 but if we add the Ambitus engraver to the
1652 @code{Staff} context it calculates the range from all
1653 the notes in all the voices on that staff:
1655 @lilypond[quote,verbatim,ragged-right]
1657 \consists Ambitus_engraver
1673 @subsubheading Changing all contexts of the same type
1675 The examples above show how to remove or add engravers to
1676 individual contexts. It is also possible to remove or add
1677 engravers to every context of a specific type by placing the
1678 commands in the appropriate context in a @code{\layout}
1679 block. For example, If we wanted to show ambiti for every
1680 staff in a four-staff score we could write
1682 @lilypond[quote,verbatim,ragged-right]
1686 \relative c'' { c a b g }
1689 \relative c' { c a b g }
1693 \relative c' { c a b g }
1697 \relative c { c a b g }
1703 \consists Ambitus_engraver
1710 The default values of context properties may also be set
1711 for all contexts of a particular type by including the
1712 @code{\set} command in a @code{\context} block in the
1715 @node Extending the templates
1716 @section Extending the templates
1718 You've read the tutorial, you know how to write music, you
1719 understand the fundamental concepts. But how can you
1720 get the staves that you want? Well, you can find lots of
1721 templates (see @ref{Templates}) which may give you a start.
1723 if you want something that isn't covered there? Read on.
1725 TODO Add links to templates after they have been moved to LSR
1728 * Soprano and cello::
1729 * Four-part SATB vocal score::
1730 * Building a score from scratch::
1733 @node Soprano and cello
1734 @subsection Soprano and cello
1736 Start off with the template that seems closest to what you want to end
1737 up with. Let's say that you want to write something for soprano and
1738 cello. In this case, we would start with @q{Notes and lyrics} (for the
1742 \version @w{"@version{}"}
1743 melody = \relative c' @{
1750 text = \lyricmode @{
1756 \new Voice = "one" @{
1760 \new Lyrics \lyricsto "one" \text
1767 Now we want to add a cello part. Let's look at the @q{Notes only} example:
1770 \version @w{"@version{}"}
1771 melody = \relative c' @{
1785 We don't need two @code{\version} commands. We'll need the
1786 @code{melody} section. We don't want two @code{\score} sections
1787 -- if we had two @code{\score}s, we'd get the two parts separately.
1788 We want them together, as a duet. Within the @code{\score}
1789 section, we don't need two @code{\layout} or @code{\midi}.
1791 If we simply cut and paste the @code{melody} section, we would
1792 end up with two @code{melody} definitions. This would not generate
1793 an error, but the second one would be used for both melodies.
1794 So let's rename them to make them distinct. We'll call the
1795 section for the soprano @code{sopranoMusic} and the section for
1796 the cello @code{celloMusic}. While we're doing this, let's rename
1797 @code{text} to be @code{sopranoLyrics}. Remember to rename both
1798 instances of all these names -- both the initial definition (the
1799 @code{melody = \relative c' @{ } part) and the name's use (in the
1800 @code{\score} section).
1802 While we're doing this, let's change the cello part's staff --
1803 celli normally use bass clef. We'll also give the cello some
1807 \version @w{"@version{}"}
1808 sopranoMusic = \relative c' @{
1815 sopranoLyrics = \lyricmode @{
1819 celloMusic = \relative c @{
1828 \new Voice = "one" @{
1832 \new Lyrics \lyricsto "one" \sopranoLyrics
1839 This is looking promising, but the cello part won't appear in the
1840 score -- we haven't used it in the @code{\score} section. If we
1841 want the cello part to appear under the soprano part, we need to add
1844 \new Staff \celloMusic
1848 underneath the soprano stuff. We also need to add @code{<<} and
1849 @code{>>} around the music -- that tells LilyPond that there's
1850 more than one thing (in this case, two @code{Staves}) happening
1851 at once. The @code{\score} looks like this now
1853 @c Indentation in this example is deliberately poor
1858 \new Voice = "one" @{
1862 \new Lyrics \lyricsto "one" \sopranoLyrics
1864 \new Staff \celloMusic
1872 This looks a bit messy; the indentation is messed up now. That is
1873 easily fixed. Here's the complete soprano and cello template.
1875 @lilypond[quote,verbatim,ragged-right]
1877 sopranoMusic = \relative c' {
1884 sopranoLyrics = \lyricmode {
1888 celloMusic = \relative c {
1898 \new Voice = "one" {
1902 \new Lyrics \lyricsto "one" \sopranoLyrics
1904 \new Staff \celloMusic
1912 @node Four-part SATB vocal score
1913 @subsection Four-part SATB vocal score
1915 Most vocal scores of music written for four-part mixed choir
1916 with orchestral accompaniment such as Mendelssohn's Elijah or
1917 Handel's Messiah have the choral music and words on four
1918 staves, one for each of SATB, with a piano reduction of the
1919 orchestral accompaniment underneath. Here's an example
1920 from Handel's Messiah:
1922 @c The following should appear as music without code
1923 @lilypond[quote,ragged-right]
1924 global = { \key d \major \time 4/4 }
1925 sopMusic = \relative c'' {
1927 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
1929 sopWords = \lyricmode {
1930 Wor -- thy is the lamb that was slain
1932 altoMusic = \relative a' {
1934 r4 a2 a4 | fis4. fis8 a2 | g4 fis e2 |
1936 altoWords = \sopWords
1937 tenorMusic = \relative c' {
1939 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
1941 tenorWords = \sopWords
1942 bassMusic = \relative c' {
1944 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
1946 bassWords = \sopWords
1947 upper = \relative a' {
1950 r4 <a d fis>2 <a e' a>4 |
1951 <d fis d'>4. <d fis d'>8 <a d a'>2 |
1952 <g cis g'>4 <a d fis> <a cis e>2 |
1954 lower = \relative c, {
1957 <d d'>4 <d d'>2 <cis cis'>4 |
1958 <b b'>4. <b' b'>8 <fis fis'>2 |
1959 <e e'>4 <d d'> <a' a'>2 |
1963 << % combine ChoirStaff and PianoStaff in parallel
1965 \new Staff = "sopranos" <<
1966 \set Staff.instrumentName = "Soprano"
1967 \new Voice = "sopranos" { \global \sopMusic }
1969 \new Lyrics \lyricsto "sopranos" { \sopWords }
1970 \new Staff = "altos" <<
1971 \set Staff.instrumentName = "Alto"
1972 \new Voice = "altos" { \global \altoMusic }
1974 \new Lyrics \lyricsto "altos" { \altoWords }
1975 \new Staff = "tenors" <<
1976 \set Staff.instrumentName = "Tenor"
1977 \new Voice = "tenors" { \global \tenorMusic }
1979 \new Lyrics \lyricsto "tenors" { \tenorWords }
1980 \new Staff = "basses" <<
1981 \set Staff.instrumentName = "Bass"
1982 \new Voice = "basses" { \global \bassMusic }
1984 \new Lyrics \lyricsto "basses" { \bassWords }
1988 \set PianoStaff.instrumentName = "Piano "
1989 \new Staff = "upper" \upper
1990 \new Staff = "lower" \lower
1996 None of the templates provides this layout exactly. The
1997 nearest is @q{SATB vocal score and automatic piano reduction},
1998 but we need to change the layout and add a piano
1999 accompaniment which is not derived automatically from the
2000 vocal parts. The variables holding the music and words for
2001 the vocal parts are fine, but we shall need to add variables for
2002 the piano reduction.
2004 The order in which the contexts appear in the ChoirStaff of
2005 the template do not correspond with the order in the vocal
2006 score shown above. We need to rearrange them so there are
2007 four staves with the words written directly underneath the
2008 notes for each part.
2009 All the voices should be @code{\voiceOne}, which is
2010 the default, so the @code{\voiceXXX} commands should be removed.
2011 We also need to specify the tenor clef for the tenors.
2012 The way in which lyrics are specified in the template has not yet
2013 been encountered so we need to use the method with which we are
2014 familiar. We should also add the names of each staff.
2016 Doing this gives for our ChoirStaff:
2020 \new Staff = "sopranos" <<
2021 \set Staff.instrumentName = "Soprano"
2022 \new Voice = "sopranos" @{ \global \sopMusic @}
2024 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
2025 \new Staff = "altos" <<
2026 \set Staff.instrumentName = "Alto"
2027 \new Voice = "altos" @{ \global \altoMusic @}
2029 \new Lyrics \lyricsto "altos" @{ \altoWords @}
2030 \new Staff = "tenors" <<
2031 \set Staff.instrumentName = "Tenor"
2032 \new Voice = "tenors" @{ \global \tenorMusic @}
2034 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
2035 \new Staff = "basses" <<
2036 \set Staff.instrumentName = "Bass"
2037 \new Voice = "basses" @{ \global \bassMusic @}
2039 \new Lyrics \lyricsto "basses" @{ \bassWords @}
2043 Next we must work out the piano part. This is
2044 easy - we just pull out the piano part from the
2045 @q{Solo piano} template:
2049 \set PianoStaff.instrumentName = "Piano "
2050 \new Staff = "upper" \upper
2051 \new Staff = "lower" \lower
2055 and add the variable definitions for @code{upper}
2058 The ChoirStaff and PianoStaff must be combined
2059 using angle brackets as we want them to be
2060 stacked one above the other:
2063 << % combine ChoirStaff and PianoStaff one above the other
2065 \new Staff = "sopranos" <<
2066 \new Voice = "sopranos" @{ \global \sopMusic @}
2068 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
2069 \new Staff = "altos" <<
2070 \new Voice = "altos" @{ \global \altoMusic @}
2072 \new Lyrics \lyricsto "altos" @{ \altoWords @}
2073 \new Staff = "tenors" <<
2074 \clef "G_8" % tenor clef
2075 \new Voice = "tenors" @{ \global \tenorMusic @}
2077 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
2078 \new Staff = "basses" <<
2080 \new Voice = "basses" @{ \global \bassMusic @}
2082 \new Lyrics \lyricsto "basses" @{ bassWords @}
2086 \set PianoStaff.instrumentName = "Piano "
2087 \new Staff = "upper" \upper
2088 \new Staff = "lower" \lower
2093 Combining all these together and adding the music
2094 for the three bars of the example above gives:
2096 @lilypond[quote,verbatim,ragged-right]
2098 global = { \key d \major \time 4/4 }
2099 sopMusic = \relative c'' {
2101 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
2103 sopWords = \lyricmode {
2104 Wor -- thy is the lamb that was slain
2106 altoMusic = \relative a' {
2108 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
2110 altoWords = \sopWords
2111 tenorMusic = \relative c' {
2113 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
2115 tenorWords = \sopWords
2116 bassMusic = \relative c' {
2118 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
2120 bassWords = \sopWords
2121 upper = \relative a' {
2124 r4 <a d fis>2 <a e' a>4 |
2125 <d fis d'>4. <d fis d'>8 <a d a'>2 |
2126 <g cis g'>4 <a d fis> <a cis e>2 |
2128 lower = \relative c, {
2131 <d d'>4 <d d'>2 <cis cis'>4 |
2132 <b b'>4. <b' b'>8 <fis fis'>2 |
2133 <e e'>4 <d d'> <a' a'>2 |
2137 << % combine ChoirStaff and PianoStaff in parallel
2139 \new Staff = "sopranos" <<
2140 \set Staff.instrumentName = "Soprano"
2141 \new Voice = "sopranos" { \global \sopMusic }
2143 \new Lyrics \lyricsto "sopranos" { \sopWords }
2144 \new Staff = "altos" <<
2145 \set Staff.instrumentName = "Alto"
2146 \new Voice = "altos" { \global \altoMusic }
2148 \new Lyrics \lyricsto "altos" { \altoWords }
2149 \new Staff = "tenors" <<
2150 \set Staff.instrumentName = "Tenor"
2151 \new Voice = "tenors" { \global \tenorMusic }
2153 \new Lyrics \lyricsto "tenors" { \tenorWords }
2154 \new Staff = "basses" <<
2155 \set Staff.instrumentName = "Bass"
2156 \new Voice = "basses" { \global \bassMusic }
2158 \new Lyrics \lyricsto "basses" { \bassWords }
2162 \set PianoStaff.instrumentName = "Piano "
2163 \new Staff = "upper" \upper
2164 \new Staff = "lower" \lower
2171 @node Building a score from scratch
2172 @subsection Building a score from scratch
2174 After gaining some facility with writing LilyPond code you
2175 may find that it is easier to build a score from scratch
2176 rather than modifying one of the templates. You can also
2177 develop your own style this way to suit the sort of music you
2178 like. Let's see how to put together the score for an organ
2179 prelude as an example.
2181 We begin with a header section. Here go the title, name
2182 of composer, etc, then come any variable definitions, and
2183 finally the score block. Let's start with these in outline
2184 and fill in the details later.
2186 We'll use the first two bars of Bach's prelude
2187 based on @emph{Jesu, meine Freude} which is written for two
2188 manuals and pedal organ. You can see these two bars of music
2189 at the bottom of this section. The top manual part has two voices,
2190 the lower and pedal organ one each. So we need four
2191 music definitions and one to define the time signature
2195 \version @w{"@version{}"}
2197 title = "Jesu, meine Freude"
2198 composer = "J S Bach"
2200 TimeKey = @{ \time 4/4 \key c \minor @}
2201 ManualOneVoiceOneMusic = @{s1@}
2202 ManualOneVoiceTwoMusic = @{s1@}
2203 ManualTwoMusic = @{s1@}
2204 PedalOrganMusic = @{s1@}
2210 For now we've just used a spacer note, @code{s1},
2211 instead of the real music. We'll add that later.
2213 Next let's see what should go in the score block.
2214 We simply mirror the staff structure we want.
2215 Organ music is usually written on three staves,
2216 one for each manual and one for the pedals. The
2217 manual staves should be bracketed together so we
2218 need to use a PianoStaff for them. The first
2219 manual part needs two voices and the second manual
2224 \new Staff = "ManualOne" <<
2225 \new Voice @{ \ManualOneVoiceOneMusic @}
2226 \new Voice @{ \ManualOneVoiceTwoMusic @}
2227 >> % end ManualOne Staff context
2228 \new Staff = "ManualTwo" <<
2229 \new Voice @{ \ManualTwoMusic @}
2230 >> % end ManualTwo Staff context
2231 >> % end PianoStaff context
2234 Next we need to add a staff for the pedal organ.
2235 This goes underneath the PianoStaff, but it must
2236 be simultaneous with it, so we need angle brackets
2237 round the two. Missing these out would generate
2238 an error in the log file. It's a common mistake
2239 which you'll make sooner or later! Try copying
2240 the final example at the end of this section,
2241 remove these angle brackets, and compile it to
2242 see what errors it generates.
2245 << % PianoStaff and Pedal Staff must be simultaneous
2247 \new Staff = "ManualOne" <<
2248 \new Voice @{ \ManualOneVoiceOneMusic @}
2249 \new Voice @{ \ManualOneVoiceTwoMusic @}
2250 >> % end ManualOne Staff context
2251 \new Staff = "ManualTwo" <<
2252 \new Voice @{ \ManualTwoMusic @}
2253 >> % end ManualTwo Staff context
2254 >> % end PianoStaff context
2255 \new Staff = "PedalOrgan" <<
2256 \new Voice @{ \PedalOrganMusic @}
2261 It is not strictly necessary to use the simultaneous construct
2262 @code{<< >>} for the manual two staff and the pedal organ staff,
2263 since they contain only one music expression, but it does no harm
2264 and always using angle brackets after @code{\new Staff} is a good
2265 habit to cultivate in case there are multiple voices.
2267 Let's add this structure to the score block, and adjust the
2268 indenting. We also add the appropriate clefs, ensure the
2269 second voice stems point down with @code{\voiceTwo} and
2270 enter the time signature and key to each staff using our
2271 predefined variable, @code{\TimeKey}.
2275 << % PianoStaff and Pedal Staff must be simultaneous
2277 \new Staff = "ManualOne" <<
2278 \TimeKey % set time signature and key
2280 \new Voice @{ \ManualOneVoiceOneMusic @}
2281 \new Voice @{ \voiceTwo \ManualOneVoiceTwoMusic @}
2282 >> % end ManualOne Staff context
2283 \new Staff = "ManualTwo" <<
2286 \new Voice @{ \ManualTwoMusic @}
2287 >> % end ManualTwo Staff context
2288 >> % end PianoStaff context
2289 \new Staff = "PedalOrgan" <<
2292 \new Voice @{ \PedalOrganMusic @}
2293 >> % end PedalOrgan Staff
2295 @} % end Score context
2298 That completes the structure. Any three-staff organ music
2299 will have a similar structure, although the number of voices
2300 may vary. All that remains now
2301 is to add the music, and combine all the parts together.
2303 @lilypond[quote,verbatim,ragged-right]
2306 title = "Jesu, meine Freude"
2307 composer = "J S Bach"
2309 TimeKey = { \time 4/4 \key c \minor }
2310 ManualOneVoiceOneMusic = \relative g' {
2311 g4 g f ees | d2 c2 |
2313 ManualOneVoiceTwoMusic = \relative c' {
2314 ees16 d ees8~ ees16 f ees s c8 d~ d c~ |
2315 c c4 b8 c8. g16 c b c d |
2317 ManualTwoMusic = \relative c' {
2318 c16 b c8~ c16 b c g a8 g~ g16 g aes ees |
2319 f ees f d g aes g f ees d e8~ ees16 f ees d |
2321 PedalOrganMusic = \relative c {
2322 r8 c16 d ees d ees8~ ees16 a, b g c b c8 |
2323 r16 g ees f g f g8 c,2 |
2327 << % PianoStaff and Pedal Staff must be simultaneous
2329 \new Staff = "ManualOne" <<
2330 \TimeKey % set time signature and key
2332 \new Voice { \ManualOneVoiceOneMusic }
2333 \new Voice { \voiceTwo \ManualOneVoiceTwoMusic }
2334 >> % end ManualOne Staff context
2335 \new Staff = "ManualTwo" <<
2338 \new Voice { \ManualTwoMusic }
2339 >> % end ManualTwo Staff context
2340 >> % end PianoStaff context
2341 \new Staff = "PedalOrgan" <<
2344 \new Voice { \PedalOrganMusic }
2345 >> % end PedalOrgan Staff
2347 } % end Score context