3.4 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 Templates) which may give you a start. But what if you want something that isn’t covered there? Read on.

3.4.1 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 the ‘Notes and lyrics’ template (for the soprano part).

\version "2.21.3"

melody = \relative {
  \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 { }
}

Now we want to add a cello part. Let’s look at the ‘Notes only’ example:

\version "2.21.3"

melody = \relative {
  \clef "treble"
  \key c \major
  \time 4/4
  a4 b c d
}

\score {
  \new Staff \melody
  \layout { }
  \midi { }
}

We don’t need two \version commands. We’ll need the melody section. We don’t want two \score sections – if we had two \scores, we’d get the two parts separately. We want them together, as a duet. Within the \score section, we don’t need two \layout or \midi.

If we simply cut and paste the melody section, we would end up with two 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 sopranoMusic and the section for the cello celloMusic. While we’re doing this, let’s rename text to be sopranoLyrics. Remember to rename both instances of all these names – both the initial definition (the melody = \relative { part) and the name’s use (in the \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.

\version "2.21.3"

sopranoMusic = \relative {
  \clef "treble"
  \key c \major
  \time 4/4
  a4 b c d
}

sopranoLyrics = \lyricmode {
  Aaa Bee Cee Dee
}

celloMusic = \relative {
  \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 { }
}

This is looking promising, but the cello part won’t appear in the score – we haven’t used it in the \score section. If we want the cello part to appear under the soprano part, we need to add

\new Staff \celloMusic

underneath the soprano stuff. We also need to add << and >> around the music – that tells LilyPond that there’s more than one thing (in this case, two Staves) happening at once. The \score looks like this now:

\score {
  <<
  <<
    \new Voice = "one" {
      \autoBeamOff
      \sopranoMusic
    }
    \new Lyrics \lyricsto "one" \sopranoLyrics
  >>
  \new Staff \celloMusic
  >>
  \layout { }
  \midi { }
}

This looks a bit messy; the indentation is messed up now. That is easily fixed. Here’s the complete soprano and cello template.

\version "2.21.3" sopranoMusic = \relative { \clef "treble" \key c \major \time 4/4 a4 b c d } sopranoLyrics = \lyricmode { Aaa Bee Cee Dee } celloMusic = \relative { \clef "bass" \key c \major \time 4/4 d4 g fis8 e d4 } \score { << << \new Voice = "one" { \autoBeamOff \sopranoMusic } \new Lyrics \lyricsto "one" \sopranoLyrics >> \new Staff \celloMusic >> \layout { } \midi { } }

See also

The starting templates can be found in the ‘Templates’ appendix, see Single staff templates.

3.4.2 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:

The nearest copy-and-edit template to this layout is 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 \voiceOne, which is the default, so the \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:

\new ChoirStaff <<
  \new Staff = "sopranos"
  \with { instrumentName = "Soprano" }
  <<
    \new Voice = "sopranos" {
      \global
      \sopranoMusic
    }
  >>
  \new Lyrics \lyricsto "sopranos" {
    \sopranoWords
  }
  \new Staff = "altos"
  \with { instrumentName = "Alto" }
  <<
    \new Voice = "altos" {
      \global
      \altoMusic
    }
  >>
  \new Lyrics \lyricsto "altos" {
    \altoWords
  }
  \new Staff = "tenors"
  \with { instrumentName = "Tenor" }
  <<
    \new Voice = "tenors" {
      \global
      \tenorMusic
    }
  >>
  \new Lyrics \lyricsto "tenors" {
    \tenorWords
  }
  \new Staff = "basses"
  \with { instrumentName = "Bass" }
  <<
    \new Voice = "basses" {
      \global
      \bassMusic
    }
  >>
  \new Lyrics \lyricsto "basses" {
    \bassWords
  }
>>  % end ChoirStaff

Next we must work out the piano part. This is easy - we just pull out the piano part from the ‘Solo piano’ template:

\new PianoStaff \with { instrumentName = "Piano  " }
<<
  \new Staff = "upper" \upper
  \new Staff = "lower" \lower
>>

and add the variable definitions for upper and lower.

The ChoirStaff and PianoStaff must be combined using angle brackets as we want them to be stacked one above the other:

<<  % combine ChoirStaff and PianoStaff one above the other
  \new ChoirStaff <<
    \new Staff = "sopranos" <<
      \new Voice = "sopranos" {
        \global
        \sopranoMusic
      }
    >>
    \new Lyrics \lyricsto "sopranos" {
      \sopranoWords
     }
    \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 \with { instrumentName = "Piano" }
  <<
    \new Staff = "upper" \upper
    \new Staff = "lower" \lower
  >>
>>

Combining all these together and adding the music for the three bars of the example above gives:

\version "2.21.3" global = { \key d \major \time 4/4 } sopranoMusic = \relative { \clef "treble" r4 d''2 a4 | d4. d8 a2 | cis4 d cis2 | } sopranoWords = \lyricmode { Wor -- thy | is the lamb | that was slain | } altoMusic = \relative { \clef "treble" r4 a'2 a4 | fis4. fis8 a2 | g4 fis fis2 | } altoWords = \sopranoWords tenorMusic = \relative { \clef "G_8" r4 fis'2 e4 | d4. d8 d2 | e4 a, cis2 | } tenorWords = \sopranoWords bassMusic = \relative { \clef "bass" r4 d'2 cis4 | b4. b8 fis2 | e4 d a'2 | } bassWords = \sopranoWords upper = \relative { \clef "treble" \global r4 <a' d fis>2 <a e' a>4 | <d fis d'>4. <d fis d'>8 <a d a'>2 | <g cis g'>4 <a d fis> <a cis e>2 | } lower = \relative { \clef "bass" \global <d, d'>4 <d d'>2 <cis cis'>4 | <b b'>4. <b' b'>8 <fis fis'>2 | <e e'>4 <d d'> <a' a'>2 | } \score { << % combine ChoirStaff and PianoStaff in parallel \new ChoirStaff << \new Staff = "sopranos" \with { instrumentName = "Soprano" } << \new Voice = "sopranos" { \global \sopranoMusic } >> \new Lyrics \lyricsto "sopranos" { \sopranoWords } \new Staff = "altos" \with { instrumentName = "Alto" } << \new Voice = "altos" { \global \altoMusic } >> \new Lyrics \lyricsto "altos" { \altoWords } \new Staff = "tenors" \with { instrumentName = "Tenor" } << \new Voice = "tenors" { \global \tenorMusic } >> \new Lyrics \lyricsto "tenors" { \tenorWords } \new Staff = "basses" \with { instrumentName = "Bass" } << \new Voice = "basses" { \global \bassMusic } >> \new Lyrics \lyricsto "basses" { \bassWords } >> % end ChoirStaff \new PianoStaff \with { instrumentName = "Piano " } << \new Staff = "upper" \upper \new Staff = "lower" \lower >> >> }

3.4.3 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 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:

\version "2.21.3"
\header {
  title = "Jesu, meine Freude"
  composer = "J S Bach"
}
keyTime = { \key c \minor \time 4/4 }
ManualOneVoiceOneMusic = { s1 }
ManualOneVoiceTwoMusic = { s1 }
ManualTwoMusic = { s1 }
PedalOrganMusic = { s1 }

\score {
}

For now we’ve just used a spacer note, 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.

\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

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 around 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.

<<  % 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
    }
  >>
>>

It is not necessary to use the simultaneous construct << … >> 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 \new Staff is a good habit to cultivate in case there are multiple voices. The opposite is true for Voices: these should habitually be followed by braces { … } in case your music is coded in several variables which need to run consecutively.

Let’s add this structure to the score block, and adjust the indenting. We also add the appropriate clefs, ensure stems, ties and slurs in each voice on the upper staff point to the right direction with \voiceOne and \voiceTwo, and enter the key and time signature to each staff using our predefined variable, \keyTime.

\score {
  <<  % PianoStaff and Pedal Staff must be simultaneous
    \new PianoStaff <<
      \new Staff = "ManualOne" <<
        \keyTime  % set key and time signature
        \clef "treble"
        \new Voice {
          \voiceOne
          \ManualOneVoiceOneMusic
        }
        \new Voice {
          \voiceTwo
          \ManualOneVoiceTwoMusic
        }
      >>  % end ManualOne Staff context
      \new Staff = "ManualTwo" <<
        \keyTime
        \clef "bass"
        \new Voice {
          \ManualTwoMusic
        }
      >>  % end ManualTwo Staff context
    >>  % end PianoStaff context
    \new Staff = "PedalOrgan" <<
      \keyTime
      \clef "bass"
      \new Voice {
        \PedalOrganMusic
      }
    >>  % end PedalOrgan Staff
  >>
}  % end Score context

The above layout of the organ staves is almost perfect; however, there is a slight defect which is not visible by looking at just a single system: The distance of the pedal staff to the left hand staff should behave approximately the same as the right hand staff to the left hand staff. In particular, the stretchability of staves in a PianoStaff context is limited (so that the distance between the staves for the left and right hand can’t become too large), and the pedal staff should behave similarly.

Stretchability of staves can be controlled with the staff-staff-spacing property of the VerticalAxisGroup ‘graphical object’ (commonly called ‘grob’s within the lilypond documentation) – don’t worry about the details right now; this is fully explained later. For the curious, have a look at (notation)Overview of modifying properties section ‘Overview of modifying properties’ in Notation Reference. In this case, we want to modify the stretchability sub-property only. Any values not changed will use the default value. Again, for the curious, you can find the default values for the staff-staff-spacing property in file ‘scm/define-grobs.scm’ by looking up the definition of the default-staff-staff-spacing property of the VerticalAxisGroup grob. The value for stretchability below is taken from the definition of the StaffGrouper grob (in file ‘scm/define-grobs.scm’) so that the values are identical.

\score {
  <<  % PianoStaff and Pedal Staff must be simultaneous
    \new PianoStaff <<
      \new Staff = "ManualOne" <<
        \keyTime  % set key and time signature
        \clef "treble"
        \new Voice {
          \voiceOne
          \ManualOneVoiceOneMusic
        }
        \new Voice {
          \voiceTwo
          \ManualOneVoiceTwoMusic
        }
      >>  % end ManualOne Staff context
      \new Staff = "ManualTwo" \with {
        \override VerticalAxisGroup.staff-staff-spacing.stretchability = 5
      } <<
        \keyTime
        \clef "bass"
        \new Voice {
          \ManualTwoMusic
        }
      >>  % end ManualTwo Staff context
    >>  % end PianoStaff context
    \new Staff = "PedalOrgan" <<
      \keyTime
      \clef "bass"
      \new Voice {
        \PedalOrganMusic
      }
    >>  % end PedalOrgan Staff
  >>
}  % end Score context

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.

\version "2.21.3" \header { title = "Jesu, meine Freude" composer = "J S Bach" } keyTime = { \key c \minor \time 4/4 } ManualOneVoiceOneMusic = \relative { g'4 g f ees | d2 c | } ManualOneVoiceTwoMusic = \relative { ees'16 d ees8~ 16 f ees d c8 d~ d c~ | 8 c4 b8 c8. g16 c b c d | } ManualTwoMusic = \relative { c'16 b c8~ 16 b c g a8 g~ 16 g aes ees | f16 ees f d g aes g f ees d ees8~ 16 f ees d | } PedalOrganMusic = \relative { r8 c16 d ees d ees8~ 16 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" << \keyTime % set key and time signature \clef "treble" \new Voice { \voiceOne \ManualOneVoiceOneMusic } \new Voice { \voiceTwo \ManualOneVoiceTwoMusic } >> % end ManualOne Staff context \new Staff = "ManualTwo" \with { \override VerticalAxisGroup.staff-staff-spacing.stretchability = 5 } << \keyTime \clef "bass" \new Voice { \ManualTwoMusic } >> % end ManualTwo Staff context >> % end PianoStaff context \new Staff = "PedalOrgan" << \keyTime \clef "bass" \new Voice { \PedalOrganMusic } >> % end PedalOrgan Staff context >> } % end Score context

See also

Music Glossary: (music-glossary)system section ‘system’ in Music Glossary.

3.4.4 Saving typing with variables and functions

By this point, you’ve seen this kind of thing:

hornNotes = \relative { c''4 b dis c } \score { { \hornNotes } }

You may even realize that this could be useful in minimalist music:

fragmentA = \relative { a'4 a8. b16 } fragmentB = \relative { a'8. gis16 ees4 } violin = \new Staff { \fragmentA \fragmentA | \fragmentB \fragmentA | } \score { { \violin } }

However, you can also use these variables (also known as macros, or user-defined commands) for tweaks:

dolce = \markup { \italic \bold dolce } centreText = { \once \override TextScript.self-alignment-X = #CENTER } fthenp =_\markup { \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p } violin = \relative { \repeat volta 2 { c''4._\dolce b8 a8 g a b | \centreText c4.^"hi there!" d8 e f g d | c4.\fthenp b8 c4 c-. | } } \score { { \violin } }

These variables are obviously useful for saving typing. But they’re worth considering even if you only use them once – they reduce complexity. Let’s look at the previous example without any variables. It’s a lot harder to read, especially the last line.

violin = \relative {
  \repeat volta 2 {
    c''4._\markup { \italic \bold dolce } b8 a8 g a b |
    \once \override TextScript.self-alignment-X = #CENTER
    c4.^"hi there!" d8 e f g d |
    c4._\markup {
      \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p
    }
    b8 c4 c-. |
  }
}

Remember ‘post-events’? Articulations, fingerings, anything that has to be added after a note (see Structure of a note entry), often prefixed with a dash or a direction modifier. In fact, even these events can be stored in a variable – in which case the usual curly braces are not wanted, since you wouldn’t use them between a note and its articulations.

If such a definition includes a prefix, then the variable can be used directly after the note – unless you want to change its direction, in which case you can insert a modifier that will take precedence:

articulationVar = -^-! artEsprVar = \articulationVar ^\espressivo \relative c' { c\articulationVar d e2^\articulationVar d2\artEsprVar c_\artEsprVar }

So far we’ve seen static substitution – when LilyPond sees \centreText, it replaces it with the stuff that we’ve defined it to be (ie the stuff to the right of centreText=).

LilyPond can handle non-static substitution, too (you can think of these as functions).

padText = #(define-music-function (padding) (number?) #{ \once \override TextScript.padding = #padding #}) \relative { c''4^"piu mosso" b a b \padText #1.8 c4^"piu mosso" b a b \padText #2.6 c4^"piu mosso" b a b }

Using variables is also a good way to reduce work if the LilyPond input syntax changes (see (usage)Updating files with convert-ly section ‘Updating files with convert-ly’ in Application Usage). If you have a single definition (such as \dolce) for all your input files (see Style sheets), then if the syntax changes, you only need to update your single \dolce definition, instead of making changes throughout every ‘.ly’ file.

3.4.5 Scores and parts

In orchestral music, all notes are printed twice. Once in a part for the musicians, and once in a full score for the conductor. Variables can be used to avoid double work. The music is entered once, and stored in a variable. The contents of that variable is then used to generate both the part and the full score.

It is convenient to define the notes in a special file. For example, suppose that the file ‘horn-music.ly’ contains the following part of a horn/bassoon duo

hornNotes = \relative {
  \time 2/4
  r4 f8 a | cis4 f | e4 d |
}

Then, an individual part is made by putting the following in a file

\include "horn-music.ly"

\header {
  instrument = "Horn in F"
}

{
 \transpose f c' \hornNotes
}

The line

\include "horn-music.ly"

substitutes the contents of ‘horn-music.ly’ at this position in the file, so hornNotes is defined afterwards. The command \transpose f c' indicates that the argument, being \hornNotes, should be transposed by a fifth upwards. Sounding f is denoted by notated c', which corresponds with the tuning of a normal French Horn in F. The transposition can be seen in the following output

In ensemble pieces, one of the voices often does not play for many measures. This is denoted by a special rest, the multi-measure rest. It is entered with a capital R followed by a duration (1 for a whole note, 2 for a half note, etc.). By multiplying the duration, longer rests can be constructed. For example, this rest takes 3 measures in 2/4 time

R2*3

When printing the part, multi-measure rests must be compressed. There is a music function available to do this:

\compressMMRests { ... }

Applying this to hornNotes gives:

The score is made by combining all of the music together. Assuming that the other voice is in bassoonNotes in the file ‘bassoon-music.ly’, a score is made with

\include "bassoon-music.ly"
\include "horn-music.ly"

<<
  \new Staff \hornNotes
  \new Staff \bassoonNotes
>>

leading to

See also

Learning Manual: Organizing pieces with variables.

Notation Reference: (notation)Transpose section ‘Transpose’ in Notation Reference, (notation)Writing parts section ‘Writing parts’ in Notation Reference, (notation)Full measure rests section ‘Full measure rests’ in Notation Reference, (notation)Including LilyPond files section ‘Including LilyPond files’ in Notation Reference.

This document was generated by gub on July 13, 2020 using texi2html 1.82.

其他语言：català, česky, deutsch, español, français, magyar, italiano, 日本語, nederlands。
关于 自动语言选择