GNU LilyPond — Learning Manual

This document is also available as a PDF and as one big page.

This file documents GNU LilyPond for beginners.

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 Learning Manual (LM) for GNU LilyPond version 2.11.61. For more information about how this fits with the other documentation, see About the documentation.

More information can be found at http://www.lilypond.org/. The website contains on-line copies of this and other documentation.

Appendices

Preface

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.

1. Introduction

This chapter introduces readers to LilyPond and the documentation.

1.1 Background

This section covers the overall goals and architecture of LilyPond.

Engraving

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.

Automated engraving

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:

• When LilyPond makes mistakes, users need to override formatting decisions. Therefore, the user must have access to the formatting engine. Hence, rules and settings cannot be fixed by us at compile-time but must be accessible for users at run-time.
• Engraving is a matter of visual judgment, and therefore a matter of taste. As knowledgeable as we are, users can disagree with our personal decisions. Therefore, the definitions of typographical style must also be accessible to the user.
• Finally, we continually refine the formatting algorithms, so we need a flexible approach to rules. The C++ language forces a certain method of grouping rules that do not match well with how music notation works.

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.

What symbols to engrave?

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.

See also

Internals Reference: Contexts.

Music representation

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
}

to create 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

f4

Simultaneous notes can be constructed by enclosing them with << and >>:

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

Example applications

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.

1.2 About the documentation

This section explains the different portions of the documentation.

About the Learning Manual

This book explains how to begin learning LilyPond, as well as explaining some key concepts in easy terms. You should read these chapters in a linear fashion.

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.

• Introduction: explains the background and overall goal of LilyPond.
• Tutorial: gives a gentle introduction to typesetting music. First time users should start here.
• Fundamental concepts: explains some general concepts about the LilyPond file format. If you are not certain where to place a command, read this chapter!
• Tweaking output: shows how to change the default engraving that LilyPond produces.
• Working on LilyPond projects: discusses practical uses of LilyPond and how to avoid some common problems. Read this before undertaking large projects!

The Learning Manual also contains appendices which are not part of the recommended linear reading. They may be useful for later viewing:

• Templates: shows ready-made templates of LilyPond pieces. Just cut and paste a template into a file, add notes, and you’re done!
• Scheme tutorial: presents a short introduction to Scheme, the programming language that music functions use. This is material for advanced tweaks; many users never touch Scheme at all.

About the Music Glossary

Music glossary this explains musical terms, and includes translations to various languages. If you are not familiar with music notation or music terminology (especially if you are a non-native English speaker), it is highly advisable to consult the glossary.

About the Notation Reference

This book explains all the LilyPond commands which produce notation. It assumes that readers are familiar with the concepts in the Learning Manual.

• Musical notation: discusses topics grouped by notation construct. This section gives details about basic notation that will be useful in almost any notation project.
• Specialist notation: discusses topics grouped by notation construct. This section gives details about special notation that will only be useful for particular instrument (or vocal) groups.
• General input and output: discusses general information about LilyPond input files and controlling output.
• Spacing issues: discusses issues which affect the global output, such as selecting paper size or specifying page breaks.
• Changing defaults: explains how to tweak LilyPond to produce exactly the notation you want.
• Interfaces for programmers: explains how to create music functions with scheme.

The Notation Reference also contains appendices with useful reference charts.

• Literature list: contains a set of useful reference books for those who wish to know more on notation and engraving.
• Notation manual tables: are a set of tables showing the chord names, MIDI instruments, a list of color names, and the Feta font.
• Cheat sheet: is a handy reference of the most common LilyPond commands.
• LilyPond command index: an index of all LilyPond \commands.
• LilyPond index: a complete index.

About the Application Usage

This book explains how to execute the programs and how to integrate LilyPond notation with other programs.

• Install: explains how to install LilyPond, including compilation if desired.
• Setup: describes how to configure your computer for optimum LilyPond usage, such as using special environments for certain text editors.
• Running LilyPond: shows how to run LilyPond and its helper programs. In addition, this section explains how to upgrade input files from previous versions of LilyPond.
• LilyPond-book: explains the details behind creating documents with in-line music examples, like this manual.
• Converting from other formats: explains how to run the conversion programs. These programs are supplied with the LilyPond package, and convert a variety of music formats to the .ly format.

About the Snippet List

LilyPond Snippet List: this shows a selected set of LilyPond snippets from the LilyPond Snippet Repository (LSR). All the snippets are in the public domain.

Please note that this document is not an exact subset of LSR. LSR is running a stable LilyPond version, so any snippet which demonstrates new features of a development version must be added separately. These are stored in ‘input/new/’ in the LilyPond source tree.

The list of snippets for each subsection of the Notation Reference are also linked from the See also portion.

About the Internals Reference

Internals Reference: this 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 in the source code.

Almost all formatting functionality that is used internally is available directly to the user. For example, most 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 Reference has a See also subsection, which refers to the generated documentation. In the HTML document, these subsections have clickable links.

Other documentation

There are a number of other sources of information which may be very valuable.

• News: this is a summary of important changes and new features in LilyPond since the previous version.
• The lilypond-user mailist archives: this is a collection of previous emails sent to the user list. Many questions have been asked multiple times; there is a very good chance that if you have a question, the answer might be found in these archives.
• The lilypond-devel mailist archives: this is a collection of previous emails sent to the developer’s list. The discussion here is more technical; if you have an advanced question about lilypond internals, the answer might be in these archives.
• Embedded music fragments: in all HTML documents that have music fragments embedded, the exact LilyPond input that was used to produce that image can be viewed by clicking the image.
• Init files: 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/lsr/dirname/bla.ly’ may refer to the file ‘lilypond2.x.y/input/lsr/dirname/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/’. For more details, see Other sources of information.

2. Tutorial

This tutorial starts with an introduction to the LilyPond music language and explains how to produce printed music. After this first contact we will explain how to create beautiful printed music containing common musical notation.

2.1 First steps

This section gives a basic introduction to working with LilyPond.

2.1.1 Compiling a file

“Compiling” is the term used for processing an input file in LilyPond format to produce a file which can be printed and (optionally) a MIDI file which can be played. LilyPond input files are simple text files. The first example shows what a simple input file looks like.

To create sheet music, we write an input file that specifies the notation. For example, if we write:

{
  c’ e’ g’ e’
}

the result looks like this:

In addition, LilyPond input is case sensitive. { c d e } is valid input; { C D E } will produce an error message.

Entering music and viewing output

In this section we will explain what commands to run and how to view or print the output.

Note that there are several other text editors available with better support for LilyPond. For more information, see Text editor support.

MacOS X

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.

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.

Windows

On Windows, 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 (the file icon looks like a note). 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.

To edit an existing ‘.ly’ file, right-click on it and select “Edit source”. To get an empty file to start from, run the editor as described above and use “New” in the “File” menu, or right-click on the desktop and select “New..Text Document”, change its name to a name of your choice and change the file extension to .ly. Double-click the icon to type in your LilyPond source code as before.

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.

UNIX

Create a text file called ‘test.ly’ and enter:

{
  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.11.61
Processing ‘test.ly’
Parsing...
Interpreting music...
Preprocessing graphical objects...
Finding the ideal number of pages...
Fitting music on 1 page...
Drawing systems...
Layout output to ‘test.ps’...
Converting to ‘test.pdf’...

2.1.2 Simple notation

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

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

Pitches

Music Glossary: pitch, interval, scale, middle C, octave, accidental.

The easiest way to enter notes is by using \relative mode. In this mode, the octave is chosen automatically by assuming the following note is always to be placed closest to the previous note, i.e., it is to be placed in the octave which is within three staff spaces of the previous note. We begin by entering the most elementary piece of music, a scale, in which every note is within just one staff space of the previous note.

% set the starting point to middle C
\relative c' {
  c d e f
  g a b c
}

The initial note is middle C. Each successive note is placed closest to 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, still using only \relative mode:

\relative c' {
  d f a g
  c b f d
}

It is not necessary for the first note of the melody to start on the note which specifies the starting pitch. In the previous example, the first note – the d – is the closest D to middle C.

By adding (or removing) quotes ' or commas , from the \relative c' { command, we can change the starting octave:

% one octave above middle C
\relative c'' {
  e c a c
}

Relative mode can be confusing initially, but is the easiest way to enter most melodies. Let us see how this relative calculation works in practice. Starting from a B, which is on the middle line in a treble clef, you can reach a C, D and E within 3 staff spaces going up, and an A, G and F within 3 staff spaces going down. So if the note following a B is a C, D or E it will be assumed to be above the B, and an A, G or F will be assumed to be below.

\relative c'' {
  b c  % c is 1 staff space up, so is the c above
  b d  % d is 2 up or 5 down, so is the d above
  b e  % e is 3 up or 4 down, so is the e above
  b a  % a is 6 up or 1 down, so is the a below
  b g  % g is 5 up or 2 down, so is the g below
  b f  % f is 4 up or 3 down, so is the f below
}

Exactly the same happens even when any of these notes are sharpened or flattened. Accidentals are totally ignored in the calculation of relative position. Precisely the same staff space counting is done from a note at any other position on the staff.

To add intervals that are larger than three staff spaces, 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'
}

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.

Durations (rhythms)

Music Glossary: beam, duration, whole note, half note, quarter note, dotted note.

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.

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.

\relative c'' {
  a1
  a2 a4 a8 a
  a16 a a a a32 a a a a64 a a a a a a a a2
}

To create dotted notes, add a dot . to the duration number. The duration of a dotted note must be stated explicitly (i.e., with a number).

\relative c'' {
  a a a4. a8
  a8. a16 a a8. a8 a4.
}

Rests

Music Glossary: rest.

A rest is entered just like a note with the name r :

\relative c'' {
  a r r2
  r8 a r4 r4. r8
}

Time signature

Music Glossary: time signature.

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
}

Clef

Music Glossary: clef.

The clef can be set using the \clef command:

\relative c' {
  \clef treble
  c1
  \clef alto
  c1
  \clef tenor
  c1
  \clef bass
  c1
}

All together

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
}

See also

Notation Reference: Writing pitches, Writing rhythms, Writing rests, Time signature, Clef.

2.1.3 Working on input files

LilyPond input files are similar to source files in many common programming languages. They are case sensitive, and white-space 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’ll explain what all these terms mean:

• Case sensitive: it matters whether you enter a letter in lower case (e.g. a, b, s, t) or upper case (e.g. A, B, S, T). Notes are lower case: { c d e } is valid input; { C D E } will produce an error message.
• Whitespace insensitive: it does not matter how many spaces (or new lines) you add. { 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
  }
  

• 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 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.
  
    f f e e d d c2
  %}
  

2.1.4 How to read the manual

LilyPond input must be surrounded by { } marks or a \relative c'' { ... }, as we saw in Working on input files. For the rest of this manual, most examples will omit this. To replicate the examples, you may 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! If we included \relative c'' { } around every example, you would not be able to copy a small documentation example and paste it inside a longer piece of your own. Most people want to add material to an existing piece, so we format the manual this way.

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.

See also

There are more tips for constructing input files in Suggestions for writing LilyPond input files. But it might be best to read through the rest of the tutorial first.

2.2 Single staff notation

This section introduces common notation that is used for one voice on one staff.

2.2.1 Accidentals and key signatures

Accidentals

Music Glossary: sharp, flat, double sharp, double flat, accidental.

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. This syntax is derived from note naming conventions in Nordic and Germanic languages, like German and Dutch. To use other names for accidentals, see Note names in other languages.

cis1 ees fisis, aeses

Key signatures

Music Glossary: key signature, major, minor.

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

Warning: key signatures and pitches

Music Glossary: accidental, key signature, pitch, flat, natural, sharp, transposition.

To determine whether to print an accidental, LilyPond examines the pitches and the key signature. The key signature only affects the printed accidentals, not the note’s pitch! 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 sign 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

No note has a printed accidental, but you must still add is and type cis and fis in the input file.

The code e does not mean “print a black dot just on 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

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. For some examples how accidentals can be printed according to different rules, see Automatic accidentals.

See also

Notation Reference: Note names in other languages, Accidentals, Automatic accidentals, Key signature.

Music Glossary: Pitch names.

2.2.2 Ties and slurs

Ties

Music Glossary: tie.

A tie is created by appending a tilde ~ to the first note being tied.

g4~ g c2~
c4 ~ c8 a8 ~ a2

Slurs

Music Glossary: slur.

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)

Phrasing slurs

Music Glossary: slur, phrasing.

Slurs to indicate longer phrasing can be entered with \( and \). You can have both 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,\)

Warnings: slurs vs. ties

Music Glossary: articulation, slur, tie.

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 articulation of notes, and can be used on larger groups of notes. Slurs and ties can be nested.

c2~( c8 fis fis4 ~ fis2 g2)

See also

Notation Reference: Ties, Slurs, Phrasing slurs.

2.2.3 Articulation and dynamics

Articulations

Music Glossary: articulation.

Common articulations can be added to a note using a dash - and a single character:

c-. c-- c-> c-^ c-+ c-_

Fingerings

Music Glossary: fingering.

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

Articulations and fingerings are usually placed automatically, but you can specify a direction by replacing the dash (-) with ^ (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^-_+

Dynamics

Music Glossary: dynamics, crescendo, decrescendo.

Dynamic signs are made by adding the markings (with a backslash) to the note:

c\ff c\mf c\p c\pp

Crescendi and decrescendi are started with the commands \< and \>. The next dynamics sign, for example \f, will end the (de)crescendo, or the command \! can be used:

c2\< c2\ff\> c2 c2\!

See also

Notation Reference: Articulations and ornamentations, Fingering instructions, Dynamics.

2.2.4 Adding text

Text may be added to your scores:

c1^"espr" a_"legato"

Extra formatting may be added with the \markup command:

c1^\markup{ \bold espr}
a1_\markup{
  \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p
}

See also

Notation Reference: Writing text.

2.2.5 Automatic and manual beams

Music Glossary: beam.

All beams are drawn automatically:

a8 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 ].

a8[ ais] d[ ees r d] a b

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.

\autoBeamOff
a8 c b4 d8. c16 b4
\autoBeamOn
a8 c b4 d8. c16 b4

See also

Notation Reference: Automatic beams, Manual beams.

2.2.6 Advanced rhythmic commands

Partial measure

Music Glossary: anacrusis.

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

Tuplets

Music Glossary: note value, triplet.

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 }

Grace notes

Music Glossary: grace notes, acciaccatura, appoggiatura.

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

See also

Notation Reference: Grace notes, Tuplets, Upbeats.

2.3 Multiple notes at once

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.

2.3.1 Music expressions explained

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

a4

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

{ a4 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:

{ { a4 g } f g }

Analogy: mathematical expressions

This mechanism is similar to mathematical formulas: a big formula is created by composing small formulas. Such formulas are called expressions, and they can contain other expressions, 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.

Simultaneous music expressions: multiple staves

Music Glossary: polyphony.

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

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.

Simultaneous music expressions: single staff

To determine the number of staves in a piece, LilyPond looks at the beginning of the first expression. If 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>> } >>
}

2.3.2 Multiple staves

LilyPond input files are constructed out of music expressions, as we saw in 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 >>:

\relative c'' {
  <<
    \new Staff { \clef treble c }
    \new Staff { \clef bass c,, }
  >>
}

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

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

2.3.3 Staff groups

Music Glossary: brace.

Piano music is typeset in two staves connected by a brace. Printing such a staff is similar to the polyphonic example in Multiple staves. However, 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 }
  >>
}

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 end of every system and also controls the extent of bar lines.

See also

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

2.3.4 Combining notes into chords

Music Glossary: chord.

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

r4 <c e g>4 <c f a>2

Think of chords as almost equivalent to single notes: almost everything you can attach to a single note can be attached to a chord, and everything must go outside the angle brackets. For example, 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
r4 <c e g>8( <c e g>\> <c e g>4 <c f a>\!)

2.3.5 Single staff polyphony

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

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

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

See also

Notation Reference: Simultaneous notes.

2.4 Songs

This section introduces vocal music and simple song sheets.

2.4.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 c'' {
  \key g \major
  \time 6/8
  d4 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 c'' {
    \key g \major
    \time 6/8
    d4 b8 c4 a8 d4 b8 g4
  }
  \addlyrics {
    Girls and boys come out to play,
  }
>>

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

2.4.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 c'' {
    \key g \major
    \time 6/8
    d4 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;
  }
>>

We see 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, for details, see Ties and slurs:

<<
  \relative c'' {
    \key g \major
    \time 6/8
    d4 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, for details, see Automatic and manual beams.

<<
  \relative c'' {
    \key g \major
    \time 6/8
    d4 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, the melismata may be indicated in just the lyrics by using an underscore _ for each note that should be included in the melisma:

<<
  \relative c'' {
    \key g \major
    \time 6/8
    d4 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 __. Here is an example from the first three bars of Dido’s Lament, from Purcell’s Dido and Æneas:

<<
  \relative c'' {
    \key g \minor
    \time 3/2
    g2 a bes bes( a)
    b 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 dashes, resulting in a centered hyphen between the syllables. Here is an example showing this and everything we have learned so far about aligning lyrics to notes.

<<
  \relative c' {
    \key g \major
    \time 3/4
    \partial 4
    d4 g4 g a8( b) g4 g4
    b8( c) d4 d e4 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’s an example from Rossini’s Figaro, where al has to be sung on the same note as the go of Largo in Figaro’s aria Largo al factotum:

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

See also

Notation Reference: Vocal music.

2.4.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 Judas Maccabæus:

<<
  \relative c'' {
    \key f \major
    \time 6/8
    \partial 8
    c8 c([ bes]) a a([ g]) f f'4. b, c4.~ c4
  }
  \addlyrics {
    Let flee -- cy flocks the hills a -- dorn, __
  }
  \relative c' {
    \key f \major
    \time 6/8
    \partial 8
    r8 r4. r4 c8 a'([ g]) f f([ e]) d e([ 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. These are discussed in Organizing pieces with variables.

See also

Notation Reference: Vocal music.

2.5 Final touches

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.

2.5.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 c'' {
    a4 b c b
  }
}
cello = \new Staff {
  \relative c {
    \clef bass
    e2 d
  }
}
{
  <<
    \violin
    \cello
  >>
}

The name of a variable must have alphabetic characters only, no numbers, underscores, or dashes.

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 = \times 2/3 { c,8 e g }
barA = { \tripletA \tripletA \tripletA \tripletA }

\relative c'' {
 \barA \barA
}

Variables may be used 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 variable can be used in different places. The following example uses the above variables:

\paper {
  \aFivePaper
  line-width = \width
}
{
  c4^\name
}

2.5.2 Version number

The \version statement records the version of LilyPond that was used to write the file:

\version "2.11.61"

By convention, this is placed 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, and it uses \version to determine what rules to apply. For details, see Updating files with convert-ly.

2.5.3 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.11.61"
\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.

2.5.4 Absolute note names

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

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
}

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
}

All these quotes makes the input less readable and they are a source of errors. With \relative, the previous example is much easier to read and type:

\relative c'' {
  \key a \major
  \time 6/8
  cis8. 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 which has large intervals, and is extremely useful for computer-generated LilyPond files.

2.5.5 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. 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, 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 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 About the documentation. 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!

3. Fundamental concepts

You’ve seen in the Tutorial how to produce beautifully printed music from a simple text file. This section introduces the concepts and techniques required to produce equally beautiful but more complex scores.

3.1 How LilyPond input files work

The LilyPond input format is quite free-form, giving experienced users a lot of flexibility to structure their files however they wish. But 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.

3.1.1 Introduction to the LilyPond file structure

A basic example of a LilyPond input file is

\version "2.11.61"
\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 has used a \score{} command. This is because LilyPond automatically adds the extra commands which are needed when you give it simple input. LilyPond treats input like this:

\relative c” {
  c4 a d c
}

as shorthand for this:

\book {
  \score {
    \new Staff {
      \new Voice {
        \relative c” {
          c4 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. The way to create contexts explicitly is explained in 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 just one music expression, and this must appear immediately after the \score command. Remember that a music expression could be anything from a single note to a huge compound expression like

{
  \new GrandStaff <<
    ...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 which 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 files.

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.

In summary:

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.

For details see Multiple scores in a book.

Another great shorthand is the ability to define variables. All the templates use