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