This file documents GNU LilyPond.
Copyright 1999–2007 by the authors
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections. A copy of the license is included in the section entitled “GNU Free Documentation License”.
This is the user manual for GNU LilyPond 2.10.x series. (See the bottom of this page for the exact version number).
More information can be found at http://www.lilypond.org/. The website contains on-line copies of this and other documentation.
We want to dedicate this program to all the friends that we met through music.Han-Wen and Jan
It must have been during a rehearsal of the EJE (Eindhoven Youth Orchestra), somewhere in 1995 that Jan, one of the cranked violists, told Han-Wen, one of the distorted French horn players, about the grand new project he was working on. It was an automated system for printing music (to be precise, it was MPP, a preprocessor for MusiXTeX). As it happened, Han-Wen accidentally wanted to print out some parts from a score, so he started looking at the software, and he quickly got hooked. It was decided that MPP was a dead end. After lots of philosophizing and heated email exchanges, Han-Wen started LilyPond in 1996. This time, Jan got sucked into Han-Wen's new project.
In some ways, developing a computer program is like learning to play an instrument. In the beginning, discovering how it works is fun, and the things you cannot do are challenging. After the initial excitement, you have to practice and practice. Scales and studies can be dull, and if you are not motivated by others – teachers, conductors or audience – it is very tempting to give up. You continue, and gradually playing becomes a part of your life. Some days it comes naturally, and it is wonderful, and on some days it just does not work, but you keep playing, day after day.
Like making music, working on LilyPond can be dull work, and on some days it feels like plodding through a morass of bugs. Nevertheless, it has become a part of our life, and we keep doing it. Probably the most important motivation is that our program actually does something useful for people. When we browse around the net we find many people who use LilyPond, and produce impressive pieces of sheet music. Seeing that feels unreal, but in a very pleasant way.
Our users not only give us good vibes by using our program, many of them also help us by giving suggestions and sending bug reports, so we would like to thank all users that sent us bug reports, gave suggestions or contributed in any other way to LilyPond.
Playing and printing music is more than a nice analogy. Programming together is a lot of fun, and helping people is deeply satisfying, but ultimately, working on LilyPond is a way to express our deep love for music. May it help you create lots of beautiful music!
Han-Wen and Jan
Utrecht/Eindhoven, The Netherlands, July 2002.
The art of music typography is called (plate) engraving. The term derives from the traditional process of music printing. Just a few decades ago, sheet music was made by cutting and stamping the music into a zinc or pewter plate in mirror image. The plate would be inked, the depressions caused by the cutting and stamping would hold ink. An image was formed by pressing paper to the plate. The stamping and cutting was completely done by hand. Making a correction was cumbersome, if possible at all, so the engraving had to be perfect in one go. Engraving was a highly specialized skill; a craftsman had to complete around five years of training before earning the title of master engraver, and another five years of experience were necessary to become truly skilled.
Nowadays, all newly printed music is produced with computers. This has obvious advantages; prints are cheaper to make, and editorial work can be delivered by email. Unfortunately, the pervasive use of computers has also decreased the graphical quality of scores. Computer printouts have a bland, mechanical look, which makes them unpleasant to play from.
The images below illustrate the difference between traditional engraving and typical computer output, and the third picture shows how LilyPond mimics the traditional look. The left picture shows a scan of a flat symbol from an edition published in 2000. The center depicts a symbol from a hand-engraved Bärenreiter edition of the same music. The left scan illustrates typical flaws of computer print: the staff lines are thin, the weight of the flat symbol matches the light lines and it has a straight layout with sharp corners. By contrast, the Bärenreiter flat has a bold, almost voluptuous rounded look. Our flat symbol is designed after, among others, this one. It is rounded, and its weight harmonizes with the thickness of our staff lines, which are also much thicker than lines in the computer edition.
|
|
|
| |
| Henle (2000) | Bärenreiter (1950) |
LilyPond Feta font (2003)
|
In spacing, the distribution of space should reflect the durations between notes. However, many modern scores adhere to the durations with mathematical precision, which leads to poor results. In the next example a motive is printed twice: once using exact mathematical spacing, and once with corrections. Can you spot which fragment is which?
Each bar in the fragment only uses notes that are played in a constant rhythm. The spacing should reflect that. Unfortunately, the eye deceives us a little; not only does it notice the distance between note heads, it also takes into account the distance between consecutive stems. As a result, the notes of an up-stem/down-stem combination should be put farther apart, and the notes of a down-stem/up-stem combination should be put closer together, all depending on the combined vertical positions of the notes. The upper two measures are printed with this correction, the lower two measures without, forming down-stem/up-stem clumps of notes.
Musicians are usually more absorbed with performing than with studying the looks of a piece of music, so nitpicking about typographical details may seem academical. But it is not. In larger pieces with monotonous rhythms, spacing corrections lead to subtle variations in the layout of every line, giving each one a distinct visual signature. Without this signature all lines would look the same, and they become like a labyrinth. If a musician looks away once or has a lapse in concentration, the lines might lose their place on the page.
Similarly, the strong visual look of bold symbols on heavy staff lines stands out better when the music is far away from the reader, for example, if it is on a music stand. A careful distribution of white space allows music to be set very tightly without cluttering symbols together. The result minimizes the number of page turns, which is a great advantage.
This is a common characteristic of typography. Layout should be pretty, not only for its own sake, but especially because it helps the reader in her task. For performance material like sheet music, this is of double importance: musicians have a limited amount of attention. The less attention they need for reading, the more they can focus on playing the music. In other words, better typography translates to better performances.
These examples demonstrate that music typography is an art that is subtle and complex, and that producing it requires considerable expertise, which musicians usually do not have. LilyPond is our effort to bring the graphical excellence of hand-engraved music to the computer age, and make it available to normal musicians. We have tuned our algorithms, font-designs, and program settings to produce prints that match the quality of the old editions we love to see and love to play from.
How do we go about implementing typography? If craftsmen need over ten years to become true masters, how could we simple hackers ever write a program to take over their jobs?
The answer is: we cannot. Typography relies on human judgment of appearance, so people cannot be replaced completely. However, much of the dull work can be automated. If LilyPond solves most of the common situations correctly, this will be a huge improvement over existing software. The remaining cases can be tuned by hand. Over the course of years, the software can be refined to do more and more things automatically, so manual overrides are less and less necessary.
When we started, we wrote the LilyPond program entirely in the C++ programming language; the program's functionality was set in stone by the developers. That proved to be unsatisfactory for a number of reasons:
These problems have been addressed by integrating an interpreter for the Scheme programming language and rewriting parts of LilyPond in Scheme. The current formatting architecture is built around the notion of graphical objects, described by Scheme variables and functions. This architecture encompasses formatting rules, typographical style and individual formatting decisions. The user has direct access to most of these controls.
Scheme variables control layout decisions. For example, many graphical objects have a direction variable that encodes the choice between up and down (or left and right). Here you see two chords, with accents and arpeggios. In the first chord, the graphical objects have all directions down (or left). The second chord has all directions up (right).
The process of formatting a score consists of reading and writing the variables of graphical objects. Some variables have a preset value. For example, the thickness of many lines – a characteristic of typographical style – is a variable with a preset value. You are free to alter this value, giving your score a different typographical impression.
Formatting rules are also preset variables: each object has variables containing procedures. These procedures perform the actual formatting, and by substituting different ones, we can change the appearance of objects. In the following example, the rule which note head objects are used to produce their symbol is changed during the music fragment.
The formatting process decides where to place symbols. However, this can only be done once it is decided what symbols should be printed, in other words what notation to use.
Common music notation is a system of recording music that has evolved over the past 1000 years. The form that is now in common use dates from the early renaissance. Although the basic form (i.e., note heads on a 5-line staff) has not changed, the details still evolve to express the innovations of contemporary notation. Hence, it encompasses some 500 years of music. Its applications range from monophonic melodies to monstrous counterpoints for large orchestras.
How can we get a grip on such a many-headed beast, and force it into
the confines of a computer program? Our solution is to break up the
problem of notation (as opposed to engraving, i.e., typography) into
digestible and programmable chunks: every type of symbol is handled by
a separate module, a so-called plug-in. Each plug-in is completely
modular and independent, so each can be developed and improved
separately. Such plug-ins are called engravers, by analogy
with craftsmen who translate musical ideas to graphic symbols.
In the following example, we see how we start out with a plug-in for
note heads, the Note_heads_engraver.
Then a Staff_symbol_engraver adds the staff
the Clef_engraver defines a reference point for the staff
and the Stem_engraver adds stems.
The Stem_engraver is notified of any note head coming along.
Every time one (or more, for a chord) note head is seen, a stem
object is created and connected to the note head. By adding
engravers for beams, slurs, accents, accidentals, bar lines,
time signature, and key signature, we get a complete piece of
notation.
This system works well for monophonic music, but what about polyphony? In polyphonic notation, many voices can share a staff.
In this situation, the accidentals and staff are shared, but the stems, slurs, beams, etc., are private to each voice. Hence, engravers should be grouped. The engravers for note heads, stems, slurs, etc., go into a group called ‘Voice context’, while the engravers for key, accidental, bar, etc., go into a group called ‘Staff context’. In the case of polyphony, a single Staff context contains more than one Voice context. Similarly, multiple Staff contexts can be put into a single Score context. The Score context is the top level notation context.
Program reference: Contexts.
Ideally, the input format for any high-level formatting system is an abstract description of the content. In this case, that would be the music itself. This poses a formidable problem: how can we define what music really is? Instead of trying to find an answer, we have reversed the question. We write a program capable of producing sheet music, and adjust the format to be as lean as possible. When the format can no longer be trimmed down, by definition we are left with content itself. Our program serves as a formal definition of a music document.
The syntax is also the user-interface for LilyPond, hence it is easy to type
c'4 d'8
a quarter note C1 (middle C) and an eighth note D1 (D above middle C)
On a microscopic scale, such syntax is easy to use. On a larger scale, syntax also needs structure. How else can you enter complex pieces like symphonies and operas? The structure is formed by the concept of music expressions: by combining small fragments of music into larger ones, more complex music can be expressed. For example
c4
![[image of music]](lily-8497956b01)
Chords can be constructed with << and >> enclosing the notes
<<c4 d4 e4>>
This expression is put in sequence by enclosing it in curly braces
{ ... }
{ f4 <<c4 d4 e4>> }
The above is also an expression, and so it may be combined
again with another simultaneous expression (a half note) using <<,
\\, and >>
<< g2 \\ { f4 <<c4 d4 e4>> } >>
Such recursive structures can be specified neatly and formally in a context-free grammar. The parsing code is also generated from this grammar. In other words, the syntax of LilyPond is clearly and unambiguously defined.
User-interfaces and syntax are what people see and deal with most. They are partly a matter of taste, and also subject of much discussion. Although discussions on taste do have their merit, they are not very productive. In the larger picture of LilyPond, the importance of input syntax is small: inventing neat syntax is easy, while writing decent formatting code is much harder. This is also illustrated by the line-counts for the respective components: parsing and representation take up less than 10% of the source code.
We have written LilyPond as an experiment of how to condense the art of music engraving into a computer program. Thanks to all that hard work, the program can now be used to perform useful tasks. The simplest application is printing notes.
By adding chord names and lyrics we obtain a lead sheet.
Polyphonic notation and piano music can also be printed. The following example combines some more exotic constructs.
The fragments shown above have all been written by hand, but that is not a requirement. Since the formatting engine is mostly automatic, it can serve as an output means for other programs that manipulate music. For example, it can also be used to convert databases of musical fragments to images for use on websites and multimedia presentations.
This manual also shows an application: the input format is text, and can therefore be easily embedded in other text-based formats such as LaTeX, HTML, or in the case of this manual, Texinfo. By means of a special program, the input fragments can be replaced by music images in the resulting PDF or HTML output files. This makes it easy to mix music and text in documents.
The manual is divided into the following chapters:
.ly format.
\commands.
Once you are an experienced user, you can use the manual as reference: there is an extensive index1, but the document is also available in one big page, which can be searched easily using the search facility of a web browser. If you are not familiar with music notation or music terminology (especially if you are a non-native English speaker), it is advisable to consult the glossary as well. The Music glossary, explains musical terms and includes translations to various languages. It is also available in PDF.
This manual is not complete without a number of other documents. They are not available in print, but should be included with the documentation package for your platform
The program reference is a set of heavily cross linked HTML pages, which document the nitty-gritty details of each and every LilyPond class, object, and function. It is produced directly from the formatting definitions used.
Almost all formatting functionality that is used internally, is available directly to the user. For example, all variables that control thickness values, distances, etc., can be changed in input files. There are a huge number of formatting options, and all of them are described in this document. Each section of the notation manual has a See also subsection, which refers to the generated documentation. In the HTML document, these subsections have clickable links.
This collection of files shows various tips and tricks, and is available as a big HTML document, with pictures and explanatory texts included.
This collection of files tests each notation and engraving feature of LilyPond in one file. The collection is primarily there to help us debug problems, but it can be instructive to see how we exercise the program. The format is similar to the tips and tricks document.
In all HTML documents that have music fragments embedded, the LilyPond input that was used to produce that image can be viewed by clicking the image.
The location of the documentation files that are mentioned here can vary from system to system. On occasion, this manual refers to initialization and example files. Throughout this manual, we refer to input files relative to the top-directory of the source archive. For example, input/test/bla.ly may refer to the file lilypond2.x.y/input/test/bla.ly. On binary packages for the Unix platform, the documentation and examples can typically be found somewhere below /usr/share/doc/lilypond/. Initialization files, for example scm/lily.scm, or ly/engraver-init.ly, are usually found in the directory /usr/share/lilypond/.
Finally, this and all other manuals, are available online both as PDF files and HTML from the web site, which can be found at http://www.lilypond.org/.
This tutorial starts with an introduction to the LilyPond music language and how to produce printed music. After this first contact we will explain how to create common musical notation.
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. If you like learning in this way, you will probably want to print out or bookmark the Cheat sheet, which is a table listing of the most common commands for quick reference.
This section gives a basic introduction to working with LilyPond.
The first example demonstrates how to start working with LilyPond. To create sheet music, we write a text file that specifies the notation. For example, if we write
{
c' e' g' e'
}
the result looks like this
Warning: Every piece of LilyPond input needs to have { curly braces } placed around the input. The braces should also be surrounded by a space unless they are at the beginning or end of a line to avoid ambiguities. These may be omitted in some examples in this manual, but don't forget them in your own music!
In addition, LilyPond input is case sensitive. { c d e }
is valid input; { C D E } will produce an error message.
In this section we will explain what commands to run and how to view or print the output.
If you double click LilyPond.app, it will open with an example file. Save it, for example, to test.ly on your Desktop, and then process it with the menu command `Compile > Typeset File'. The resulting PDF file will be displayed on your screen.
Be warned that the first time you ever run LilyPond, it will take a minute or two because all of the system fonts have to be analyzed first.
For future use of LilyPond, you should begin by selecting "New" or "Open". You must save your file before typesetting it. If any errors occur in processing, please see the log window.
On Windows, start up a text-editor2 and enter
{
c' e' g' e'
}
Save it on the desktop as test.ly and make sure that it is not called test.ly.TXT. Double clicking test.ly will process the file and show the resulting PDF file. To edit an existing .ly file, right-click on it and select “Edit source”.
If you double-click in the LilyPond icon on the Desktop, it will open a simple text editor with an example file. Save it, for example, to test.ly on your Desktop, and then double-click on the file to process it. After some seconds, you will get a file test.pdf on your desktop. Double-click on this PDF file to view the typeset score. An alternative method to process the test.ly file is to drag and drop it onto the LilyPond icon using your mouse pointer.
Double-clicking the file does not only result in a PDF file, but also produces a .log file that contains some information on what LilyPond has done to the file. If any errors occur, please examine this file.
Begin by opening a terminal window and starting a text editor. For
example, you could open an xterm and execute
joe3. In your
text editor, enter the following input and save the file as
test.ly
{
c' e' g' e'
}
To process test.ly, proceed as follows
lilypond test.ly
You will see something resembling
lilypond test.ly GNU LilyPond 2.10.0 Processing `test.ly' Parsing... Interpreting music... [1] Preprocessing graphical objects... Calculating line breaks... [2] Layout output to `test.ps'... Converting to `test.pdf'...
The result is the file test.pdf which you can print or view with the standard facilities of your operating system.4
LilyPond will add some notation elements automatically. In the next example, we have only specified four pitches, but LilyPond has added a clef, time signature, and rhythms.
{ c' e' g' e' }
![[image of music]](lily-fc1309bd7a)
This behavior may be altered, but in most cases these automatic values are useful.
The easiest way to enter notes is by using \relative mode. In
this mode, the interval between the previous note and the
current note is assumed to be within a fourth. We begin by
entering the most elementary piece of music, a scale.
\relative c' { c d e f g a b c }
![[image of music]](lily-c9308206d1)
The initial note is middle C. Each successive note is within a fourth of the previous note – in other words, the first `c' is the closest C to middle C. This is followed by the closest D to the previous note. We can create melodies which have larger intervals:
\relative c' { d f a g c b f d }
![[image of music]](lily-130d5f45fe)
As you may notice, this example does not start on middle C. The first note – the `d' – is the closest D to middle C.
To add intervals that are larger than a fourth, we can raise the octave
by adding a single quote ' (or apostrophe) to the note name. We can
lower the octave by adding a comma , to the note name.
\relative c'' { a a, c' f, g g'' a,, f' }
![[image of music]](lily-e6f800524b)
To change a note by two (or more!) octaves, we use multiple '' or
,, – but be careful that you use two single quotes '' and
not one double quote " ! The initial value in
\relative c' may also be modified like this.
The duration of a note is specified by a number after the note name. `1' for a whole note, `2' for a half note, `4' for a quarter note and so on. Beams are added automatically.
\relative c'' { a1 a2 a4 a8 a a16 a a a a32 a a a a64 a a a a a a a a2 }
![[image of music]](lily-f204dca6b2)
If you do not specify a duration, the previous duration is used for the next note. The duration of the first note defaults to a quarter.
To create dotted notes, add a dot `.' to the duration number.
\relative c'' { a a a4. a8 a8. a16 a a8. a8 a4. }
![[image of music]](lily-58efd1fb3e)
A rest is entered just like a note with the name `r':
\relative c'' { a r r2 r8 a r4 r4. r8 }
![[image of music]](lily-59c7b954b3)
The time signature) can be set with the \time command:
\relative c'' { \time 3/4 a4 a a \time 6/8 a4. a \time 4/4 a4 a a a }
![[image of music]](lily-a010f80383)
The clef can be set using the \clef command:
\relative c' { \clef treble c1 \clef alto c1 \clef tenor c1 \clef bass c1 }
![[image of music]](lily-3e254893b4)
Here is a small example showing all these elements together:
\relative c, { \time 3/4 \clef bass c2 e8 c' g'2. f4 e d c4 c, r4 }
![[image of music]](lily-a504ca25c1)
- Entering pitches and durations
- see Pitches and Durations.
- Rests
- see Rests.
- Time signatures and other timing commands
- see Time signature.
- Clefs
- see Clef.
LilyPond input files are treated like files in most programming languages:
they are case sensitive, white-space insensitive, expressions are
formed with curly braces { }, and comments are denoted with % or
%{ .. %}.
If the previous sentence sounds like nonsense, don't worry! We'll explain what all these terms mean:
a, b, s, t) or upper case (i.e.
A, B, S, T). Notes are lower case: { c d e }
is valid input; { C D E } will produce an error message.
{ c d e } means the same thing
as { c d e } and
{
c d
e }
Of course, the previous example is hard to read. A good rule of thumb is to indent code blocks with either a tab or two spaces:
{
c d e
}
A function (such as \relative { } ) also counts as a single
music expression.
%{ and %} is
ignored. 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.
g g f f e e d d c2
%}
There are more tips for constructing input files in Suggestions for writing LilyPond files.
As we saw in Working on text files, LilyPond input must be
surrounded by { } marks or a \relative c'' { ... }. For the
rest of this manual, most examples will omit this.
If you are reading the HTML documentation and wish to see the exact
exact LilyPond code that was used to create the example, simply click
on the picture. If you are not reading the HTML version, you could
copy and paste the displayed input, but you must add the
\relative c'' { } like this:
\relative c'' {
... example goes here...
}
Why omit the braces? Most examples
in this manual can be inserted into the middle of a longer piece of
music. For these examples, it does not make sense to add
\relative c'' { } – you should not place a \relative
inside another \relative, so you would not be able to copy
a small documentation example and paste it inside a longer piece
of your own.
This section introduces common notation that is used for one voice on one staff.
As we saw in Simple notation, LilyPond calculates the pitch of
each note relative to the previous one5. If no extra octave marks
(' and ,) are added, it assumes that each pitch is within
a fourth of the previous note.
LilyPond examines pitches based on the note names – in other words, an augmented fourth is not the same as a diminished fifth. If we begin at a C, then an F-sharp will be placed a higher than the C, while a G-flat will be placed lower than the C.
c2 fis c2 ges
![[image of music]](lily-051c81d70d)
- Relative octaves
- see Relative octaves.
- Octave check
- see Octave check.
A sharp pitch is made by adding `is' to the name, and a flat pitch by adding `es'. As you might expect, a double sharp or double flat is made by adding `isis' or `eses'6
cis1 ees fisis, aeses
![[image of music]](lily-3a1a50098d)
The key signature is set with the command \key followed by
a pitch and \major or \minor.
\key d \major a1 \key c \minor a
![[image of music]](lily-d510e4b363)
To determine whether to print an accidental, LilyPond examines the pitches and the key signature. The key signature only effects the printed accidentals, not the actual pitches! This is a feature that often causes confusion to newcomers, so let us explain it in more detail.
LilyPond makes a sharp distinction between musical content and layout. The alteration (flat, natural or sharp) of a note is part of the pitch, and is therefore musical content. Whether an accidental (a printed flat, natural or sharp sign) is printed in front of the corresponding note is a question of layout. Layout is something that follows rules, so accidentals are printed automatically according to those rules. The pitches in your music are works of art, so they will not be added automatically, and you must enter what you want to hear.
In this example
\key d \major d cis fis
![[image of music]](lily-d6e20e89ed)
No note has a printed accidental, but you must still add the `is' to
cis and fis.
The code `e' does not mean “print a black dot just below the first line of the staff.” Rather, it means: “there is a note with pitch E-natural.” In the key of A-flat major, it does get an accidental:
\key aes \major e
![[image of music]](lily-a5d3d489ad)
Adding all alterations explicitly might require a little more effort when typing, but the advantage is that transposing is easier, and accidentals can be printed according to different conventions. See Automatic accidentals for some examples how accidentals can be printed according to different rules.
- Accidentals
- see Accidentals and Automatic accidentals.
- Key signature
- see Key signature.
A tie is created by appending a tilde `~' to the first note being tied
g4~ g c2~ c4 ~ c8 a8 ~ a2
![[image of music]](lily-683a9f79b7)
A slur is a curve drawn across many notes. The starting note and ending note are marked with `(' and `)' respectively.
d4( c16) cis( d e c cis d) e( d4)
![[image of music]](lily-512dc5b957)
Slurs to indicate longer phrasing can be entered with \( and
\). You can have both legato slurs and phrasing slurs at the
same time, but you cannot have simultaneous slurs or simultaneous
phrasing slurs.
a8(\( ais b c) cis2 b'2 a4 cis,\)
![[image of music]](lily-da214f05a7)
A slur looks like a tie, but it has a different meaning. A tie simply makes the first note longer, and can only be used on pairs of notes with the same pitch. Slurs indicate the articulations of notes, and can be used on larger groups of notes. Slurs and ties can be nested.
c2~( c8 fis fis4 ~ fis2 g2)
![[image of music]](lily-f1ae0cf972)
- Ties
- see Ties.
- Slurs
- see Slurs.
- Phrasing slurs
- see Phrasing slurs.
Common articulations can be added to a note using a dash `-' and a single character:
c-. c-- c-> c-^ c-+ c-_
![[image of music]](lily-36d1871da5)
Similarly, fingering indications can be added to a note using a dash (`-') and the digit to be printed:
c-3 e-5 b-2 a-1
![[image of music]](lily-38a1261696)
Articulations and fingerings are usually placed automatically, but you can specify a direction using `^' (up) or `_' (down). You can also use multiple articulations on the same note. However, in most cases it is best to let LilyPond determine the articulation directions.
c_-^1 d^. f^4_2-> e^-_+
![[image of music]](lily-4346ab001c)
Dynamic signs are made by adding the markings (with a backslash) to the note
c\ff c\mf c\p c\pp
![[image of music]](lily-b6b6c99496)
Crescendi and decrescendi are started with the commands \< and
\>. An ending dynamic, for example \f, will finish the
(de)crescendo, or the command \! can be used
c2\< c2\ff\> c2 c2\!
![[image of music]](lily-f5b66ae68b)
- Articulations
- see Articulations.
- Fingering
- see Fingering instructions.
- Dynamics
- see Dynamics.
All beams are drawn automatically:
a8 ais d ees r d c16 b a8
![[image of music]](lily-252d6c388f)
If you do not like the automatic beams, they may be overridden manually. Mark the first note to be beamed with `[' and the last one with `]'.
a8[ ais] d[ ees r d] a b
![[image of music]](lily-a2a88b6e82)
- Automatic beams
- see Automatic beams.
- Manual beams
- see Manual beams.
A pickup (or anacrusis) is entered with the keyword
\partial. It is followed by a duration: \partial 4 is
a quarter note pickup and \partial 8 an eighth note.
\partial 8 f8 c2 d
![[image of music]](lily-338caa7ff7)
Tuplets are made with the \times keyword. It takes two
arguments: a fraction and a piece of music. The duration of the piece
of music is multiplied by the fraction. Triplets make notes occupy
2/3 of their notated duration, so a triplet has 2/3 as its fraction
\times 2/3 { f8 g a } \times 2/3 { c r c } \times 2/3 { f,8 g16[ a g a] } \times 2/3 { d4 a8 }
![[image of music]](lily-08a5ad555e)
Grace notes are created with the \grace command, although they
can also be created by prefixing a music expression with the
keyword \appoggiatura or \acciaccatura
c2 \grace { a32[ b] } c2 c2 \appoggiatura b16 c2 c2 \acciaccatura b16 c2
![[image of music]](lily-a2cdb49208)
- Grace notes
- see Grace notes,
- Tuplets
- see Tuplets,
- Pickups
- see Partial measures.
This section introduces having more than one note at the same time: multiple instruments, multiple staves for a single instrument (i.e. piano), and chords.
Polyphony in music refers to having more than one voice occurring in a piece of music. Polyphony in LilyPond refers to having more than one voice on the same staff.
In LilyPond input files, music is represented by music expressions. A single note is a music expression, although it is not valid input all on its own.
a4
![[image of music]](lily-04a7421736)
Enclosing a group of notes in braces creates a new music expression:
{ a4 g4 }
![[image of music]](lily-fd88375008)
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:
{ { a4 g } f g }
![[image of music]](lily-3a2bad32e2)
This technique is useful for polyphonic music. To enter music
with more voices or more staves, we combine expressions in
parallel. To indicate that two voices should play at the same time,
simply enter a simultaneous combination of music expressions. A
‘simultaneous’ music expression is formed by enclosing expressions inside
<< and >>. In the following example, three sequences (all
containing two separate notes) are combined simultaneously:
\relative c'' { << { a4 g } { f e } { d b } >> }
![[image of music]](lily-c2b0da726c)
Note that we have indented each level of the input with a different amount of space. LilyPond does not care how much (or little) space there is at the beginning of a line, but indenting LilyPond code like this makes it much easier for humans to read.
Warning: each note is relative to the
previous note in the input, not relative to the c'' in the
initial \relative command.
To determine the number of staves in a piece, LilyPond looks at the first expression. If it is a single note, there is one staff; if there is a simultaneous expression, there is more than one staff.
\relative c'' { c2 <<c e>> << { e f } { c <<b d>> } >> }
![[image of music]](lily-bc7ac93241)
This mechanism is similar to mathematical formulas: a big formula is created by composing small formulas. Such formulas are called expressions, and their definition is recursive so you can make arbitrarily complex and large expressions. For example,
1 1 + 2 (1 + 2) * 3 ((1 + 2) * 3) / (4 * 5)
This is a sequence of expressions, where each expression is contained in the next (larger) one. The simplest expressions are numbers, and larger ones are made by combining expressions with operators (like `+', `*' and `/') and parentheses. Like mathematical expressions, music expressions can be nested arbitrarily deep, which is necessary for complex music like polyphonic scores.
As we saw in Music expressions explained, LilyPond input files are constructed out of music expressions. 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
>>:
\relative c'' { << \new Staff { \clef treble c } \new Staff { \clef bass c,, } >> }
![[image of music]](lily-f8cfae96ca)
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. Score, Staff,
and Voice 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 affects all other staves, but the key signature of one staff does not affect other staves7.
\relative c'' { << \new Staff { \clef treble \time 3/4 c } \new Staff { \clef bass \key d \major c,, } >> }
![[image of music]](lily-3659e8b48b)
Piano music is typeset in two staves connected by a brace. Printing
such a staff is similar to the polyphonic example in Multiple staves,
but now this entire expression is inserted inside a PianoStaff:
\new PianoStaff << \new Staff ... \new Staff ... >>
Here is a small example
\relative c'' { \new PianoStaff << \new Staff { \time 2/4 c4 e g g, } \new Staff { \clef bass c,, c' e c } >> }
![[image of music]](lily-65c1c55eac)
See Piano music.
When different melodic lines are combined on a single staff they are printed as polyphonic voices; each voice has its own stems, slurs and beams, and the top voice has the stems up, while the bottom voice has them down.
Entering such parts is done by entering each voice as a sequence (with
{...}) and combining these simultaneously, separating the
voices with \\
<< { a4 g2 f4~ f4 } \\ { r4 g4 f2 f4 } >>
![[image of music]](lily-66a12bf824)
For polyphonic music typesetting, spacer rests can also be convenient; these are rests that do not print. They are useful for filling up voices that temporarily do not play. Here is the same example with a spacer rest (`s') instead of a normal rest (`r'),
<< { a4 g2 f4~ f4 } \\ { s4 g4 f2 f4 } >>
![[image of music]](lily-652005430e)
Again, these expressions can be nested arbitrarily.
<< \new Staff << { a4 g2 f4~ f4 } \\ { s4 g4 f2 f4 } >> \new Staff << \clef bass { <c g>1 ~ <c g>4 } \\ { e,,4 d e2 ~ e4} >> >>
![[image of music]](lily-d400b3aa90)
See Basic polyphony.
Chords can be made by surrounding pitches with single angle brackets. Angle brackets are the symbols `<' and `>'.
r4 <c e g>4 <c f a>2
![[image of music]](lily-9b4f124e60)
You can combine markings like beams and ties with chords. They must be placed outside the angle brackets
r4 <c e g>8[ <c f a>]~ <c f a>2
![[image of music]](lily-f35e000b20)
r4 <c e g>8\>( <c e g> <c e g>4 <c f a>\!)
![[image of music]](lily-f779e65feb)
This section introduces vocal music and simple song sheets.
\relative c'' { a4 e c8 e r4 b2 c4( d) }
![[image of music]](lily-5df4e73c12)
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 c'' { a4 e c8 e r4 b2 c4( d) } \addlyrics { One day this shall be free } >>
![[image of music]](lily-23138ba05e)
This melody ends on a melisma, a single syllable (‘free’)
sung to more than one note. This is indicated with an extender
line. It is entered as two underscores __:
<< \relative c'' { a4 e c8 e r4 b2 c4( d) } \addlyrics { One day this shall be free __ } >>
![[image of music]](lily-fec9306b85)
Similarly, hyphens between words can be entered as two dashes, resulting in a centered hyphen between two syllables
<< \relative c' { \time 2/4 f4 f c c } \addlyrics { A -- le -- gri -- a } >>
![[image of music]](lily-3f13899bab)
More options, such as putting multiple stanzas below a melody, are discussed in Vocal music.
In popular music it is common to denote accompaniment with chord names. Such chords can be entered like notes,
\chordmode { c2 f4. g8 }
![[image of music]](lily-a60f4c4378)
Now each pitch is read as the root of a chord instead of a note.
This mode is switched on with \chordmode. Other chords can be
created by adding modifiers after a colon. The
following example shows a few common modifiers:
\chordmode { c2 f4:m g4:maj7 gis1:dim7 }
![[image of music]](lily-078cbcd412)
For lead sheets, chords are not printed on staves, but as names on a
line for themselves. This is achieved by using \chords instead
of \chordmode. This uses the same syntax as \chordmode,
but renders the notes in a ChordNames context, with the
following result:
\chords { c2 f4.:m g4.:maj7 gis8:dim7 }
![[image of music]](lily-3518557478)
When put together, chord names, lyrics and a melody form a lead sheet,
<< \chords { c2 g:sus4 f e } \relative c'' { a4 e c8 e r4 b2 c4( d) } \addlyrics { One day this shall be free __ } >>
![[image of music]](lily-4f8639e2b3)
A complete list of modifiers and other options for layout can be found in Chords.
This is the final section of the tutorial; it demonstrates how to add the final touches to simple pieces, and provides an introduction to the rest of the manual.
The \version statement marks for which version of LilyPond the file
was written. To mark a file for version 2.10.1, place
\version "2.10.10"
at the top of your LilyPond file.
These annotations make future upgrades of LilyPond go more
smoothly. Changes in the syntax are handled with a special program,
convert-ly (see Updating files with convert-ly), and it uses
\version to determine what rules to apply.
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.10.10"
\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.
So far we have always used \relative to define pitches. This is
the easiest way to enter most music, but another way of defining pitches
exists: absolute mode.
If you omit the \relative, LilyPond treats all pitches as
absolute values. A c' will always mean middle C, a b will
always mean the note one step below middle C, and a g, will
always mean the note on the bottom staff of the bass clef.
{ \clef bass c' b g, g, g, f, f c' }
![[image of music]](lily-2701888023)
Here is a four-octave scale:
{ \clef bass c, d, e, f, g, a, b, c d e f g a b c' d' \clef treble e' f' g' a' b' c'' d'' e'' f'' g'' a'' b'' c'''1 }
![[image of music]](lily-eb1bd57811)
As you can see, 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 }
![[image of music]](lily-5c9d599b51)
All these quotes makes the input less readable and it is a source of
errors. With \relative, the previous example is much easier
to read:
\relative c'' { \key a \major \time 6/8 cis8. d16 cis8 e4 e8 b8. cis16 b8 d4 d8 }
![[image of music]](lily-14b96a6168)
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 which has large intervals, and is extremely useful for computer-generated LilyPond files.
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 identifiers.
With identifiers (also known as variables or macros), we can break up complex music expressions. An identifier 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). Identifiers
must be defined before the main music expression.
violin = \new Staff { \relative c'' { a4 b c b }} cello = \new Staff { \relative c { \clef bass e2 d }} { << \violin \cello >> }
![[image of music]](lily-99c8ef95a3)
The name of an identifier must have alphabetic characters only: no numbers, underscores, or dashes.
It is possible to use variables for many other types of objects in the input. For example,
width = 4.5\cm
name = "Wendy"
aFivePaper = \paper { paperheight = 21.0 \cm }
Depending on its contents, the identifier can be used in different places. The following example uses the above variables:
\paper {
\aFivePaper
line-width = \width
}
{ c4^\name }
After finishing the tutorial, you should probably try writing a piece or two. Start with one of the Templates and add notes. If you need any notation that was not covered in the tutorial, look at the Notation Reference, starting with Basic notation. If you want to write for an instrument ensemble which is not covered in the templates, take a look at 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 them 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.
As we saw in How to read the tutorial, many examples in the
tutorial omitted a \relative c'' { ... } around the printed
example.
In the rest of the manual, we are much more lax about the
printed examples: sometimes they may have omitted a
\relative c'' { ... }, but in other times a different initial
pitch may be used (such as c' or c,,), and in some cases
the whole example is in absolute note mode! However, ambiguities like
this only exist where the pitches are not important. In any example
where the pitch matters, we have explicitly stated our \relative
our our absolute-mode { }.
If you are still confused about the exact LilyPond input that was used in an example, read the HTML version (if you are not already doing so) and click on the picture of the music. This will display the exact input that LilyPond used to generate this manual.
This chapter discusses general LilyPond concepts and how to
create \score blocks.
You've read the tutorial, you know how to write music. But how can you get the staves that you want? The templates are ok, but what if you want something that isn't covered?
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 “Notes and lyrics” (for the soprano part).
\version "2.10.10"
melody = \relative c' {
\clef treble
\key c \major
\time 4/4
a4 b c d
}
text = \lyricmode {
Aaa Bee Cee Dee
}
\score{
<<
\new Voice = "one" {
\autoBeamOff
\melody
}
\new Lyrics \lyricsto "one" \text
>>
\layout { }
\midi { }
}
Now we want to add a cello part. Let's look at the “Notes only” example:
\version "2.10.10"
melody = \relative c' {
\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 sections. So let's rename them. 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 c' { 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.10.10"
sopranoMusic = \relative c' {
\clef treble
\key c \major
\time 4/4
a4 b c d
}
sopranoLyrics = \lyricmode {
Aaa Bee Cee Dee
}
celloMusic = \relative c {
\clef bass
\key c \major
\time 4/4
d4 g fis8 e d4
}
\score{
<<
\new Voice = "one" {
\autoBeamOff
\sopranoMusic
}
\new Lyrics \lyricsto "one" \sopranoLyrics
>>
\layout { }
\midi { }
}
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, Staff) 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.10.10" sopranoMusic = \relative c' { \clef treble \key c \major \time 4/4 a4 b c d } sopranoLyrics = \lyricmode { Aaa Bee Cee Dee } celloMusic = \relative c { \clef bass \key c \major \time 4/4 d4 g fis8 e d4 } \score{ << << \new Voice = "one" { \autoBeamOff \sopranoMusic } \new Lyrics \lyricsto "one" \sopranoLyrics >> \new Staff \celloMusic >> \layout { } \midi { } }
![[image of music]](lily-accb4c008b)
The LilyPond input format is quite free-form, giving experienced users a lot of flexibility to structure their files however they wish. However, this flexibility can make things confusing for new users. This section will explain some of this structure, but may gloss over some details in favor of simplicity. For a complete description of the input format, see File structure.
Most examples in this manual are little snippets – for example
c4 a b c
As you are (hopefully) aware by now, this will not compile by itself. These examples are shorthand for complete examples. They all need at least curly braces to compile
{
c4 a b c
}
Most examples also make use of the \relative c'
(or c'') command. This is not necessary to merely
compile the examples, but in most cases the output will
look very odd if you omit the \relative c'.
\relative c'' { c4 a b c }
![[image of music]](lily-8fd68340b8)
Now we get to the only real stumbling block: LilyPond input in this form is actually another shorthand. Although it compiles and displays the correct output, it is shorthand for
\score {
\relative c'' {
c4 a b c
}
}
A \score must begin with a single music
expression. Remember that a music expression could
be anything from a single note to a huge
{
\new GrandStaff <<
insert the whole score of a Wagner opera in here
>>
}
Since everything is inside { ... }, it counts
as one music expression.
The \score can contain other things, such as
\score {
{ c'4 a b c' }
\layout { }
\midi { }
\header { }
}
Some people put some of those commands outside the
\score block – for example, \header is
often placed above the \score. That's just
another shorthand that LilyPond accepts.
Another great shorthand is the ability to define variables. All the templates use this
melody = \relative c' {
c4 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
names – it could be melody, global,
pianorighthand, or foofoobarbaz. You
can use whatever variable names you want. For
more details, see
Saving typing with identifiers and functions.
For a complete definition of the input format, see File structure.
In the previous section, How LilyPond files work,
we saw the general organization of LilyPond input
files. 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 must begin with a single music expression.
You may find it useful to review 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.
\score {
{ % this brace begins the overall music expression
\new GrandStaff <<
insert the whole score of a Wagner opera in here
>>
} % this brace ends the overall music expression
\layout { }
}
A whole Wagner opera would easily double the length of
this manual, so let's just do a singer and piano. We
don't need a GrandStaff for this ensemble, so we
shall remove it. We do need a singer and a piano,
though.
\score {
{
<<
\new Staff = "singer" <<
>>
\new PianoStaff = piano <<
>>
>>
}
\layout { }
}
Remember that we use << and >> to show
simultaneous music. And we definitely want to show
the vocal part and piano part at the same time!
\score {
{
<<
\new Staff = "singer" <<
\new Voice = "vocal" { }
>>
\new Lyrics \lyricsto vocal \new Lyrics { }
\new PianoStaff = "piano" <<
\new Staff = "upper" { }
\new Staff = "lower" { }
>>
>>
}
\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).
At this stage, we could start filling in notes. Inside
the curly braces next to \new Voice = vocal,
we could start writing
\relative c'' {
a4 b c d
}
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 identifiers (or
variables) instead.
melody = { }
text = { }
upper = { }
lower = { }
\score {
{
<<
\new Staff = "singer" <<
\new Voice = "vocal" { \melody }
>>
\new Lyrics \lyricsto vocal \new Lyrics { \text }
\new PianoStaff = "piano" <<
\new Staff = "upper" { \upper }
\new Staff = "lower" { \lower }
>>
>>
}
\layout { }
}
Remember that you can use almost any name you like. The limitations on identifier names are detailed in File structure.
When writing a \score section, or when reading
one, just take it slowly and carefully. Start with
the outer layer, then work on each smaller
layer. It also really helps to be strict with
indentation – make sure that each item on the same
layer starts on the same horizontal position in your
text editor!
In orchestral music, all notes are printed twice. Once in a part for the musicians, and once in a full score for the conductor. Identifiers can be used to avoid double work. The music is entered once, and stored in a variable.