LilyPond Quick Guide

Introduction

LilyPond is a powerful and versatile typesetting program for musical scores. Authors prepare a source file, with suffix .ly, and run the lilypond executable to create a musical score in both .pdf and .ps formats.
LilyPond is available at http://lilypond.org/web/. The documentation can be found at http://lilypond.org/doc/v2.12/Documentation/; good luck with that.
The documentation is voluminous, but difficult to penetrate. I found it difficult to find out about such simple features as the overall structure of a LilyPond source file. Many commands and features are described without any context whatsoever, and it becomes a matter of trial and error to determine exactly how they should be integrated into a source file. And some features that one would expect to be quite simple, seem to be achievable only by complex and obscure "commands" or "variables". One is frequently tempted to attach multiple features to a single note (e.g. sharp/flat, duration, pitch, slur start or end, phrase start or end, dynamic mark, crescendo/decrescendo start or end and text are a few examples!), and it typically requires trial and error to determine which of the particular orders is the only one that LilyPond accepts. LilyPond source files appear to be written in a custom programming language whose grammar is never discussed.
In spite of these difficulties, LilyPond is astoundingly powerful, and produces very beautiful output. It's therefore worth the trouble to get to know it. This document summarizes the techniques which were for me the essentials for creating simple musical scores using LilyPond.

Running LilyPond

Running LilyPond is quite simple. First create the source file, with suffix .ly, using a text editor. Then, in a command window, run the following:
"c:\Program Files\LilyPond\usr\bin\lilypond.exe" source.ly
You may of course need to modify the path to the executable, depending on how you installed LilyPond. You might like to make a batch file that runs the command on an arbitrary file.
Assuming that your lilypond source file compiles properly, the result will be two files, source.pdf and source.ps, which you can then open using whatever viewer is appropriate.

Program Structure

This produces a main title centered, and a sequences of sections. The music in each section is defined in a \score.
#(set-default-paper-size "letter") \version "2.10.33" \header{ title = "Main Title" composer="The Composer" } \include "english.ly" \layout { indent = 0.0\cm } \markup { Subsection 1 } \score { ... } \markup { Subsection 2 } \score { ... } \markup { Subsection 3 } \score { ... }
The title is displayed centered at the top of the page, with the composer below it to the right. The include of english.ly allows us to use English names for sharps and flats ("s" and "f"), instead of the default Dutch names ("is" and "es"). The layout instruction tells Lilypond to not indent the first line of each score in a very annoying fashion. The markup texts are left justified on the page.

The Score

The score defines a section of music.
\score { \relative c' { \clef treble \time 3/4 \key c \major c d e f g a b c d e f g } }
The \relative command specifies the pitch of the initial note (within a 4th): see the next section.
The \clef command defines the clef (naturally), with "treble" and "base" being the most common values. Treble is assumed if no \clef command is provided.
The \time command defines the time signature: 3/4, 4/4, 3/2, 6/8, etc.
The \key command defines the key signature: \c major, \a minor, etc.
The clef, time and key commands can appear in the middle of a section if it is needed to change any of these values.
\score { \relative c' { \clef treble \time 4/4 \key c \major c c c c \clef bass \time 3/4 \key d \major c c c \clef treble \time 5/4 \key 3 \major c c c c c } }

Notes

Notes are defined using letter notation a, b, c, d, e, f, g. The actual pitch of the first note is defined via the \relative command; the first note will be within a fourth up or down from the relative note.
\relative c' = middle C
\relative d' = D above middle C
\relative c'' = C above middle C
\relative c''' = second C above middle C
Rests are indicated by the letter 'r'.
\score { \relative a' { \time 4/4 \key f \minor a b c d e d c b r b c d } }
Note that the note "a" is interpreted as A natural, even though the key signature has been specified as F minor, in which A would normally be flat.
Notes are separated by spaces. Lines can be broken anywhere.

Sharps and Flats

All sharps and flat MUST be indicated, even if they are implied by the key signature.
If english.ly is included, sharps are indicated by appending "s" to the note name, and flats are indicated by appending "f". Without english.ly included, Dutch seems to be the default, and the appends are the rather foreign looking "is" and "es".
The flat or sharp won't be printed, if it is implied by the key signature. On the other hand, if you forget an "s" or "f" that is in the key signature, then LilyPond will print a natural for you, as seen in the previous example.
For example, the D minor scale:
\score { \relative a' { \time 4/4 \key d \minor d e f g a bf cs d } }
Note how the B-flat (written "bf") appears without an accidental, since the flat is implied by the key signature.

Note pitches

When writing a sequence of notes, the pitch of each note is interpreted relative to the preceding note. If the note is within a fourth of the preceding note, no special notation is required. If the note is more than a fourth above the preceding note, append an apostrophe ('). If the note is more than a fourth below the preceding note, append a comma (,).
\score { \relative c'' { \time 6/8 \key g \major c d c e c f c g' c, a' c, b' c, a' c, g' c, f c e c b c c } }
The pitch indicator follows the sharp or flat indicator.

Note durations

Note durations are indicated by appending a numerical value after the note, AFTER the pitch shift indicator (apostrophe or comma) if there is one.
1 = whole note
2 = half note
4 = quarter note
8 = eighth note
16 = sixteenth note
etc.
For example, here's four bars in 4/4 time:
\score { \relative c'' { \time 4/4 \key g \major c4 d4 e4 fs8 g8 a2 c,4 f,4 f4 g8 f16 e16 d1 } }
It's possible to omit the duration if the note is the same duration as the preceding note. For example:
\score { \relative c'' { \time 4/4 \key g \major c4 c d d e8 f e d c4 c } }
However, it's easy to make a mistake this way!
For dotted notes, append a period '.':
\score { \relative c'' { \time 4/4 \key g \major c4 c4 c8. c16 c4 d4. d8 d2 } }
The duration indicator follows the pitch indicator:
fs,4

Note decorations

Decorations are indicated by appending a \command after the note:
c2.\staccato
Other decorations:
\marcato
\accent
\turn
\tenuto
\trill
\prall
\mordent
\fermata
\segno
\coda
Some of these have shorter forms, by appending a dash and a character after the note:
statccato: c4-.
accent: c4->
marcato: c4-^
tenuto: c4--
\score { \relative c'' { \time 4/4 \key g \major c4\staccato c4\marcato c4\accent c4\turn d4\tenuto d4\trill d4\prall d4\mordent e4\fermata e4\segno e2\coda f4-. f4-> f4-^ f4-- } }
The decoration indicator follows the duration indicator:
fs'4\trill

Bars

You can use '|' to explicitly indicate bars. This is not strictly necessary, however, since LilyPond will automatically fill in the bars at the appropriate locations.
To add a double bar, use \bar "||".
For example, we don't need to mark the bar lines in the first three bars; the bar line markers in the last three bars are superfluous.
\score { \relative c'' { \time 3/4 \key g \major c4 c4 c4 c4 c4 c4 c4 c4 c4 \bar "||" d4 d4 d4 | d4 d4 d4 | d4 d4 d4 \bar "||" } }

Ties

Use ~ between two notes to indicate a tie.
\score { \relative c'' { \time 3/4 \key g \major c4 d4 e4 ~ e4 e4 ~ e8 e8 c1. } }

Slurs

Use ( and ) to indicate slurs. The ( follows the first note of the slur, and the ) follows the last note of the slur.
\score { \relative c'' { \time 3/4 \key g \major c4( b4) c4 c4( b4) c4 c4( b4 a4) d4( e4 fs4 | e4) d4 d4 | d4.\trill( e8) fs4 } }

Phrasing

Use \( and \) to indicate phrases. The \( follows the first note of the phrase, and the \) follows the last note of the phrase. It seems that slurs can only be within a single bar, so if a phrase extends over multiple bars, the backslash notation is required. Note that a slur and a phrase can begin on the same note, but it's not possible to begin two slurs or two phrases on one note.
\score { \relative c'' { \time 3/4 \key g \major c4-. b4\( c4 d4 c4 d4 e4 d4\) e4-. } }

Beams

LilyPond automatically connects notes according to a default algorithm, but you can override the defaults by means of the [ and ] characters. Use these the same way as the parenthese for slurs: append [ to the first note of a connected sequence, and append ] to the last one.
To turn off and on LilyPond's automatic beaming algorithm, use the \autoBeamOff and \autoBeamOn commands.
\score { \relative c'' { \time 4/4 \key g \major d16 d16 d16 d16 d16 d16 d16 d16 d16[ d16 d16 d16 d16 d16 d16 d16] d16[ d16 d16 d16] \autoBeamOff d16 d16 d16 d16 \autoBeamOn d16 d16 d16 d16 d16[ d16] d16[ d16] } }
This construction is also useful when creating multiple grace notes.

Repeated Sections

For a repeated section, use the "\repeat volta n" construction. I'm sure there must be a reason for this terminology.
\score { \relative c'' { \time 4/4 \key c \major \repeat volta 2 { c4 d4 e4 f4 g4 c4 c,2 g'4 f4 e4 d4 e2 a,2 } \repeat volta 2 { c4 d4 e4 f4 g4 c4 c,2 g'4 f4 e4 d4 c1 } } }

Alternate Endings

Use the \alternate construction to code for alternate endings of a repeated section.
\score { \relative c'' { \time 4/4 \key c \major \repeat volta 2 { c4 d4 e4 f4 g4 c4 c,2 g'4 f4 e4 d4 } \alternative { { e2 a,2 } { c1 } } } }

Partial Bars

If the music starts with a partial bar, you should include a \partial command to indicate how many beats precede the first full bar.
\score { \relative g' { \time 3/4 \key c \major \partial 4 f4 | f2. | f4( e4 e4) | f2 f4 | f2 d8 e8 | f2 e4 | f4( g2) | f2 f4 | f2 } }

Multiple Rest Bars

To include a multi-bar rest, you must add some pretty obscure commands (\set and \override, see below), and then use the construction:
Rx*n
where Rx indicates the duration of the bar (e.g. R1 in 4/4, R2 in 2/4, R2. in 3/4, etc), and n is the number of bars of rest.
For example, here's a really interesting part:
\score { \relative c'' { \set Score.skipBars = ##t \override MultiMeasureRest #'expand-limit = 1 \time 2/4 \key c \major c4 c4 c4 c4 R2*16 c4 c4 c2 } }

Dynamics

To indicate dynamics (ppp, mf, ff, etc), append a backslash and the desired dynamic:
\score { \relative c'' { \time 4/4 \key c \major c4\ppp c4\pp c4\p c4\mp c4\mf c4\f c4\ff c4\fff c1\sfz } }
For crescendi and decrescendi, append \< or \> to the starting note, and \! to the ending note.
\score { \relative c'' { \time 4/4 \key c \major c4\< c4 c4 c4 c4 c4 c4 c4\! c4 c4 c4\> c4 c4 c4\! c4 c4 } }

Text

To add some text above or below the staff, use ^"the text" or _"the text" respectively, following the note where the text should be positioned.
\score { \relative c'' { \time 4/4 \key c \major c4^"Jovially" c4 c4 c4 c4 c4 c4 c4 c4_"Without any sense of futility" c4 c4 c4 c4 c4 c4 c4 } }
To right-align text with a bar line, for text such as the indispensable "D.S. al coda" and "D.S. al fine", you can use the following extremely obscure construction:
\score { \relative c'' { \time 4/4 \key c \major c4 c4 c4 c4 c4 c4 c4 c4 c4 c4 c4 c4 c4 c4 d2 \override Score.RehearsalMark #'break-visibility = #begin-of-line-invisible \override Score.RehearsalMark #'self-alignment-X = #RIGHT \mark "D.C. al Fine" } }

Triplets

To produce triplets, or any other alteration of the basic tempo, use the following construction:
\times m/n { notes }
where m is the normal number of intervals that the notes should occupy, and n is the actual number of notes to be played during that interval. For example, triplets are indicated by "\times 2/3", since three notes are to played in the time that two of them would normally be played.
\score { \relative c'' { \time 4/4 \key c \major c4 c4 \times 2/3 { c8 d8 e8 } f4 c4 c4 \times 4/5 { c16 d16 c16 b16 c16 } d4 } }

Grace notes

Use "\grace note", or "\grace { notes }" to add simple grace notes before a main note. Instead of "grace", use "acciaccatura" to add grace notes with slashed stems that are slurred to the main note, and "appoggiatura" for unslashed stems.
\score { \relative c'' { \time 4/4 \key c \major c4 \grace d16 c4 c4 c4 c4 \grace { e16 d16 } c4 c4 c4 c4 \acciaccatura d16 c4 c4 c4 \acciaccatura { e16 d16 } c4 c4 c4 \appoggiatura d16 c4 c4 } }

Transposing

Transposing is deliciously easy, with the transpose command:
\score { \relative c'' { \time 4/4 \key c \major c4 d4 e4 f4 g4 a,4 gs4 a2 } } \score { \transpose c' ees' \relative c'' { \time 4/4 \key c \major c4 d4 e4 f4 g4 a,4 gs4 a2 } }

An Example

Here's a relatively complex example that brings together nearly all of the techniques mentioned above.
#(set-default-paper-size "letter") \version "2.10.33" \header{ title="Syrinx" composer="Claude Debussy" } \include "english.ly" \markup { à Louis Fleury } \score { \relative c''' { \time 3/4 \key df \major bf8.--\mf^"Trés modéré"( a32 b32) af8.--( g32 a32) gf16( f e df) bf'8.( c32 cf bf2\fermata) bf8.--\mf( a32 b32) af8.--( g32 a32) gf16( f e df) bf8.--\<( fs32 g)\! b8--\p ~ \times 2/3 { b16\<\([ fs g] } \times 2/3 { c16[ fs, g] } \times 2/3 { df'16[ \acciaccatura f e d\!] } bf8.\p fs32\< g b4\!\) \times 2/3 { r16 af\<( cf } \times 2/3 { df ff af\!) } r8. af16\p cf2\<( ~ cf2\! df4\>) ef2^"retenu"\p\!\>( bf4)\! \bar "||" } }
Some notes:
  • While the source code resembles gibberish to a high order, the output is quite impressive!
  • It's often useful in complex music to organize the source .ly file so that it's easy to match up the code with the generated music; in the example above, for example, each bar defined in a separate section.
  • To use accented characters, you must use the UTF-8 encoding for the source file, and enter the accented characters as UTF-8 values. You may need to use an editor that is slightly more sophisticated than the usual Microsoft crap, such as UltraEdit or TextPad.

Miscellaneous

Here's some more useful techniques...

Tightening up the score

The output is often quite generous with white space, and in a longer piece, it's possible to save pages of output by getting Lilypond to cram the notes in closer together. To do this, add the "layout" section in the example below to your score. God knows how or why it works, or what to change if you want a slightly different spacing; the documentation certainly doesn't explain anything.
\score { \relative ... { ... some notes and other stuff } \layout { \context { \Score \override SpacingSpanner #'common-shortest-duration = #(ly:make-moment 1 2) } } }

Getting rid of the indent

For unknown reasons, lilypond by default indents the first line of a score by about half an inch. Here's how to defeat this peculiar behaviour:
\score { \relative ... { ... some notes and other stuff } \layout { indent = 0.0 } }