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.
10 @node Fundamental concepts
11 @chapter Fundamental concepts
13 You've seen in the Tutorial how to produce beautifully printed
14 music from a simple text file. This section introduces the
15 concepts and techniques required to produce equally beautiful
16 but more complex scores.
19 * How LilyPond input files work::
20 * Voices contain music::
21 * Contexts and engravers::
22 * Extending the templates::
26 @node How LilyPond input files work
27 @section How LilyPond input files work
29 The LilyPond input format is quite free-form, giving experienced
30 users a lot of flexibility to structure their files however they
31 wish. But this flexibility can make things confusing for new
32 users. This section will explain some of this structure, but may
33 gloss over some details in favor of simplicity. For a complete
34 description of the input format, see @ruser{File structure}.
37 * Introduction to the LilyPond file structure::
38 * Score is a (single) compound musical expression::
39 * Nesting music expressions::
40 * On the un-nestedness of brackets and ties::
43 @node Introduction to the LilyPond file structure
44 @subsection Introduction to the LilyPond file structure
47 @cindex file structure
49 A basic example of a LilyPond input file is
52 \version @w{"@version{}"}
55 @var{...compound music expression...} % all the music goes here!
62 There are many variations of this basic pattern, but this
63 example serves as a useful starting place.
72 Up to this point none of the examples you have seen has used a
73 @code{\score@{@}} command. This is because LilyPond automatically
74 adds the extra commands which are needed when you give it simple
75 input. LilyPond treats input like this:
84 as shorthand for this:
101 In other words, if the input contains a single music expression,
102 LilyPond will interpret the file as though the music expression
103 was wrapped up inside the commands shown above.
105 @cindex implicit contexts
106 @cindex contexts, implicit
108 @strong{A word of warning!} Many of the examples in the LilyPond
109 documentation will omit the @code{\new Staff} and @code{\new Voice}
110 commands, leaving them to be created implicitly. For simple
111 examples this works well, but for more complex examples, especially
112 when additional commands are used, the implicit creation of contexts
113 can give surprising results, maybe creating extra unwanted staves.
114 The way to create contexts explicitly is explained in
115 @ref{Contexts and engravers}.
117 @warning{When entering more than a few lines of music it is
118 advisable to always create staves and voices explicitly.}
120 For now, though, let us return to the first example and examine the
121 @code{\score} command, leaving the others to default.
123 A @code{\score} block must always contain just one music expression,
124 and this must appear immediately after the @code{\score} command.
125 Remember that a music expression could be anything from a single
126 note to a huge compound expression like
131 @var{...insert the whole score of a Wagner opera in here...}
137 Since everything is inside @code{@{ ... @}}, it counts
138 as one music expression.
140 As we saw previously, the @code{\score} block can contain other
163 Note that these three commands -- @code{\header}, @code{\layout} and
164 @code{\midi} -- are special: unlike many other commands which begin
165 with a backward slash (@code{\}) they are @emph{not} music expressions
166 and are not part of any music expression. So they may be placed
167 inside a @code{\score} block or outside it. In fact, these commands
168 are commonly placed outside the @code{\score} block -- for example,
169 @code{\header} is often placed above the @code{\score} command, as the
170 example at the beginning of this section shows.
172 Two more commands you have not previously seen are
173 @code{\layout @{ @}} and @code{\midi @{@}}. If these appear as
174 shown they will cause LilyPond to produce a printed output and a
175 MIDI output respectively. They are described fully in the
176 Notation Reference -- @ruser{Score layout}, and
177 @ruser{Creating MIDI files}.
179 @cindex scores, multiple
180 @cindex book block, implicit
181 @cindex implicit book block
185 You may code multiple @code{\score} blocks. Each will be
186 treated as a separate score, but they will be all combined into
187 a single output file. A @code{\book} command is not necessary
188 -- one will be implicitly created. However, if you would like
189 separate output files from one @code{.ly} file then the
190 @code{\book} command should be used to separate the different
191 sections: each @code{\book} block will produce a
192 separate output file.
196 Every @code{\book} block creates a separate output file (e.g., a
197 PDF file). If you haven't explicitly added one, LilyPond wraps
198 your entire input code in a @code{\book} block implicitly.
200 Every @code{\score} block is a separate chunk of music within a
203 @cindex layout block, effect of location
205 Every @code{\layout} block affects the @code{\score} or
206 @code{\book} block in which it appears -- i.e., a @code{\layout}
207 block inside a @code{\score} block affects only that @code{\score}
208 block, but a @code{\layout} block outside of a @code{\score} block
209 (and thus in a @code{\book} block, either explicitly or
210 implicitly) will affect every @code{\score} in that @code{\book}.
212 For details see @ruser{Multiple scores in a book}.
216 Another great shorthand is the ability to define variables. All
217 the templates use this
220 melody = \relative c' @{
229 When LilyPond looks at this file, it takes the value of
230 @code{melody} (everything after the equals sign) and inserts it
231 whenever it sees @code{\melody}. There's nothing special about
232 the names -- it could be @code{melody}, @code{global},
234 @code{pianorighthand}, or @code{foofoobarbaz}. For more details,
235 see @ref{Saving typing with variables and functions}.
236 Remember that you can use almost any name you like as long
237 as it contains just alphabetic characters and is distinct from
238 LilyPond command names. The exact
239 limitations on variable names are detailed in
240 @ruser{File structure}.
246 For a complete definition of the input format, see
247 @ruser{File structure}.
249 @node Score is a (single) compound musical expression
250 @subsection Score is a (single) compound musical expression
255 @cindex contents of a score block
256 @cindex score block, contents of
257 @cindex compound music expression
258 @cindex music expression, compound
260 We saw the general organization of LilyPond input files in the
261 previous section, @ref{Introduction to the LilyPond file structure}.
262 But we seemed to skip over the most important part: how do we figure
263 out what to write after @code{\score}?
265 We didn't skip over it at all. The big mystery is simply that
266 there @emph{is} no mystery. This line explains it all:
269 @emph{A @code{\score} block must begin with a compound music expression.}
273 To understand what is meant by a music expression and a compound
274 music expression, you may find it useful to review the tutorial,
275 @ref{Music expressions explained}. In that section, we saw how to
276 build big music expressions from small pieces -- we started from
277 notes, then chords, etc. Now we're going to start from a big
278 music expression and work our way down.
282 @{ % this brace begins the overall compound music expression
284 @var{...insert the whole score of a Wagner opera in here...}
286 @} % this brace ends the overall compound music expression
291 A whole Wagner opera would easily double the length of this
292 manual, so let's just add a singer and piano. We don't need a
293 @code{GrandStaff} for this ensemble, which simply groups a number
294 of staves together with a brace at the left, so we shall remove
295 it. We @emph{do} need a singer and a piano, though.
300 \new Staff = "singer" <<
302 \new PianoStaff = "piano" <<
309 Remember that we use @code{<< ... >>} instead of @code{@{ ... @}} to
310 show simultaneous music. And we definitely want to show the vocal
311 part and piano part at the same time, not one after the other! Note
312 that the @code{<< ... >>} construct is not really necessary for the
313 Singer staff, as it contains only one sequential music expression;
314 however, using @code{<< ... >>} instead of braces is still necessary
315 if the music in the Staff is made of two simultaneous expressions,
316 e.g. two simultaneous Voices, or a Voice with lyrics. We'll add some
317 real music later; for now let's just put in some dummy notes and
320 @lilypond[verbatim,quote,ragged-right]
323 \new Staff = "singer" <<
324 \new Voice = "vocal" { c'1 }
327 \new PianoStaff = "piano" <<
328 \new Staff = "upper" { c'1 }
329 \new Staff = "lower" { c'1 }
336 Now we have a lot more details. We have the singer's staff: it
337 contains a @code{Voice} (in LilyPond, this term refers to a set of
338 notes, not necessarily vocal notes -- for example, a violin
339 generally plays one voice) and some lyrics. We also have a piano
340 staff: it contains an upper staff (right hand) and a lower staff
343 At this stage, we could start filling in notes. Inside the curly
344 braces next to @code{\new Voice = "vocal"}, we could start writing
352 But if we did that, the @code{\score} section would get pretty
353 long, and it would be harder to understand what was happening. So
354 let's use variables instead. These were introduced at the end
355 of the previous section, remember? So, adding a few notes, we
356 now have a piece of real music:
358 @lilypond[verbatim,quote,ragged-right]
359 melody = \relative c'' { r4 d8\noBeam g, c4 r }
360 text = \lyricmode { And God said, }
361 upper = \relative c'' { <g d g,>2~ <g d g,> }
362 lower = \relative c { b2 e2 }
366 \new Staff = "singer" <<
367 \new Voice = "vocal" { \melody }
370 \new PianoStaff = "piano" <<
371 \new Staff = "upper" { \upper }
372 \new Staff = "lower" {
383 Be careful about the difference between notes, which are introduced
384 with @code{\relative} or which are directly included in a music
385 expression, and lyrics, which are introduced with
386 @code{\lyricmode}. These are essential to tell LilyPond
387 to interpret the following content as music and text
390 When writing (or reading) a @code{\score} section, just take it
391 slowly and carefully. Start with the outer level, then work on
392 each smaller level. It also really helps to be strict with
393 indentation -- make sure that each item on the same level starts
394 on the same horizontal position in your text editor.
398 Notation Reference: @ruser{Structure of a score}.
400 @node Nesting music expressions
401 @subsection Nesting music expressions
403 @cindex staves, temporary
404 @cindex temporary staves
407 It is not essential to declare all staves at the beginning; they may
408 be introduced temporarily at any point. This is particularly useful
409 for creating ossia sections -- see @rglos{ossia}. Here is a simple
410 example showing how to introduce a new staff temporarily for the
411 duration of three notes:
413 @lilypond[verbatim,quote,ragged-right]
430 Note that the size of the clef is the same as a clef printed
431 following a clef change -- slightly smaller than the clef
432 at the beginning of the line. This is usual for clefs printed
433 in the middle of a line.
435 @cindex staff, positioning
437 The ossia section may be placed above the staff
440 @lilypond[verbatim,quote,ragged-right]
441 \new Staff = "main" {
448 alignAboveContext = "main" }
456 This example uses @code{\with}, which will be explained more
457 fully later. It is a means of modifying the default behavior
458 of a single Staff. Here it says that the new staff should be
459 placed above the staff called @qq{main} instead of the default
460 position which is below.
464 Ossia are often written without clef and without
465 time signature and are usually in a smaller font.
466 These require further commands which
467 have not yet been introduced. See @ref{Size of objects},
468 and @ruser{Ossia staves}.
471 @node On the un-nestedness of brackets and ties
472 @subsection On the un-nestedness of brackets and ties
474 @cindex brackets, nesting
475 @cindex bracket types
476 @cindex brackets, enclosing vs. marking
478 You have already met a number of different types of bracket in
479 writing the input file to LilyPond. These obey different rules
480 which can be confusing at first. Before we explain the rules
481 let's first review the different types of bracket.
483 @c attempt to force this onto a new page
485 @multitable @columnfractions .3 .7
486 @headitem Bracket Type
488 @item @code{@{ .. @}}
489 @tab Encloses a sequential segment of music
491 @tab Encloses the notes of a chord
492 @item @code{<< .. >>}
493 @tab Encloses simultaneous music expressions
495 @tab Marks the start and end of a slur
496 @item @code{\( .. \)}
497 @tab Marks the start and end of a phrasing slur
499 @tab Marks the start and end of a manual beam
502 To these we should add other constructs which generate lines
503 between or across notes: ties (marked by a tilde, @code{~}),
504 tuplets written as @code{\times x/y @{..@}}, and grace notes
505 written as @code{\grace@{..@}}.
507 Outside LilyPond, the conventional use of brackets requires
508 the different types to be properly nested, like this,
509 @code{<< [ @{ ( .. ) @} ] >>}, with the closing brackets being
510 encountered in exactly the opposite order to the opening
511 brackets. This @strong{is} a requirement for the three types of
512 bracket described by the word @q{Encloses} in the table above --
513 they must nest properly. However, the remaining brackets,
514 described with the word @q{Marks} in the table above together
515 with ties and tuplets, do @strong{not} have to nest properly
516 with any of the brackets. In fact, these are not brackets in
517 the sense that they enclose something -- they are simply
518 markers to indicate where something starts and ends.
520 So, for example, a phrasing slur can start before a manually
521 inserted beam and end before the end of the beam -- not very
522 musical, perhaps, but possible:
524 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
525 { g8\( a b[ c b\) a] }
528 In general, different kinds of brackets, and those implied by
529 tuplets, ties and grace notes, may be mixed freely.
530 This example shows a beam extending into a tuplet (line 1),
531 a slur extending into a tuplet (line 2),
532 a beam and a slur extending into a tuplet, a tie crossing
533 two tuplets, and a phrasing slur extending out of a tuplet
536 @lilypond[quote,verbatim,fragment,ragged-right]
538 r16[ g16 \times 2/3 {r16 e'8] }
539 g16( a \times 2/3 {b d) e' }
540 g8[( a \times 2/3 {b d') e'~]}
541 \times 4/5 {e'32\( a b d' e'} a'4.\)
546 @node Voices contain music
547 @section Voices contain music
549 Singers need voices to sing, and so does LilyPond.
550 The actual music for all instruments in a score
551 is contained in Voices -- the most fundamental
552 of all LilyPond's concepts.
555 * I'm hearing Voices::
556 * Explicitly instantiating voices::
557 * Voices and vocals::
560 @node I'm hearing Voices
561 @subsection I'm hearing Voices
565 @cindex multiple voices
566 @cindex voices, multiple
567 @cindex Voice context
568 @cindex context, Voice
569 @cindex simultaneous music
570 @cindex music, simultaneous
571 @cindex concurrent music
572 @cindex music, concurrent
573 @cindex voices vs. chords
574 @cindex chords vs. voices
576 The lowest, most fundamental or innermost layers in a LilyPond
577 score are called @q{Voice contexts} or just @q{Voices} for short.
578 Voices are sometimes called @q{layers} in other notation
581 In fact, a Voice layer or context is the only one which can
582 contain music. If a Voice context is not explicitly declared
583 one is created automatically, as we saw at the beginning of
584 this chapter. Some instruments such as an
585 Oboe can play only one note at a time. Music written for
586 such instruments is monophonic and requires just a single
587 voice. Instruments which can play more than one note at a
588 time like the piano will often require multiple voices to
589 encode the different concurrent notes and rhythms they are
592 A single voice can contain many notes in a chord, of course,
593 so when exactly are multiple voices needed? Look first at
594 this example of four chords:
596 @lilypond[quote,verbatim,fragment,ragged-right,relative=1]
598 <d g>4 <d fis> <d a'> <d g>
601 This can be expressed using just the single angle bracket chord
602 symbols, @code{< ... >}, and for this just a single voice is
603 needed. But suppose the F-sharp were actually an eighth-note
604 followed by an eighth-note G, a passing note on the way to the A?
605 Now we have two notes which start at the same time but have
606 different durations: the quarter-note D and the eighth-note
607 F-sharp. How are these to be coded? They cannot be written as
608 a chord because all the notes in a chord must have the same
609 duration. And they cannot be written as two sequential notes
610 as they need to start at the same time. This is when two
613 Let us see how this is done in LilyPond input syntax.
618 The easiest way to enter fragments with more than one voice on a
619 staff is to enter each voice as a sequence (with @code{@{...@}}),
620 and combine them simultaneously with angle brackets, @code{<<...>>}.
621 The fragments must also be separated with double backward slashes,
622 @code{\\}, to place them in separate voices. Without these, the
623 notes would be entered into a single voice, which would usually
624 cause errors. This technique is particularly suited to pieces of
625 music which are largely monophonic with occasional short sections
628 Here's how we split the chords above into two voices and add both
629 the passing note and a slur:
631 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
633 % Voice "1" Voice "2"
634 << { g4 fis8( g) a4 g } \\ { d4 d d d } >> |
637 Notice how the stems of the second voice now point down.
639 Here's another simple example:
641 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
643 % Voice "1" Voice "2"
644 << { r4 g g4. a8 } \\ { d,2 d4 g } >> |
645 << { bes4 bes c bes } \\ { g4 g g8( a) g4 } >> |
646 << { a2. r4 } \\ { fis2. s4 } >> |
649 It is not necessary to use a separate @code{<< \\ >>} construct
650 for each bar. For music with few notes in each bar this layout
651 can help the legibility of the code, but if there are many
652 notes in each bar it may be better to split out each voice
653 separately, like this:
655 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
671 @cindex voices, naming
672 @cindex voices crossing brackets
673 @cindex slurs crossing brackets
674 @cindex ties crossing brackest
676 This example has just two voices, but the same construct may be
677 used to encode three or more voices by adding more back-slash
680 The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
681 In each of these contexts, the vertical direction of slurs,
682 stems, ties, dynamics etc., is set appropriately.
684 @lilypond[quote,verbatim,fragment]
685 \new Staff \relative c' {
688 % Voice "1" Voice "2" Voice "3"
689 << { g4 f e } \\ { r8 e4 d c8 ~ } >> |
690 << { d2 e2 } \\ { c8 b16 a b8 g ~ g2 } \\ { s4 b4 c2 } >> |
694 These voices are all separate from the main voice that contains
695 the notes just outside the @code{<< .. >>} construct. Let's call
696 this the @emph{simultaneous construct}. Slurs and ties may only
697 connect notes within the same voice, so slurs and ties cannot go
698 into or out of a simultaneous construct. Conversely,
699 parallel voices from separate simultaneous constructs on the same
700 staff are the same voice. Other voice-related properties also
701 carry across simultaneous constructs. Here is the same example,
702 with different colors and note heads for each voice. Note that
703 changes in one voice do not affect other voices, but they do
704 persist in the same voice later. Note also that tied notes may be
705 split across the same voices in two constructs, shown here in the
708 @lilypond[quote,verbatim]
709 \new Staff \relative c' {
728 { c8 b16 a b8 g ~ g2 }
738 @funindex \voiceOneStyle
739 @funindex \voiceTwoStyle
740 @funindex \voiceThreeStyle
741 @funindex \voiceFourStyle
742 @funindex \voiceNeutralStyle
744 The commands @code{\voiceXXXStyle} are mainly intended for use in
745 educational documents such as this one. They modify the color
746 of the note head, the stem and the beams, and the style of the
747 note head, so that the voices may be easily distinguished.
748 Voice one is set to red diamonds, voice two to blue triangles,
749 voice three to green crossed circles, and voice four (not used
750 here) to magenta crosses; @code{\voiceNeutralStyle} (also not
751 used here) reverts the style back to the default.
752 We shall see later how commands like these may be created by the
754 See @ref{Visibility and color of objects} and
755 @ref{Using variables for tweaks}.
757 @cindex polyphony and relative note entry
758 @cindex relative note entry and polyphony
760 Polyphony does not change the relationship of notes within a
761 @code{\relative @{ @}} block. Each note is still calculated
762 relative to the note immediately preceding it, or to the first
763 note of the preceding chord. So in
766 \relative c' @{ noteA << < noteB noteC > \\ noteD >> noteE @}
770 @code{noteB} is relative to @code{noteA} @*
771 @code{noteC} is relative to @code{noteB}, not @code{noteA}; @*
772 @code{noteD} is relative to @code{noteB}, not @code{noteA} or
774 @code{noteE} is relative to @code{noteD}, not @code{noteA}.
776 An alternative way, which may be clearer if the notes in the
777 voices are widely separated, is to place a @code{\relative}
778 command at the start of each voice:
781 \relative c' @{ noteA ... @}
783 \relative c'' @{ < noteB noteC > ... @}
785 \relative g' @{ noteD ... @}
787 \relative c' @{ noteE ... @}
790 Let us finally analyze the voices in a more complex piece of music.
791 Here are the notes from the first two bars of the second of Chopin's
792 Deux Nocturnes, Op 32. This example will be used at later stages in
793 this and the next chapter to illustrate several techniques for
794 producing notation, so please ignore for now anything in the
795 underlying code which looks mysterious and concentrate just on the
796 music and the voices -- the complications will all be explained in
799 @c The following should appear as music without code
800 @lilypond[quote,ragged-right]
801 \new Staff \relative c'' {
810 % Ignore these for now - they are explained in Ch 4
811 \once \override NoteColumn #'force-hshift = #0
813 \once \override NoteColumn #'force-hshift = #0.5
821 The direction of the stems is often used to indicate the continuity of
822 two simultaneous melodic lines. Here the stems of the highest notes
823 are all pointing up and the stems of the lower notes are all pointing
824 down. This is the first indication that more than one voice is
827 But the real need for multiple voices arises when notes
828 which start at the same time have different durations.
829 Look at the notes which start at beat three in the first
830 bar. The A-flat is a dotted quarter note, the F is a
831 quarter note and the D-flat is a half note. These
832 cannot be written as a chord as all the notes in a chord
833 must have the same duration. Neither can they be written
834 as sequential notes, as they must start at the same time.
835 This section of the bar requires three voices, and the
836 normal practice would be to write the whole bar as three
837 voices, as shown below, where we have used different note heads
838 and colors for the three voices. Again, the code behind this
839 example will be explained later, so ignore anything you do
842 @c The following should appear as music without code
843 @c The three voice styles should be defined in -init
844 @lilypond[quote,ragged-right]
845 \new Staff \relative c'' {
856 \\ % No Voice three (we want stems down)
859 % Ignore these for now - they are explained in Ch 4
860 \once \override NoteColumn #'force-hshift = #0
862 \once \override NoteColumn #'force-hshift = #0.5
871 Let us try to encode this music from scratch. As we
872 shall see, this encounters some difficulties. We begin as
873 we have learnt, using the @code{<< \\ >>} construct to
874 enter the music of the first bar in three voices:
876 @lilypond[quote,verbatim,fragment,ragged-right]
877 \new Staff \relative c'' {
880 { c2 aes4. bes8 } \\ { aes2 f4 fes } \\ { <ees c>2 des2 }
887 @cindex voices and stem directions
888 @cindex stem directions and voices
891 The stem directions are automatically assigned with the
892 odd-numbered voices taking upward stems and the even-numbered
893 voices downward ones. The stems for voices 1 and 2 are right,
894 but the stems in voice 3 should go down in this particular piece
895 of music. We can correct this simply by missing out voice three
896 and placing the music in voice four:
898 @lilypond[quote,verbatim,fragment,ragged-right]
899 \new Staff \relative c'' {
905 \\ % Omit Voice three
914 We see that this fixes the stem direction, but exposes a problem
915 sometimes encountered with multiple voices -- the stems of the notes
916 in one voice can collide with the note heads in other voices. In
917 laying out the notes, LilyPond allows the notes or chords from two
918 voices to occupy the same vertical note column provided the stems are
919 in opposite directions, but the notes from the third and fourth voices
920 are displaced, if necessary, to avoid the note heads colliding. This
921 usually works well, but in this example the notes of the lowest voice
922 are clearly not well placed by default. LilyPond provides several ways
923 to adjust the horizontal placing of notes. We are not quite ready yet
924 to see how to correct this, so we shall leave this problem until a
925 later section --- see the @code{force-hshift} property in @ref{Fixing
926 overlapping notation}.
930 Notation Reference: @ruser{Multiple voices}.
933 @node Explicitly instantiating voices
934 @subsection Explicitly instantiating voices
940 @funindex \voiceThree
947 @cindex voice contexts, creating
949 Voice contexts can also be created manually
950 inside a @code{<< >>} block to create polyphonic music, using
951 @code{\voiceOne} ... @code{\voiceFour} to indicate the required
952 directions of stems, slurs, etc. In longer scores this method
953 is clearer, as it permits the voices to be separated and to be
954 given more descriptive names.
956 Specifically, the construct @code{<< \\ >>} which we used in
957 the previous section:
962 << @{ e4 f g a @} \\ @{ c,4 d e f @} >>
972 \new Voice = "1" @{ \voiceOne \relative c' @{ e4 f g a @} @}
973 \new Voice = "2" @{ \voiceTwo \relative c' @{ c4 d e f @} @}
977 Both of the above would produce
979 @c The following example should not display the code
980 @lilypond[ragged-right,quote]
982 \new Voice = "1" { \voiceOne \relative c' { e4 f g a } }
983 \new Voice = "2" { \voiceTwo \relative c' { c4 d e f } }
987 @cindex voices, reverting to single
988 @cindex reverting to a single voice
990 The @code{\voiceXXX} commands set the direction of stems, slurs,
991 ties, articulations, text annotations, augmentation dots of dotted
992 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
993 make these objects point upwards, while @code{\voiceTwo} and
994 @code{\voiceFour} make them point downwards. These commands also
995 generate a horizontal shift for each voice when this is required
996 to avoid clashes of note heads. The command @code{\oneVoice}
997 reverts the settings back to the normal values for a single voice.
999 Let us see in some simple examples exactly what effect
1000 @code{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on
1001 markup, ties, slurs, and dynamics:
1003 @lilypond[quote,ragged-right,verbatim]
1005 % Default behavior or behavior after \oneVoice
1006 c d8 ~ d e4 ( f g a ) b-> c
1010 @lilypond[quote,ragged-right,verbatim]
1013 c d8 ~ d e4 ( f g a ) b-> c
1015 c, d8 ~ d e4 ( f g a ) b-> c
1019 @lilypond[quote,ragged-right,verbatim]
1022 c d8 ~ d e4 ( f g a ) b-> c
1024 c, d8 ~ d e4 ( f g a ) b-> c
1028 Now let's look at three different ways to notate the same passage
1029 of polyphonic music, each of which is advantageous in different
1030 circumstances, using the example from the previous section.
1032 An expression that appears directly inside a @code{<< >>} belongs
1033 to the main voice (but, note, @strong{not} in a @code{<< \\ >>}
1034 construct). This is useful when extra voices appear while the
1035 main voice is playing. Here is a more correct rendition of our
1036 example. The red diamond-shaped notes
1037 demonstrate that the main melody is now in a single voice context,
1038 permitting a phrasing slur to be drawn over them.
1040 @lilypond[quote,ragged-right,verbatim]
1041 \new Staff \relative c' {
1043 % The following notes are monophonic
1045 % Start simultaneous section of three voices
1047 % Continue the main voice in parallel
1049 % Initiate second voice
1051 % Set stems, etc, down
1053 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
1055 % Initiate third voice
1057 % Set stems, etc, up
1065 @cindex nesting music expressions
1066 @cindex nesting simultaneous constructs
1067 @cindex nesting voices
1068 @cindex voices, temporary
1069 @cindex voices, nesting
1071 More deeply nested polyphony constructs are possible, and if a
1072 voice appears only briefly this might be a more natural way to
1075 @lilypond[quote,ragged-right,verbatim]
1076 \new Staff \relative c' {
1084 {c8 b16 a b8 g ~ g2}
1095 @cindex spacing notes
1097 This method of nesting new voices briefly is useful
1098 when only small sections of the music
1099 are polyphonic, but when the whole staff is largely polyphonic
1100 it can be clearer to use multiple voices throughout, using
1101 spacing notes to step over sections where the voice is silent,
1104 @lilypond[quote,ragged-right,verbatim]
1105 \new Staff \relative c' <<
1106 % Initiate first voice
1109 c16^( d e f g4 f e | d2 e2) |
1111 % Initiate second voice
1113 % Set stems, etc, down
1115 s4 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 |
1117 % Initiate third voice
1119 % Set stems, etc, up
1126 @subsubheading Note columns
1129 @cindex note collisions
1130 @cindex collisions, notes
1131 @cindex shift commands
1138 @funindex \shiftOnnn
1141 Closely spaced notes in a chord, or notes occurring at the same
1142 time in different voices, are arranged in two, occasionally more,
1143 columns to prevent the note heads overlapping. These are called
1144 note columns. There are separate columns for each voice, and
1145 the currently specified voice-dependent shift is applied to the
1146 note column if there would otherwise be a collision. This can
1147 be seen in the example above. In bar 2 the C in voice two is
1148 shifted to the right relative to the D in voice one, and in the
1149 final chord the C in voice three is also shifted to the right
1150 relative to the other notes.
1152 The @code{\shiftOn}, @code{\shiftOnn}, @code{\shiftOnnn}, and
1153 @code{\shiftOff} commands specify the degree to which notes and
1154 chords of the voice should be shifted if a collision
1155 would otherwise occur. By default, the outer voices (normally
1156 voices one and two) have @code{\shiftOff} specified, while the
1157 inner voices (three and four) have @code{\shiftOn} specified.
1158 When a shift is applied, voices one and three are shifted to
1159 the right and voices two and four to the left.
1161 @code{\shiftOnn} and @code{\shiftOnnn} define further shift
1162 levels which may be specified temporarily to resolve collisions
1163 in complex situations -- see @ref{Real music example}.
1165 A note column can contain just one note (or chord) from a voice
1166 with stems up and one note (or chord) from a voice with stems
1167 down. If notes from two voices which have their stems in the
1168 same direction are placed at the same position and both voices
1169 have no shift or the same shift specified, the error message
1170 @qq{Too many clashing note columns} will be produced.
1174 Notation Reference: @ruser{Multiple voices}.
1177 @node Voices and vocals
1178 @subsection Voices and vocals
1180 Vocal music presents a special difficulty: we need to combine two
1181 expressions -- notes and lyrics.
1183 @funindex \new Lyrics
1187 @cindex Lyrics context, creating
1188 @cindex lyrics, linking to voice
1190 You have already seen the @code{\addlyrics@{@}} command, which
1191 handles simple scores well. However, this technique is
1192 quite limited. For more complex music, you must introduce the
1193 lyrics in a @code{Lyrics} context using @code{\new Lyrics} and
1195 the lyrics to the notes with @code{\lyricsto@{@}}, using the
1196 name assigned to the Voice.
1198 @lilypond[quote,verbatim,fragment]
1200 \new Voice = "one" \relative c'' {
1203 c4 b8. a16 g4. f8 e4 d c2
1205 \new Lyrics \lyricsto "one" {
1206 No more let sins and sor -- rows grow.
1211 Note that the lyrics must be linked to a @code{Voice} context,
1212 @emph{not} a @code{Staff} context. This is a case where it is
1213 necessary to create @code{Staff} and @code{Voice} contexts
1216 @cindex lyrics and beaming
1217 @cindex beaming and lyrics
1218 @funindex \autoBeamOff
1219 @funindex autoBeamOff
1221 The automatic beaming which LilyPond uses by default works well
1222 for instrumental music, but not so well for music with lyrics,
1223 where beaming is either not required at all or is used to indicate
1224 melismata in the lyrics. In the example above we use the command
1225 @code{\autoBeamOff} to turn off the automatic beaming.
1227 @funindex \new ChoirStaff
1228 @funindex ChoirStaff
1229 @funindex \lyricmode
1231 @cindex vocal score structure
1234 Let us reuse the earlier example from Judas Maccabæus to
1235 illustrate this more flexible technique. We first recast
1236 it to use variables so the music and lyrics can be separated
1237 from the staff structure. We also introduce a ChoirStaff
1238 bracket. The lyrics themselves must be introduced with
1239 @code{\lyricmode} to ensure they are interpreted as lyrics
1242 @lilypond[quote,verbatim]
1243 global = { \time 6/8 \partial 8 \key f \major}
1244 SopOneMusic = \relative c'' {
1245 c8 | c([ bes)] a a([ g)] f | f'4. b, | c4.~ c4 }
1246 SopTwoMusic = \relative c' {
1247 r8 | r4. r4 c8 | a'([ g)] f f([ e)] d | e([ d)] c bes' }
1248 SopOneLyrics = \lyricmode {
1249 Let | flee -- cy flocks the | hills a -- dorn, __ }
1250 SopTwoLyrics = \lyricmode {
1251 Let | flee -- cy flocks the | hills a -- dorn, }
1256 \new Voice = "SopOne" {
1260 \new Lyrics \lyricsto "SopOne" {
1265 \new Voice = "SopTwo" {
1269 \new Lyrics \lyricsto "SopTwo" {
1277 This is the basic structure of all vocal scores. More staves may be
1278 added as required, more voices may be added to the staves, more verses
1279 may be added to the lyrics, and the variables containing the music can
1280 easily be placed in separate files should they become too long.
1282 @cindex hymn structure
1283 @cindex SATB structure
1284 @cindex vocal scores with multiple verses
1285 @cindex multiple vocal verses
1286 @cindex verses, multiple vocal
1288 Here is an example of the first line of a hymn with four
1289 verses, set for SATB. In this case the words for all four
1290 parts are the same. Note how we use variables to separate the
1291 music notation and words from the staff structure. See too
1292 how a variable, which we have chosen to call @q{TimeKey}, is used
1293 to hold several commands for use within the two staves. In other
1294 examples this is often called @q{global}.
1296 @lilypond[quote,verbatim]
1297 TimeKey = { \time 4/4 \partial 4 \key c \major}
1298 SopMusic = \relative c' { c4 | e4. e8 g4 g | a a g }
1299 AltoMusic = \relative c' { c4 | c4. c8 e4 e | f f e }
1300 TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 }
1301 BassMusic = \relative c { c4 | c4. c8 c4 c | f8 g a b c4 }
1302 VerseOne = \lyricmode {
1303 E -- | ter -- nal fa -- ther, | strong to save, }
1304 VerseTwo = \lyricmode {
1305 O | Christ, whose voice the | wa -- ters heard, }
1306 VerseThree = \lyricmode {
1307 O | Ho -- ly Spi -- rit, | who didst brood }
1308 VerseFour = \lyricmode {
1309 O | Tri -- ni -- ty of | love and pow'r }
1315 \new Voice = "Sop" { \voiceOne \TimeKey \SopMusic }
1316 \new Voice = "Alto" { \voiceTwo \AltoMusic }
1317 \new Lyrics \lyricsto "Sop" { \VerseOne }
1318 \new Lyrics \lyricsto "Sop" { \VerseTwo }
1319 \new Lyrics \lyricsto "Sop" { \VerseThree }
1320 \new Lyrics \lyricsto "Sop" { \VerseFour }
1324 \new Voice = "Tenor" { \voiceOne \TimeKey \TenorMusic }
1325 \new Voice = "Bass" { \voiceTwo \BassMusic }
1331 @cindex verse and refrain
1333 We end with an example to show how we might code a solo verse which
1334 continues into a two-part refrain in two staves. The
1335 positioning of the sequential and simultaneous sections to achieve
1336 this within a single score is quite tricky, so follow the
1337 explanation carefully!
1339 Let's start with a score block containing a @code{ChoirStaff}, as
1340 we would like the brace to appear at the start of the chorus.
1341 Normally you would need angle brackets after @code{\new ChoirStaff}
1342 to bring in all the staves in parallel, but here we want to
1343 defer the parallelism during the solo so we use braces, although
1344 angle brackets here wouldn't hurt. Inside the @code{ChoirStaff} we
1345 want first the staff which will contain the verse. This must
1346 contain notes and lyrics in parallel, so here we need angle
1347 brackets around the @code{\new Voice} and @code{\new Lyrics} to
1348 start them at the same time:
1350 @lilypond[quote,verbatim,ragged-right]
1351 versenotes = \relative c'' {
1354 \time 3/4 g g g b b b
1356 versewords = \lyricmode {
1357 One two three four five six
1362 \new Voice = "verse" {
1365 \new Lyrics \lyricsto verse {
1373 That gives the verse line.
1375 Now we want to continue with refrainA on the same staff while a
1376 second staff is introduced in parallel with it for refrainB, so
1377 this is a parallel section which must be positioned immediately
1378 following the @code{\break} in the verse Voice. Yes, @emph{within}
1379 the verse Voice! Here's that parallel section. More staves
1380 could be introduced here in the same way.
1385 \new Lyrics \lyricsto verse @{
1389 \new Voice = "refrainB" @{
1392 \new Lyrics \lyricsto "refrainB" @{
1399 Here's the final result with two staves in the chorus showing
1400 how the parallel section is positioned within the verse Voice:
1402 @lilypond[quote,verbatim, ragged-right]
1403 versenotes = \relative c'' {
1406 \time 3/4 g g g b b b
1408 refrainnotesA = \relative c'' {
1412 refrainnotesB = \relative c {
1417 versewords = \lyricmode {
1418 One two three four five six
1420 refrainwordsA = \lyricmode {
1423 refrainwordsB = \lyricmode {
1429 \new Voice = "verse" {
1433 \new Lyrics \lyricsto "verse" {
1437 \new Voice = "refrainB" {
1440 \new Lyrics \lyricsto "refrainB" {
1446 \new Lyrics \lyricsto "verse" {
1454 @cindex book, example of using
1458 However, although this is an interesting and useful exercise to
1459 help you to understand how sequential and simultaneous blocks work,
1460 in practice one would perhaps choose to code this as two
1461 @code{\score} blocks within an implicit @code{\book} block, as
1464 @lilypond[quote,verbatim,ragged-right]
1465 versenotes = \relative c'' {
1468 \time 3/4 g g g b b b
1470 refrainnotesA = \relative c'' {
1474 refrainnotesB = \relative c {
1479 versewords = \lyricmode {
1480 One two three four five six
1482 refrainwordsA = \lyricmode {
1485 refrainwordsB = \lyricmode {
1490 \new Voice = "verse" {
1493 \new Lyrics \lyricsto "verse" {
1502 \new Voice = "refrainA" {
1505 \new Lyrics \lyricsto "refrainA" {
1510 \new Voice = "refrainB" {
1513 \new Lyrics \lyricsto "refrainB" {
1523 Notation Reference: @ruser{Vocal music}.
1526 @node Contexts and engravers
1527 @section Contexts and engravers
1529 Contexts and engravers have been mentioned informally
1530 in earlier sections; we now must look at
1531 these concepts in more detail, as they are important
1532 in the fine-tuning of LilyPond output.
1536 * Contexts explained::
1537 * Creating contexts::
1538 * Engravers explained::
1539 * Modifying context properties::
1540 * Adding and removing engravers::
1543 @node Contexts explained
1544 @subsection Contexts explained
1546 @cindex contexts explained
1548 When music is printed, many notational elements which do not
1549 appear explicitly in the input file must be added to the
1550 output. For example, compare the input and output of the
1553 @lilypond[quote,verbatim,relative=2,fragment]
1557 The input is rather sparse, but in the output, bar lines,
1558 accidentals, clef, and time signature have been added. When
1559 LilyPond @emph{interprets} the input the musical information
1560 is inspected in time order, similar to reading a score from left
1561 to right. While reading the input, the program remembers where
1562 measure boundaries are, and which pitches require explicit
1563 accidentals. This information must be held on several levels.
1564 For example, the effect of an accidental is limited
1565 to a single staff, while a bar line must be synchronized across
1568 Within LilyPond, these rules and bits of information are grouped
1569 in @emph{Contexts}. We have already met the
1570 @code{Voice} context.
1571 Others are the @code{Staff} and @code{Score} contexts.
1572 Contexts are hierarchical to reflect the hierarchical nature of
1574 For example: a @code{Staff} context can contain many
1575 @code{Voice} contexts, and a @code{Score} context can
1576 contain many @code{Staff} contexts.
1579 @sourceimage{context-example,5cm,,}
1582 Each context has the responsibility for enforcing some notation rules,
1583 creating some notation objects and maintaining the associated
1584 properties. For example, the @code{Voice} context may introduce an
1585 accidental and then the @code{Staff} context maintains the rule to
1586 show or suppress the accidental for the remainder of the measure.
1588 As another example, the synchronization of bar lines is, by default,
1589 handled in the @code{Score} context.
1590 However, in some music we may not want the bar lines to be
1591 synchronized -- consider a polymetric score in 4/4 and 3/4 time.
1592 In such cases, we must modify the default settings of the
1593 @code{Score} and @code{Staff} contexts.
1595 For very simple scores, contexts are created implicitly, and you need
1596 not be aware of them. For larger pieces, such as anything with more
1597 than one staff, they must be
1598 created explicitly to make sure that you get as many staves as you
1599 need, and that they are in the correct order. For typesetting pieces
1600 with specialized notation, it is usual to modify existing, or
1601 even to define totally new, contexts.
1603 In addition to the @code{Score,} @code{Staff} and
1604 @code{Voice} contexts there are contexts which fit between
1605 the score and staff levels to control staff groups, such as the
1606 @code{PianoStaff} and @code{ChoirStaff} contexts. There
1607 are also alternative staff and voice contexts, and contexts for
1608 lyrics, percussion, fret boards, figured bass, etc.
1610 The names of all context types are formed from one or more
1611 words, each word being capitalized and joined immediately to the
1612 preceding word with no hyphen or underscore, e.g.,
1613 @code{GregorianTranscriptionStaff}.
1617 Notation Reference: @ruser{Contexts explained}.
1620 @node Creating contexts
1621 @subsection Creating contexts
1624 @cindex new contexts
1625 @cindex creating contexts
1626 @cindex contexts, creating
1628 There can be only one top level context: the
1630 context. This is created with the @code{\score} command,
1631 or, in simple scores, it is created automatically.
1633 For scores with only one voice and one staff, the
1634 @code{Voice} and @code{Staff} contexts may be left to be
1635 created automatically, but for more complex scores it is
1636 necessary to create them by hand.
1637 The simplest command that does this is @code{\new}.
1638 It is prepended to a music expression, for example
1641 \new @var{type} @var{music-expression}
1645 where @var{type} is a context name (like @code{Staff} or
1646 @code{Voice}). This command creates a new context, and starts
1647 interpreting the @var{music-expression} within that context.
1649 Note that there is no @code{\new Score} command;
1650 the single top-level @code{Score} context is introduced
1653 You have seen many practical examples which created new
1654 @code{Staff} and @code{Voice} contexts in earlier sections, but
1655 to remind you how these commands are used in practice, here's an
1656 annotated real-music example:
1658 @lilypond[quote,verbatim,ragged-right]
1659 \score { % start of single compound music expression
1660 << % start of simultaneous staves section
1662 \new Staff { % create RH staff
1665 \new Voice { % create voice for RH notes
1666 \relative c'' { % start of RH notes
1672 \new Staff << % create LH staff; needs two simultaneous voices
1675 \new Voice { % create LH voice one
1677 \relative g { % start of LH voice one notes
1678 g8 <bes d> ees, <g c> |
1679 g8 <bes d> ees, <g c> |
1680 } % end of LH voice one notes
1681 } % end of LH voice one
1682 \new Voice { % create LH voice two
1684 \relative g { % start of LH voice two notes
1687 } % end of LH voice two notes
1688 } % end of LH voice two
1689 >> % end of LH staff
1690 >> % end of simultaneous staves section
1691 } % end of single compound music expression
1694 (Note how all the statements which open a block with either a
1695 curly bracket, @code{@{}, or double angle brackets, @code{<<},
1696 are indented by two further spaces, and the corresponding
1697 closing bracket is indented by exactly the same amount. While
1698 this is not required, following this practice will greatly
1699 reduce the number of @q{unmatched bracket} errors, and is
1700 strongly recommended. It enables the structure of the music to
1701 be seen at a glance, and any unmatched brackets will be obvious.
1702 Note too how the LH staff is created using double angle brackets
1703 because it requires two voices for its music, whereas the RH staff
1704 is created with a single music expression surrounded by curly
1705 brackets because it requires only one voice.)
1707 @cindex contexts, naming
1708 @cindex naming contexts
1710 The @code{\new} command may also give a identifying name to the
1711 context to distinguish it from other contexts of the same type,
1714 \new @var{type} = @var{id} @var{music-expression}
1717 Note the distinction between the name of the context type,
1718 @code{Staff}, @code{Voice}, etc, and the identifying name of a
1719 particular instance of that type, which can be any sequence of letters
1720 invented by the user. Digits and spaces can also be used in the
1721 identifying name, but then it has to be placed in quotes,
1722 i.e. @code{\new Staff = "MyStaff 1" @var{music-expression}}.
1723 The identifying name is used to
1724 refer back to that particular instance of a context. We saw this in
1725 use in the section on lyrics, see @ref{Voices and vocals}.
1729 Notation Reference: @ruser{Creating contexts}.
1732 @node Engravers explained
1733 @subsection Engravers explained
1737 Every mark on the printed output of a score produced by LilyPond
1738 is produced by an @code{Engraver}. Thus there is an engraver
1739 to print staves, one to print note heads, one for stems, one for
1740 beams, etc, etc. In total there are over 120 such engravers!
1741 Fortunately, for most scores it is not necessary to know about
1742 more than a few, and for simple scores you do not need to know
1745 Engravers live and operate in Contexts.
1746 Engravers such as the @code{Metronome_mark_engraver}, whose
1747 action and output apply to the score as a whole, operate in
1748 the highest level context -- the @code{Score} context.
1750 The @code{Clef_engraver} and @code{Key_engraver} are to be
1751 found in every @code{Staff} Context, as different staves may require
1752 different clefs and keys.
1754 The @code{Note_heads_engraver} and @code{Stem_engraver} live
1755 in every @code{Voice} context, the lowest level context of all.
1757 Each engraver processes the particular objects associated
1758 with its function, and maintains the properties that relate
1759 to that function. These properties, like the properties
1760 associated with contexts, may be modified to change the
1761 operation of the engraver or the appearance of those elements
1762 in the printed score.
1764 Engravers all have compound names formed from words which
1765 describe their function. Just the first word is capitalized,
1766 and the remainder are joined to it with underscores. Thus
1767 the @code{Staff_symbol_engraver} is responsible for creating the
1768 lines of the staff, the @code{Clef_engraver} determines and sets
1769 the pitch reference point on the staff by drawing a clef symbol.
1771 Here are some of the most common engravers together with their
1772 function. You will see it is usually easy to guess the function
1773 from the name, or vice versa.
1775 @multitable @columnfractions .3 .7
1778 @item Accidental_engraver
1779 @tab Makes accidentals, cautionary and suggested accidentals
1784 @item Completion_heads_engraver
1785 @tab Splits notes which cross bar lines
1786 @c The old Dynamic_engraver is deprecated. -jm
1787 @item New_dynamic_engraver
1788 @tab Creates hairpins and dynamic texts
1789 @item Forbid_line_break_engraver
1790 @tab Prevents line breaks if a musical element is still active
1792 @tab Creates the key signature
1793 @item Metronome_mark_engraver
1794 @tab Engraves metronome marking
1795 @item Note_heads_engraver
1796 @tab Engraves note heads
1799 @item Staff_symbol_engraver
1800 @tab Engraves the five (by default) lines of the staff
1802 @tab Creates stems and single-stem tremolos
1803 @item Time_signature_engraver
1804 @tab Creates time signatures
1809 We shall see later how the output of LilyPond can be changed
1810 by modifying the action of Engravers.
1814 Internals reference: @rinternals{Engravers and Performers}.
1817 @node Modifying context properties
1818 @subsection Modifying context properties
1820 @cindex context properties
1821 @cindex context properties, modifying
1822 @cindex modifying context properties
1826 Contexts are responsible for holding the values of a number of
1827 context @emph{properties}. Many of them can be changed to
1828 influence the interpretation of the input and so change the
1829 appearance of the output. They are changed by the
1830 @code{\set} command. This takes the form
1833 \set @emph{ContextName}.@emph{propertyName} = #@emph{value}
1836 Where the @emph{ContextName} is usually @code{Score},
1837 @code{Staff} or @code{Voice}. It may be omitted,
1838 in which case @code{Voice} is assumed.
1840 The names of context properties consist of words joined
1841 together with no hyphens or underscores, all except the
1842 first having a capital letter. Here are a few examples
1843 of some commonly used ones. There are many more.
1845 @c attempt to force this onto a new page
1847 @multitable @columnfractions .25 .15 .45 .15
1848 @headitem propertyName
1854 @tab If true, set extra natural signs before accidentals
1855 @tab @code{#t}, @code{#f}
1856 @item currentBarNumber
1858 @tab Set the current bar number
1862 @tab If true, print slurs both above and below notes
1863 @tab @code{#t}, @code{#f}
1864 @item instrumentName
1866 @tab Set the name to be placed at the start of the staff
1867 @tab @code{"Cello I"}
1870 @tab Increase or decrease the font size
1874 @tab Set the text to print before the start of a verse
1879 where a Boolean is either True (@code{#t}) or False (@code{#f}),
1880 an Integer is a positive whole number, a Real is a positive
1881 or negative decimal number, and text is enclosed in double
1882 apostrophes. Note the occurrence of hash signs,
1883 (@code{#}), in two different places -- as part of the Boolean
1884 value before the @code{t} or @code{f}, and before @emph{value}
1885 in the @code{\set} statement. So when a Boolean is being
1886 entered you need to code two hash signs, e.g., @code{##t}.
1888 Before we can set any of these properties we need to know
1889 in which context they operate. Sometimes this is obvious,
1890 but occasionally it can be tricky. If the wrong context
1891 is specified, no error message is produced, but the expected
1892 action will not take place. For example, the
1893 @code{instrumentName} clearly lives in the @code{Staff} context, since
1894 it is the staff that is to be named.
1895 In this example the first staff is labelled, but not the second,
1896 because we omitted the context name.
1898 @lilypond[quote,verbatim,ragged-right]
1900 \new Staff \relative c'' {
1901 \set Staff.instrumentName = #"Soprano"
1904 \new Staff \relative c' {
1905 \set instrumentName = #"Alto" % Wrong!
1911 Remember the default context name is @code{Voice}, so the second
1912 @code{\set} command set the property @code{instrumentName} in the
1913 @code{Voice} context to @qq{Alto}, but as LilyPond does not look
1914 for any such property in the @code{Voice} context, no
1915 further action took place. This is not an error, and no error
1916 message is logged in the log file.
1918 Similarly, if the property name is mis-spelt no error message is
1919 produced, and clearly the expected action cannot be performed. In
1920 fact, you can set any (fictitious) @q{property} using any name you
1921 like in any context that exists by using the @code{\set} command. But
1922 if the name is not known to LilyPond it will not cause any action to
1923 be taken. Some text editors with special support for LilyPond input
1924 files document property names with bullets when you hover them with
1925 the mouse, like JEdit with LilyPondTool, or highlight unknown property
1926 names differently, like ConTEXT. If you do not use an editor with
1927 such features, it is recommended to check the property name in the
1928 Internals Reference: see @rinternals{Tunable context properties}, or
1929 @rinternals{Contexts}.
1931 The @code{instrumentName} property will take effect only
1932 if it is set in the @code{Staff} context, but
1933 some properties can be set in more than one context.
1934 For example, the property @code{extraNatural} is by
1935 default set to ##t (true) for all staves.
1936 If it is set to ##f (false) in one particular @code{Staff}
1937 context it applies just to the accidentals on that staff.
1938 If it is set to false in the @code{Score} context
1939 it applies to all staves.
1941 So this turns off extra naturals in one staff:
1943 @lilypond[quote,verbatim,ragged-right]
1945 \new Staff \relative c'' {
1948 \new Staff \relative c'' {
1949 \set Staff.extraNatural = ##f
1956 and this turns them off in all staves:
1958 @lilypond[quote,verbatim,ragged-right]
1960 \new Staff \relative c'' {
1963 \new Staff \relative c'' {
1964 \set Score.extraNatural = ##f
1970 As another example, if @code{clefOctavation} is set in
1971 the @code{Score} context this immediately changes the value
1972 of the octavation in all current staves and sets a new default
1973 value which will be applied to all staves.
1975 The opposite command, @code{\unset}, effectively removes the
1976 property from the context, which causes most properties to
1977 revert to their default value. Usually @code{\unset} is not
1978 required as a new @code{\set} command will achieve what is
1981 The @code{\set} and @code{\unset} commands can appear anywhere
1982 in the input file and will take effect from the time they are
1983 encountered until the end of the score or until the property is
1984 @code{\set} or @code{\unset} again. Let's try changing the
1985 font size, which affects the size of the note heads (among
1986 other things) several times. The change is from the default
1987 value, not the most recently set value.
1989 @lilypond[quote,verbatim,ragged-right,relative=1,fragment]
1991 % make note heads smaller
1994 % make note heads larger
1995 \set fontSize = #2.5
1997 % return to default size
2002 We have now seen how to set the values of several different types of
2003 property. Note that integers and numbers are always preceded by a
2004 hash sign, @code{#}, while a true or false value is specified by
2005 @code{##t} and @code{##f}, with two hash signs. A text property
2006 should be enclosed in double quotation signs, as above, although we
2007 shall see later that text can actually be specified in a much more
2008 general way by using the very powerful @code{markup} command.
2010 @unnumberedsubsubsec Setting context properties with @code{\with}
2013 @cindex context properties, setting with \with
2015 Context properties may also be set at the time the context is
2016 created. Sometimes this is a clearer way of specifying a
2017 property value if it is to remain fixed for the duration of
2018 the context. When a context is created with a @code{\new}
2019 command it may be followed immediately by a
2020 @code{\with @{ .. @}} block in which the property values are
2021 set. For example, if we wish to suppress the printing of
2022 extra naturals for the duration of a staff we would write:
2025 \new Staff \with @{ extraNatural = ##f @}
2031 @lilypond[quote,verbatim,ragged-right]
2037 \new Staff \with { extraNatural = ##f }
2044 Properties set in this way may still be changed dynamically using
2045 @code{\set} and returned to their default value with @code{\unset}.
2047 The @code{fontSize} property is treated differently. If this is
2048 set in a @code{\with} clause it effectively resets the default
2049 value of the font size. If it is later changed with @code{\set},
2050 this new default value may be restored with the
2051 @code{\unset fontSize} command.
2053 @unnumberedsubsubsec Setting context properties with @code{\context}
2055 The values of context properties may be set in @emph{all} contexts
2056 of a particular type, such as all @code{Staff} contexts, with a single
2057 command. The context type is identified by using its
2058 type name, like @code{Staff}, prefixed by a back-slash: @code{\Staff}.
2059 The statement which sets the property value is the same as that in a
2060 @code{\with} block, introduced above. It is placed in a
2061 @code{\context} block within a @code{\layout} block. Each
2062 @code{\context} block will affect all contexts of the type specified
2063 throughout the @code{\score} or @code{\book} block in which the
2064 @code{\layout} block appears. Here is a example to show the format:
2066 @lilypond[verbatim,quote]
2083 Context properties set in this way may be overridden for particular
2084 instances of contexts by statements in a @code{\with} block, and by
2085 @code{\set} commands embedded in music statements.
2090 @ruser{Changing context default settings}.
2092 @c uncomment when backslash-node-name issue is resolved -pm
2093 @c @ruser{The set command}.
2095 Internals Reference:
2096 @rinternals{Contexts},
2097 @rinternals{Tunable context properties}.
2100 @node Adding and removing engravers
2101 @subsection Adding and removing engravers
2103 @cindex engravers, adding
2104 @cindex engravers, removing
2109 We have seen that contexts each contain several engravers, each
2110 of which is responsible for producing a particular part of the
2111 output, like bar lines, staves, note heads, stems, etc. If an
2112 engraver is removed from a context, it can no longer produce its
2113 output. This is a crude way of modifying the output, but it
2114 can sometimes be useful.
2116 @subsubheading Changing a single context
2118 To remove an engraver from a single context we use the
2119 @code{\with} command placed immediately after the context creation
2120 command, as in the previous section.
2122 As an illustration, let's repeat an example from the previous section
2123 with the staff lines removed. Remember that the staff lines are
2124 produced by the @code{Staff_symbol_engraver}.
2126 @lilypond[quote,verbatim,ragged-right]
2128 \remove Staff_symbol_engraver
2132 \set fontSize = #-4 % make note heads smaller
2134 \set fontSize = #2.5 % make note heads larger
2136 \unset fontSize % return to default size
2141 @cindex ambitus engraver
2143 Engravers can also be added to individual contexts.
2144 The command to do this is
2146 @code{\consists @var{Engraver_name}},
2149 placed inside a @code{\with} block. Some vocal scores have an ambitus
2150 placed at the beginning of a staff to indicate the range of notes in
2151 that staff -- see @rglos{ambitus}. The ambitus is produced by the
2152 @code{Ambitus_engraver}, which is not normally included in any
2153 context. If we add it to the @code{Voice} context, it calculates the
2154 range from that voice only:
2156 @lilypond[quote,verbatim,ragged-right]
2159 \consists Ambitus_engraver
2174 but if we add the ambitus engraver to the
2175 @code{Staff} context, it calculates the range from all
2176 the notes in all the voices on that staff:
2178 @lilypond[quote,verbatim,ragged-right]
2180 \consists Ambitus_engraver
2196 @subsubheading Changing all contexts of the same type
2200 The examples above show how to remove or add engravers to
2201 individual contexts. It is also possible to remove or add
2202 engravers to every context of a specific type by placing the
2203 commands in the appropriate context in a @code{\layout}
2204 block. For example, if we wanted to show an ambitus for every
2205 staff in a four-staff score, we could write
2207 @lilypond[quote,verbatim,ragged-right]
2211 \relative c'' { c a b g }
2214 \relative c' { c a b g }
2218 \relative c' { c a b g }
2222 \relative c { c a b g }
2228 \consists Ambitus_engraver
2235 The values of context properties may also be set
2236 for all contexts of a particular type by including the
2237 @code{\set} command in a @code{\context} block in the
2242 Notation Reference: @ruser{Modifying context plug-ins},
2243 @ruser{Changing context default settings}.
2246 @node Extending the templates
2247 @section Extending the templates
2249 You've read the tutorial, you know how to write music, you
2250 understand the fundamental concepts. But how can you
2251 get the staves that you want? Well, you can find lots of
2252 templates (see @ref{Templates}) which may give you a start.
2253 But what if you want something that isn't covered there? Read on.
2256 * Soprano and cello::
2257 * Four-part SATB vocal score::
2258 * Building a score from scratch::
2261 @node Soprano and cello
2262 @subsection Soprano and cello
2264 @cindex template, modifying
2266 Start off with the template that seems closest to what you want to end
2267 up with. Let's say that you want to write something for soprano and
2268 cello. In this case, we would start with @q{Notes and lyrics} (for the
2272 \version @w{"@version{}"}
2273 melody = \relative c' @{
2280 text = \lyricmode @{
2286 \new Voice = "one" @{
2290 \new Lyrics \lyricsto "one" \text
2297 Now we want to add a cello part. Let's look at the @q{Notes only} example:
2300 \version @w{"@version{}"}
2301 melody = \relative c' @{
2315 We don't need two @code{\version} commands. We'll need the
2316 @code{melody} section. We don't want two @code{\score} sections
2317 -- if we had two @code{\score}s, we'd get the two parts separately.
2318 We want them together, as a duet. Within the @code{\score}
2319 section, we don't need two @code{\layout} or @code{\midi}.
2321 If we simply cut and paste the @code{melody} section, we would
2322 end up with two @code{melody} definitions. This would not generate
2323 an error, but the second one would be used for both melodies.
2324 So let's rename them to make them distinct. We'll call the
2325 section for the soprano @code{sopranoMusic} and the section for
2326 the cello @code{celloMusic}. While we're doing this, let's rename
2327 @code{text} to be @code{sopranoLyrics}. Remember to rename both
2328 instances of all these names -- both the initial definition (the
2329 @code{melody = \relative c' @{ } part) and the name's use (in the
2330 @code{\score} section).
2332 While we're doing this, let's change the cello part's staff --
2333 celli normally use bass clef. We'll also give the cello some
2337 \version @w{"@version{}"}
2338 sopranoMusic = \relative c' @{
2345 sopranoLyrics = \lyricmode @{
2349 celloMusic = \relative c @{
2358 \new Voice = "one" @{
2362 \new Lyrics \lyricsto "one" \sopranoLyrics
2369 This is looking promising, but the cello part won't appear in the
2370 score -- we haven't used it in the @code{\score} section. If we
2371 want the cello part to appear under the soprano part, we need to add
2374 \new Staff \celloMusic
2378 underneath the soprano stuff. We also need to add @code{<<} and
2379 @code{>>} around the music -- that tells LilyPond that there's
2380 more than one thing (in this case, two @code{Staves}) happening
2381 at once. The @code{\score} looks like this now:
2383 @c Indentation in this example is deliberately poor
2388 \new Voice = "one" @{
2392 \new Lyrics \lyricsto "one" \sopranoLyrics
2394 \new Staff \celloMusic
2402 This looks a bit messy; the indentation is messed up now. That is
2403 easily fixed. Here's the complete soprano and cello template.
2405 @lilypond[quote,verbatim,ragged-right,addversion]
2406 sopranoMusic = \relative c' {
2413 sopranoLyrics = \lyricmode {
2417 celloMusic = \relative c {
2427 \new Voice = "one" {
2431 \new Lyrics \lyricsto "one" \sopranoLyrics
2433 \new Staff \celloMusic
2442 The starting templates can be found in the @q{Templates} appendix,
2443 see @ref{Single staff}.
2446 @node Four-part SATB vocal score
2447 @subsection Four-part SATB vocal score
2449 @cindex template, SATB
2450 @cindex SATB template
2452 Most vocal scores of music written for four-part mixed choir
2453 with orchestral accompaniment such as Mendelssohn's Elijah or
2454 Handel's Messiah have the choral music and words on four
2455 staves, one for each of SATB, with a piano reduction of the
2456 orchestral accompaniment underneath. Here's an example
2457 from Handel's Messiah:
2459 @c The following should appear as music without code
2460 @lilypond[quote,ragged-right]
2461 global = { \key d \major \time 4/4 }
2462 sopranoMusic = \relative c'' {
2464 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
2466 sopranoWords = \lyricmode {
2467 Wor -- thy is the lamb that was slain
2469 altoMusic = \relative a' {
2471 r4 a2 a4 | fis4. fis8 a2 | g4 fis e2 |
2473 altoWords = \sopranoWords
2474 tenorMusic = \relative c' {
2476 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
2478 tenorWords = \sopranoWords
2479 bassMusic = \relative c' {
2481 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
2483 bassWords = \sopranoWords
2484 upper = \relative a' {
2487 r4 <a d fis>2 <a e' a>4 |
2488 <d fis d'>4. <d fis d'>8 <a d a'>2 |
2489 <g cis g'>4 <a d fis> <a cis e>2 |
2491 lower = \relative c, {
2494 <d d'>4 <d d'>2 <cis cis'>4 |
2495 <b b'>4. <b' b'>8 <fis fis'>2 |
2496 <e e'>4 <d d'> <a' a'>2 |
2500 << % combine ChoirStaff and PianoStaff in parallel
2502 \new Staff = "sopranos" <<
2503 \set Staff.instrumentName = "Soprano"
2504 \new Voice = "sopranos" { \global \sopranoMusic }
2506 \new Lyrics \lyricsto "sopranos" { \sopranoWords }
2507 \new Staff = "altos" <<
2508 \set Staff.instrumentName = "Alto"
2509 \new Voice = "altos" { \global \altoMusic }
2511 \new Lyrics \lyricsto "altos" { \altoWords }
2512 \new Staff = "tenors" <<
2513 \set Staff.instrumentName = "Tenor"
2514 \new Voice = "tenors" { \global \tenorMusic }
2516 \new Lyrics \lyricsto "tenors" { \tenorWords }
2517 \new Staff = "basses" <<
2518 \set Staff.instrumentName = "Bass"
2519 \new Voice = "basses" { \global \bassMusic }
2521 \new Lyrics \lyricsto "basses" { \bassWords }
2525 \set PianoStaff.instrumentName = "Piano"
2526 \new Staff = "upper" \upper
2527 \new Staff = "lower" \lower
2533 None of the templates provides this layout exactly. The nearest is
2534 @q{SATB vocal score and automatic piano reduction} -- see @ref{Vocal
2535 ensembles} -- but we need to change the layout and add a piano
2536 accompaniment which is not derived automatically from the vocal parts.
2537 The variables holding the music and words for the vocal parts are
2538 fine, but we shall need to add variables for the piano reduction.
2540 The order in which the contexts appear in the ChoirStaff of
2541 the template do not correspond with the order in the vocal
2542 score shown above. We need to rearrange them so there are
2543 four staves with the words written directly underneath the
2544 notes for each part.
2545 All the voices should be @code{\voiceOne}, which is
2546 the default, so the @code{\voiceXXX} commands should be removed.
2547 We also need to specify the tenor clef for the tenors.
2548 The way in which lyrics are specified in the template has not yet
2549 been encountered so we need to use the method with which we are
2550 familiar. We should also add the names of each staff.
2552 Doing this gives for our ChoirStaff:
2556 \new Staff = "sopranos" <<
2557 \set Staff.instrumentName = "Soprano"
2558 \new Voice = "sopranos" @{ \global \sopranoMusic @}
2560 \new Lyrics \lyricsto "sopranos" @{ \sopranoWords @}
2561 \new Staff = "altos" <<
2562 \set Staff.instrumentName = "Alto"
2563 \new Voice = "altos" @{ \global \altoMusic @}
2565 \new Lyrics \lyricsto "altos" @{ \altoWords @}
2566 \new Staff = "tenors" <<
2567 \set Staff.instrumentName = "Tenor"
2568 \new Voice = "tenors" @{ \global \tenorMusic @}
2570 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
2571 \new Staff = "basses" <<
2572 \set Staff.instrumentName = "Bass"
2573 \new Voice = "basses" @{ \global \bassMusic @}
2575 \new Lyrics \lyricsto "basses" @{ \bassWords @}
2579 Next we must work out the piano part. This is
2580 easy - we just pull out the piano part from the
2581 @q{Solo piano} template:
2585 \set PianoStaff.instrumentName = "Piano "
2586 \new Staff = "upper" \upper
2587 \new Staff = "lower" \lower
2591 and add the variable definitions for @code{upper}
2594 The ChoirStaff and PianoStaff must be combined
2595 using angle brackets as we want them to be
2596 stacked one above the other:
2599 << % combine ChoirStaff and PianoStaff one above the other
2601 \new Staff = "sopranos" <<
2602 \new Voice = "sopranos" @{ \global \sopranoMusic @}
2604 \new Lyrics \lyricsto "sopranos" @{ \sopranoWords @}
2605 \new Staff = "altos" <<
2606 \new Voice = "altos" @{ \global \altoMusic @}
2608 \new Lyrics \lyricsto "altos" @{ \altoWords @}
2609 \new Staff = "tenors" <<
2610 \clef "G_8" % tenor clef
2611 \new Voice = "tenors" @{ \global \tenorMusic @}
2613 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
2614 \new Staff = "basses" <<
2616 \new Voice = "basses" @{ \global \bassMusic @}
2618 \new Lyrics \lyricsto "basses" @{ \bassWords @}
2622 \set PianoStaff.instrumentName = "Piano"
2623 \new Staff = "upper" \upper
2624 \new Staff = "lower" \lower
2629 Combining all these together and adding the music
2630 for the three bars of the example above gives:
2632 @lilypond[quote,verbatim,ragged-right,addversion]
2633 global = { \key d \major \time 4/4 }
2634 sopranoMusic = \relative c'' {
2636 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
2638 sopranoWords = \lyricmode {
2639 Wor -- thy is the lamb that was slain
2641 altoMusic = \relative a' {
2643 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
2645 altoWords = \sopranoWords
2646 tenorMusic = \relative c' {
2648 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
2650 tenorWords = \sopranoWords
2651 bassMusic = \relative c' {
2653 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
2655 bassWords = \sopranoWords
2656 upper = \relative a' {
2659 r4 <a d fis>2 <a e' a>4 |
2660 <d fis d'>4. <d fis d'>8 <a d a'>2 |
2661 <g cis g'>4 <a d fis> <a cis e>2 |
2663 lower = \relative c, {
2666 <d d'>4 <d d'>2 <cis cis'>4 |
2667 <b b'>4. <b' b'>8 <fis fis'>2 |
2668 <e e'>4 <d d'> <a' a'>2 |
2672 << % combine ChoirStaff and PianoStaff in parallel
2674 \new Staff = "sopranos" <<
2675 \set Staff.instrumentName = "Soprano"
2676 \new Voice = "sopranos" { \global \sopranoMusic }
2678 \new Lyrics \lyricsto "sopranos" { \sopranoWords }
2679 \new Staff = "altos" <<
2680 \set Staff.instrumentName = "Alto"
2681 \new Voice = "altos" { \global \altoMusic }
2683 \new Lyrics \lyricsto "altos" { \altoWords }
2684 \new Staff = "tenors" <<
2685 \set Staff.instrumentName = "Tenor"
2686 \new Voice = "tenors" { \global \tenorMusic }
2688 \new Lyrics \lyricsto "tenors" { \tenorWords }
2689 \new Staff = "basses" <<
2690 \set Staff.instrumentName = "Bass"
2691 \new Voice = "basses" { \global \bassMusic }
2693 \new Lyrics \lyricsto "basses" { \bassWords }
2697 \set PianoStaff.instrumentName = "Piano "
2698 \new Staff = "upper" \upper
2699 \new Staff = "lower" \lower
2706 @node Building a score from scratch
2707 @subsection Building a score from scratch
2709 @cindex template, writing your own
2711 After gaining some facility with writing LilyPond code, you
2712 may find that it is easier to build a score from scratch
2713 rather than modifying one of the templates. You can also
2714 develop your own style this way to suit the sort of music you
2715 like. Let's see how to put together the score for an organ
2716 prelude as an example.
2718 We begin with a header section. Here go the title, name
2719 of composer, etc, then come any variable definitions, and
2720 finally the score block. Let's start with these in outline
2721 and fill in the details later.
2723 We'll use the first two bars of Bach's prelude
2724 based on @emph{Jesu, meine Freude} which is written for two
2725 manuals and pedal organ. You can see these two bars of music
2726 at the bottom of this section. The top manual part has two voices,
2727 the lower and pedal organ one each. So we need four
2728 music definitions and one to define the time signature
2732 \version @w{"@version{}"}
2734 title = "Jesu, meine Freude"
2735 composer = "J S Bach"
2737 TimeKey = @{ \time 4/4 \key c \minor @}
2738 ManualOneVoiceOneMusic = @{s1@}
2739 ManualOneVoiceTwoMusic = @{s1@}
2740 ManualTwoMusic = @{s1@}
2741 PedalOrganMusic = @{s1@}
2747 For now we've just used a spacer note, @code{s1},
2748 instead of the real music. We'll add that later.
2750 Next let's see what should go in the score block.
2751 We simply mirror the staff structure we want.
2752 Organ music is usually written on three staves,
2753 one for each manual and one for the pedals. The
2754 manual staves should be bracketed together, so we
2755 need to use a PianoStaff for them. The first
2756 manual part needs two voices and the second manual
2761 \new Staff = "ManualOne" <<
2762 \new Voice @{ \ManualOneVoiceOneMusic @}
2763 \new Voice @{ \ManualOneVoiceTwoMusic @}
2764 >> % end ManualOne Staff context
2765 \new Staff = "ManualTwo" <<
2766 \new Voice @{ \ManualTwoMusic @}
2767 >> % end ManualTwo Staff context
2768 >> % end PianoStaff context
2771 Next we need to add a staff for the pedal organ.
2772 This goes underneath the PianoStaff, but it must
2773 be simultaneous with it, so we need angle brackets
2774 around the two. Missing these out would generate
2775 an error in the log file. It's a common mistake
2776 which you'll make sooner or later! Try copying
2777 the final example at the end of this section,
2778 remove these angle brackets, and compile it to
2779 see what errors it generates.
2782 << % PianoStaff and Pedal Staff must be simultaneous
2784 \new Staff = "ManualOne" <<
2785 \new Voice @{ \ManualOneVoiceOneMusic @}
2786 \new Voice @{ \ManualOneVoiceTwoMusic @}
2787 >> % end ManualOne Staff context
2788 \new Staff = "ManualTwo" <<
2789 \new Voice @{ \ManualTwoMusic @}
2790 >> % end ManualTwo Staff context
2791 >> % end PianoStaff context
2792 \new Staff = "PedalOrgan" <<
2793 \new Voice @{ \PedalOrganMusic @}
2798 It is not necessary to use the simultaneous construct
2799 @code{<< .. >>} for the manual two staff and the pedal organ staff,
2800 since they contain only one music expression, but it does no harm,
2801 and always using angle brackets after @code{\new Staff} is a good
2802 habit to cultivate in case there are multiple voices. The opposite
2803 is true for Voices: these should habitually be followed by braces
2804 @code{@{ .. @}} in case your music is coded in several variables
2805 which need to run consecutively.
2807 Let's add this structure to the score block, and adjust the indenting.
2808 We also add the appropriate clefs, ensure stems, ties and slurs in
2809 each voice on the upper staff point to the right direction with
2810 @code{\voiceOne} and @code{\voiceTwo}, and enter the time signature
2811 and key to each staff using our predefined variable, @code{\TimeKey}.
2815 << % PianoStaff and Pedal Staff must be simultaneous
2817 \new Staff = "ManualOne" <<
2818 \TimeKey % set time signature and key
2820 \new Voice @{ \voiceOne \ManualOneVoiceOneMusic @}
2821 \new Voice @{ \voiceTwo \ManualOneVoiceTwoMusic @}
2822 >> % end ManualOne Staff context
2823 \new Staff = "ManualTwo" <<
2826 \new Voice @{ \ManualTwoMusic @}
2827 >> % end ManualTwo Staff context
2828 >> % end PianoStaff context
2829 \new Staff = "PedalOrgan" <<
2832 \new Voice @{ \PedalOrganMusic @}
2833 >> % end PedalOrgan Staff
2835 @} % end Score context
2838 That completes the structure. Any three-staff organ music
2839 will have a similar structure, although the number of voices
2840 may vary. All that remains now
2841 is to add the music, and combine all the parts together.
2843 @lilypond[quote,verbatim,ragged-right,addversion]
2845 title = "Jesu, meine Freude"
2846 composer = "J S Bach"
2848 TimeKey = { \time 4/4 \key c \minor }
2849 ManualOneVoiceOneMusic = \relative g' {
2850 g4 g f ees | d2 c2 |
2852 ManualOneVoiceTwoMusic = \relative c' {
2853 ees16 d ees8~ ees16 f ees d c8 d~ d c~ |
2854 c c4 b8 c8. g16 c b c d |
2856 ManualTwoMusic = \relative c' {
2857 c16 b c8~ c16 b c g a8 g~ g16 g aes ees |
2858 f ees f d g aes g f ees d e8~ ees16 f ees d |
2860 PedalOrganMusic = \relative c {
2861 r8 c16 d ees d ees8~ ees16 a, b g c b c8 |
2862 r16 g ees f g f g8 c,2 |
2866 << % PianoStaff and Pedal Staff must be simultaneous
2868 \new Staff = "ManualOne" <<
2869 \TimeKey % set time signature and key
2871 \new Voice { \voiceOne \ManualOneVoiceOneMusic }
2872 \new Voice { \voiceTwo \ManualOneVoiceTwoMusic }
2873 >> % end ManualOne Staff context
2874 \new Staff = "ManualTwo" <<
2877 \new Voice { \ManualTwoMusic }
2878 >> % end ManualTwo Staff context
2879 >> % end PianoStaff context
2880 \new Staff = "PedalOrgan" <<
2883 \new Voice { \PedalOrganMusic }
2884 >> % end PedalOrgan Staff context
2886 } % end Score context