X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Ffundamental.itely;h=f9f9343f5f4e141663235d1ad910b329aca6ac1f;hb=e44f9f849d05d3169088f71f4960923b1da826c3;hp=4aa1eb68c29c57f0033cdb6503714876b09420ca;hpb=6be33a0b6d6781fc8f2fce09bd996189c1c59c73;p=lilypond.git diff --git a/Documentation/user/fundamental.itely b/Documentation/user/fundamental.itely index 4aa1eb68c2..f9f9343f5f 100644 --- a/Documentation/user/fundamental.itely +++ b/Documentation/user/fundamental.itely @@ -4,9 +4,16 @@ @node Fundamental concepts @chapter Fundamental concepts +You've seen in the Tutorial how to produce beautifully printed +music from a simple text file. This section introduces the +concepts and techniques required to produce equally beautiful +but more complex scores. + @menu * How LilyPond files work:: -* Score is a single musical expression:: +* Voices contain music:: +* Contexts and engravers:: +* Extending the templates:: @end menu @@ -15,17 +22,27 @@ The LilyPond input format is quite free-form, giving experienced users a lot of flexibility to structure their files however they -wish. However, this flexibility can make things confusing for new +wish. But this flexibility can make things confusing for new users. This section will explain some of this structure, but may gloss over some details in favor of simplicity. For a complete description of the input format, see @ruser{File structure}. +@menu +* Introduction to the LilyPond file structure:: +* Score is a (single) compound musical expression:: +* Nesting music expressions:: +* On the un-nestedness of brackets and ties:: +@end menu + +@node Introduction to the LilyPond file structure +@subsection Introduction to the LilyPond file structure + A basic example of a lilypond input file is @example -\version "2.11.23" +\version @w{"@version{}"} \score @{ - @{@var{...music expression...}@} % all the music goes here! + @var{...compound music expression...} % all the music goes here! \header @{ @} \layout @{ @} \midi @{ @} @@ -36,10 +53,10 @@ A basic example of a lilypond input file is There are many variations of this basic pattern, but this example serves as a useful starting place. -At this point, you may be confused, since you have never seen a -@code{\score@{@}} before. This is because LilyPond automatically -adds the extra commands when you give it simple input. LilyPond -treats input like this: +Up to this point none of the examples you have seen has used a +@code{\score@{@}} command. This is because LilyPond automatically +adds the extra commands which are needed when you give it simple +input. LilyPond treats input like this: @example \relative c'' @{ @@ -51,23 +68,31 @@ treats input like this: as shorthand for this: @example -\score @{ - \relative c'' @{ - c4 a b c +\book @{ + \score @{ + \new Staff @{ + \new Voice @{ + \relative c'' @{ + c4 a b c + @} + @} + @} + \layout @{ @} @} - \layout @{ @} @} @end example In other words, if the input contains a single music expression, LilyPond will interpret the file as though the music expression -was wrapped up inside a @code{\score@{@}}. +was wrapped up inside the commands shown above. For now, though, +let us return to the first example and examine the @code{\score} +command, leaving the others to default. -@smallspace - -A @code{\score} must begin with a single music -expression. Remember that a music expression could -be anything from a single note to a huge +A @code{\score} block must always contain just one music +expression, and +this must appear immediately after the @code{\score} command. +Remember that a music expression could be anything from a single +note to a huge compound expression like @example @{ @@ -81,8 +106,8 @@ be anything from a single note to a huge Since everything is inside @code{@{ ... @}}, it counts as one music expression. -As we saw previously, the @code{\score} can contain other things, -such as +As we saw previously, the @code{\score} block can contain other +things, such as @example \score @{ @@ -96,15 +121,29 @@ such as @noindent Some people put some of those commands outside the @code{\score} block -- for example, @code{\header} is often placed above the -@code{\score}. That's just another shorthand that LilyPond +@code{\score} command. That's just another shorthand that LilyPond accepts. -@smallspace +Two more commands you have not previously seen are +@code{\layout @{ @}} and @code{\midi @{@}}. If these appear as +shown they will cause LilyPond to produce a printed output and a +MIDI output respectively. They are described fully in the +Notation Reference -- @ruser{Score layout} and +@ruser{Creating MIDI files}. + +You may code multiple @code{\score} blocks. Each will be +treated as a separate score, but they will be all combined into +a single output file. A @code{\book} command is not necessary +-- one will be implicitly created. However, if you would like +separate output files from one @code{.ly} file then the +@code{\book} command should be used to separate the different +sections: each @code{\book} block will produce a +separate output file. For details see @ruser{Multiple scores +in a book}. @cindex variables -@cindex identifiers -Another great shorthand is the ability to define identifiers. All +Another great shorthand is the ability to define variables. All the templates use this @example @@ -113,27 +152,35 @@ melody = \relative c' @{ @} \score @{ - @{ \melody @} + \melody @} @end example When LilyPond looks at this file, it takes the value of @code{melody} (everything after the equals sign) and inserts it whenever it sees @code{\melody}. There's nothing special about -the names -- it could be @code{melody}, @code{global}, -@code{pianorighthand}, or @code{foofoobarbaz}. You can use -whatever variable names you want. For more details, see -@ruser{Saving typing with identifiers and functions}. +the names -- it could be @code{melody}, @code{global}, +@code{TimeKey}, +@code{pianorighthand}, or @code{foofoobarbaz}. For more details, +see @ref{Saving typing with variables and functions}. +Remember that you can use almost any name you like as long +as it contains just alphabetic characters and is distinct from +LilyPond command names. The exact +limitations on variable names are detailed in +@ruser{File structure}. + @seealso -For a complete definition of the input format, see @ruser{File -structure}. +For a complete definition of the input format, see +@ruser{File structure}. +@node Score is a (single) compound musical expression +@subsection Score is a (single) compound musical expression -@node Score is a single musical expression -@section Score is a single musical expression +@cindex Compound music expression +@cindex Music expression, compound We saw the general organization of LilyPond input files in the previous section, @ref{How LilyPond files work}. But we seemed to @@ -144,67 +191,71 @@ We didn't skip over it at all. The big mystery is simply that there @emph{is} no mystery. This line explains it all: @quotation -@emph{A @code{\score} must begin with a single music expression.} +@emph{A @code{\score} block must begin with a compound music expression.} @end quotation @noindent -You may find it useful to review @ruser{Music expressions -explained}. In that section, we saw how to build big music -expressions from small pieces -- we started from notes, then -chords, etc. Now we're going to start from a big music expression -and work our way down. +You may find it useful to review +@ref{Music expressions explained}. In that section, we saw how to +build big music expressions from small pieces -- we started from +notes, then chords, etc. Now we're going to start from a big +music expression and work our way down. @example \score @{ - @{ % this brace begins the overall music expression + @{ % this brace begins the overall compound music expression \new GrandStaff << @var{...insert the whole score of a Wagner opera in here...} >> - @} % this brace ends the overall music expression + @} % this brace ends the overall compound music expression \layout @{ @} @} @end example A whole Wagner opera would easily double the length of this manual, so let's just add a singer and piano. We don't need a -@code{GrandStaff} for this ensemble, so we shall remove it. We -@emph{do} need a singer and a piano, though. +@code{GrandStaff} for this ensemble, which simply groups a number +of staves together with a brace at the left, so we shall remove +it. We @emph{do} need a singer and a piano, though. @example \score @{ - @{ - << - \new Staff = "singer" << - >> - \new PianoStaff = piano << - >> + << + \new Staff = "singer" << >> - @} + \new PianoStaff = piano << + >> + >> \layout @{ @} @} @end example -Remember that we use @code{<<} and @code{>>} to show simultaneous +Remember that we use @code{<< ... >>} instead of +@code{@{ ... @}} to show simultaneous music. And we definitely want to show the vocal part and piano -part at the same time, not one after the other! +part at the same time, not one after the other! However, the +@code{<< ... >>} construct is not really necessary for the Singer +staff, as it contains only one music expression, but Staves often +do require simultaneous Voices within them, so using +@code{<< ... >>} +rather than braces is a good habit to adopt. We'll add some real +music later; for now let's just put in some dummy notes and lyrics. -@example -\score @{ - @{ - << - \new Staff = "singer" << - \new Voice = "vocal" @{ @} - >> - \new Lyrics \lyricsto vocal \new Lyrics @{ @} - \new PianoStaff = "piano" << - \new Staff = "upper" @{ @} - \new Staff = "lower" @{ @} - >> +@lilypond[verbatim,quote,ragged-right] +\score { + << + \new Staff = "singer" << + \new Voice = "vocal" { c'1 } + \addlyrics { And } >> - @} - \layout @{ @} -@} -@end example + \new PianoStaff = "piano" << + \new Staff = "upper" { c'1 } + \new Staff = "lower" { c'1 } + >> + >> + \layout { } +} +@end lilypond Now we have a lot more details. We have the singer's staff: it contains a @code{Voice} (in LilyPond, this term refers to a set of @@ -218,46 +269,2086 @@ braces next to @code{\new Voice = vocal}, we could start writing @example \relative c'' @{ - a4 b c d + r4 d8\noBeam g, c4 r @} @end example But if we did that, the @code{\score} section would get pretty long, and it would be harder to understand what was happening. So -let's use identifiers (or variables) instead. +let's use variables instead. These were introduced at the end +of the previous section, remember? So, adding a few notes, we +now have a piece of real music: + +@lilypond[verbatim,quote,ragged-right] +melody = \relative c'' { r4 d8\noBeam g, c4 r } +text = \lyricmode { And God said, } +upper = \relative c'' { 2~ } +lower = \relative c { b2 e2 } + +\score { + << + \new Staff = "singer" << + \new Voice = "vocal" { \melody } + \addlyrics { \text } + >> + \new PianoStaff = "piano" << + \new Staff = "upper" { \upper } + \new Staff = "lower" { + \clef "bass" + \lower + } + >> + >> + \layout { } +} +@end lilypond + + +Be careful about the difference between notes, which are introduced +with @code{\relative}, and lyrics, which are introduced with +@code{\lyricmode}. These are essential to tell LilyPond +to interpret the following content as music and text +respectively. + +When writing (or reading) a @code{\score} section, just take it +slowly and carefully. Start with the outer layer, then work on +each smaller layer. It also really helps to be strict with +indentation -- make sure that each item on the same layer starts +on the same horizontal position in your text editor. + + +@node Nesting music expressions +@subsection Nesting music expressions + +It is not essential to declare all staves at the beginning; +they may be introduced temporarily at any point. This is +particularly useful for creating ossia sections +(see @rglos{ossia}). Here is a simple example showing how +to introduce a new staff temporarily for the duration of +three notes: + +@lilypond[verbatim,quote,ragged-right] +\new Staff { + \relative g' { + r4 g8 g c4 c8 d | + e4 r8 + << + { f c c } + \new Staff { + f8 f c + } + >> + r4 | + } +} +@end lilypond + +@noindent +Note that the size of the clef is the same as a clef printed +following a clef change -- slightly smaller than the clef +at the begining of the line. This is usual for clefs printed +in the middle of a line. + +The ossia section may be placed above the staff +as follows: + +@lilypond[verbatim,quote,ragged-right] +\new Staff ="main" { + \relative g' { + r4 g8 g c4 c8 d | + e4 r8 + << + { f c c } + \new Staff \with { + alignAboveContext = "main" } + { f8 f c } + >> + r4 | + } +} +@end lilypond + +This example uses @code{\with}, which will be explained more +fully later. It is a means of modifying the default behaviour +of a single Staff. Here it says that the new staff should be +placed above the staff called @qq{main} instead of the default +position which is below. + +Ossia are often written without clef and without +time signature and are usually in a smaller font. +These require further commands which +have not yet been introduced. See @ref{Size of objects} + +@node On the un-nestedness of brackets and ties +@subsection On the un-nestedness of brackets and ties + +You have already met a number of different types of bracket in +writing the input file to LilyPond. These obey different rules +which can be confusing at first. Before we explain the rules +let's first review the different types of bracket. + +@c attempt to force this onto a new page +@need 50 +@multitable @columnfractions .3 .7 +@headitem Bracket Type + @tab Function +@item @code{@{ .. @}} + @tab Encloses a sequential segment of music +@item @code{< .. >} + @tab Encloses the notes of a chord +@item @code{<< .. >>} + @tab Encloses concurrent or simultaneous sections +@item @code{( .. )} + @tab Marks the start and end of a slur +@item @code{\( .. \)} + @tab Marks the start and end of a phrase mark +@item @code{[ .. ]} + @tab Marks the start and end of a manual beam +@end multitable + +To these we should add other constructs which generate lines +between or across notes: ties (marked by a tilde, @code{~}), +tuplets written as @code{\times x/y @{..@}}, and grace notes +written as @code{\grace@{..@}}. + +Outside LilyPond, the conventional use of brackets requires +the different types to be properly nested, like this, +@code{<< [ @{ ( .. ) @} ] >>}, with the closing brackets being +encountered in exactly the opposite order to the opening +brackets. This @strong{is} a requirement for the three types of +bracket described by the word @q{Encloses} in the table above -- +they must nest properly. +However, the remaining brackets, described with the word +@q{Marks} in the table above together with ties and tuplets, +do @strong{not} have to nest +properly with any of the brackets. In fact, these are not +brackets in the sense that +they enclose something -- they are simply markers to indicate +where something starts and ends. + +So, for example, a phrasing slur can start before a manually +inserted beam and end before the end of the beam -- not very +musical, perhaps, but possible: + +@lilypond[quote,verbatim,fragment,ragged-right,relative=2] + { g8\( a b[ c b\) a] } +@end lilypond + +In general, different kinds of brackets, and those implied by +tuplets, ties and grace notes, may be mixed freely. +This example shows a beam extending into a tuplet (line 1), +a slur extending into a tuplet (line 2), +a beam and a slur extending into a tuplet, a tie crossing +two tuplets, and a phrasing slur extending out of a tuplet +(lines 3 and 4). + +@lilypond[quote,verbatim,fragment,ragged-right] +{ + r16[ g16 \times 2/3 {r16 e'8] } + g16( a \times 2/3 {b d) e' } + g8[( a \times 2/3 {b d') e'~]} + \times 4/5 {e'32\( a b d' e'} a'4.\) +} +@end lilypond + + +@node Voices contain music +@section Voices contain music + +Singers need voices to sing, and so does LilyPond. +The actual music for all instruments in a score +is contained in Voices -- the most fundamental +of all LilyPond's concepts. + +@menu +* I'm hearing Voices:: +* Explicitly instantiating voices:: +* Voices and vocals:: +@end menu + +@node I'm hearing Voices +@subsection I'm hearing Voices + +@cindex polyphony +@cindex layers +@cindex Voice context + +The lowest, most fundamental or innermost layers in a LilyPond +score are called @q{Voice contexts} or just @q{Voices} for short. +Voices are sometimes called @q{layers} in other notation +packages. + +In fact, a Voice layer or context is the only one which can +contain music. If a Voice context is not explicitly declared +one is created automatically, as we saw at the beginning of +this chapter. Some instruments such as an +Oboe can play only one note at a time. Music written for +such instruments is monophonic and requires just a single +voice. Instruments which can play more than one note at a +time like the piano will often require multiple voices to +encode the different concurrent notes and rhythms they are +capable of playing. + +A single voice can contain many notes in a chord, of course, +so when exactly are multiple voices needed? Look first at +this example of four chords: + +@lilypond[quote,verbatim,fragment,ragged-right,relative=1] +\key g \major +4 +@end lilypond + +This can be expressed using just the single angle bracket chord +symbols, @code{< ... >}, and for this just a single voice is +needed. But suppose the F-sharp were actually an eighth-note +followed by an eighth-note G, a passing note on the way to the A? +Now we have two notes which start at the same time but have +different durations: the quarter-note D and the eighth-note +F-sharp. How are these to be coded? They cannot be written as +a chord because all the notes in a chord must have the same +duration. And they cannot be written as two separate notes +as they need to start at the same time. This is when two +voices are required. + +Let us see how this is done in LilyPond input syntax. + +@funindex << \\ >> +@funindex \\ + +The easiest way to enter fragments with more than one voice on a +staff is to enter each voice as a sequence (with @code{@{...@}}), +and combine them simultaneously with angle brackets, @code{<<...>>}. +The fragments must also be separated with double backward slashes, +@code{\\}, to place them in separate voices. Without these, the +notes would be entered into a single voice, which would usually +cause errors. This technique is particularly suited to pieces of +music which are largely monophonic with occasional short sections +of polyphony. + +Here's how we split the chords above into two voices and add both +the passing note and a slur: + +@lilypond[quote,verbatim,fragment,ragged-right,relative=2] +\key g \major +% Voice "1" Voice "2" +<< { g4 fis8( g) a4 g } \\ { d4 d d d } >> | +@end lilypond + +Notice how the stems of the second voice now point down. + +Here's another simple example: + +@lilypond[quote,verbatim,fragment,ragged-right,relative=2] +\key d \minor +% Voice "1" Voice "2" +<< { r4 g g4. a8 } \\ { d,2 d4 g } >> | +<< { bes4 bes c bes } \\ { g4 g g8( a) g4 } >> | +<< { a2. r4 } \\ { fis2. s4 } >> | +@end lilypond + +It is not necessary to use a separate @code{<< \\ >>} construct +for each bar. For music with few notes in each bar this layout +can help the legibility of the code, but if there are many +notes in each bar it may be better to split out each voice +separately, like this: + +@lilypond[quote,verbatim,fragment,ragged-right,relative=2] +\key d \minor +<< { + % Voice "1" + r4 g g4. a8 | + bes4 bes c bes | + a2. r4 | +} \\ { + % Voice "2" + d,2 d4 g | + g4 g g8( a) g4 | + fis2. s4 | +} >> +@end lilypond + + +This example has just two voices, but the same contruct may be +used to encode three or more voices by adding more back-slash +separators. + +The Voice contexts bear the names @code{"1"}, @code{"2"}, etc. +In each of these contexts, the vertical direction of slurs, +stems, ties, dynamics etc., is set appropriately. + +@lilypond[quote,verbatim,fragment] +\new Staff \relative c' { + % Main voice + c16 d e f + % Voice "1" Voice "2" Voice "3" + << { g4 f e } \\ { r8 e4 d c8 ~ } >> | + << { d2 e2 } \\ { c8 b16 a b8 g ~ g2 } \\ { s4 b4 c2 } >> | +} +@end lilypond + +These voices are all separate from the main voice that contains +the notes just outside the @code{<< .. >>} construct. Let's call +this the @emph{simultaneous construct}. Slurs and ties may only +connect notes within the same voice, so slurs and ties cannot go +into or out of a simultaneous construct. Conversely, +parallel voices from separate simultaneous constructs on the same +staff are the same voice. Other voice-related properties also +carry across simultaneous constructs. Here is the same example, +with different colors and note heads for each voice. Note that +changes in one voice do not affect other voices, but they do +persist in the same voice later. Note also that tied notes may be +split across the same voices in two constructs, shown here in the +blue triangle voice. + +@lilypond[quote,verbatim] +\new Staff \relative c' { + % Main voice + c16 d e f + << % Bar 1 + { + \voiceOneStyle + g4 f e + } + \\ + { + \voiceTwoStyle + r8 e4 d c8 ~ + } + >> + << % Bar 2 + % Voice 1 continues + { d2 e2 } + \\ + % Voice 2 continues + { c8 b16 a b8 g ~ g2 } + \\ + { + \voiceThreeStyle + s4 b4 c2 + } + >> +} +@end lilypond + +The commands @code{\voiceXXXStyle} are mainly intended for use in +educational documents such as this one. They modify the color +of the note head, the stem and the beams, and the style of the +note head, so that the voices may be easily distinguished. +Voice one is set to red diamonds, voice two to blue triangles, +voice three to green crossed circles, and voice four (not used +here) to magenta crosses. We shall see later how commands like +these may be created by the user. +See @ref{Visibility and color of objects} +TODO Add link to using variables for tweaks + +Polyphony does not change the relationship of notes within a +@code{\relative @{ @}} block. Each note is still calculated +relative to the note immediately preceding it, or to the first +note of the preceding chord. So in + +@example +\relative c' @{ noteA << < noteB noteC > \\ noteD >> noteE @} +@end example + +@noindent +@code{noteB} is relative to @code{noteA} @* +@code{noteC} is relative to @code{noteB}, not @code{noteA}; @* +@code{noteD} is relative to @code{noteB}, not @code{noteA} or +@code{noteC}. @* +@code{noteE} is relative to @code{noteD}, not @code{noteA} + +An alternative way, which may be clearer if the notes in the +voices are widely separated, is to place a @code{\relative} +command at the start of each voice: + +@example +\relative c' @{ noteA ... @} +<< + \relative c'' @{ < noteB noteC > ... @} +\\ + \relative g' @{ noteD ... @} +>> +\relative c' @{ noteE ... @} +@end example + +Let us finally analyse the voices in a more complex piece of +music. Here are +the notes from the first two bars of the second of Chopin's +Deux Nocturnes, Op 32. This example will be used at later +stages in this and the next chapter to illustrate several +techniques for producing notation, so please ignore for now +anything in the underlying code which looks mysterious and +concentrate just on the music and the voices -- the +complications will all be explained in later sections. + +@c The following should appear as music without code +@lilypond[quote,ragged-right] +\new Staff \relative c'' { + \key aes \major + << % Voice one + { c2 aes4. bes8 } + \\ % Voice two + { aes2 f4 fes } + \\ % No voice three + \\ % Voice four + { + % Ignore these for now - they are explained in Ch 4 + \once \override NoteColumn #'force-hshift = #0 + 2 + \once \override NoteColumn #'force-hshift = #0.5 + des2 + } + >> | + 1 | +} +@end lilypond + +The direction of the stems is often used to indicate the +continuity of two simultaneous melodic lines. Here the +stems of the highest notes are all pointing up and the +stems of the lower notes are all pointing down. +This is the first indication that more than one voice +is required. + +But the real need for multiple voices arises when notes +which start at the same time have different durations. +Look at the notes which start at beat three in the first +bar. The A-flat is a dotted quarter note, the F is a +quarter note and the D-flat is a half note. These +cannot be written as a chord as all the notes in a chord +must have the same duration. Neither can they be written +as sequential notes, as they must start at the same time. +This section of the bar requires three voices, and the +normal practice would be to write the whole bar as three +voices, as shown below, where we have used different note heads +and colors for the three voices. Again, the code behind this +example will be explained later, so ignore anything you do +not understand. + +@c The following should appear as music without code +@c The three voice styles should be defined in -init +@lilypond[quote,ragged-right] +\new Staff \relative c'' { + \key aes \major + << + { % Voice one + \voiceOneStyle + c2 aes4. bes8 + } + \\ % Voice two + { \voiceTwoStyle + aes2 f4 fes + } + \\ % No Voice three (we want stems down) + \\ % Voice four + { \voiceThreeStyle + % Ignore these for now - they are explained in Ch 4 + \once \override NoteColumn #'force-hshift = #0 + 2 + \once \override NoteColumn #'force-hshift = #0.5 + des2 + } + >> | + 1 | +} +@end lilypond + + +Let us try to encode this music from scratch. As we +shall see, this encounters some difficulties. We begin as +we have learnt, using the @code{<< \\ >>} construct to +enter the music of the first bar in three voices: + +@lilypond[quote,verbatim,fragment,ragged-right] +\new Staff \relative c'' { + \key aes \major + << + { c2 aes4. bes8 } \\ { aes2 f4 fes } \\ { 2 des2 } + >> + 1 +} +@end lilypond + +@cindex stem down +@cindex stem up + +The stem directions are automatically assigned with the +odd-numbered voices taking upward stems and the even-numbered +voices downward ones. The stems for voices 1 and 2 are right, +but the stems in voice 3 should go down in this particular piece +of music. We can correct this simply by missing out voice three +and placing the music in voice four: + +@lilypond[quote,verbatim,fragment,ragged-right] +\new Staff \relative c'' { + \key aes \major + << % Voice one + { c2 aes4. bes8 } + \\ % Voice two + { aes2 f4 fes } + \\ % Omit Voice three + \\ % Voice four + { 2 des2 } + >> | + 1 | +} +@end lilypond + +@noindent +We see that this fixes the stem direction, but exposes a +problem sometimes encountered with multiple voices -- the +stems of the notes in one voice can collide with the note heads +in other voices. In laying out the notes, LilyPond allows the +notes or chords from two voices to occupy the same vertical +note column provided the stems are in opposite directions, but +the notes from the third and fourth voices are displaced to if +necessary to avoid the note heads +colliding. This usually works well, but in this example the +notes of the lowest voice are clearly not well placed by default. +LilyPond provides several ways to adjust the horizontal placing +of notes. We are not quite ready yet to see how to correct this, +so we shall leave this problem until a later section +(see the force-hshift property in @ref{Fixing overlapping +notation} ) + +@node Explicitly instantiating voices +@subsection Explicitly instantiating voices + +@funindex \voiceOne +@funindex \voiceTwo +@funindex \voiceThree +@funindex \voiceFour + +Voice contexts can also be created manually +inside a @code{<< >>} block to create polyphonic music, using +@code{\voiceOne} ... @code{\voiceFour} to indicate the required +directions of stems, slurs, etc. In longer scores this method +is clearer, as it permits the voices to be separated and to be +given more descriptive names. + +Specifically, the construct @code{<< \\ >>} which we used in +the previous section: + +@example +\new Staff @{ + \relative c' @{ + << @{ e4 f g a @} \\ @{ c,4 d e f @} >> + @} +@} +@end example + +@noindent +is equivalent to + +@example +\new Staff << + \new Voice = "1" @{ \voiceOne \relative c' @{ e4 f g a @} @} + \new Voice = "2" @{ \voiceTwo \relative c' @{ c4 d e f @} @} +>> +@end example + +Both of the above would produce + +@c The following example should not display the code +@lilypond[ragged-right,quote] +\new Staff << + \new Voice = "1" { \voiceOne \relative c' { e4 f g a } } + \new Voice = "2" { \voiceTwo \relative c' { c4 d e f } } +>> +@end lilypond + +The @code{\voiceXXX} commands set the direction of stems, slurs, +ties, articulations, text annotations, augmentation dots of dotted +notes, and fingerings. @code{\voiceOne} and @code{\voiceThree} +make these objects point upwards, while @code{\voiceTwo} and +@code{\voiceFour} make them point downwards. These commands also +generate a horizontal shift for each voice when this is required +to avoid clashes of note heads. The command @code{\oneVoice} +reverts the settings back to the normal values for a single voice. + +Let us see in some simple examples exactly what effect +@code{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on +markup, ties, slurs, and dynamics: + +@lilypond[quote,ragged-right,verbatim] +\relative c'{ + % Default behaviour or behaviour after \oneVoice + c d8 ~ d e4 ( f g a ) b-> c +} +@end lilypond + +@lilypond[quote,ragged-right,verbatim] +\relative c'{ + \voiceOne + c d8 ~ d e4 ( f g a ) b-> c + \oneVoice + c, d8 ~ d e4 ( f g a ) b-> c +} +@end lilypond + +@lilypond[quote,ragged-right,verbatim] +\relative c'{ + \voiceTwo + c d8 ~ d e4 ( f g a ) b-> c + \oneVoice + c, d8 ~ d e4 ( f g a ) b-> c +} +@end lilypond + +An expression that appears directly inside a @code{<< >>} belongs +to the main voice (but, note, @strong{not} in a @code{<< \\ >>} +construct). This is useful when extra voices appear while the +main voice is playing. Here is a more correct rendition of the +example from the previous section. The red diamond-shaped notes +demonstrate that the main melody is now in a single voice context, +permitting a phrasing slur to be drawn over them. + +@lilypond[quote,ragged-right,verbatim] +\new Staff \relative c' { + \voiceOneStyle + % The following notes are monophonic + c16^( d e f + % Start simultaneous section of three voices + << + % Continue the main voice in parallel + { g4 f e | d2 e2) } + % Initiate second voice + \new Voice { + % Set stems, etc, down + \voiceTwo + r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 + } + % Initiate third voice + \new Voice { + % Set stems, etc, up + \voiceThree + s2. | s4 b4 c2 + } + >> +} +@end lilypond + +@cindex nesting music expressions +@cindex nesting simultaneous constructs + +More deeply nested polyphony constructs are possible, and if a +voice appears only briefly this might be a more natural way to +typeset the music. + +@lilypond[quote,ragged-right,verbatim] +\new Staff \relative c' { + c16^( d e f + << + { g4 f e | d2 e2) } + \new Voice { + \voiceTwo + r8 e4 d c8 ~ | + << + {c8 b16 a b8 g ~ g2} + \new Voice { + \voiceThree + s4 b4 c2 + } + >> + } + >> +} +@end lilypond + + +This method of nesting new voices briefly is useful +when only small sections of the music +are polyphonic, but when the whole staff is largely polyphonic +it can be clearer to use multiple voices throughout, using +spacing notes to step over sections where the voice is silent, +as here: + +@lilypond[quote,ragged-right,verbatim] +\new Staff \relative c' << + % Initiate first voice + \new Voice { + \voiceOne + c16^( d e f g4 f e | d2 e2) | + } + % Initiate second voice + \new Voice { + % set stems, etc down + \voiceTwo + s4 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 | + } + % Initiate third voice + \new Voice { + % set stems, etc up + \voiceThree + s1 | s4 b4 c2 | + } +>> +@end lilypond + +@cindex note column +@cindex shift commands +@funindex \shiftOff +@funindex \shiftOn +@funindex \shiftOnn +@funindex \shiftOnnn + +Closely spaced notes in a chord, or notes occuring at the same +time in different voices, are arranged in two, occasionally more, +columns to prevent the note heads overlapping. These are called +note columns. There are separate columns for each voice, and +the currently specified voice-dependent shift is applied to the +note column if there would otherwise be a collision. This can +be seen in the example above. In bar 2 the C in voice two is +shifted to the right relative to the D in voice one, and in the +final chord the C in voice three is also shifted to the right +relative to the other notes. + +The @code{\shiftOn}, @code{\shiftOnn}, @code{\shiftOnnn}, and +@code{\shiftOff} commands specify the degree to which notes and +chords of the voice should be shifted if a collision +would otherwise occur. By default, the outer voices (normally +voices one and two) have @code{\shiftOff} specified, while the +inner voices (three and four) have @code{\shiftOn} specified. +When a shift is applied, Voices one and three are shifted to +the right and voices two and four to the left. + +@code{\shiftOnn} and @code{\shiftOnnn} define further shift +levels which may be specified temporarily to resolve collisions +in complex situations -- see @ref{Real music example}. + +A note column can contain just one note (or chord) from a voice +with stems up and one note (or chord) from a voice with stems +down. If notes from two voices which have their stems in the +same direction are placed at the same position and both voices +have no shift or the same shift specified, the error message +@qq{Too many clashing note columns} will be produced. + +@node Voices and vocals +@subsection Voices and vocals + +Vocal music presents a special difficulty: we need to combine two +expressions -- notes and lyrics. + +You have already seen the @code{\addlyrics@{@}} command, which +handles simple scores well. However, this technique is +quite limited. For more complex music, you must introduce the +lyrics in a @code{Lyrics} context using @code{\new Lyrics} and +explicitly link +the lyrics to the notes with @code{\lyricsto@{@}}, using the +name assigned to the Voice. + +@lilypond[quote,verbatim,fragment] +<< + \new Voice = "one" \relative c'' { + \autoBeamOff + \time 2/4 + c4 b8. a16 g4. f8 e4 d c2 + } + \new Lyrics \lyricsto "one" { + No more let sins and sor -- rows grow. + } +>> +@end lilypond + +The automatic beaming which LilyPond uses by default works well +for instrumental music, but not so well for music with lyrics, +where beaming is either not required at all or is used to indicate +melismata in the lyrics. In the example above we use the command +@code{\autoBeamOff} to turn off the automatic beaming. + +Let us reuse the earlier example from Judas Maccabæus to +illustrate this more flexible technique. We first recast +it to use variables so the music and lyrics can be separated +from the staff structure. We also introduce a ChoirStaff +bracket. The lyrics themselves must be introduced with +@code{\lyricmode} to ensure they are interpreted as lyrics +rather than music. + +@lilypond[quote,verbatim] +global = { \time 6/8 \partial 8 \key f \major} +SopOneMusic = \relative c'' { + c8 | c([ bes)] a a([ g)] f | f'4. b, | c4.~ c4 } +SopTwoMusic = \relative c' { + r8 | r4. r4 c8 | a'([ g)] f f([ e)] d | e([ d)] c bes' } +SopOneLyrics = \lyricmode { + Let | flee -- cy flocks the | hills a -- dorn, __ } +SopTwoLyrics = \lyricmode { + Let | flee -- cy flocks the | hills a -- dorn, } + +\score { + \new ChoirStaff << + \new Staff << + \new Voice = "SopOne" { + \global + \SopOneMusic + } + \new Lyrics \lyricsto "SopOne" { + \SopOneLyrics + } + >> + \new Staff << + \new Voice = "SopTwo" { + \global + \SopTwoMusic + } + \new Lyrics \lyricsto "SopTwo" { + \SopTwoLyrics + } + >> + >> +} +@end lilypond + +This is the basic structure of all vocal scores. More staves may +be added as required, more voices may be added to the staves, +more verses may be added to the lyrics, +and the variables containing the music can easily be placed +in separate files should they become too long. + +Here is a final example of the first line of a hymn with four +verses, set for SATB. In this case the words for all four +parts are the same. + +@lilypond[quote,verbatim] +TimeKey = { \time 4/4 \partial 4 \key c \major} +SopMusic = \relative c' { c4 | e4. e8 g4 g | a a g } +AltoMusic = \relative c' { c4 | c4. c8 e4 e | f f e } +TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 } +BassMusic = \relative c { c4 | c4. c8 c4 c | f8 g a b c4 } +VerseOne = \lyricmode { + E -- | ter -- nal fa -- ther, | strong to save, } +VerseTwo = \lyricmode { + O | Christ, whose voice the | wa -- ters heard, } +VerseThree = \lyricmode { + O | Ho -- ly Spi -- rit, | who didst brood } +VerseFour = \lyricmode { + O | Tri -- ni -- ty of | love and pow'r } + +\score { + \new ChoirStaff << + \new Staff << + \clef "treble" + \new Voice = "Sop" { \voiceOne \TimeKey \SopMusic } + \new Voice = "Alto" { \voiceTwo \AltoMusic } + \new Lyrics \lyricsto "Sop" { \VerseOne } + \new Lyrics \lyricsto "Sop" { \VerseTwo } + \new Lyrics \lyricsto "Sop" { \VerseThree } + \new Lyrics \lyricsto "Sop" { \VerseFour } + >> + \new Staff << + \clef "bass" + \new Voice = "Tenor" { \voiceOne \TimeKey \TenorMusic } + \new Voice = "Bass" { \voiceTwo \BassMusic } + >> + >> +} +@end lilypond + +@node Contexts and engravers +@section Contexts and engravers + +Contexts and engravers have been mentioned informally +in earlier sections; we now must look at +these concepts in more detail, as they are important +in the fine-tuning of LilyPond output. + + +@menu +* Contexts explained:: +* Creating contexts:: +* Engravers explained:: +* Modifying context properties:: +* Adding and removing engravers:: +@end menu + +@node Contexts explained +@subsection Contexts explained + +When music is printed, many notational elements which do not +appear explicitly in the input file must be added to the +output. For example, compare the input and output of the +following example: + +@lilypond[quote,verbatim,relative=2,fragment] +cis4 cis2. g4 +@end lilypond + +The input is rather sparse, but in the output, bar lines, +accidentals, clef, and time signature have been added. When +LilyPond @emph{interprets} the input the musical information +is inspected in time order, similar to reading a score from left +to right. While reading the input, the program remembers where +measure boundaries are, and which pitches require explicit +accidentals. This information must be held on several levels. +For example, the effect of an accidental is limited +to a single staff, while a bar line must be synchronized across +the entire score. + +Within LilyPond, these rules and bits of information are grouped +in @emph{Contexts}. We have already met the +@code{Voice} context. +Others are the @code{Staff} and @code{Score} contexts. +Contexts are hierarchical to reflect the heirarchical nature of +a musical score. +For example: a @code{Staff} context can contain many +@code{Voice} contexts, and a @code{Score} context can +contain many @code{Staff} contexts. + +@quotation +@sourceimage{context-example,5cm,,} +@end quotation + +Each context has the responsibility for enforcing some notation rules, +creating some notation objects and maintaining the associated +properties. For example, the @code{Voice} context may introduce an +accidental and then the @code{Staff} context maintains the rule to +show or suppress the accidental for the remainder of the measure. + +As another example, the synchronization of bar lines is, by default, +handled in the @code{Score} context. +However, in some music we may not want the bar lines to be +synchronized -- consider a polymetric score in 4/4 and 3/4 time. +In such cases, we must modify the default settings of the +@code{Score} and @code{Staff} contexts. + +For very simple scores, contexts are created implicitly, and you need +not be aware of them. For larger pieces, such as anything with more +than one staff, they must be +created explicitly to make sure that you get as many staves as you +need, and that they are in the correct order. For typesetting pieces +with specialized notation, it is usual to modify existing, or +even to define totally new, contexts. + +In addition to the @code{Score,} @code{Staff} and +@code{Voice} contexts there are contexts which fit between +the score and staff levels to control staff groups, such as the +@code{PianoStaff} and @code{ChoirStaff} contexts. There +are also alternative staff and voice contexts, and contexts for +lyrics, percussion, fret boards, figured bass, etc. + +The names of all context types are formed from one or more +words, each word being capitalised and joined immediately to the +preceding word with no hyphen or underscore, e.g., +@code{GregorianTranscriptionStaff}. + +@node Creating contexts +@subsection Creating contexts + +There can be only one top level context: the +@code{Score} +context. This is created with the @code{\score} command, +or, in simple scores, it is created automatically. + +For scores with only one voice and one staff, the +@code{Voice} and @code{Staff} contexts may be left to be +created automatically, but for more complex scores it is +necessary to create them by hand. +The simplest command that does this is @code{\new}. +It is prepended to a music expression, for example + +@funindex \new +@cindex new contexts +@cindex Context, creating + +@example +\new @var{type} @var{music-expression} +@end example + +@noindent +where @var{type} is a context name (like @code{Staff} or +@code{Voice}). This command creates a new context, and starts +interpreting the @var{music-expression} within that context. + +Note that there is no @code{\new Score} command; +the single top-level @code{Score} context is introduced +with @code{\score}. + +The @code{\new} command may also give a identifying name to the +context to distinguish it from other contexts of the same type, + +@example +\new @var{type} = @var{id} @var{music-expression} +@end example + +Note the distinction between the name of the context type, +@code{Staff}, @code{Voice}, etc, and +the identifying name of a particular instance of that type, +which can be any sequence of letters invented by the user. +The identifying name is used to refer back to that particular +instance of a context. We saw this in use in the section on +lyrics in @ref{Voices and vocals}. + + +@node Engravers explained +@subsection Engravers explained + +@cindex engravers + +Every mark on the printed output of a score produced by LilyPond +is produced by an @code{Engraver}. Thus there is an engraver +to print staves, one to print note heads, one for stems, one for +beams, etc, etc. In total there are over 120 such engravers! +Fortunately, for most scores it is not necessary to know about +more than a few, and for simple scores you do not need to know +about any. + +Engravers live and operate in Contexts. +Engravers such as the @code{Metronome_mark_engraver}, whose +action and output applies to the score as a whole, operate in +the highest level context -- the @code{Score} context. + +The @code{Clef_engraver} and @code{Key_engraver} are to be +found in every Staff Context, as different staves may require +different clefs and keys. + +The @code{Note_heads_engraver} and @code{Stem_engraver} live +in every @code{Voice} context, the lowest level context of all. + +Each engraver processes the particular objects associated +with its function, and maintains the properties that relate +to that function. These properties, like the properties +associated with contexts, may be modified to change the +operation of the engraver or the appearance of those elements +in the printed score. + +Engravers all have compound names formed from words which +describe their function. Just the first word is capitalised, +and the remainder are joined to it with underscores. Thus +the @code{Staff_symbol_engraver} is responsible for creating the +lines of the staff, the @code{Clef_engraver} determines and sets +the pitch reference point on the staff by drawing a clef symbol. + +Here are some of the most common engravers together with their +function. You will see it is easy to guess the function from +the name, or vice versa. + +@multitable @columnfractions .3 .7 +@headitem Engraver + @tab Function +@item Accidental_engraver + @tab Makes accidentals, cautionary and suggested accidentals +@item Beam_engraver + @tab Engraves beams +@item Clef_engraver + @tab Engraves clefs +@item Dynamic_engraver + @tab Creates hairpins and dynamic texts +@item Key_engraver + @tab Creates the key signature +@item Metronome_mark_engraver + @tab Engraves metronome marking +@item Note_heads_engraver + @tab Engraves note heads +@item Rest_engraver + @tab Engraves rests +@item Staff_symbol_engraver + @tab Engraves the five (by default) lines of the staff +@item Stem_engraver + @tab Creates stems and single-stem tremulos +@item Time_signature_engraver + @tab Creates time signatures +@end multitable + +@smallspace + +We shall see later how the output of LilyPond can be changed +by modifying the action of Engravers. + + +@node Modifying context properties +@subsection Modifying context properties + +@cindex context properties +@funindex \set +@funindex \unset + +Contexts are responsible for holding the values of a number of +context @emph{properties}. Many of them can be changed to +influence the interpretation of the input and so change the +appearance of the output. They are changed by the +@code{\set} command. This takes the form + +@example +\set @emph{ContextName}.@emph{propertyName} = #@emph{value} +@end example + +Where the @emph{ContextName} is usually @code{Score}, +@code{Staff} or @code{Voice}. It may be omitted, +in which case @code{Voice} is assumed. + +The names of context properties consist of words joined +together with no hyphens or underscores, all except the +first having a capital letter. Here are a few examples +of some commonly used ones. There are many more. + +@c attempt to force this onto a new page +@need 50 +@multitable @columnfractions .25 .15 .45 .15 +@headitem propertyName + @tab Type + @tab Function + @tab Example Value +@item extraNatural + @tab Boolean + @tab If true, set extra natural signs before accidentals + @tab @code{#t}, @code{#f} +@item currentBarNumber + @tab Integer + @tab Set the current bar number + @tab @code{50} +@item doubleSlurs + @tab Boolean + @tab If true, print slurs both above and below notes + @tab @code{#t}, @code{#f} +@item instrumentName + @tab Text + @tab Set the name to be placed at the start of the staff + @tab @code{"Cello I"} +@item fontSize + @tab Real + @tab Increase or decrease the font size + @tab @code{2.4} +@item stanza + @tab Text + @tab Set the text to print before the start of a verse + @tab @code{"2"} +@end multitable + +@noindent +where a Boolean is either True (@code{#t}) or False (@code{#f}), +an Integer is a positive whole number, a Real is a positive +or negative decimal number, and text is enclosed in double +apostrophes. Note the occurrence of hash signs, +(@code{#}), in two different places -- as part of the Boolean +value before the @code{t} or @code{f}, and before @emph{value} +in the @code{\set} statement. So when a Boolean is being +entered you need to code two hash signs, e.g., @code{##t}. + +Before we can set any of these properties we need to know +in which context they operate. Sometimes this is obvious, +but occasionally it can be tricky. If the wrong context +is specified, no error message is produced, but the expected +action will not take place. For example, the +@code{instrumentName} clearly lives in the Staff context, since +it is the staff that is to be named. +In this example the first staff is labelled, but not the second, +because we omitted the context name. + +@lilypond[quote,verbatim,ragged-right] +<< + \new Staff \relative c'' { + \set Staff.instrumentName = #"Soprano" + c4 c + } + \new Staff \relative c' { + \set instrumentName = #"Alto" % Wrong! + d4 d + } +>> +@end lilypond + +Remember the default context name is Voice, so the second +@code{\set} command set the property @code{instrumentName} in the +Voice context to @qq{Alto}, but as LilyPond does not look +for any such property in the @code{Voice} context, no +further action took place. This is not an error, and no error +message is logged in the log file. + +Similarly, if the property name is mis-spelt no error message +is produced, and clearly the expected action cannot be performed. +If fact, you can set any (fictitious) @q{property} using any +name you like in any context that exists by using the +@code{\set} command. But if the name is not +known to LilyPond it will not cause any action to be taken. +This is one of the reasons why it is highly recommended to +use a context-sensitive editor with syntax highlighting for +editing LilyPond files, such as Vim, Jedit, ConTEXT or Emacs, +since unknown property names will be highlighted differently. + +The @code{instrumentName} property will take effect only +if it is set in the @code{Staff} context, but +some properties can be set in more than one context. +For example, the property @code{extraNatural} is by +default set to ##t (true) for all staves. +If it is set to ##f (false) in one particular @code{Staff} +context it applies just to the accidentals on that staff. +If it is set to false in the @code{Score} context +it applies to all staves. + +So this turns off extra naturals in one staff: + +@lilypond[quote,verbatim,ragged-right] +<< + \new Staff \relative c'' { + ais4 aes + } + \new Staff \relative c'' { + \set Staff.extraNatural = ##f + ais4 aes + } +>> +@end lilypond + +@noindent +and this turns them off in all staves: + +@lilypond[quote,verbatim,ragged-right] +<< + \new Staff \relative c'' { + ais4 aes + } + \new Staff \relative c'' { + \set Score.extraNatural = ##f + ais4 aes + } +>> +@end lilypond + +The value of every property set in this way can be reset +to its original value with the @code{\unset} command. + +The @code{\set} and @code{\unset} commands can appear anywhere +in the input file and will take effect from the time they are +encountered until the end of the score or until the property is +@code{\set} or @code{\unset} again. Let's try changing the +font size, which affects the size of the note heads (among +other things) several times. The change is from the default +value, not the current value. + +@lilypond[quote,verbatim,ragged-right,relative=1,fragment] +c4 +% make note heads smaller +\set fontSize = #-4 +d e +% make note heads larger +\set fontSize = #2.5 +f g +% return to original size +\unset fontSize +a b +@end lilypond + +We have now seen how to set the values of several different +types of property. Note that integers and numbers are alway +preceded by a hash sign, @code{#}, while a true or false value +is specified by ##t and ##f, with two hash signs. A text +property should be enclosed in double quotation signs, as above, +although we shall see later that text can actually be specified +in a much more general way by using the very powerful +@code{markup} command. + + +@funindex \with + +Context properties may also be set at the time the context is +created. Sometimes this is a clearer way of specifying a +property value if it is to remain fixed for the duration of +the context. When a context is created with a @code{\new} +command it may be followed immediately by a +@code{\with @{ .. @}} block in which the property values are +set. For example, if we wish to suppress the printing of +extra naturals for the duration of a staff we would write: + +@example +\new Staff \with @{ extraNatural = ##f @} +@end example + +@noindent +like this: + +@lilypond[quote,verbatim,ragged-right] +<< + \new Staff + \relative c'' { + gis ges aes ais + } + \new Staff \with { extraNatural = ##f } + \relative c'' { + gis ges aes ais + } +>> +@end lilypond + +In effect this overrides the default value of the property. It +may still be changed dynamically using @code{\set} and returned +to its (new) default value with @code{\unset}. + +@node Adding and removing engravers +@subsection Adding and removing engravers + +@cindex Engravers, adding +@cindex Engravers, removing + +@funindex \consists +@funindex \remove + +We have seen that contexts each contain several engravers, each +of which is responsible for producing a particular part of the +output, like bar lines, staves, note heads, stems, etc. If an +engraver is removed from a context it can no longer produce its +output. This is a crude way of modifying the output, but it +can sometimes be useful. + +@subsubheading Changing a single context + +To remove an engraver from a single context we use the +@code{\with} command placed immediately after the context creation +command, as in the previous section. + +As an +illustration let's repeat an example from the previous +section with the staff lines removed. Remember that the +staff lines are produced by the Staff_symbol_engraver. + +@lilypond[quote,verbatim,ragged-right] +\new Staff \with { + \remove Staff_symbol_engraver +} +\relative c' { + c4 + \set fontSize = #-4 % make note heads smaller + d e + \set fontSize = #2.5 % make note heads larger + f g + \unset fontSize % return to original size + a b +} +@end lilypond + +@cindex ambitus engraver + +Engravers can also be added to individual contexts. +The command to do this is + +@code{\consists @emph{Engraver_name}}, + +placed inside a @code{\with} block. Some vocal scores +have an @rglos{ambitus} placed at the beginning of a +staff to indicate the range of notes in that staff. +The ambitus is produced by the @code{Ambitus_engraver}, +which is not normally included in any context. If +we add it to the @code{Voice} context it calculates +the range from that voice only: + +@lilypond[quote,verbatim,ragged-right] +\new Staff << + \new Voice \with { + \consists Ambitus_engraver + } + \relative c'' { + \voiceOne + c a b g + } + \new Voice + \relative c' { + \voiceTwo + c e d f + } +>> +@end lilypond + +@noindent +but if we add the Ambitus engraver to the +@code{Staff} context it calculates the range from all +the notes in all the voices on that staff: + +@lilypond[quote,verbatim,ragged-right] +\new Staff \with { + \consists Ambitus_engraver + } + << + \new Voice + \relative c'' { + \voiceOne + c a b g + } + \new Voice + \relative c' { + \voiceTwo + c e d f + } +>> +@end lilypond + +@subsubheading Changing all contexts of the same type + +The examples above show how to remove or add engravers to +individual contexts. It is also possible to remove or add +engravers to every context of a specific type by placing the +commands in the appropriate context in a @code{\layout} +block. For example, If we wanted to show ambiti for every +staff in a four-staff score we could write + +@lilypond[quote,verbatim,ragged-right] +\score { + << + \new Staff << + \relative c'' { c a b g } + >> + \new Staff << + \relative c' { c a b g } + >> + \new Staff << + \clef "G_8" + \relative c' { c a b g } + >> + \new Staff << + \clef "bass" + \relative c { c a b g } + >> + >> + \layout { + \context { + \Staff + \consists Ambitus_engraver + } + } +} +@end lilypond + +@noindent +The default values of context properties may also be set +for all contexts of a particular type by including the +@code{\set} command in a @code{\context} block in the +same way. + +@node Extending the templates +@section Extending the templates + +You've read the tutorial, you know how to write music, you +understand the fundamental concepts. But how can you +get the staves that you want? Well, you can find lots of +templates (see @ref{Templates}) which may give you a start. +But what +if you want something that isn't covered there? Read on. + +TODO Add links to templates after they have been moved to LSR + +@menu +* Soprano and cello:: +* Four-part SATB vocal score:: +* Building a score from scratch:: +@end menu + +@node Soprano and cello +@subsection Soprano and cello + +Start off with the template that seems closest to what you want to end +up with. Let's say that you want to write something for soprano and +cello. In this case, we would start with @q{Notes and lyrics} (for the +soprano part). + +@example +\version @w{"@version{}"} +melody = \relative c' @{ + \clef treble + \key c \major + \time 4/4 + a4 b c d +@} + +text = \lyricmode @{ + Aaa Bee Cee Dee +@} + +\score @{ + << + \new Voice = "one" @{ + \autoBeamOff + \melody + @} + \new Lyrics \lyricsto "one" \text + >> + \layout @{ @} + \midi @{ @} +@} +@end example + +Now we want to add a cello part. Let's look at the @q{Notes only} example: + +@example +\version @w{"@version{}"} +melody = \relative c' @{ + \clef treble + \key c \major + \time 4/4 + a4 b c d +@} + +\score @{ + \new Staff \melody + \layout @{ @} + \midi @{ @} +@} +@end example + +We don't need two @code{\version} commands. We'll need the +@code{melody} section. We don't want two @code{\score} sections +-- if we had two @code{\score}s, we'd get the two parts separately. +We want them together, as a duet. Within the @code{\score} +section, we don't need two @code{\layout} or @code{\midi}. + +If we simply cut and paste the @code{melody} section, we would +end up with two @code{melody} definitions. This would not generate +an error, but the second one would be used for both melodies. +So let's rename them to make them distinct. We'll call the +section for the soprano @code{sopranoMusic} and the section for +the cello @code{celloMusic}. While we're doing this, let's rename +@code{text} to be @code{sopranoLyrics}. Remember to rename both +instances of all these names -- both the initial definition (the +@code{melody = \relative c' @{ } part) and the name's use (in the +@code{\score} section). + +While we're doing this, let's change the cello part's staff -- +celli normally use bass clef. We'll also give the cello some +different notes. + +@example +\version @w{"@version{}"} +sopranoMusic = \relative c' @{ + \clef treble + \key c \major + \time 4/4 + a4 b c d +@} + +sopranoLyrics = \lyricmode @{ + Aaa Bee Cee Dee +@} + +celloMusic = \relative c @{ + \clef bass + \key c \major + \time 4/4 + d4 g fis8 e d4 +@} + +\score @{ + << + \new Voice = "one" @{ + \autoBeamOff + \sopranoMusic + @} + \new Lyrics \lyricsto "one" \sopranoLyrics + >> + \layout @{ @} + \midi @{ @} +@} +@end example + +This is looking promising, but the cello part won't appear in the +score -- we haven't used it in the @code{\score} section. If we +want the cello part to appear under the soprano part, we need to add @example -melody = @{ @} -text = @{ @} -upper = @{ @} -lower = @{ @} +\new Staff \celloMusic +@end example + +@noindent +underneath the soprano stuff. We also need to add @code{<<} and +@code{>>} around the music -- that tells LilyPond that there's +more than one thing (in this case, two @code{Staves}) happening +at once. The @code{\score} looks like this now + +@c Indentation in this example is deliberately poor +@example \score @{ - @{ + << + << + \new Voice = "one" @{ + \autoBeamOff + \sopranoMusic + @} + \new Lyrics \lyricsto "one" \sopranoLyrics + >> + \new Staff \celloMusic + >> + \layout @{ @} + \midi @{ @} +@} +@end example + +@noindent +This looks a bit messy; the indentation is messed up now. That is +easily fixed. Here's the complete soprano and cello template. + +@lilypond[quote,verbatim,ragged-right] +\version "2.11.38" +sopranoMusic = \relative c' { + \clef treble + \key c \major + \time 4/4 + a4 b c d +} + +sopranoLyrics = \lyricmode { + Aaa Bee Cee Dee +} + +celloMusic = \relative c { + \clef bass + \key c \major + \time 4/4 + d4 g fis8 e d4 +} + +\score { + << << - \new Staff = "singer" << - \new Voice = "vocal" @{ \melody @} + \new Voice = "one" { + \autoBeamOff + \sopranoMusic + } + \new Lyrics \lyricsto "one" \sopranoLyrics + >> + \new Staff \celloMusic + >> + \layout { } + \midi { } +} +@end lilypond + + +@node Four-part SATB vocal score +@subsection Four-part SATB vocal score + +Most vocal scores of music written for four-part mixed choir +with orchestral accompaniment such as Mendelssohn's Elijah or +Handel's Messiah have the choral music and words on four +staves, one for each of SATB, with a piano reduction of the +orchestral accompaniment underneath. Here's an example +from Handel's Messiah: + +@c The following should appear as music without code +@lilypond[quote,ragged-right] +global = { \key d \major \time 4/4 } +sopMusic = \relative c'' { + \clef "treble" + r4 d2 a4 | d4. d8 a2 | cis4 d cis2 | +} +sopWords = \lyricmode { + Wor -- thy is the lamb that was slain +} +altoMusic = \relative a' { + \clef "treble" + r4 a2 a4 | fis4. fis8 a2 | g4 fis e2 | +} +altoWords = \sopWords +tenorMusic = \relative c' { + \clef "G_8" + r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 | +} +tenorWords = \sopWords +bassMusic = \relative c' { + \clef "bass" + r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 | +} +bassWords = \sopWords +upper = \relative a' { + \clef "treble" + \global + r4 2 4 | + 4. 8 2 | + 4 2 | +} +lower = \relative c, { + \clef "bass" + \global + 4 2 4 | + 4. 8 2 | + 4 2 | +} + +\score { + << % combine ChoirStaff and PianoStaff in parallel + \new ChoirStaff << + \new Staff = "sopranos" << + \set Staff.instrumentName = "Soprano" + \new Voice = "sopranos" { \global \sopMusic } >> - \new Lyrics \lyricsto vocal \new Lyrics @{ \text @} - \new PianoStaff = "piano" << - \new Staff = "upper" @{ \upper @} - \new Staff = "lower" @{ \lower @} + \new Lyrics \lyricsto "sopranos" { \sopWords } + \new Staff = "altos" << + \set Staff.instrumentName = "Alto" + \new Voice = "altos" { \global \altoMusic } >> + \new Lyrics \lyricsto "altos" { \altoWords } + \new Staff = "tenors" << + \set Staff.instrumentName = "Tenor" + \new Voice = "tenors" { \global \tenorMusic } + >> + \new Lyrics \lyricsto "tenors" { \tenorWords } + \new Staff = "basses" << + \set Staff.instrumentName = "Bass" + \new Voice = "basses" { \global \bassMusic } + >> + \new Lyrics \lyricsto "basses" { \bassWords } + >> % end ChoirStaff + + \new PianoStaff << + \set PianoStaff.instrumentName = "Piano " + \new Staff = "upper" \upper + \new Staff = "lower" \lower >> - @} - \layout @{ @} + >> +} +@end lilypond + +None of the templates provides this layout exactly. The +nearest is @q{SATB vocal score and automatic piano reduction}, +but we need to change the layout and add a piano +accompaniment which is not derived automatically from the +vocal parts. The variables holding the music and words for +the vocal parts are fine, but we shall need to add variables for +the piano reduction. + +The order in which the contexts appear in the ChoirStaff of +the template do not correspond with the order in the vocal +score shown above. We need to rearrange them so there are +four staves with the words written directly underneath the +notes for each part. +All the voices should be @code{\voiceOne}, which is +the default, so the @code{\voiceXXX} commands should be removed. +We also need to specify the tenor clef for the tenors. +The way in which lyrics are specified in the template has not yet +been encountered so we need to use the method with which we are +familiar. We should also add the names of each staff. + +Doing this gives for our ChoirStaff: + +@example + \new ChoirStaff << + \new Staff = "sopranos" << + \set Staff.instrumentName = "Soprano" + \new Voice = "sopranos" @{ \global \sopMusic @} + >> + \new Lyrics \lyricsto "sopranos" @{ \sopWords @} + \new Staff = "altos" << + \set Staff.instrumentName = "Alto" + \new Voice = "altos" @{ \global \altoMusic @} + >> + \new Lyrics \lyricsto "altos" @{ \altoWords @} + \new Staff = "tenors" << + \set Staff.instrumentName = "Tenor" + \new Voice = "tenors" @{ \global \tenorMusic @} + >> + \new Lyrics \lyricsto "tenors" @{ \tenorWords @} + \new Staff = "basses" << + \set Staff.instrumentName = "Bass" + \new Voice = "basses" @{ \global \bassMusic @} + >> + \new Lyrics \lyricsto "basses" @{ \bassWords @} + >> % end ChoirStaff +@end example + +Next we must work out the piano part. This is +easy - we just pull out the piano part from the +@q{Solo piano} template: + +@example +\new PianoStaff << + \set PianoStaff.instrumentName = "Piano " + \new Staff = "upper" \upper + \new Staff = "lower" \lower +>> +@end example + +and add the variable definitions for @code{upper} +and @code{lower}. + +The ChoirStaff and PianoStaff must be combined +using angle brackets as we want them to be +stacked one above the other: + +@example +<< % combine ChoirStaff and PianoStaff one above the other + \new ChoirStaff << + \new Staff = "sopranos" << + \new Voice = "sopranos" @{ \global \sopMusic @} + >> + \new Lyrics \lyricsto "sopranos" @{ \sopWords @} + \new Staff = "altos" << + \new Voice = "altos" @{ \global \altoMusic @} + >> + \new Lyrics \lyricsto "altos" @{ \altoWords @} + \new Staff = "tenors" << + \clef "G_8" % tenor clef + \new Voice = "tenors" @{ \global \tenorMusic @} + >> + \new Lyrics \lyricsto "tenors" @{ \tenorWords @} + \new Staff = "basses" << + \clef "bass" + \new Voice = "basses" @{ \global \bassMusic @} + >> + \new Lyrics \lyricsto "basses" @{ bassWords @} + >> % end ChoirStaff + + \new PianoStaff << + \set PianoStaff.instrumentName = "Piano " + \new Staff = "upper" \upper + \new Staff = "lower" \lower + >> +>> +@end example + +Combining all these together and adding the music +for the three bars of the example above gives: + +@lilypond[quote,verbatim,ragged-right] +\version "2.11.38" +global = { \key d \major \time 4/4 } +sopMusic = \relative c'' { + \clef "treble" + r4 d2 a4 | d4. d8 a2 | cis4 d cis2 | +} +sopWords = \lyricmode { + Wor -- thy is the lamb that was slain +} +altoMusic = \relative a' { + \clef "treble" + r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 | +} +altoWords = \sopWords +tenorMusic = \relative c' { + \clef "G_8" + r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 | +} +tenorWords = \sopWords +bassMusic = \relative c' { + \clef "bass" + r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 | +} +bassWords = \sopWords +upper = \relative a' { + \clef "treble" + \global + r4 2 4 | + 4. 8 2 | + 4 2 | +} +lower = \relative c, { + \clef "bass" + \global + 4 2 4 | + 4. 8 2 | + 4 2 | +} + +\score { + << % combine ChoirStaff and PianoStaff in parallel + \new ChoirStaff << + \new Staff = "sopranos" << + \set Staff.instrumentName = "Soprano" + \new Voice = "sopranos" { \global \sopMusic } + >> + \new Lyrics \lyricsto "sopranos" { \sopWords } + \new Staff = "altos" << + \set Staff.instrumentName = "Alto" + \new Voice = "altos" { \global \altoMusic } + >> + \new Lyrics \lyricsto "altos" { \altoWords } + \new Staff = "tenors" << + \set Staff.instrumentName = "Tenor" + \new Voice = "tenors" { \global \tenorMusic } + >> + \new Lyrics \lyricsto "tenors" { \tenorWords } + \new Staff = "basses" << + \set Staff.instrumentName = "Bass" + \new Voice = "basses" { \global \bassMusic } + >> + \new Lyrics \lyricsto "basses" { \bassWords } + >> % end ChoirStaff + + \new PianoStaff << + \set PianoStaff.instrumentName = "Piano " + \new Staff = "upper" \upper + \new Staff = "lower" \lower + >> + >> +} +@end lilypond + + +@node Building a score from scratch +@subsection Building a score from scratch + +After gaining some facility with writing LilyPond code you +may find that it is easier to build a score from scratch +rather than modifying one of the templates. You can also +develop your own style this way to suit the sort of music you +like. Let's see how to put together the score for an organ +prelude as an example. + +We begin with a header section. Here go the title, name +of composer, etc, then come any variable definitions, and +finally the score block. Let's start with these in outline +and fill in the details later. + +We'll use the first two bars of Bach's prelude +based on @emph{Jesu, meine Freude} which is written for two +manuals and pedal organ. You can see these two bars of music +at the bottom of this section. The top manual part has two voices, +the lower and pedal organ one each. So we need four +music definitions and one to define the time signature +and key: + +@example +\version @w{"@version{}"} +\header @{ + title = "Jesu, meine Freude" + composer = "J S Bach" +@} +TimeKey = @{ \time 4/4 \key c \minor @} +ManualOneVoiceOneMusic = @{s1@} +ManualOneVoiceTwoMusic = @{s1@} +ManualTwoMusic = @{s1@} +PedalOrganMusic = @{s1@} + +\score @{ @} @end example -@noindent -Remember that you can use almost any name you like. The -limitations on identifier names are detailed in @ruser{File -structure}. +For now we've just used a spacer note, @code{s1}, +instead of the real music. We'll add that later. + +Next let's see what should go in the score block. +We simply mirror the staff structure we want. +Organ music is usually written on three staves, +one for each manual and one for the pedals. The +manual staves should be bracketed together so we +need to use a PianoStaff for them. The first +manual part needs two voices and the second manual +part just one. + +@example + \new PianoStaff << + \new Staff = "ManualOne" << + \new Voice @{ \ManualOneVoiceOneMusic @} + \new Voice @{ \ManualOneVoiceTwoMusic @} + >> % end ManualOne Staff context + \new Staff = "ManualTwo" << + \new Voice @{ \ManualTwoMusic @} + >> % end ManualTwo Staff context + >> % end PianoStaff context +@end example + +Next we need to add a staff for the pedal organ. +This goes underneath the PianoStaff, but it must +be simultaneous with it, so we need angle brackets +round the two. Missing these out would generate +an error in the log file. It's a common mistake +which you'll make sooner or later! Try copying +the final example at the end of this section, +remove these angle brackets, and compile it to +see what errors it generates. + +@example +<< % PianoStaff and Pedal Staff must be simultaneous + \new PianoStaff << + \new Staff = "ManualOne" << + \new Voice @{ \ManualOneVoiceOneMusic @} + \new Voice @{ \ManualOneVoiceTwoMusic @} + >> % end ManualOne Staff context + \new Staff = "ManualTwo" << + \new Voice @{ \ManualTwoMusic @} + >> % end ManualTwo Staff context + >> % end PianoStaff context + \new Staff = "PedalOrgan" << + \new Voice @{ \PedalOrganMusic @} + >> +>> +@end example + +It is not strictly necessary to use the simultaneous construct +@code{<< >>} for the manual two staff and the pedal organ staff, +since they contain only one music expression, but it does no harm +and always using angle brackets after @code{\new Staff} is a good +habit to cultivate in case there are multiple voices. + +Let's add this structure to the score block, and adjust the +indenting. We also add the appropriate clefs, ensure the +second voice stems point down with @code{\voiceTwo} and +enter the time signature and key to each staff using our +predefined variable, @code{\TimeKey}. + +@example +\score @{ + << % PianoStaff and Pedal Staff must be simultaneous + \new PianoStaff << + \new Staff = "ManualOne" << + \TimeKey % set time signature and key + \clef "treble" + \new Voice @{ \ManualOneVoiceOneMusic @} + \new Voice @{ \voiceTwo \ManualOneVoiceTwoMusic @} + >> % end ManualOne Staff context + \new Staff = "ManualTwo" << + \TimeKey + \clef "bass" + \new Voice @{ \ManualTwoMusic @} + >> % end ManualTwo Staff context + >> % end PianoStaff context + \new Staff = "PedalOrgan" << + \TimeKey + \clef "bass" + \new Voice @{ \PedalOrganMusic @} + >> % end PedalOrgan Staff + >> +@} % end Score context +@end example + +That completes the structure. Any three-staff organ music +will have a similar structure, although the number of voices +may vary. All that remains now +is to add the music, and combine all the parts together. + +@lilypond[quote,verbatim,ragged-right] +\version "2.11.38" +\header { + title = "Jesu, meine Freude" + composer = "J S Bach" +} +TimeKey = { \time 4/4 \key c \minor } +ManualOneVoiceOneMusic = \relative g' { + g4 g f ees | d2 c2 | +} +ManualOneVoiceTwoMusic = \relative c' { + ees16 d ees8~ ees16 f ees s c8 d~ d c~ | + c c4 b8 c8. g16 c b c d | +} +ManualTwoMusic = \relative c' { + c16 b c8~ c16 b c g a8 g~ g16 g aes ees | + f ees f d g aes g f ees d e8~ ees16 f ees d | +} +PedalOrganMusic = \relative c { + r8 c16 d ees d ees8~ ees16 a, b g c b c8 | + r16 g ees f g f g8 c,2 | + } + +\score { + << % PianoStaff and Pedal Staff must be simultaneous + \new PianoStaff << + \new Staff = "ManualOne" << + \TimeKey % set time signature and key + \clef "treble" + \new Voice { \ManualOneVoiceOneMusic } + \new Voice { \voiceTwo \ManualOneVoiceTwoMusic } + >> % end ManualOne Staff context + \new Staff = "ManualTwo" << + \TimeKey + \clef "bass" + \new Voice { \ManualTwoMusic } + >> % end ManualTwo Staff context + >> % end PianoStaff context + \new Staff = "PedalOrgan" << + \TimeKey + \clef "bass" + \new Voice { \PedalOrganMusic } + >> % end PedalOrgan Staff + >> +} % end Score context +@end lilypond + + -When writing (or reading) a @code{\score} section, just take it -slowly and carefully. Start with the outer layer, then work on -each smaller layer. It also really helps to be strict with -indentation -- make sure that each item on the same layer starts -on the same horizontal position in your text editor.