LilyPond — Learning Manual

2.2.1 Input characters

If you open a new file for LilyPond input, ensure that your editor uses UTF-8 input encoding. Frescobaldi (see Installing) does this automatically for you, but especially under Windows this might not be the default under a different editor.

Note also that some characters used for LilyPond notation have look-alike siblings. In particular, you have to use straight quotes ('), not curly quotes (’) or acute accents (´). Some editors, especially e-mail clients, automatically replace straight quotes with curly ones; such a feature must be switched off.

2.2.2 Simple notation

LilyPond adds some notation elements automatically. In the next example, we have only specified four pitches, but LilyPond has added a clef, a time signature, and rhythms.

{
  c' e' g' e'
}

This behavior may be altered, but in most cases these automatic values are useful.

2.2.3 Working on input files

LilyPond input files are similar to source files in many common programming languages. They contain a version statement, are case sensitive, and whitespace is generally ignored. Expressions are formed with curly braces { }, and comments are denoted with ‘%’ or ‘%{ … %}’.

If the previous sentences sound like nonsense, don’t worry! We are now going to explain what all these terms mean.

• Version statement: Every LilyPond file should contain a version statement. A version statement is a line that describes the version of LilyPond for which the file was written, as in the following example:

  \version "2.25.21"
  

  By convention, the version statement is placed at the top of the LilyPond file.

  The version statement is important for at least two reasons. First, it allows automatic updating of the input file as LilyPond syntax changes. Second, it describes the version of LilyPond needed to compile the file.

  If the version statement is omitted from an input file, LilyPond prints a warning during the compilation of the file.

• Case sensitive: It matters whether you enter a letter in lowercase (e.g., ‘a’, ‘b’, ‘s’, ‘t’) or uppercase (e.g., ‘A’, ‘B’, ‘S’, ‘T’). Notes are lowercase: ‘{ c d e }’ is valid input; ‘{ C D E }’ produces an error message.
• Whitespace insensitive: It does not matter how many spaces (or tabs, or new lines) you add.

  { c4 d e}
  

  means the same thing as

  { c4       d e }
  

  or

  { c4                       d
                     e   }
  

  Of course, the previous example is hard to read. A good rule of thumb is to indent code blocks with two spaces:

  {
    c4 d e
  }
  

  However, whitespace is required to separate many syntactical elements from others. In other words, whitespace can always be added, but not always eliminated. Since missing whitespace can give rise to strange errors, it is advisable to always insert whitespace before and after every syntactic element, for example, before and after every curly brace.

• Expressions: Every piece of LilyPond input needs to have { curly braces } placed around the input. These braces tell LilyPond that the input is a single music expression, just like parentheses ‘()’ in mathematics. The braces should be surrounded by a space unless they are at the beginning or end of a line to avoid ambiguities.

  A LilyPond command followed by a simple expression in braces (such as ‘\relative { … }’) also counts as a single music expression.

• Comments: A comment is a remark for the human reader of the music input; it is ignored while parsing, so it has no effect on the printed output. There are two types of comments. The percent symbol ‘%’ introduces a line comment; anything after ‘%’ on that line is ignored. By convention, a line comment is placed above the code it refers to.

  a4 a a a
  % this comment refers to the next line with the two bs
  b2 b
  

  A block comment marks a whole section of music input as a comment. Anything that is enclosed in %{ and %} is ignored. However, block comments do not ‘nest’. This means that you cannot place a block comment inside another block comment. If you try, the first %} will terminate both block comments. The following fragment shows possible uses for comments.

  % notes for twinkle twinkle follow
  c4 c g' g a a g2
  
  %{
    This line, and the notes below are ignored,
    since they are in a block comment.
  
    f4 f e e d d c2
  %}
  

2.4.1 Omitted material

LilyPond input must be surrounded by { } marks or ‘\relative { … }’ (see Working on input files). For the rest of this manual, some short examples omit this. To replicate these examples, you can copy displayed input, but paste it between ‘{’ and ‘}’ in your input file.

{
  …example goes here…
}

Also, remember that every LilyPond file should have a \version statement. Because the examples in the manuals are snippets, not files, the \version statement is omitted. But you should make a practice of including them in your files.

2.4.2 Clickable examples

Many people learn programs by trying and fiddling around with the program. This is also possible with LilyPond. If you click on a picture in the HTML version of this manual, you will see the exact LilyPond input that was used to generate that image. Try it on this image:

By cutting and pasting everything in the “ly snippet” section, you have a starting template for experiments. To see exactly the same output (line-width and all), copy everything from “Start cut-&-pastable section” to the bottom of the file.

2.4.3 Overview of manuals

There is a lot of documentation for LilyPond. New users are sometimes confused about what part(s) they should read, and occasionally skip over reading vital portions.

• Before trying to do anything: see Tutorial, and Common notation of this manual. If you encounter musical terms which you do not recognize, please look them up in the Music Glossary.
• Before trying to write a complete piece of music: see Fundamental concepts of this manual. After that, you may want to look into relevant sections of the Notation Reference.
• Before trying to change the default output: see Tweaking output in this manual.
• Before undertaking a large project: read the Usage document’s Suggestions for writing files.

3.1.1 Bar lines and bar checks

warning: bar check failed at: 1/2
 g'1 | e1 | c2. c'
                   | g4 c g e | c4 r r2 |

3.1.2 Pitches and key signatures

3.1.3 Ties and slurs

Because of the similar optical appearance, we introduce ties and slurs in the same section.

3.1.4 Articulations and dynamics

Articulations and dynamics are indicated by adding special codes after the notes to which they apply.

3.1.5 Adding text

Text may be added to your scores:

\relative { c''2^"espr" a_"legato" }

Extra formatting may be added with the \markup command:

\relative {
  c''2^\markup { \bold espr }
  a2_\markup {
    \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p }
}

See also

Notation Reference: Writing text.

3.1.6 Automatic and manual beams

Music Glossary: beam.

All beams are drawn automatically:

\relative { a'8 ais d ees r d c16 b a8 }

If you do not like the automatic beams, they may be overridden manually. To correct just an occasional beam mark the first note to be beamed with ‘[’ and the last one with ‘]’. Note that ‘[’ comes after the first beamed note.

\relative { a'8[ ais] d[ ees r d] c16 b a8 }

If you want to turn off automatic beaming entirely or for an extended section of music, use the command \autoBeamOff to turn off automatic beaming and \autoBeamOn to turn it on again.

\relative {
  \autoBeamOff
  a'8 c b4 d8. c16 b4 |
  \autoBeamOn
  a8 c b4 d8. c16 b4 |
}

See also

Notation Reference: Automatic beams, Manual beams.

3.1.7 Advanced rhythmic commands

We have to extend simple durations (i.e., numbers appended to pitches, with or without trailing dots) with more concepts to cover a broader range of rhythmic input.

3.2.1 Music expressions explained

In LilyPond input files, music is represented by music expressions. A single note is a music expression:

a'4

Enclosing music in braces creates a compound music expression. Here we have created a compound music expression with two notes:

\relative { a'4 g4 }

Putting a group of music expressions (e.g., notes) in braces means that they are in sequence (i.e., each one follows the previous one). The result is another music expression:

\relative { { a'4 g } f4 g }

1
1 + 2
(1 + 2) * 3
((1 + 2) * 3) / (4 * 5)

3.2.2 Multiple staves

LilyPond input files are constructed out of music expressions (see Music expressions explained). If the score begins with simultaneous music expressions, LilyPond creates multiples staves. However, it is easier to see what happens if we create each staff explicitly.

To print more than one staff, each piece of music that makes up a staff is marked by adding \new Staff before it. These Staff elements are then combined in parallel with << and >>:

<<
  \new Staff { \clef treble c''4 }
  \new Staff { \clef bass c4 }
>>

The command \new introduces a notation context. A notation context is an environment in which musical events (like notes or \clef commands) are interpreted. For simple pieces, such notation contexts are created automatically. For more complex pieces, it is best to mark contexts explicitly.

There are several types of contexts. The most important ones are Score, Staff, and Voice, which handle melodic notation, while Lyrics sets lyric texts and ChordNames prints chord names.

In terms of syntax, prepending \new to a music expression creates a bigger music expression. In this way it resembles the minus sign in mathematics. The formula (4+5) is an expression, so -(4+5) is a bigger expression.

Time signatures entered in one staff affect all other staves by default. On the other hand, the key signature of one staff does not affect other staves. This different default behavior is because scores with transposing instruments are more common than polyrhythmic scores.

<<
  \new Staff { \clef treble \key d \major \time 3/4 c''4 }
  \new Staff { \clef bass c4 }
>>

3.2.3 Staff groups

Music Glossary: brace, staff, system.

Piano music is typeset in two staves connected by a brace. Printing such a staff is similar to polyphonic music in multiple staves (see Multiple staves). However, now this entire expression is inserted into a PianoStaff context:

\new PianoStaff <<
  \new Staff …
  \new Staff …
>>

Here is a small example.

\new PianoStaff <<
  \new Staff \relative { \time 2/4 c''4 e | g g, | }
  \new Staff \relative { \clef bass c4 c' | e c | }
>>

Other staff groupings are introduced with \new GrandStaff, suitable for orchestral scores, and \new ChoirStaff, suitable for vocal scores. These staff groups each form another type of context, one that generates the brace at the left side of every system and also controls the vertical extent of bar lines.

See also

Notation Reference: Keyboard and other multi-staff instruments, Displaying staves.

3.2.4 Combining notes into chords

Music Glossary: chord.

We saw earlier how notes can be combined into chords: by enclosing them in double angle brackets we indicated that they are simultaneous. However, the normal way of producing a chord is to surround the pitches with single angle brackets. Note that all notes in a chord must have the same duration, and that the duration is placed after the closing bracket.

\relative { r4 <c'' e g> <c f a>2 }

Think of chords as almost equivalent to single notes: virtually everything you can attach to a single note can be attached to a chord, and usually these attachments must be put outside the angle brackets. For example, you can combine markings like beams and ties with chords.

\relative {
  r4 <c'' e g>~ <c f a>2 |
  <c e g>8[ <c f a> <c e g> <c f a>]
    <c e g>8\>[ <c f a> q q]\! |
  r4 <c e g>8.\p q16( q4-. <c f a>) |
}

The above example also demonstrates a very useful feature: a chord can be repeated by using the symbol ‘q’. This even works with interspersed single notes.

\relative { c'8 <e g>8 q q g, q q q }

See also

Notation Reference: Chorded notes.

3.2.5 Single-staff polyphony

Polyphonic music in LilyPond, while not difficult, uses concepts that we have not discussed yet, so we are not going to introduce them here. Instead, the following sections establish the basics of these concepts and explain them thoroughly.

See also

Learning Manual: Voices contain music.

Notation Reference: Simultaneous notes.

3.3.1 Setting simple songs

Music Glossary: lyrics.

Here is the start of the melody to a nursery rhyme, Girls and boys come out to play.

\relative {
  \key g \major
  \time 6/8
  d''4 b8 c4 a8 | d4 b8 g4
}

The lyrics can be set to these notes, combining both with the \addlyrics keyword. Lyrics are entered by separating each syllable with a space.

<<
  \relative {
    \key g \major
    \time 6/8
    d''4 b8 c4 a8 | d4 b8 g4
  }
  \addlyrics {
    Girls and boys come out to play,
  }
>>

Note the double angle brackets << … >> around the whole piece to show that the music and lyrics are to occur at the same time.

3.3.2 Aligning lyrics to a melody

Music Glossary: melisma, extender line.

The next line in the nursery rhyme is The moon doth shine as bright as day. Let’s extend it:

<<
  \relative {
    \key g \major
    \time 6/8
    d''4 b8 c4 a8 | d4 b8 g4 g8 |
    a4 b8 c b a | d4 b8 g4. |
  }
  \addlyrics {
    Girls and boys come out to play,
    The moon doth shine as bright as day;
  }
>>

Looking at the music, we see that the extra lyrics do not align properly with the notes. The word shine should be sung on two notes, not one. This is called a melisma, a single syllable sung to more than one note. There are several ways to spread a syllable over multiple notes, the simplest being to add a slur across them. See Ties and slurs, for more information.

<<
  \relative {
    \key g \major
    \time 6/8
    d''4 b8 c4 a8 | d4 b8 g4 g8 |
    a4 b8 c( b) a | d4 b8 g4. |
  }
  \addlyrics {
    Girls and boys come out to play,
    The moon doth shine as bright as day;
  }
>>

The words now line up correctly with the notes, but the automatic beaming for the notes above shine as does not look right. We can correct this by inserting manual beaming commands to override the automatic beaming here. See Automatic and manual beams, for more information.

<<
  \relative {
    \key g \major
    \time 6/8
    d''4 b8 c4 a8 | d4 b8 g4 g8 |
    a4 b8 c([ b]) a | d4 b8 g4. |
  }
  \addlyrics {
    Girls and boys come out to play,
    The moon doth shine as bright as day;
  }
>>

As an alternative to using slurs, melismata may be indicated in just the lyrics by using an underscore ‘_’ for each note that should be included in the melisma.

<<
  \relative {
    \key g \major
    \time 6/8
    d''4 b8 c4 a8 | d4 b8 g4 g8 |
    a4 b8 c[ b] a | d4 b8 g4. |
  }
  \addlyrics {
    Girls and boys come out to play,
    The moon doth shine _ as bright as day;
  }
>>

If a syllable extends over several notes or a single very long note an extender line is usually drawn from the syllable extending under all the notes for that syllable. It is entered as two underscores (__). It is important that the underscores are separated with one or more spaces from the preceding (and following) syllable.

Here is an example from the first three bars of Dido’s Lament, from Purcell’s opera Dido and Æneas:

<<
  \relative {
    \key g \minor
    \time 3/2
    g'2 a bes | bes2( a) b2 |
    c4.( bes8 a4. g8 fis4.) g8 | fis1
  }
  \addlyrics {
    When I am laid,
    am laid __ in earth,
  }
>>

None of the examples so far have involved words containing more than one syllable. Such words are usually split one syllable to a note, with hyphens between syllables. Such hyphens are entered as two consecutive dashes (--), resulting in a centered hyphen between the syllables. It is important that the dashes are separated with one or more spaces from the preceding and following syllable.

Here is an example showing this and everything we have learned so far about aligning lyrics to notes.

<<
  \relative {
    \key g \major
    \time 3/4
    \partial 4
    d'4 | g4 g a8( b) | g4 g b8( c) |
    d4 d e | c2
  }
  \addlyrics {
    A -- way in a __ man -- ger,
    no __ crib for a bed,
  }
>>

Some lyrics, especially those in Italian, require the opposite: setting more than one syllable to a single note. This is achieved by linking the syllables together with a single underscore (‘_’, with no spaces), or enclosing them in quotes. Here is an example from Rossini’s opera Il barbiere di Siviglia, where al has to be sung on the same note as the go of Largo in Figaro’s aria Largo al factotum:

<<
  \relative {
    \clef bass
    \key c \major
    \time 6/8
    c'4.~ 8 d b | c8([ d]) b c d b | c8
  }
  \addlyrics {
    Lar -- go_al fac -- to -- tum del -- la cit -- tà
  }
>>

See also

Notation Reference: Vocal music.

3.3.3 Lyrics to multiple staves

The simple approach using \addlyrics can be used for placing lyrics under more than one staff. Here is an example from Handel’s oratorio Judas Maccabæus.

<<
  \relative {
    \key f \major
    \time 6/8
    \partial 8
    c''8 | c8([ bes]) a a([ g]) f | f'4. b, | c4.~ 4
  }
  \addlyrics {
    Let flee -- cy flocks the hills a -- dorn, __
  }
  \relative {
    \key f \major
    \time 6/8
    \partial 8
    r8 | r4. r4 c'8 | a'8([ g]) f f([ e]) d | e8([ d]) c bes'4
  }
  \addlyrics {
    Let flee -- cy flocks the hills a -- dorn,
  }
>>

Scores any more complex than this simple example are better produced by separating out the score structure from the notes and lyrics with variables. See Organizing pieces with variables, for an introduction.

See also

Notation Reference: Vocal music.

3.4.1 Organizing pieces with variables

When all of the elements discussed earlier are combined to produce larger files, the music expressions get a lot bigger. In polyphonic music with many staves, the input files can become very confusing. We can reduce this confusion by using variables.

With variables (also known as identifiers or macros), we can break up complex music expressions. A variable is assigned as follows:

namedMusic = { … }

The contents of the music expression namedMusic can be used later by placing a backslash in front of the name (\namedMusic), just like a normal LilyPond command.

Violin = \new Staff {
  \relative {
    a'4 b c b
  }
}

Cello = \new Staff {
  \relative {
    \clef bass
    e2 d
  }
}

{
  <<
    \Violin
    \Cello
  >>
}

By convention, variable names consist of alphabetic characters only. For detailed information, see File structure.

Variables must be defined before the main music expression, but may be used as many times as required anywhere after they have been defined. They may even be used in a later definition of another variable, giving a way of shortening the input if a section of music is repeated many times.

tripletA = \relative { \tuplet 3/2 { c'8 e g } }
barA = { \tripletA \tripletA \tripletA \tripletA }

{ \barA \barA }

Variables may be used for many other types of objects in the input. For example,

myWidth = 60      % a number to pass to a \paper variable
                  % (the unit is millimeter)
myName = "Wendy"  % a string to pass to a markup
aFivePaper = \paper { #(set-paper-size "a5") }

Depending on its contents, the variable can be used in different places. The following example uses the above variables:

\paper {
  \aFivePaper
  line-width = \myWidth
}

{
  c4^\myName
}

3.4.2 Adding titles

The title, composer, opus number, and similar information are entered in the \header block. This exists outside of the main music expression; the \header block is usually placed underneath the version number.

\version "2.25.21"

\header {
  title = "Symphony"
  composer = "Me"
  opus = "Op. 9"
}

{
  … music …
}

When the file is processed, the title and composer are printed above the music. More information on titling can be found in Creating titles headers and footers.

3.4.3 Absolute note names

So far we have used \relative to define pitches. This is usually the fastest way to enter most music. Without \relative, pitches are interpreted in absolute mode.

In this mode, LilyPond treats all pitches as absolute values: a ‘c'’ always means middle C, a ‘b’ always means the note one step below middle C, and a ‘g,’ always means the note on the bottom line of a staff with a bass clef.

{
  \clef bass
  c'4 b g, g, |
  g,4 f, f c' |
}

Writing a melody in the treble clef involves a lot of quote ‘'’ marks. Consider this fragment from Mozart:

{
  \key a \major
  \time 6/8
  cis''8. d''16 cis''8 e''4 e''8 |
  b'8. cis''16 b'8 d''4 d''8 |
}

Common octave marks can be indicated just once, using the command \fixed followed by a reference pitch:

\fixed c'' {
  \key a \major
  \time 6/8
  cis8. d16 cis8 e4 e8 |
  b,8. cis16 b,8 d4 d8 |
}

With \relative, the previous example needs no octave marks because this melody moves in steps no larger than three staff positions:

\relative {
  \key a \major
  \time 6/8
  cis''8. d16 cis8 e4 e8 |
  b8. cis16 b8 d4 d8 |
}

If you make a mistake with an octave mark (‘'’ or ‘,’) while working in \relative mode, it is very obvious – many notes will be in the wrong octave. When working in absolute mode, a single mistake will not be as visible, and will not be as easy to find.

However, absolute mode is useful for music with large intervals, and is extremely useful for computer-generated LilyPond files. When cutting and pasting melody fragments, absolute mode preserves the original octave.

See Relative octave entry for more complex situations.

3.4.4 After the tutorial

After finishing the tutorial, you should probably try writing a piece or two. Start by adding notes to one of the templates (see Templates). If you need any notation that was not covered in the tutorial, look at the Notation Reference, starting with Musical notation. If you want to write for an instrument ensemble that is not covered in the templates, see Extending the templates.

Once you have written a few short pieces, read the rest of the Learning Manual (chapters 3–5). There’s nothing wrong with reading it now, of course! However, the rest of the Learning Manual assumes that you are familiar with LilyPond input. You may wish to skim these chapters right now, and come back to them after you have more experience.

In this tutorial and in the rest of the Learning Manual, there is a paragraph See also at the end of each section, which contains cross references to other sections: you should not follow these cross references at first reading; when you have read all of the Learning Manual, you may want to read some sections again and follow cross references for further reading.

If you have not done so already, please read Overview of manuals. There is a lot of information about LilyPond, so newcomers often do not know where they should look for help. If you spend five minutes reading that section carefully, you might save yourself hours of frustration looking in the wrong places!

4.1.1 Introduction to the LilyPond file structure

A basic example of a LilyPond input file is

\version "2.25.21"

\header { }

\score {
   … compound music expression …   % all the music goes here!
  \layout { }
  \midi { }
}

There are many variations of this basic pattern, but this example serves as a useful starting place.

Up to this point none of the examples you have seen have used a \score command. This is because LilyPond automatically adds the extra commands that are needed when you give it simple input. LilyPond treats input like this:

\relative {
  c''4 a b c
}

as shorthand for this:

\book {
  \score {
    \new Staff {
      \new Voice {
        \relative {
          c''4 a b c
        }
      }
    }
    \layout { }
  }
}

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 the commands shown above.

A word of warning! Many of the examples in the LilyPond documentation will omit the \new Staff and \new Voice commands, leaving them to be created implicitly. For simple examples this works well, but for more complex examples, especially when additional commands are used, the implicit creation of contexts can give surprising results, maybe creating extra unwanted staves. For a detailed explanation how to create contexts explicitly, see Contexts and engravers.

For now, though, let us return to the first example and examine the \score command, leaving the others to default.

A \score block must always contain exactly one music expression. Remember that a music expression could be anything from a single note to a huge compound expression like

{
  \new StaffGroup <<
     … insert the whole score of a Wagner opera in here … 
  >>
}

Since everything is inside { … }, it counts as one music expression.

As we saw previously, the \score block can contain other things, such as

\score {
  { c'4 a b c' }
  \header { }
  \layout { }
  \midi { }
}

Note that these three commands – \header, \layout, and \midi – are special: unlike many other commands that begin with a backward slash (\) they are not music expressions and are not part of any music expression. So they may be placed inside a \score block or outside it. In fact, these commands are commonly placed outside the \score block – for example, \header is often placed above the \score command, as the example at the beginning of this section shows.

Two more commands you have not previously seen are \layout and \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 – Score layout, and Creating MIDI output.

You may code multiple \score blocks. Each will be treated as a separate score, but they will be all combined into a single output file. A \book command is not necessary – one will be implicitly created. However, if you would like separate output files from one .ly file then the \book command should be used to separate the different sections: each \book block will produce a separate output file.

To summarize:

• Every \book block creates a separate output file (e.g., a PDF file). If you haven’t explicitly added one, LilyPond wraps your entire input code in a \book block implicitly.
• Every \score block is a separate chunk of music within a \book block.
• Every \layout block affects the \score or \book block in which it appears – i.e., a \layout block inside a \score block affects only that \score block, but a \layout block outside of a \score block (and thus in a \book block, either explicitly or implicitly) will affect every \score in that \book.

See Multiple scores in a book for details.

Another great shorthand is the ability to define variables, as shown previously (see Organizing pieces with variables). All the templates use this:

melody = \relative {
  c'4 a b c
}

\score {
  \melody
}

When LilyPond looks at this file, it takes the value of melody (everything after the equals sign) and inserts it whenever it sees \melody. There’s nothing special about the name – it could be melody, global, keyTime, pianorighthand, or something else. 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. For more details, see Saving typing with variables and functions. The exact limitations on variable names are detailed in File structure.

See also

For a complete definition of the input format, see File structure.

4.1.2 A score is a (single) compound musical expression

We saw the general organization of LilyPond input files in the previous section, Introduction to the LilyPond file structure. But we seemed to skip over the most important part: how do we figure out what to write after \score?

We didn’t skip over it at all. The big mystery is simply that there is no mystery. This line explains it all:

A \score block must contain exactly one music expression.

To understand what is meant by a music expression, you may find it useful to review the tutorial (see 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. For simplicity, we’ll use just a singer and piano in our example. We don’t need a StaffGroup for this ensemble, which simply groups a number of staves together with a bracket at the left, but we do need staves for a singer and a piano, though.

\score {
  <<
    \new Staff = "singer" <<
    >>
    \new PianoStaff = "piano" <<
    >>
  >>
  \layout { }
}

Here we have given names to the staves – “singer” and “piano”. This is not essential here, but it is a useful habit to cultivate so that you can see at a glance what each stave is for.

Remember that we use << … >> instead of { … } to show simultaneous music. This causes the vocal part and piano part to appear one above the other in the score. The << … >> construct would not be necessary for the “singer” staff in the example above if it were going to contain only one sequential music expression, but << … >> rather than braces is necessary if the music in the staff is to contain two or more simultaneous expressions, e.g., two simultaneous voices, or a voice with lyrics. We’re going to have a voice with lyrics, so angle brackets are required. We’ll add some real music later; for now let’s just put in some dummy notes and lyrics. If you’ve forgotten how to add lyrics you may wish to review \addlyrics, see Setting simple songs.

\score {
  <<
    \new Staff = "singer" <<
      \new Voice = "vocal" { c'1 }
      \addlyrics { And }
    >>
    \new PianoStaff = "piano" <<
      \new Staff = "upper" { c'1 }
      \new Staff = "lower" { c'1 }
    >>
  >>
  \layout { }
}

Now we have a lot more details. We have the singer’s staff: it contains a Voice (in LilyPond, this term refers to a set of notes, not necessarily vocal notes – for example, a violin generally plays one voice) and some lyrics. We also have a piano staff: it contains an upper staff (right hand) and a lower staff (left hand), although the lower staff has yet to be given a bass clef.

At this stage, we could start filling in notes. Inside the curly braces next to \new Voice = "vocal", we could start writing

\relative {
  r4 d''8\noBeam g, c4 r
}

But if we did that, the \score section would get pretty long, and it would be harder to understand what was happening. So let’s use variables instead. These were introduced at the end of the previous section, remember? To ensure the contents of the words variable below are interpreted as lyrics we preface them with \lyricmode. Like \addlyrics, this switches the input mode to lyrics. Without that, LilyPond would try to interpret the contents as notes, which would generate errors. (Several other input modes are available, see Input modes.)

So, adding a few notes and a bass clef for the left hand, we now have a piece of real music:

melody = \relative { r4 d''8\noBeam g, c4 r }
words  = \lyricmode { And God said, }
upper  = \relative { <g' d g,>2~ <g c, g> }
lower  = \relative { b,2 e }

\score {
  <<
    \new Staff = "singer" <<
      \new Voice = "vocal" { \melody }
      \addlyrics { \words }
    >>
    \new PianoStaff = "piano" <<
      \new Staff = "upper" { \upper }
      \new Staff = "lower" {
        \clef "bass"
        \lower
      }
    >>
  >>
  \layout { }
}

When writing (or reading) a \score section, just take it slowly and carefully. Start with the outer level, then work on each smaller level. It also really helps to be strict with indentation – make sure that each item on the same level starts on the same horizontal position in your text editor.

See also

Notation Reference: Structure of a score.

4.1.3 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 ossia. Here is a simple example showing how to introduce a new staff temporarily for the duration of three notes:

\new Staff {
  \relative {
    r4 g'8 g c4 c8 e |
    <<
      { c4 c }
      \new Staff { d4 c }
    >>
    r2 |
  }
}

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

\new Staff = "main" {
  \relative {
    r4 g'8 g c4 c8 e |
    <<
      { c4 c }
      \new Staff \with {
        alignAboveContext = "main"
      } { d4 c }
    >>
    r2 |
  }
}

This example uses \with, which will be explained later in more detail. It is a means of modifying the default behavior of a single staff. Here it says that the new staff should be placed above the staff called “main” instead of the default position, which is below.

See also

Ossia staves are often written without clef and without time signature and are usually printed at a smaller size. Achieving this requires further commands, which have not yet been introduced. See Size of objects, and Ossia staves.

4.1.4 Structure of a note entry

A note entry in LilyPond consists of a pitch, followed by a duration, optionally followed by one or more post-events. LilyPond post-events add things such as articulations, fingerings, string numbers, slurs, ties, and explanatory text.

The pitch may be explicitly defined using the current LilyPond input language as described in Note names in other languages. The pitch may be omitted. If the pitch is omitted, the pitch of the current note will be the same as the pitch of the previous note in the input file, see Durations. Note that neither ‘r’ nor ‘s’ (a spacer rest, see Invisible rests) is a pitch.

The duration includes a number and optionally one or more dots. If a duration is not explicitly defined, the duration of the current note will be the same as the duration of the previous note, chord, rest, or spacer rest, see Durations.

Post-events follow the note to which they are attached. Suppose we want to have an eighth note c’ with a fingering of 1, a tenuto articulation, a slur beginning with the note, a tie beginning with the note, and a text annotation. This can be accomplished as shown.

{ c'8-1--(~^\markup{"text annotation"} c' d') }

See also

Learning Manual: Ties and slurs, Articulations and dynamics, Adding text.

Notation Reference: Pitches, Rhythms, Expressive marks.

4.1.5 On the un-nestedness of brackets and ties

You have already met a number of different types of bracket and bracket-like constructs in writing the input file to LilyPond. These obey different rules which can be confusing at first. Let’s first review the different types of brackets and bracket-like constructs.

Bracket Type	Function
{ … }	Encloses a sequential segment of music
< … >	Encloses the notes of a chord
<< … >>	Encloses simultaneous music expressions
( … )	Marks the start and end of a slur
\( … \)	Marks the start and end of a phrasing slur
[ … ]	Marks the start and end of a manual beam

To these we should add other constructs that generate lines between or across notes: ties (marked by a tilde, ‘~’), tuplets written as \tuplet x/y { … }, and grace notes written as \grace { … }.

Outside LilyPond, the conventional use of brackets requires the different types to be properly nested, like this, << [ { ( … ) } ] >>, with the closing brackets being encountered in exactly the opposite order to the opening brackets. This is a requirement for the three types of bracket described by the word ‘Encloses’ in the table above – they must nest properly. However, the remaining bracket-like constructs, described with the word ‘Marks’ in the table above together with ties and tuplets, do not have to nest properly with any of the brackets or bracket-like constructs. 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:

\relative { g'8\( a b[ c b\) a] g4 }

In general, different kinds of brackets, bracket-like constructs, 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).

\relative {
  r16[ g' \tuplet 3/2 { r16 e'8] }
  g,16( a \tuplet 3/2 { b16 d) e }
  g,8[( a \tuplet 3/2 { b8 d) e~] } |
  \tuplet 5/4 { e32\( a, b d e } a4.\)
}

4.2.1 I’m hearing voices

The lowest, most fundamental or innermost layers in a LilyPond score are called voice contexts or just ‘voices’ for short. Voices are sometimes called ‘layers’ in other notation packages.

In fact, a voice layer or context is the only one that 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 requires just a single voice. Instruments that 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:

\relative {
  \key g \major
  <d' g>4 <d fis> <d a'> <d g>
}

This can be expressed using just the single angle bracket chord symbols, < … >, and for this just a single voice is needed. But suppose the F-sharp was 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 sequential 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.

The easiest way to enter fragments with more than one voice on a staff is to enter each voice as a sequence (with { … }), and combine them simultaneously with angle brackets, << … >>. The fragments must also be separated with double backward slashes, \\, 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 homophonic 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:

\relative {
  \key g \major
  %    Voice = "1"              Voice = "2"
  << { g'4 fis8( g) a4 g } \\ { d4 d d d } >>
}

Notice how the stems of the second voice now point down.

Here’s another simple example:

\relative {
  \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. r4 }       >> |
}

It is not necessary to use a separate << \\ >> construct for each bar. For music with few notes in each bar this layout can help improve 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:

<<
  \key d \minor
  \relative { % Voice = "1"
    r4 g' g4. a8 |
    bes4 bes c bes |
    a2. r4 |
  } \\
  \relative { % Voice = "2"
    d'2 d4 g |
    g4 g g8( a) g4 |
    fis2. r4 |
  }
>>

This example has just two voices, but the same construct may be used to encode three or more voices by adding more back-slash separators.

The Voice contexts implicitly created by << \\ >> bear the names "1", "2", etc. The first contexts set the outer voices, the highest voice in context "1" and the lowest voice in context "2". The inner voices go in contexts "3" and "4". In each of these contexts, the vertical direction of slurs, stems, ties, dynamics, etc., is set appropriately.

\new Staff \relative {
  % Main voice
  c'16 d e f
  %  Voice = "1"   Voice = "2"             Voice = "3"
  << { g4 f e } \\ { r8 e4 d c8~ } >> |
  << { d2 e }   \\ { c8 b16 a b8 g~ 2 } \\ { s4 b c2 } >> |
}

Note the use of s4 to insert an invisible spacer rest, thus delaying the (visible) start of voice "3".

If you prefer entering the voices in a different order, like top to bottom, you can specify the respective voice numbers in front of one << … >> construct using the \voices command, like

\new Staff \relative {
  % Main voice
  c'16 d e f
  %  Voice = "1"   Voice = "2"
  << { g4 f e } \\ { r8 e4 d c8~ } >> |
  \voices 1,3,2
  %  Voice = "1"   Voice = "3"    Voice = "2"
  << { d2 e }   \\ { s4 b c2 } \\ { c8 b16 a b8 g~ 2 } >> |
}

These voices are all separate from the main voice that contains the notes just outside the << … >> construct. Let’s call this the 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.

\new Staff \relative {
  % Main voice
  c'16 d e f
  <<  % Bar 1
    { \voiceOneStyle g4 f e }
  \\
    { \voiceTwoStyle r8 e4 d c8~ }
  >> |
  <<  % Bar 2
    % Voice 1 continues
    { d2 e }
  \\
    % Voice 2 continues
    { c8 b16 a b8 g~ 2 }
  \\
    { \voiceThreeStyle s4 b c2 }
  >> |
}

The commands \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; \voiceNeutralStyle (also not used here) reverts the style back to the default. We shall see later how commands like these may be created by the user. See Visibility and color of objects and Using variables for layout adjustments.

Polyphony does not change the relationship of notes within a \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

\relative { noteA << <noteB noteC> \\ noteD >> noteE }

• noteB is relative to noteA;
• noteC is relative to noteB, not noteA;
• noteD is relative to noteB, not noteA or noteC;
• noteE is relative to noteD, not noteA.

An alternative way, which may be clearer if the notes in the voices are widely separated, is to place a \relative command at the start of each voice:

\relative { noteA … }
<<
  \relative { <noteB noteC> … }
\\
  \relative { noteD … }
>>
\relative { noteE … }

Let us finally analyze 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 that looks mysterious and concentrate just on the music and the voices – the complications will all be explained in later sections.

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 starting at the same time have different durations. Look at the notes that 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.

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 << \\ >> construct to enter the music of the first bar in three voices:

\new Staff \relative {
  \key aes \major
  <<
    { c''2 aes4. bes8 } \\ { <ees, c>2 des } \\ { aes'2 f4 fes }
  >> |
  <c ees aes c>1 |
}