This file documents GNU LilyPond.

Copyright 1999–2006 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”.

GNU LilyPond — The music typesetter

This is the user manual for GNU LilyPond 2.8.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

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

1.1 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. It is printed once using exact mathematical spacing, and once with corrections. Can you spot which fragment is which?

The fragment only uses quarter notes: 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 first two measures are printed with this correction, the last two measures without. The notes in the last two measures form 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.

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

1.3 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

Program reference: Contexts.

1.4 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

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

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.

1.5 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.6 About this manual

The manual is divided into the following chapters:

• The Tutorial gives a gentle introduction to typesetting music. First time users should start here.
• Working on LilyPond projects demonstrates practical uses of LilyPond.
• 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.
• Basic notation discusses topics grouped by notation construct. This section gives details about basic notation that will be useful in almost any notation project.
• Instrument-specific 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.
• Advanced notation discusses topics grouped by notation construct. This section gives details about complicated or unusual notation.
• Changing defaults explains how to fine tune layout.
• Global issues discusses issues which affect the global output, such as selecting paper size or which MIDI instruments to use.
• 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.
• The Literature list contains a set of useful reference books for those who wish to know more on notation and engraving.
• Example templates provides templates of LilyPond pieces. Just cut and paste a template into a file, add notes, and you're done!

Once you are an experienced user, you can use the manual as reference: there is an extensive index¹, 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

• Program reference.

  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.

• Various input examples.

  This collection of files shows various tips and tricks, and is available as a big HTML document, with pictures and explanatory texts included.

• The regression tests.

  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 lilypond-2.8.0/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/.

2 Tutorial

This tutorial starts with a short introduction to the LilyPond music language. After this first contact we will show you how to produce printed output. Then you will be able to create and print your own sheets of music.

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 the full input into a test file, 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 all commands for quick reference.

2.1 First steps

The first example demonstrates how to enter the most elementary piece of music, a scale. A note can be entered by typing its name, from `a' through `g'. So, if you enter

{
c d e f g a b
}

the result looks like this

Every piece of LilyPond input needs to have {curly braces} placed around the input. For the rest of this manual, most examples will omit these braces, but don't forget them in your own music!

In addition, many examples use relative mode. This is explained in Octave entry; for now simply be aware that some examples should be placed inside \relative { ...music... }

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

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

a1 a2 a4 a16 a32

If you do not specify a duration, the duration last entered is used for the next notes. The duration of the first note in input defaults to a quarter

a a8 a a2 a

A rest is entered just like a note, but with the name `r'

r2 r4 r8 r16

Add a dot `.' after the duration to get a dotted note

a2. a4 a8. a16

The (or time signature) can be set with the \time command

\time 3/4
\time 6/8
\time 4/4

The clef can be set using the \clef command

\clef treble
\clef bass
\clef alto
\clef tenor

Remember to enclose the notes and commands in curly braces { ... } to convert it to printable output.

     
     \time 3/4
     \clef bass
     c2 e4 g2.
     f4 e d c2 r4

For more information on

Entering pitches and durations

see Pitches, and Durations.

Clefs

see Clef.

Rests

see Rests.

Time signatures and other timing commands

see Time signature.

2.2 Running LilyPond for the first time

In the last section we explained what kind of things you can enter in a LilyPond file. In this section we will explain what commands to run and how to view or print the output. If you have not used LilyPond before, want to test your setup, or want to run an example file yourself, read this section.

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.

Be warned that the first-ever run will take a minute or two, because all of the system fonts have to be analyzed first.

Windows

On Windows, start up a text-editor² and enter

{ c'4 e' g' }

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.

Unix

Begin by opening a terminal window and starting a text editor. For example, you could open an xterm and execute joe.³ In your text editor, enter the following input and save the file as test.ly

{ c'4 e' g' }

To process test.ly, proceed as follows

lilypond test.ly

You will see something resembling

lilypond test.ly
GNU LilyPond 2.6.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.⁴

2.3 More about pitches

A sharp (#) pitch is made by adding `is' to the name, a flat (b) pitch by adding `es'. As you might expect, a double sharp or double flat is made by adding `isis' or `eses'⁵

cis1 ees fisis aeses

The key signature is set with the command \key, followed by a pitch and \major or \minor

\key d \major
g1
\key c \minor
g

Key signatures together with the pitches (including alterations) are used to determine when to print accidentals. 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 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

no note has an explicit accidental, but you still must enter

\key d \major
d cis fis

The code `d' does not mean `print a black dot just below the staff.' Rather, it means: `a note with pitch D-natural.' In the key of A-flat major, it does get an accidental

     
     \key as \major
     d

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.

For more information on

Accidentals

see Automatic accidentals.

Key signature

see Key signature.

2.4 Entering ties

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

     
     g4~ g a2~ a4

For more information on Ties see Ties.

2.5 Automatic and manual beams

All beams are drawn automatically

     
     a8 ais d es r d

If you do not like where beams are put, they can be entered by hand. Mark the first note to be beamed with `[' and the last one with `]'.

     
     a8[ ais] d[ es r d]

For more information on beams, see Manual beams.

Here are key signatures, accidentals and ties in action

\relative c'' {
  \time 4/4
  \key g \minor
  \clef treble
  r4 r8 a8 gis4 b
  a8 d4.~ d e,8
  fis4 fis8 fis8 eis4 a8 gis~
  gis2 r2
}

There are some interesting points to note in this example. Bar lines and beams are drawn automatically. Line breaks are calculated automatically; it does not matter where the line breaks are in the source file. Finally, the order in which time, key, and clef changes are entered is not relevant: in the printout, these are ordered according to standard notation conventions.

2.6 Octave entry

To raise a note by an octave, add a high quote ' (apostrophe) to the note name, to lower a note one octave, add a `low quote' , (comma). Middle C is c'

     
     c'4 c'' c''' \clef bass c c,

An example of the use of quotes is in the following Mozart fragment

     
     \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 

This example shows that music in a high register needs lots of quotes. This makes the input less readable, and it is a source of errors. The solution is to use `relative octave' mode. This is the most convenient way to copy existing music.

In relative mode, a note without octavation quotes (i.e. the ' or , after a note) is chosen so that it is closest to the previous one. For example, `c f' goes up while `c g' goes down.

To use relative mode, add \relative before the piece of music. The first note is taken relative to the middle C (i.e., c')

     
     \relative {
       c' f c g c
     }

Since most music has small intervals, pieces can be written almost without octavation quotes in relative mode. The previous example is entered as

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

Larger intervals are made by adding octavation quotes.

     
     \relative c {
       c'' f, f c' c g' c,
     }

In summary, quotes or commas no longer determine the absolute height of a note in \relative mode. Rather, the height of a note is relative to the previous one, and changing the octave of a single note shifts all following notes an octave up or down.

For more information on relative octaves see Relative octaves, and Octave check.

2.7 Music expressions explained

In input files, music is represent by so-called music expressions. We have already seen some in the previous examples; a single note is a music expression

     
     a4

Enclosing a group of notes in braces creates a new music expression

     
     { a4 g4 }

Putting a bunch of music expressions (e.g., notes) in braces, means that they should be played in sequence. The result again is a music expression, which can be grouped with other expressions sequentially. Here, the expression from the previous example is combined with two notes

     
     { { a4 g } f g } 

This technique is useful for non-monophonic music. To enter music with more voices or more staves, we also combine expressions in parallel. Two voices that should play at the same time, are entered as a simultaneous combination of two sequences. A `simultaneous' music expression is formed by enclosing expressions in << and >>. In the following example, three sequences (all containing two separate notes) are combined simultaneously

     
     <<
       { a4 g }
       { f e }
       { d b }
     >>

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.

Note that this example only has one staff, whereas the previous example had three separate staves. That is because this example begins with a single note. To determine the number of staves, LilyPond looks at the first element. If it is a single note, there is one staff; if there is a simultaneous expression, there is more than one staff.

     
     {
       c <<c e>>
       << { e f } { c <<b d>> } >>
     }

Music files with deep nesting can be confusing to enter and maintain. One convention that helps against this confusion is indenting. When entering a file with deep nesting of braces and angles, it is customary to use an indent that indicates the nesting level. Formatting music like this eases reading and helps you insert the right number of closing braces at the end of an expression. For example,

<<
  {
    ...
  }
  {
    ...
  }
>>

Some editors have special support for entering LilyPond, and can help indenting source files. See Editor support for more information.

2.8 More staves

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 >>, as demonstrated here

     
     <<
       \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. This ensures that each fragment gets its own stave.

There are several types of contexts. Staff, Voice and Score 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.

We can now typeset a melody with two staves

     
     \relative <<
       \new Staff {
         \time 3/4
         \clef treble 
         
         e'2 d4 c2 b4 a8[ a]
         b[ b] g[ g] a2. 
       }
       \new Staff {
          \clef bass
          c,,2 e4 g2.
          f4 e d c2.
       }
     >>

For more information on contexts see the description in Interpretation contexts.

2.9 Adding articulation marks to notes

Common accents can be added to a note using a dash (`-') and a single character

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

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 using `^' (up) or `_' (down). You can also use multiple articulations on the same note. In most cases, however, it is best to let LilyPond determine the articulation directions.

     
     c_-^1 d^. f^4_2-> e^-_+

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

     
     c\ff c\mf

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\!

A slur is a curve drawn across many notes, and indicates legato articulation. The starting note and ending note are marked with `(' and `)', respectively

     
     d4( c16) cis( d e c cis d) e( d4)

A slur looks like a tie, but it has a different meaning. A tie simply makes the first note sound 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

Slurs to indicate phrasing can be entered with \( and \), so you can have both legato slurs and phrasing slurs at the same time. You cannot have simultaneous slurs or simultaneous phrasing slurs.

     
     a8(\( ais b c) cis2 b'2 a4 cis, c\)

For more information on

Fingering

see Fingering instructions.

Articulations

see Articulations.

Slurs

see Slurs.

Phrasing slurs

see Phrasing slurs.

Dynamics

see Dynamics.

2.10 Combining notes into chords

Chords can be made by surrounding pitches with angle brackets. Angle brackets are the symbols `<' and `>'.

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

You can combine markings like beams and ties with chords. They must be placed outside the angled brackets

     
     r4 <c e g>8[ <c f a>]~ <c f a>

r4 <c e g>8\>( <c e g> <c e g> <c f a>\!)

2.11 Advanced rhythmic commands

A pickup is entered with the keyword \partial. It is followed by a duration: \partial 4 is a quarter note upstep and \partial 8 an eighth note

     
     \partial 8
     f8 c2 d e

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 }

Grace notes are also made by prefixing a music expression with the keyword \appoggiatura or \acciaccatura

     
     c4 \appoggiatura b16 c4
     c4 \acciaccatura b16 c4

For more information on

Grace notes

see Grace notes,

Tuplets

see Tuplets,

Pickups

see Partial measures.

2.12 Commenting input files

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; after % the rest of the line is ignored. A block comment marks a whole section of music input. Anything that is enclosed in %{ 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 is a special statement that is a kind of comment. The \version statement marks for which version of LilyPond the file was written. To mark a file for version 2.6.0, use

\version "2.6.0"

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.

2.13 Printing lyrics

Lyrics are entered by separating each syllable with a space

I want to break free

Consider the melody

     
     \relative {
       r4 c \times 2/3 { f g g }
       \times 2/3 { g4( a2) }
     }

The lyrics can be set to these notes, combining both with the \addlyrics keyword

     
     <<
       \relative {
         r4 c \times 2/3 { f g g }
         \times 2/3 { g4( a2) }
       }
       \addlyrics { I want to break free }
     >>

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, i.e.,

{ I want to break free __ }

Similarly, hyphens between words can be entered as two dashes, resulting in a centered hyphen between two syllables

Twin -- kle twin -- kle

More options, like putting multiple lines of lyrics below a melody are discussed in Vocal music.

2.14 A lead sheet

In popular music, it is common to denote accompaniment with chord names. Such chords can be entered like notes,

     
     \chordmode { c2 f4. g8 }

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 }

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 }

When put together, chord names, lyrics and a melody form a lead sheet, for example,

<<
  \chords { chords }
  the melody
  \addlyrics { the text }
>>
}

A complete list of modifiers and other options for layout can be found in Chords.

2.15 Adding titles

Bibliographic information is entered in a separate block, the \header block. The name of the piece, its composer, etc., are entered as an assignment, within \header { ... }. The \header block is usually put at the top of the file. For example,

\header {
  title = "Miniature"
  composer = "Igor Stravinsky"
}

{ ... }

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

More features of polyphonic typesetting are described in this manual in section Polyphony.

2.17 Piano staves

Piano music is typeset in two staves connected by a brace. Printing such a staff is similar to the polyphonic example in More staves,

<< \new Staff { ... }
   \new Staff { ... } >>

but now this entire expression must be interpreted as a PianoStaff

\new PianoStaff << \new Staff ... >>

Here is a small example

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

More information on formatting piano music is given in Piano music.

2.18 Organizing larger pieces

When all of the elements discussed earlier are combined to produce larger files, the \score blocks get a lot bigger because the music expressions are longer, and, in the case of polyphonic music, more deeply nested. Such large expressions can become unwieldy.

By using variables, also known as identifiers, it is possible to break up complex music expressions. An identifier is assigned as follows

namedMusic = { ... }

The contents of the music expression namedMusic, can be used later by preceding the name with a backslash, i.e., \namedMusic. In the next example, a two-note motive is repeated two times by using variable substitution

     
     seufzer = {
       e'4( dis'4)
     }
     { \seufzer \seufzer }

The name of an identifier should have alphabetic characters only: no numbers, underscores, or dashes. The assignment should be outside of running music.

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 }

More information on the possible uses of identifiers is given in the technical manual, in Input variables and Scheme.

2.19 An orchestral part

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. The contents of that variable is then used to generate both the part and the full score.

It is convenient to define the notes in a special file. For example, suppose that the file horn-music.ly contains the following part of a horn/bassoon duo

hornNotes = \relative c {
  \time 2/4
  r4 f8 a cis4 f e d
}

Then, an individual part is made by putting the following in a file

\include "horn-music.ly"
\header {
  instrument = "Horn in F"
}

{
 \transpose f c' \hornNotes
}

The line

\include "horn-music.ly"

substitutes the contents of horn-music.ly at this position in the file, so hornNotes is defined afterwards. The command \transpose f c' indicates that the argument, being \hornNotes, should be transposed by a fifth upwards. Sounding `f' is denoted by notated c', which corresponds with the tuning of a normal French Horn in F. The transposition can be seen in the following output

In ensemble pieces, one of the voices often does not play for many measures. This is denoted by a special rest, the multi-measure rest. It is entered with a capital `R' followed by a duration (1 for a whole note, 2 for a half note, etc.). By multiplying the duration, longer rests can be constructed. For example, this rest takes 3 measures in 2/4 time

R2*3

When printing the part, multi-rests must be condensed. This is done by setting a run-time variable

\set Score.skipBars = ##t

This command sets the property skipBars in the Score context to true (##t). Prepending the rest and this option to the music above, leads to the following result

The score is made by combining all of the music together. Assuming that the other voice is in bassoonNotes in the file bassoon-music.ly, a score is made with

\include "bassoon-music.ly"
\include "horn-music.ly"

<<
  \new Staff \hornNotes
  \new Staff \bassoonNotes
>>

leading to

More in-depth information on preparing parts and scores can be found in the notation manual; see Orchestral music.

Setting run-time variables (`properties') is discussed in Changing context properties on the fly.

2.20 After the tutorial

After finishing the tutorial, you should probably try writing a piece or two. Start with one of the Example 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 Example 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.

3 Putting it all together

This chapter discusses general LilyPond concepts and how to create \score blocks.

3.1 Extending the templates

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.7.39"
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 { \tempo 4=60 }
}

Now we want to add a cello part. Let's look at the “Notes only” example:

\version "2.7.39"
melody = \relative c' {
  \clef treble
  \key c \major
  \time 4/4

  a4 b c d
}

\score {
\new Staff \melody
\layout { }
\midi { \tempo 4=60 }
}

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.7.39"
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 { \tempo 4=60 }
}

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 { \tempo 4=60 }
}

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.7.39"
     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 { \tempo 4=60 }
     }

3.2 How LilyPond files work

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
     }

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

3.3 Score is a single musical expression

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!

4 Working on LilyPond projects

This section explains a how to solve or avoid certain common problems. If you have programming experience, many of these tips may seem obvious, but it is still advisable to read this chapter.

4.1 Suggestions for writing LilyPond files

Now you're ready to begin writing larger LilyPond files – not just the little examples in the tutorial, but whole pieces. But how should you go about doing it?

The best answer is “however you want to do it.” As long as LilyPond can understand your files and produces the output that you want, it doesn't matter what your files look like. That said, sometimes we make mistakes when writing files. If LilyPond can't understand your files, or produces output that you don't like, how do you fix the problem?

Here are a few suggestions that can help you to avoid or fix problems:

• Include \version numbers in every file. Note that all templates contain a \version "2.8.0" string. We highly recommend that you always include the \version, no matter how small your file is. Speaking from personal experience, it's quite frustrating to try to remember which version of LilyPond you were using a few years ago. convert-ly requires you to declare which version of LilyPond you used.
• Include checks: Bar check and Octave check. If you include checks every so often, then if you make a mistake, you can pinpoint it quicker. How often is “every so often”? It depends on the complexity of the music. For very simple music, perhaps just once or twice. For very complex music, perhaps every bar.
• One bar per line of text. If there is anything complicated, either in the music itself or in the output you desire, it's often good to write only one bar per line. Saving screen space by cramming eight bars per line just isn't worth it if you have to `debug' your files.
• Comment your files. Use either bar numbers (every so often) or references to musical themes (“second theme in violins,” “fourth variation”, etc). You may not need comments when you're writing the piece for the first time, but if you want to go back to change something two or three years later, or if you pass the source over to a friend, it will be much more challenging to determine your intentions or how your file is structured if you didn't comment the file.
• Indent your braces. A lot of problems are caused by an imbalance in the number of { and }.

4.2 Typesetting existing music

If you are entering music from an existing score (i.e., typesetting a piece of existing sheet music),

• Enter one manuscript (the physical copy) system at a time (but still only one bar per line of text), and check each system when you finish it. You may use the showLastLength command to speed up processing – see Skipping corrected music.
• Define mBreak = { \break } and insert \mBreak in the input file whenever the manuscript has a line break. This makes it much easier to compare the LilyPond music to the original music. When you are finished proofreading your score, you may define mBreak = { } to remove all those line breaks. This will allow LilyPond to place line breaks wherever it feels are best.

4.3 Updating old files

The LilyPond input syntax occasionally changes. As LilyPond itself improves, the syntax (input language) is modified accordingly. Sometimes these changes are made to make the input easier to read and write or sometimes the changes are made to accomodate new features of LilyPond.

LilyPond comes with a file that makes this updating easier: convert-ly. For details about how to run this program, see Updating files with convert-ly.

Unforunately, convert-ly cannot handle all input changes. It takes care of simple search-and-replace changes (such as raggedright becoming ragged-right), but some changes are too complicated. The syntax changes that convert-ly cannot handle are listed in Updating files with convert-ly.

For example, in LilyPond 2.4 and earlier, accents and non-English letters were entered using LaTeX – for example, "No\"el" (this would print the French word for `Christmas'). In LilyPond 2.6 and above, the special "ë" must be entered directly into the LilyPond file as an UTF-8 character. convert-ly cannot change all the LaTeX special characters into UTF-8 characters; you must manually update your old LilyPond files.

4.4 Troubleshooting (taking it all apart)

Sooner or later, you will write a file that LilyPond cannot compile. The messages that LilyPond gives may help you find the error, but in many cases you need to do some investigation to determine the source of the problem.

The most powerful tools for this purpose are the single line comment (indicated by %) and the block comment (indicated by %{ ... %}). If you don't know where a problem is, start commenting out huge portions of your input file. After you comment out a section, try compiling the file again. If it works, then the problem must exist in the portion you just commented. If it doesn't work, then keep on commenting out material until you have something that works.

In an extreme case, you might end up with only

\score {
  <<
    % \melody
    % \harmony
    % \bass
  >>
  \layout{}
}

(in other words, a file without any music)

If that happens, don't give up. Uncomment a bit – say, the bass part – and see if it works. If it doesn't work, then comment out all of the bass music (but leave \bass in the \score uncommented.

bass = \relative c' {
%{
  c4 c c c
  d d d d
%}
}

Now start slowly uncommenting more and more of the bass part until you find the problem line.

4.5 Saving typing with identifiers and functions

By this point, you've seen this kind of thing:

     
     hornNotes = \relative c'' { c4 b dis c }
     \score {
       {
         \hornNotes
       }
     }

You may even realize that this could be useful in minimalist music:

     
     fragA = \relative c'' { a4 a8. b16 }
     fragB = \relative c'' { a8. gis16 ees4 }
     violin = \new Staff { \fragA \fragA \fragB \fragA }
     \score {
       {
         \violin
       }
     }

However, you can also use these identifiers (also known as variables, macros, or (user-defined) command) for tweaks:

     
     dolce = \markup{ \italic \bold dolce }
     padText = { \once \override TextScript #'padding = #5.0 }
     fthenp=_\markup{ \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p }
     violin = \relative c'' {
       \repeat volta 2 {
         c4._\dolce b8 a8 g a b |
         \padText
         c4.^"hi there!" d8 e' f g d |
         c,4.\fthenp b8 c4 c-. |
       }
     }
     \score {
       {
         \violin
       }
     \layout{ragged-right=##t}
     }

These identifiers are obviously useful for saving typing. But they're worth considering even if you only use them once – they reduce complexity. Let's look at the previous example without any identifiers. It's a lot harder to read, especially the last line.

violin = \relative c'' {
  \repeat volta 2 {
    c4._\markup{ \italic \bold dolce } b8 a8 g a b |
    \once \override TextScript #'padding = #5.0
    c4.^"hi there!" d8 e' f g d |
    c,4.\markup{ \dynamic f \italic \small { 2nd }
      \hspace #0.1 \dynamic p } b8 c4 c-. |
  }
}

So far we've seen static substitution – when LilyPond sees \padText, it replaces it with the stuff that we've defined it to be (ie the stuff to the right of padtext=).

LilyPond can handle non-static substitution, too (you can think of these as functions).

     
     padText =
     #(define-music-function (parser location padding) (number?)
       #{
         \once \override TextScript #'padding = #$padding
       #})
     
     \relative c''' {
       c4^"piu mosso" b a b
       \padText #1.8
       c4^"piu mosso" d e f
       \padText #2.6
       c4^"piu mosso" fis a g
     }

Using identifiers is also a good way to reduce work if the LilyPond input syntax changes (see Updating old files). If you have a single definition (such as \dolce) for all your files (see Style sheets), then if the syntax changes, you only need to update your single \dolce definition, instead of making changes throughout every .ly file.

4.6 Style sheets

The output that LilyPond produces can be heavily modified; see Tweaking output for details. But what if you have many files that you want to apply your tweaks to? Or what if you simply want to separate your tweaks from the actual music? This is quite easy to do.

Let's look at an example. Don't worry if you don't understand the parts with all the #(). This is explained in Advanced tweaks with Scheme.

     
     mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
       #:line(#:dynamic "mp" #:text #:italic "dolce" )))
     tempoMark = #(define-music-function (parser location markp) (string?)
     #{
       \once \override Score . RehearsalMark #'self-alignment-X = #left
       \once \override Score . RehearsalMark #'no-spacing-rods = ##t
       \mark \markup { \bold $markp }
     #})
     
     \relative c'' {
       \tempo 4=50
       a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
       \tempoMark "Poco piu mosso"
       cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
     }