This file documents GNU LilyPond.

Copyright 1999–2007 by the authors

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections. A copy of the license is included in the section entitled “GNU Free Documentation License”.

GNU LilyPond — The music typesetter

This is the user manual for GNU LilyPond 2.10.x series. (See the bottom of this page for the exact version number).

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

We want to dedicate this program to all the friends that we met through music.

Han-Wen and Jan

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

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.
• Putting it all together explains some general concepts about the lilypond file format. If you are not certain where to place a command, read this chapter!
• Working on LilyPond projects discusses practical uses of LilyPond and how to avoid some common problems.
• Tweaking output shows how to change the default engraving that LilyPond produces.
• 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.
• Non-musical notation discusses non-musical output such as titles, multiple movements, and how to select which MIDI instruments to use.
• Spacing issues discusses issues which affect the global output, such as selecting paper size or specifying page breaks.
• Interfaces for programmers explains how to create music functions.
• 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.
• The Literature list contains a set of useful reference books for those who wish to know more on notation and engraving.
• The Scheme tutorial presents a short introduction to Scheme, the programming language that music functions use.
• Notation manual tables are a set of tables showing the chord names, MIDI instruments, a list of color names, and the Feta font.
• Templates of LilyPond pieces. Just cut and paste a template into a file, add notes, and you're done!
• The Cheat sheet is a handy reference of the most common LilyPond commands.
• The LilyPond command index is an index of all LilyPond \commands.
• The LilyPond index is a complete index.

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 lilypond2.x.y/input/test/bla.ly. On binary packages for the Unix platform, the documentation and examples can typically be found somewhere below /usr/share/doc/lilypond/. Initialization files, for example scm/lily.scm, or ly/engraver-init.ly, are usually found in the directory /usr/share/lilypond/.

Finally, this and all other manuals, are available online both as PDF files and HTML from the web site, which can be found at http://www.lilypond.org/.

2 Tutorial

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

Many people learn programs by trying and fiddling around with the program. This is also possible with LilyPond. If you click on a picture in the HTML version of this manual, you will see the exact LilyPond input that was used to generate that image. Try it on this image

By cutting and pasting everything in the “ly snippet” section, you have a starting template for experiments. If you like learning in this way, you will probably want to print out or bookmark the Cheat sheet, which is a table listing of the most common commands for quick reference.

2.1 First steps

This section gives a basic introduction to working with LilyPond.

2.1.1 Compiling a file

The first example demonstrates how to start working with LilyPond. To create sheet music, we write a text file that specifies the notation. For example, if we write

{
  c' e' g' e'
}

the result looks like this

Warning: Every piece of LilyPond input needs to have { curly braces } placed around the input. The braces should also be surrounded by a space unless they are at the beginning or end of a line to avoid ambiguities. These may be omitted in some examples in this manual, but don't forget them in your own music!

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

Entering music and viewing output

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

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 time you ever run LilyPond, it will take a minute or two because all of the system fonts have to be analyzed first.

For future use of LilyPond, you should begin by selecting "New" or "Open". You must save your file before typesetting it. If any errors occur in processing, please see the log window.

Windows

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

{
  c' e' g' e'
}

Save it on the desktop as test.ly and make sure that it is not called test.ly.TXT. Double clicking test.ly will process the file and show the resulting PDF file. To edit an existing .ly file, right-click on it and select “Edit source”.

If you double-click in the LilyPond icon on the Desktop, it will open a simple text editor with an example file. Save it, for example, to test.ly on your Desktop, and then double-click on the file to process it. After some seconds, you will get a file test.pdf on your desktop. Double-click on this PDF file to view the typeset score. An alternative method to process the test.ly file is to drag and drop it onto the LilyPond icon using your mouse pointer.

Double-clicking the file does not only result in a PDF file, but also produces a .log file that contains some information on what LilyPond has done to the file. If any errors occur, please examine this file.

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

To process test.ly, proceed as follows

lilypond test.ly

You will see something resembling

lilypond test.ly
GNU LilyPond 2.10.0
Processing `test.ly'
Parsing...
Interpreting music... [1]
Preprocessing graphical objects...
Calculating line breaks... [2]
Layout output to `test.ps'...
Converting to `test.pdf'...

The result is the file test.pdf which you can print or view with the standard facilities of your operating system.⁴

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

The easiest way to enter notes is by using \relative mode. In this mode, the interval between the previous note and the current note is assumed to be within a fourth. We begin by entering the most elementary piece of music, a scale.

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

The initial note is middle C. Each successive note is within a fourth of the previous note – in other words, the first `c' is the closest C to middle C. This is followed by the closest D to the previous note. We can create melodies which have larger intervals:

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

As you may notice, this example does not start on middle C. The first note – the `d' – is the closest D to middle C.

To add intervals that are larger than a fourth, we can raise the octave by adding a single quote ' (or apostrophe) to the note name. We can lower the octave by adding a comma , to the note name.

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

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)

The duration of a note is specified by a number after the note name. `1' for a whole note, `2' for a half note, `4' for a quarter note and so on. Beams are added automatically.

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

If you do not specify a duration, the previous duration is used for the next note. The duration of the first note defaults to a quarter.

To create dotted notes, add a dot `.' to the duration number.

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

Rests

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

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

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

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
     }

More information

Entering pitches and durations

see Pitches and Durations.

Rests

see Rests.

Time signatures and other timing commands

see Time signature.

Clefs

see Clef.

2.1.3 Working on text files

LilyPond input files are treated like files in most programming languages: they are case sensitive, white-space insensitive, expressions are formed with curly braces { }, and comments are denoted with % or %{ .. %}.

If the previous sentence sounds like nonsense, don't worry! We'll explain what all these terms mean:

• Case sensitive: it matters whether you enter a letter in lower case (i.e. a, b, s, t) or upper case (i.e. A, B, S, T). Notes are lower case: { c d e } is valid input; { C D E } will produce an error message.
• 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 parenthesis `()' 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 function (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. A block comment marks a whole section of music input as a comment. 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 are more tips for constructing input files in Suggestions for writing LilyPond files.

2.1.4 How to read the tutorial

As we saw in Working on text files, LilyPond input must be surrounded by { } marks or a \relative c'' { ... }. For the rest of this manual, most examples will omit this.

If you are reading the HTML documentation and wish to see the exact exact LilyPond code that was used to create the example, simply click on the picture. If you are not reading the HTML version, you could copy and paste the displayed input, but you must add the \relative c'' { } like this:

\relative c'' {
  ... example goes here...
}

Why omit the braces? Most examples in this manual can be inserted into the middle of a longer piece of music. For these examples, it does not make sense to add \relative c'' { } – you should not place a \relative inside another \relative, so you would not be able to copy a small documentation example and paste it inside a longer piece of your own.

2.2 Single staff notation

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

2.2.1 Relative note names

As we saw in Simple notation, LilyPond calculates the pitch of each note relative to the previous one⁵. If no extra octave marks (' and ,) are added, it assumes that each pitch is within a fourth of the previous note.

LilyPond examines pitches based on the note names – in other words, an augmented fourth is not the same as a diminished fifth. If we begin at a C, then an F-sharp will be placed a higher than the C, while a G-flat will be placed lower than the C.

     
     c2 fis
     c2 ges

More information

Relative octaves

see Relative octaves.

Octave check

see Octave check.

2.2.2 Accidentals and key signatures

Accidentals

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

     
     cis1 ees fisis, aeses

Key signatures

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

To determine whether to print an accidental, LilyPond examines the pitches and the key signature. The key signature only effects the printed accidentals, not the actual pitches! This is a feature that often causes confusion to newcomers, so let us explain it in more detail.

LilyPond makes a sharp distinction between musical content and layout. The alteration (flat, natural or sharp) of a note is part of the pitch, and is therefore musical content. Whether an accidental (a printed flat, natural or sharp sign) is printed in front of the corresponding note is a question of layout. Layout is something that follows rules, so accidentals are printed automatically according to those rules. The pitches in your music are works of art, so they will not be added automatically, and you must enter what you want to hear.

In this example

     
     \key d \major
     d cis fis

No note has a printed accidental, but you must still add the `is' to cis and fis.

The code `e' does not mean “print a black dot just below the first line of the staff.” Rather, it means: “there is a note with pitch E-natural.” In the key of A-flat major, it does get an accidental:

     
     \key aes \major
     e

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.

More information

Accidentals

see Accidentals and Automatic accidentals.

Key signature

see Key signature.

2.2.3 Ties and slurs

Ties

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

     
     g4~ g c2~
     c4 ~ c8 a8 ~ a2

Slurs

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

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

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

Warnings: slurs vs. ties

A slur looks like a tie, but it has a different meaning. A tie simply makes the first note longer, and can only be used on pairs of notes with the same pitch. Slurs indicate the articulations of notes, and can be used on larger groups of notes. Slurs and ties can be nested.

     
     c2~( c8 fis fis4 ~ fis2 g2)

More information

Ties

see Ties.

Slurs

see Slurs.

Phrasing slurs

see Phrasing slurs.

2.2.4 Articulation and dynamics

Articulations

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

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

Fingerings

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. However, in most cases it is best to let LilyPond determine the articulation directions.

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

Dynamics

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 \>. An ending dynamic, for example \f, will finish the (de)crescendo, or the command \! can be used

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

More information

Articulations

see Articulations.

Fingering

see Fingering instructions.

Dynamics

see Dynamics.

2.2.5 Automatic and manual beams

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. Mark the first note to be beamed with `[' and the last one with `]'.

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

More information

Automatic beams

see Automatic beams.

Manual beams

see Manual beams.

2.2.6 Advanced rhythmic commands

Partial measure

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

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

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

More information

Grace notes

see Grace notes,

Tuplets

see Tuplets,

Pickups

see Partial measures.

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, although it is not valid input all on its own.

     
     a4

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

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

Simultaneous music expressions: multiple staves

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.

Warning: each note is relative to the previous note in the input, not relative to the c'' in the initial \relative command.

Simultaneous music expressions: single staff

To determine the number of staves in a piece, LilyPond looks at the first expression. If it is a single note, there is one staff; if there is a simultaneous expression, there is more than one staff.

     
     \relative c'' {
       c2 <<c e>>
       << { e f } { c <<b d>> } >>
     }

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

2.3.2 Multiple staves

As we saw in Music expressions explained, LilyPond input files are constructed out of music expressions. If the score begins with simultaneous music expressions, LilyPond creates multiples staves. However, it is easier to see what happens if we create each staff explicitly.

To print more than one staff, each piece of music that makes up a staff is marked by adding \new Staff before it. These Staff elements are then combined in parallel with << and >>:

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

The command \new introduces a ‘notation context.’ A notation context is an environment in which musical events (like notes or \clef commands) are interpreted. For simple pieces, such notation contexts are created automatically. For more complex pieces, it is best to mark contexts explicitly.

There are several types of contexts. Score, Staff, and Voice handle melodic notation, while Lyrics sets lyric texts and ChordNames prints chord names.

In terms of syntax, prepending \new to a music expression creates a bigger music expression. In this way it resembles the minus sign in mathematics. The formula (4+5) is an expression, so -(4+5) is a bigger expression.

Time signatures entered in one staff affects all other staves, but the key signature of one staff does not affect other staves⁷.

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

2.3.3 Piano staves

Piano music is typeset in two staves connected by a brace. Printing such a staff is similar to the polyphonic example in Multiple staves, but now this entire expression is inserted inside a PianoStaff:

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

Here is a small example

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

More information

See Piano music.

2.3.4 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 information

See Basic polyphony.

2.3.5 Combining notes into chords

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

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

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

This section introduces vocal music and simple song sheets.

2.4.1 Printing lyrics

Consider a simple melody:

     
     \relative c'' {
       a4 e c8 e r4
       b2 c4( d)
     }

The lyrics can be set to these notes, combining both with the \addlyrics keyword. Lyrics are entered by separating each syllable with a space.

     
     <<
       \relative c'' {
         a4 e c8 e r4
         b2 c4( d)
       }
       \addlyrics { One day this shall be free }
     >>

This melody ends on a melisma, a single syllable (‘free’) sung to more than one note. This is indicated with an extender line. It is entered as two underscores __:

     
     <<
       \relative c'' {
         a4 e c8 e r4
         b2 c4( d)
       }
       \addlyrics { One day this shall be free __ }
     >>

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

     
     <<
       \relative c' {
         \time 2/4
         f4 f c c
       }
       \addlyrics { A -- le -- gri -- a }
     >>

More information

More options, such as putting multiple stanzas below a melody, are discussed in Vocal music.

2.4.2 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,

     
     <<
       \chords { c2 g:sus4 f e }
       \relative c'' {
         a4 e c8 e r4
         b2 c4( d)
       }
       \addlyrics { One day this shall be free __ }
     >>

More information

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

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 Version number

The \version statement marks for which version of LilyPond the file was written. To mark a file for version 2.10.1, place

\version "2.10.10"

at the top of your LilyPond file.

These annotations make future upgrades of LilyPond go more smoothly. Changes in the syntax are handled with a special program, convert-ly (see Updating files with convert-ly), and it uses \version to determine what rules to apply.

2.5.2 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.10.10"
\header {
  title = "Symphony"
  composer = "Me"
  opus = "Op. 9"
}

{
  ... music ...
}

When the file is processed, the title and composer are printed above the music. More information on titling can be found in Creating titles.

2.5.3 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 it is a source of errors. With \relative, the previous example is much easier to read:

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

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.4 Organizing pieces with identifiers

When all of the elements discussed earlier are combined to produce larger files, the music expressions get a lot bigger. In polyphonic music with many staves, the input files can become very confusing. We can reduce this confusion by using identifiers.

With identifiers (also known as variables or macros), we can break up complex music expressions. An identifier is assigned as follows

namedMusic = { ... }

The contents of the music expression namedMusic can be used later by placing a backslash in front of the name (\namedMusic, just like a normal LilyPond command). Identifiers must be defined before the main music expression.

     
     violin = \new Staff { \relative c'' {
       a4 b c b
     }}
     cello = \new Staff { \relative c {
       \clef bass
       e2 d
     }}
     {
       <<
         \violin
         \cello
       >>
     }

The name of an identifier must have alphabetic characters only: no numbers, underscores, or dashes.

It is possible to use variables for many other types of objects in the input. For example,

width = 4.5\cm
name = "Wendy"
aFivePaper = \paper { paperheight = 21.0 \cm }

Depending on its contents, the identifier can be used in different places. The following example uses the above variables:

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

2.5.5 After the tutorial

After finishing the tutorial, you should probably try writing a piece or two. Start with one of the Templates and add notes. If you need any notation that was not covered in the tutorial, look at the Notation Reference, starting with Basic notation. If you want to write for an instrument ensemble which is not covered in the templates, take a look at Extending the templates.

Once you have written a few short pieces, read the rest of the Learning Manual (chapters 3-5). There's nothing wrong with reading them now, of course! However, the rest of the Learning Manual assumes that you are familiar with LilyPond input. You may wish to skim these chapters right now, and come back to them after you have more experience.

2.5.6 How to read the manual

As we saw in How to read the tutorial, many examples in the tutorial omitted a \relative c'' { ... } around the printed example.

In the rest of the manual, we are much more lax about the printed examples: sometimes they may have omitted a \relative c'' { ... }, but in other times a different initial pitch may be used (such as c' or c,,), and in some cases the whole example is in absolute note mode! However, ambiguities like this only exist where the pitches are not important. In any example where the pitch matters, we have explicitly stated our \relative our our absolute-mode { }.

If you are still confused about the exact LilyPond input that was used in an example, read the HTML version (if you are not already doing so) and click on the picture of the music. This will display the exact input that LilyPond used to generate this manual.

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.10.10"
melody = \relative c' {
  \clef treble
  \key c \major
  \time 4/4

  a4 b c d
}

text = \lyricmode {
  Aaa Bee Cee Dee
}

\score{
  <<
    \new Voice = "one" {
      \autoBeamOff
      \melody
    }
    \new Lyrics \lyricsto "one" \text
  >>
  \layout { }
  \midi { }
}

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

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

  a4 b c d
}

\score {
\new Staff \melody
\layout { }
\midi { }
}

We don't need two \version commands. We'll need the melody section. We don't want two \score sections – if we had two \scores, we'd get the two parts separately. We want them together, as a duet. Within the \score section, we don't need two \layout or \midi.

If we simply cut and paste the melody section, we would end up with two melody sections. So let's rename them. We'll call the section for the soprano sopranoMusic and the section for the cello celloMusic. While we're doing this, let's rename text to be sopranoLyrics. Remember to rename both instances of all these names – both the initial definition (the melody = relative c' { part) and the name's use (in the \score section).

While we're doing this, let's change the cello part's staff – celli normally use bass clef. We'll also give the cello some different notes.

\version "2.10.10"
sopranoMusic = \relative c' {
  \clef treble
  \key c \major
  \time 4/4

  a4 b c d
}

sopranoLyrics = \lyricmode {
  Aaa Bee Cee Dee
}

celloMusic = \relative c {
  \clef bass
  \key c \major
  \time 4/4

  d4 g fis8 e d4
}

\score{
  <<
    \new Voice = "one" {
      \autoBeamOff
      \sopranoMusic
    }
    \new Lyrics \lyricsto "one" \sopranoLyrics
  >>
  \layout { }
  \midi { }
}

This is looking promising, but the cello part won't appear in the score – we haven't used it in the \score section. If we want the cello part to appear under the soprano part, we need to add

\new Staff \celloMusic

underneath the soprano stuff. We also need to add << and >> around the music – that tells LilyPond that there's more than one thing (in this case, Staff) happening at once. The \score looks like this now

\score{
  <<
    <<
      \new Voice = "one" {
        \autoBeamOff
        \sopranoMusic
      }
      \new Lyrics \lyricsto "one" \sopranoLyrics
    >>
    \new Staff \celloMusic
  >>
  \layout { }
  \midi { }
}

This looks a bit messy; the indentation is messed up now. That is easily fixed. Here's the complete soprano and cello template.

     
     \version "2.10.10"
     sopranoMusic = \relative c' {
       \clef treble
       \key c \major
       \time 4/4
     
       a4 b c d
     }
     
     sopranoLyrics = \lyricmode {
       Aaa Bee Cee Dee
     }
     
     celloMusic = \relative c {
       \clef bass
       \key c \major
       \time 4/4
     
       d4 g fis8 e d4
     }
     
     \score{
       <<
         <<
           \new Voice = "one" {
             \autoBeamOff
             \sopranoMusic
           }
           \new Lyrics \lyricsto "one" \sopranoLyrics
         >>
         \new Staff \celloMusic
       >>
       \layout { }
       \midi { }
     }

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

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

4 Working on LilyPond projects

This section explains 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?

As long as LilyPond can understand your files and produces the output that you want, it doesn't matter what your files look like. However, there are a few other things to consider when writing lilypond files.

• What if you make a mistake? The structure of a lilypond file can make certain errors easier (or harder) to find.
• What if you want to share your files with somebody else? In fact, what if you want to alter your own files in a few years? Some lilypond files are understandable at first glance; other files may leave you scratching your head for an hour.
• What if you want to upgrade your lilypond file for use with a later version of lilypond? The input syntax changes occasionally as lilypond improves. Most changes can be done automatically with convert-ly, but some changes might require manual assistance. Lilypond files can be structured in order to be easier (or header) to update.

4.1.1 General suggestions

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.10.10" 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, Octave check and Barnumber 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 }.
• Explicity add durations at the beginnings of sections and identifiers. If you specify c4 d e at the beginning of a phrase (instead of just c d e) you can save yourself some problems if you rearrange your music later.
• Separate tweaks from music definitions. See Saving typing with identifiers and functions and Style sheets.

4.1.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.1.3 Large projects

When working on a large project, having a clear structure to your lilypond files becomes vital.

• Use an identifier for each voice, with a minimum of structure inside the definition. The structure of the \score section is the most likely thing to change; the violin definition is extremely unlikely to change in a new version of LilyPond.

       violin = \relative c'' {
       g4 c'8. e16
       }
       ...
       \score {
         \new GrandStaff {
           \new Staff {
             \violin
           }
         }
       }
  

• Separate tweaks from music definitions. This point was made in General suggestions, but for large projects it is absolutely vital. We might need to change the definition of fthenp, but then we only need to do this once, and we can still avoid touching anything inside violin.

       fthenp = _\markup{
         \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p }
       violin = \relative c'' {
       g4\fthenp c'8. e16
       }
  

4.2 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.3 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
     }

There are some problems with overlapping output; we'll fix those using the techniques in Moving objects. But let's also do something about the mpdolce and tempoMark definitions. They produce the output we desire, but we might want to use them in another piece. We could simply copy-and-paste them at the top of every file, but that's an annoyance. It also leaves those definitions in our music files, and I personally find all the #() somewhat ugly. Let's hide them in another file:

%%% save this to a file called "definitions.ly"
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 }
#})

Now let's modify our music (let's save this file as "music.ly").

\include "definitions.ly"

\relative c'' {
  \tempo 4=50
  a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
  \once \override Score.RehearsalMark #'padding = #2.0
  \tempoMark "Poco piu mosso"
  cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
}

That looks better, but let's make a few changes. The glissando is hard to see, so let's make it thicker and closer to the noteheads. Let's put the metronome marking above the clef, instead of over the first note. And finally, my composition professor hates "C" time signatures, so we'd better make that "4/4" instead.

Don't change music.ly, though. Replace our definitions.ly with this:

%%%  definitions.ly
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 }
#})

\layout{
  \context { \Score
    \override MetronomeMark #'extra-offset = #'(-9 . 0)
    \override MetronomeMark #'padding = #'3
  }
  \context { \Staff
    \override TimeSignature #'style = #'numbered
  }
  \context { \Voice
    \override Glissando #'thickness = #3
    \override Glissando #'gap = #0.1
  }
}

That looks nicer! But now suppose that I want to publish this piece. My composition professor doesn't like "C" time signatures, but I'm somewhat fond of them. Let's copy the current definitions.ly to web-publish.ly and modify that. Since this music is aimed at producing a pdf which will be displayed on the screen, we'll also increase the overall size of the output.

%%%  definitions.ly
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 }
#})

#(set-global-staff-size 23)
\layout{
  \context { \Score
    \override MetronomeMark #'extra-offset = #'(-9 . 0)
    \override MetronomeMark #'padding = #'3
  }
  \context { \Staff
  }
  \context { \Voice
    \override Glissando #'thickness = #3
    \override Glissando #'gap = #0.1
  }
}

Now in our music, I simply replace \include "definitions.ly" with \include "web-publish.ly". Of course, we could make this even more convenient. We could make a definitions.ly file which contains only the definitions of mpdolce and tempoMark, a web-publish.ly file which contains only the \layout section listed above, and a university.ly file which contains only the tweaks to produce the output that my professor prefers. The top of music.ly would then look like this:

\include "definitions.ly"

%%%  Only uncomment one of these two lines!
\include "web-publish.ly"
%\include "university.ly"

This approach can be useful even if you are only producing one set of parts. I use half a dozen different “style sheet” files for my projects. I begin every music file with \include "../global.ly", which contains

%%%   global.ly
\version "2.10.10"
#(ly:set-option 'point-and-click #f)
\include "../init/init-defs.ly"
\include "../init/init-layout.ly"
\include "../init/init-headers.ly"
\include "../init/init-paper.ly"

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

Unfortunately, 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.5 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.

Another very useful debugging technique is constructing Minimal examples.

4.6 Minimal examples

A minimal example is an example which is as small as possible. These examples are much easier to understand than long examples. Minimal examples are used for

• Bug reports
• Sending a help request to mailists
• Adding an example to the LilyPond Snippet Repository

To construct an example which is as small as possible, the rule is quite simple: remove anything which is not necessary. When trying to remove unnecessary parts of a file, it is a very good idea to comment out lines instead of deleting them. That way, if you discover that you actually do need some lines, you can uncomment them, instead of typing them in from scratch.

There are two exceptions to the “as small as possible” rule:

• Include the \version number.
• If possible, use \paper{ ragged-right=##t } at the top of your example.

The whole point of a minimal example is to make it easy to read:

• Avoid using complicated notes, keys, or time signatures, unless you wish to demonstrate something is about the behavior of those items.
• Do not use \override commands unless that is the point of the example.

5 Tweaking output

This chapter discusses how to modify output. LilyPond is extremely configurable; virtually every fragment of output may be changed.

5.1 Moving objects

This may come as a surprise, but LilyPond is not perfect. Some notation elements can overlap. This is unfortunate, but (in most cases) is easily solved.

     
     e4^\markup{ \italic ritenuto } g b e

The easiest solution is to increase the distance between the object (in this case text, but it could easily be fingerings or dynamics instead) and the note. In LilyPond, this is called the padding property; it is measured in staff spaces. For most objects, this value is around 1.0 or less (it varies with each object). We want to increase it, so let's try 1.5

     
     \once \override TextScript #'padding = #1.5
     e4^\markup{ \italic ritenuto } g b e

That looks better, but it isn't quite big enough. After experimenting with a few values, we think 2.3 is the best number in this case. However, this number is merely the result of experimentation and my personal taste in notation. Try the above example with 2.3... but also try higher (and lower) numbers. Which do you think looks the best?

The staff-padding property is closely related. padding controls the minimum amount of space between an object and the nearest other object (generally the note or the staff lines); staff-padding controls the minimum amount of space between an object and the staff. This is a subtle difference, but you can see the behavior here.

     
     c4^"piu mosso" b a b
     \once \override TextScript #'padding = #2.6
     c4^"piu mosso" d e f
     \once \override TextScript #'staff-padding = #2.6
     c4^"piu mosso" fis a g
     \break
     c'4^"piu mosso" b a b
     \once \override TextScript #'padding = #2.6
     c4^"piu mosso" d e f
     \once \override TextScript #'staff-padding = #2.6
     c4^"piu mosso" fis a g

Another solution gives us complete control over placing the object – we can move it horizontally or vertically. This is done with the extra-offset property. It is slightly more complicated and can cause other problems. When we move objects with extra-offset, the movement is done after LilyPond has placed all other objects. This means that the result can overlap with other objects.

     
     \once \override TextScript #'extra-offset = #'( 1.0 . -1.0 )
     e4^\markup{ \italic ritenuto } g b e

With extra-offset, the first number controls the horizontal movement (left is negative); the second number controls the vertical movement (up is positive). After a bit of experimenting, we decided that these values look good

     
     \once \override TextScript #'extra-offset = #'( -1.6 . 1.0 )
     e4^\markup{ \italic ritenuto } g b e

Again, these numbers are simply the result of a few experiments and looking at the output. You might prefer the text to be slightly higher, or to the left, or whatever. Try it and look at the result!

One final warning: in this section, we used

\once \override TextScript ...

This tweaks the display of text for the next note. If the note has no text, this tweak does nothing (and does not wait until the next bit of text). To change the behavior of everything after the command, omit the \once. To stop this tweak, use a \revert. This is explained in depth in The \override command.

     
     c4^"piu mosso" b
     \once \override TextScript #'padding = #2.6
       a4 b
     c4^"piu mosso" d e f
     \once \override TextScript #'padding = #2.6
     c4^"piu mosso" d e f
     c4^"piu mosso" d e f
     \break
     \override TextScript #'padding = #2.6
     c4^"piu mosso" d e f
     c4^"piu mosso" d e f
     \revert TextScript #'padding
     c4^"piu mosso" d e f

See also

This manual: The \override command, Common tweaks.

5.2 Fixing overlapping notation

In Moving objects, we saw how to move a TextScript object. The same mechanism can be used to move other types of objects; simply replace TextScript with the name of another object.

To find the object name, look at the “see also” at bottom of the relevant documentation page. For example, at the bottom of Dynamics, we see

See also

Program reference: DynamicText, Hairpin. Vertical positioning of these symbols is handled by DynamicLineSpanner.

So to move dynamics around vertically, we use

\override DynamicLineSpanner #'padding = #2.0

We cannot list every object, but here is a list of the most common objects.

Object type	Object name
Dynamics (vertically)	DynamicLineSpanner
Dynamics (horizontally)	DynamicText
Ties	Tie
Slurs	Slur
Articulations	Script
Fingerings	Fingering
Text e.g. ^"text"	TextScript
Rehearsal / Text marks	RehearsalMark

5.3 Common tweaks

Some overrides are so common that predefined commands are provided as short-cuts, such as \slurUp and \stemDown. These commands are described in the Notation Reference under the appropriate sections.

The complete list of modifications available for each type of object (like slurs or beams) are documented in the Program Reference. However, many layout objects share properties which can be used to apply generic tweaks.

• The padding property can be set to increase (or decrease) the distance between symbols that are printed above or below notes. This applies to all objects with side-position-interface.

            
            c2\fermata
            \override Script #'padding = #3
            b2\fermata
       

  

            
            % This will not work, see below:
            \override MetronomeMark #'padding = #3
            \tempo 4=120
            c1
            % This works:
            \override Score.MetronomeMark #'padding = #3
            \tempo 4=80
            d1
       

  

  Note in the second example how important it is to figure out what context handles a certain object. Since the MetronomeMark object is handled in the Score context, property changes in the Voice context will not be noticed. For more details, see Constructing a tweak.

• The extra-offset property moves objects around in the output; it requires a pair of numbers. The first number controls horizontal movement; a positive number will move the object to the right. The second number controls vertical movement; a positive number will move it higher. The extra-offset property is a low-level feature: the formatting engine is completely oblivious to these offsets.

  In the following example, the second fingering is moved a little to the left, and 1.8 staff space downwards:

            
            \stemUp
            f-5
            \once \override Fingering
                #'extra-offset = #'(-0.3 . -1.8)
            f-5
       

  

• Setting the transparent property will cause an object to be printed in ‘invisible ink’: the object is not printed, but all its other behavior is retained. The object still takes up space, it takes part in collisions, and slurs, ties, and beams can be attached to it.

  The following example demonstrates how to connect different voices using ties. Normally, ties only connect two notes in the same voice. By introducing a tie in a different voice,

  

  and blanking the first up-stem in that voice, the tie appears to cross voices:

            
            << {
              \once \override Stem #'transparent = ##t
              b8~ b8\noBeam
            } \\ {
              b[ g8]
            } >>
       

  

  To make sure that the just blanked stem doesn't squeeze the too much tie, we also lengthen the stem, by setting the length to 8,

            
            << {
              \once \override Stem #'transparent = ##t
              \once \override Stem #'length = #8
              b8~ b8\noBeam
            } \\ {
              b[ g8]
            } >>
       

  

Distances in LilyPond are measured in staff-spaces, while most thickness properties are measured in line-thickness. Some properties are different; for example, the thickness of beams are measured in staff-spaces. For more information, see the relevant portion of the program reference.

5.4 Default files

The Program Reference documentation contains a lot of information about LilyPond, but even more information can be gathered from looking at the internal LilyPond files.

Some default settings (such as the definitions for \header{}s) are stored as .ly files. Other settings (such as the definitions of markup commands) are stored as .scm (Scheme) files. Further explanation is outside the scope of this manual; users should be warned that a substantial amount of technical knowledge or time is required to understand these files.

• Linux: installdir/lilypond/usr/share/lilypond/current/
• OSX: installdir/LilyPond.app/Contents/Resources/share/lilypond/current/. To access this, either cd into this directory from the Terminal, or control-click on the LilyPond application and select "Show Package Contents".
• Windows: installdir/LilyPond/usr/share/lilypond/current/

The ly/ and scm/ directories will be of particular interest. Files such as ly/property-init.ly and ly/declarations-init.ly define all the common tweaks.

5.5 Fitting music onto fewer pages

Sometimes you can end up with one or two staves on a second (or third, or fourth...) page. This is annoying, especially if you look at previous pages and it looks like there is plenty of room left on those.

When investigating layout issues, annotate-spacing is an invaluable tool. This command prints the values of various layout spacing commands; see Displaying spacing for more details. From the output of annotate-spacing, we can see which margins we may wish to alter.

Other than margins, there are a few other options to save space:

• You may tell LilyPond to place systems as close together as possible (to fit as many systems as possible onto a page), but then to space those systems out so that there is no blank space at the bottom of the page.

       \paper {
         between-system-padding = #0.1
         between-system-space = #0.1
         ragged-last-bottom = ##f
         ragged-bottom = ##f
       }
  

• You may force the number of systems (i.e., if LilyPond wants to typeset some music with 11 systems, you could force it to use 10).

       \paper {
         system-count = #10
       }
  

• Avoid (or reduce) objects which increase the vertical size of a system. For example, volta repeats (or alternate repeats) require extra space. If these repeats are spread over two systems, they will take up more space than one system with the volta repeats and another system without.

  Another example is moving dynamics which “stick out” of a system.

            
            \relative c' {
              e4 c g\f c
              \override DynamicLineSpanner #'padding = #-1.8
              \override DynamicText #'extra-offset = #'( -2.1 . 0)
              e4 c g\f c
            }
       

  

• Alter the horizontal spacing via SpacingSpanner. See Changing horizontal spacing for more details.

            
            \score {
              \relative c'' {
                g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
                g4 e e2 | f4 d d2 | c4 e g g | c,1 |
                d4 d d d | d4 e f2 | e4 e e e | e4 f g2 |
                g4 e e2 | f4 d d2 | c4 e g g | c,1 |
              }
              \layout {
                \context {
                  \Score
                  \override SpacingSpanner
                            #'base-shortest-duration = #(ly:make-moment 1 4)
                }
              }
            }
       

  

5.6 Advanced tweaks with Scheme

We have seen how LilyPond output can be heavily modified using commands like \override TextScript #'extra-offset = ( 1 . -1). But we have even more power if we use Scheme. For a full explantion of this, see the Scheme tutorial and Interfaces for programmers.

We can use Scheme to simply \override commands,

     
     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
     }

We can use it to create new commands,

     
     tempoMark = #(define-music-function (parser location padding marktext)
                                         (number? string?)
     #{
       \once \override Score . RehearsalMark #'padding = $padding
       \once \override Score . RehearsalMark #'no-spacing-rods = ##t
       \mark \markup { \bold $marktext }
     #})
     
     \relative c'' {
       c2 e
       \tempoMark #3.0 #"Allegro"
       g c
     }

Even music expressions can be passed in.

     
     pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
     #{
       $x e8 a b $y b a e
     #})
     
     \relative c''{
       \pattern c8 c8\f
       \pattern {d16 dis} { ais16-> b\p }
     }

5.7 Avoiding tweaks with slower processing

LilyPond can perform extra checks while it processes files. These commands will take extra time, but the result may require fewer manual tweaks.

%%  makes sure text scripts and lyrics are within the paper margins
\override Score.PaperColumn #'keep-inside-line = ##t

6 Basic notation

This chapter explains how to use basic notation features.

6.1 Pitches

This section discusses how to specify the pitch of notes.

6.1.1 Normal pitches

A pitch name is specified using lowercase letters a through g. An ascending C-major scale is engraved with

     
     \clef bass
     c d e f g a b c'

The note name c is engraved one octave below middle C.

     
     \clef treble
     c1
     \clef bass
     c1

The optional octave specification takes the form of a series of single quote (`'') characters or a series of comma (`,') characters. Each ' raises the pitch by one octave; each , lowers the pitch by an octave.

     
     \clef treble
     c' c'' e' g d'' d' d c
     \clef bass
     c, c,, e, g d,, d, d c

An alternate method may be used to declare which octave to engrave a pitch; this method does not require as many octave specifications (' and ,). See Relative octaves.

6.1.2 Accidentals

A sharp is formed by adding -is to the end of a pitch name and a flat is formed by adding -es. Double sharps and double flats are obtained by adding -isis or -eses to a note name.

     
     a2 ais a aes
     a2 aisis a aeses

These are the Dutch note names. In Dutch, aes is contracted to as, but both forms are accepted. Similarly, both es and ees are accepted

     
     a2 as e es

A natural will cancel the effect of an accidental or key signature. However, naturals are not encoded into the note name syntax with a suffix; a natural pitch is shown as a simple note name

     
     a4 aes a2

The input d e f is interpreted as “print a D-natural, E-natural, and an F-natural,” regardless of the key signature. For more information about the distinction between musical content and the presentation of that content, see Accidentals and key signatures.

     
     \key d \major
     d e f g
     d e fis g

Commonly tweaked properties

In accordance with standard typesetting rules, a natural sign is printed before a sharp or flat if a previous accidental needs to be cancelled. To change this behavior, use \set Staff.extraNatural = ##f

     
     ceses4 ces cis c
     \set Staff.extraNatural = ##f
     ceses4 ces cis c

See also

Program reference: LedgerLineSpanner, NoteHead.

6.1.3 Cautionary accidentals

Normally accidentals are printed automatically, but you may also print them manually. A reminder accidental can be forced by adding an exclamation mark ! after the pitch. A cautionary accidental (i.e., an accidental within parentheses) can be obtained by adding the question mark `?' after the pitch. These extra accidentals can be used to produce natural signs, too.

     
     cis cis cis! cis? c c? c! c

See also

The automatic production of accidentals can be tuned in many ways. For more information, see Automatic accidentals.

6.1.4 Micro tones

Half-flats and half-sharps are formed by adding -eh and -ih; the following is a series of Cs with increasing pitches

     
     \set Staff.extraNatural = ##f
     ceseh ceh cih cisih

Micro tones are also exported to the MIDI file.

Bugs

There are no generally accepted standards for denoting three-quarter flats, so LilyPond's symbol does not conform to any standard.

6.1.5 Note names in other languages

There are predefined sets of note names for various other languages. To use them, include the language specific init file. For example, add \include "english.ly" to the top of the input file. The available language files and the note names they define are

                        Note Names               sharp       flat
nederlands.ly  c   d   e   f   g   a   bes b   -is         -es
english.ly     c   d   e   f   g   a   bf  b   -s/-sharp   -f/-flat
                                               -x (double)
deutsch.ly     c   d   e   f   g   a   b   h   -is         -es
norsk.ly       c   d   e   f   g   a   b   h   -iss/-is    -ess/-es
svenska.ly     c   d   e   f   g   a   b   h   -iss        -ess
italiano.ly    do  re  mi  fa  sol la  sib si  -d          -b
catalan.ly     do  re  mi  fa  sol la  sib si  -d/-s       -b
espanol.ly     do  re  mi  fa  sol la  sib si  -s          -b

6.1.6 Relative octaves

Octaves are specified by adding ' and , to pitch names. When you copy existing music, it is easy to accidentally put a pitch in the wrong octave and hard to find such an error. The relative octave mode prevents these errors by making the mistakes much larger: a single error puts the rest of the piece off by one octave

\relative startpitch musicexpr

or

\relative musicexpr

c' is used as the default if no starting pitch is defined.

The octave of notes that appear in musicexpr are calculated as follows: if no octave changing marks are used, the basic interval between this and the last note is always taken to be a fourth or less. This distance is determined without regarding alterations; a fisis following a ceses will be put above the ceses. In other words, a doubly-augmented fourth is considered a smaller interval than a diminished fifth, even though the doubly-augmented fourth spans seven semitones while the diminished fifth only spans six semitones.

The octave changing marks ' and , can be added to raise or lower the pitch by an extra octave. Upon entering relative mode, an absolute starting pitch can be specified that will act as the predecessor of the first note of musicexpr. If no starting pitch is specified, then middle C is used as a start.

Here is the relative mode shown in action

     
     \relative c'' {
       b c d c b c bes a
     }

Octave changing marks are used for intervals greater than a fourth

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

If the preceding item is a chord, the first note of the chord is used to determine the first note of the next chord

     
     \relative c' {
       c <c e g>
       <c' e g>
       <c, e' g>
     }

The pitch after \relative contains a note name.

The relative conversion will not affect \transpose, \chordmode or \relative sections in its argument. To use relative within transposed music, an additional \relative must be placed inside \transpose.

6.1.7 Octave check

Octave checks make octave errors easier to correct: a note may be followed by =quotes which indicates what its absolute octave should be. In the following example,

\relative c'' { c='' b=' d,='' }

the d will generate a warning, because a d'' is expected (because b' to d'' is only a third), but a d' is found. In the output, the octave is corrected to be a d'' and the next note is calculated relative to d'' instead of d'.

There is also an octave check that produces no visible output. The syntax

\octave pitch

This checks that pitch (without quotes) yields pitch (with quotes) in \relative mode compared to the note given in the \relative command. If not, a warning is printed, and the octave is corrected. The pitch is not printed as a note.

In the example below, the first check passes without incident, since the e (in relative mode) is within a fifth of a'. However, the second check produces a warning, since the e is not within a fifth of b'. The warning message is printed, and the octave is adjusted so that the following notes are in the correct octave once again.

\relative c' {
  e
  \octave a'
  \octave b'
}

The octave of a note following an octave check is determined with respect to the note preceding it. In the next fragment, the last note is an a', above middle C. That means that the \octave check passes successfully, so the check could be deleted without changing the output of the piece.

     
     \relative c' {
       e
       \octave b
       a
     }

6.1.8 Transpose

A music expression can be transposed with \transpose. The syntax is

\transpose from to musicexpr

This means that musicexpr is transposed by the interval between the pitches from and to: any note with pitch from is changed to to.

For example, consider a piece written in the key of D-major. If this piece is a little too low for its performer, it can be transposed up to E-major with

\transpose d e ...

Consider a part written for violin (a C instrument). If this part is to be played on the A clarinet (for which an A is notated as a C, and which sounds a minor third lower than notated), the following transposition will produce the appropriate part

\transpose a c ...

\transpose distinguishes between enharmonic pitches: both \transpose c cis or \transpose c des will transpose up half a tone. The first version will print sharps and the second version will print flats

     
     mus = { \key d \major cis d fis g }
     \new Staff {
       \clef "F" \mus
       \clef "G"
       \transpose c g' \mus
       \transpose c f' \mus
     }

\transpose may also be used to input written notes for a transposing instrument. Pitches are normally entered into LilyPond in C (or “concert pitch”), but they may be entered in another key. For example, when entering music for a B-flat trumpet which begins on concert D, one would write

\transpose c bes { e4 ... }

To print this music in B-flat again (i.e., producing a trumpet part, instead of a concert pitch conductor's score) you would wrap the existing music with another transpose

\transpose bes c { \transpose c bes { e4 ... } }

See also

Program reference: TransposedMusic.

Example: input/test/smart-transpose.ly.

Bugs

If you want to use both \transpose and \relative, you must put \transpose outside of \relative, since \relative will have no effect on music that appears inside a \transpose.

6.1.9 Rests

Rests are entered like notes with the note name r

     
     r1 r2 r4 r8

Whole bar rests, centered in middle of the bar, must be done with multi-measure rests. They can be used for a single bar as well as many bars, and are discussed in Multi measure rests.

To explicitly specify a rest's vertical position, write a note followed by \rest. A rest will be placed in the position where the note would appear,

     
     a'4\rest d'4\rest

This makes manual formatting of polyphonic music much easier, since the automatic rest collision formatter will leave these rests alone.

See also

Program reference: Rest.

6.1.10 Skips

An invisible rest (also called a ‘skip’) can be entered like a note with note name `s' or with \skip duration

     
     a4 a4 s4 a4 \skip 1 a4

The s syntax is only available in note mode and chord mode. In other situations, for example, when entering lyrics, you should use the \skip command

     
     <<
       \relative { a'2 a2 }
       \new Lyrics \lyricmode { \skip 2 bla2 }
     >>

The skip command is merely an empty musical placeholder. It does not produce any output, not even transparent output.

The s skip command does create Staff and Voice when necessary, similar to note and rest commands. For example, the following results in an empty staff.

     
     { s4 }

The fragment { \skip 4 } would produce an empty page.

See also

Program reference: SkipMusic.

6.2 Rhythms

This section discusses rhythms, durations, and bars.

6.2.1 Durations

In Note, Chord, and Lyrics mode, durations are designated by numbers and dots: durations are entered as their reciprocal values. For example, a quarter note is entered using a 4 (since it is a 1/4 note), while a half note is entered using a 2 (since it is a 1/2 note). For notes longer than a whole you must use the \longa and \breve commands

c'\breve
c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
r\longa r\breve
r1 r2 r4 r8 r16 r32 r64 r64

If the duration is omitted then it is set to the previously entered duration. The default for the first note is a quarter note.

     
     { a a a2 a a4 a a1 a }

6.2.2 Augmentation dots

To obtain dotted note lengths, simply add a dot (`.') to the number. Double-dotted notes are produced in a similar way.

     
     a'4 b' c''4. b'8 a'4. b'4.. c''8.

Predefined commands

Dots are normally moved up to avoid staff lines, except in polyphonic situations. The following commands may be used to force a particular direction manually

\dotsUp, \dotsDown, \dotsNeutral.

See also

Program reference: Dots, and DotColumn.

6.2.3 Tuplets

Tuplets are made out of a music expression by multiplying all durations with a fraction

\times fraction musicexpr

The duration of musicexpr will be multiplied by the fraction. The fraction's denominator will be printed over the notes, optionally with a bracket. The most common tuplet is the triplet in which 3 notes have the length of 2, so the notes are 2/3 of their written length

     
     g'4 \times 2/3 {c'4 c' c'} d'4 d'4

Tuplets may be nested, for example,

\override TupletNumber #'text = #tuplet-number::calc-fraction-text
\times 4/6 {
  a4 a
  \times 3/5 { a a a a a }
}

Predefined commands

\tupletUp, \tupletDown, \tupletNeutral.

Commonly tweaked properties

The property tupletSpannerDuration specifies how long each bracket should last. With this, you can make lots of tuplets while typing \times only once, thus saving lots of typing. In the next example, there are two triplets shown, while \times was only used once

     
     \set tupletSpannerDuration = #(ly:make-moment 1 4)
     \times 2/3 { c8 c c c c c }

For more information about make-moment, see Time administration.

The format of the number is determined by the property text in TupletNumber. The default prints only the denominator, but if it is set to the function tuplet-number::calc-fraction-text, num:den will be printed instead.

To avoid printing tuplet numbers, use

     
     \times 2/3 { c8 c c } \times 2/3 { c8 c c }
     \override TupletNumber #'transparent = ##t
     \times 2/3 { c8 c c } \times 2/3 { c8 c c }

Tuplet brackets can be made to run to prefatory matter or the next note

See also

Program reference: TupletBracket, TupletNumber, and TimeScaledMusic.

Examples: input/regression/tuplet-nest.ly.

6.2.4 Scaling durations

You can alter the length of duration by a fraction N/M appending ‘*N/M’ (or ‘*N’ if M=1). This will not affect the appearance of the notes or rests produced.

In the following example, the first three notes take up exactly two beats, but no triplet bracket is printed.

     
     \time 2/4
     a4*2/3 gis4*2/3 a4*2/3
     a4 a4 a4*2
     b16*4 c4

See also

This manual: Tuplets

6.2.5 Bar check

Bar checks help detect errors in the durations. A bar check is entered using the bar symbol, `|'. Whenever it is encountered during interpretation, it should fall on a measure boundary. If it does not, a warning is printed. In the next example, the second bar check will signal an error

\time 3/4 c2 e4 | g2 |

Bar checks can also be used in lyrics, for example

\lyricmode {
  \time 2/4
  Twin -- kle | Twin -- kle
}

Failed bar checks are caused by entering incorrect durations. Incorrect durations often completely garble up the score, especially if the score is polyphonic, so a good place to start correcting input is by scanning for failed bar checks and incorrect durations.

It is also possible to redefine the meaning of |. This is done by assigning a music expression to pipeSymbol,

     
     pipeSymbol = \bar "||"
     
     { c'2 c' | c'2 c' }

6.2.6 Barnumber check

When copying large pieces of music, it can be helpful to check that the LilyPond bar number corresponds to the original that you are entering from. This can be checked with \barNumberCheck, for example,

\barNumberCheck #123

will print a warning if the currentBarNumber is not 123 when it is processed.

6.2.7 Automatic note splitting

Long notes can be converted automatically to tied notes. This is done by replacing the Note_heads_engraver by the Completion_heads_engraver. In the following examples, notes crossing the bar line are split and tied.

\new Voice \with {
  \remove "Note_heads_engraver"
  \consists "Completion_heads_engraver"
} {
  c2. c8 d4 e f g a b c8 c2 b4 a g16 f4 e d c8. c2
}

This engraver splits all running notes at the bar line, and inserts ties. One of its uses is to debug complex scores: if the measures are not entirely filled, then the ties exactly show how much each measure is off.

If you want to allow line breaking on the bar lines where Completion_heads_engraver splits notes, you must also remove Forbid_line_breaks_engraver.

Bugs

Not all durations (especially those containing tuplets) can be represented exactly with normal notes and dots, but the engraver will not insert tuplets.

Completion_heads_engraver only affects notes; it does not split rests.

See also

Examples: input/regression/completion-heads.ly.

Program reference: Completion_heads_engraver.

6.3 Polyphony

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.

6.3.1 Chords

A chord is formed by a enclosing a set of pitches between < and >. A chord may be followed by a duration, and a set of articulations, just like simple notes

     
     <c e g>4 <c>8

For more information about chords, see Chord names.

6.3.2 Stems

Whenever a note is found, a Stem object is created automatically. For whole notes and rests, they are also created but made invisible.

Predefined commands

\stemUp, \stemDown, \stemNeutral.

Commonly tweaked properties

To change the direction of stems in the middle of the staff, use

     
     a4 b c b
     \override Stem #'neutral-direction = #up
     a4 b c b
     \override Stem #'neutral-direction = #down
     a4 b c b

6.3.3 Basic polyphony

The easiest way to enter fragments with more than one voice on a staff is to enter each voice as a sequence (with {...}), and combine them simultaneously, separating the voices with \\

     
     \new Staff \relative c' {
       c16 d e f
       <<
         { g4 f e | d2 e2 } \\
         { r8 e4 d c8 ~ | c b16 a b8 g ~ g2 } \\
         { s2. | s4 b4 c2 }
       >>
     }

The separator causes Voice contexts⁸ to be instantiated. They bear the names "1", "2", etc. In each of these contexts, vertical direction of slurs, stems, etc., is set appropriately.

These voices are all separate from the voice that contains the notes just outside the << \\ >> construct. This should be noted when making changes at the voice level. This also means that slurs and ties cannot go into or out of a << \\ >> construct. Conversely, parallel voices from separate << \\ >> constructs on the same staff are the the same voice. Here is the same example, with different noteheads for each voice. Note that the change to the note-head style in the main voice does not affect the inside of the << \\ >> constructs. Also, the change to the second voice in the first << \\ >> construct is effective in the second << \\ >>, and the voice is tied across the two constructs.

     
     \new Staff \relative c' {
       \override NoteHead #'style = #'cross
       c16 d e f
       <<
         { g4 f e } \\
         { \override NoteHead #'style = #'triangle
         r8 e4 d c8 ~ }
       >> |
       <<
         { d2 e2 } \\
         { c8 b16 a b8 g ~ g2 } \\
         { \override NoteHead #'style = #'slash s4 b4 c2 }
       >>
     }

Polyphony does not change the relationship of notes within a \relative { } block. Each note is calculated relative to the note immediately preceding it.

\relative { noteA << noteB \\ noteC >> noteD }

noteC is relative to noteB, not noteA; noteD is relative to noteC, not noteB or noteA.

6.3.4 Explicitly instantiating voices

Voice contexts can also be instantiated manually inside a << >> block to create polyphonic music, using \voiceOne, up to \voiceFour to assign stem directions and a horizontal shift for each part.

Specifically,

<< \upper \\ \lower >>

is equivalent to

<<
  \new Voice = "1" { \voiceOne \upper }
  \new Voice = "2" { \voiceTwo \lower }
>>

The \voiceXXX commands set the direction of stems, slurs, ties, articulations, text annotations, augmentation dots of dotted notes, and fingerings. \voiceOne and \voiceThree make these objects point upwards, while \voiceTwo and \voiceFour make them point downwards. The command \oneVoice will revert back to the normal setting.

An expression that appears directly inside a << >> belongs to the main voice. This is useful when extra voices appear while the main voice is playing. Here is a more correct rendition of the example from the previous section. The crossed noteheads demonstrate that the main melody is now in a single voice context.

     
     \new Staff \relative c' {
       \override NoteHead #'style = #'cross
       c16 d e f
       \voiceOne
       <<
         { g4 f e | d2 e2 }
         \new Voice="1" { \voiceTwo
           r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
           \oneVoice
         }
         \new Voice { \voiceThree
           s2. | s4 b4 c2
           \oneVoice
         }
       >>
       \oneVoice
     }

The correct definition of the voices allows the melody to be slurred.

     
     \new Staff \relative c' {
       c16^( d e f
       \voiceOne
       <<
         { g4 f e | d2 e2) }
         \context Voice="1" { \voiceTwo
           r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
           \oneVoice
         }
         \new Voice { \voiceThree
           s2. s4 b4 c2
           \oneVoice
         }
       >>
       \oneVoice
     }

Avoiding the \\ separator also allows nesting polyphony constructs, which in some case might be a more natural way to typeset the music.

     
     \new Staff \relative c' {
       c16^( d e f
       \voiceOne
       <<
         { g4 f e | d2 e2) }
         \context Voice="1" { \voiceTwo
           r8 e4 d c8 ~ |
           <<
             {c8 b16 a b8 g ~ g2}
             \new Voice { \voiceThree
               s4 b4 c2
               \oneVoice
             }
           >>
         \oneVoice
         }
       >>
       \oneVoice
     }

In some instances of complex polyphonic music, you may need additional voices to avoid collisions between notes. Additional voices are added by defining an identifier, as shown below:

     
     voiceFive = #(context-spec-music (make-voice-props-set 4) 'Voice)
     
     \relative c''' <<
       { \voiceOne g4 ~  \stemDown g32[ f( es d c b a b64 )g] } \\
       { \voiceThree  b4} \\
       { \voiceFive d,} \\
       { \voiceTwo g,}
     >>

6.3.5 Collision Resolution

Normally, note heads with a different number of dots are not merged, but when the object property merge-differently-dotted is set in the NoteCollision object, they are merged:

     
     \new Voice << {
       g8 g8
       \override Staff.NoteCollision
         #'merge-differently-dotted = ##t
       g8 g8
     } \\ { g8.[ f16] g8.[ f16] } >>

Similarly, you can merge half note heads with eighth notes, by setting merge-differently-headed:

     
     \new Voice << {
       c8 c4.
       \override Staff.NoteCollision
         #'merge-differently-headed = ##t
     c8 c4. } \\ { c2 c2 } >>

merge-differently-headed and merge-differently-dotted only apply to opposing stem directions (ie. Voice 1 & 2).

LilyPond also vertically shifts rests that are opposite of a stem, for example

     
     \new Voice << c''4 \\ r4 >>

If three or more notes line up in the same column, merge-differently-headed cannot successfully complete the merge of the two notes that should be merged. To allow the merge to work properly, apply a \shift to the note that should not be merged. In the first measure of following example, merge-differently-headed does not work (the half-note head is solid). In the second measure, \shiftOn is applied to move the top g out of the column, and merge-differently-headed works properly.

     
     \override Staff.NoteCollision #'merge-differently-headed = ##t
     <<
       { d=''2 g2 } \\
       { \oneVoice d=''8 c8 r4 e,8 c'8 r4 } \\
       { \voiceFour e,,2 e'2}
     >>
     <<
       { d'=''2 \shiftOn g2 } \\ 
       { \oneVoice d=''8 c8 r4 e,8 c'8 r4 } \\
       { \voiceFour e,,2 e'2}
     >>

Predefined commands

\oneVoice, \voiceOne, \voiceTwo, \voiceThree, \voiceFour.

\shiftOn, \shiftOnn, \shiftOnnn, \shiftOff: these commands specify the degree to which chords of the current voice should be shifted. The outer voices (normally: voice one and two) have \shiftOff, while the inner voices (three and four) have \shiftOn. \shiftOnn and \shiftOnnn define further shift levels.

When LilyPond cannot cope, the force-hshift property of the NoteColumn object and pitched rests can be used to override typesetting decisions.

     
     \relative <<
     {
       <d g>
       <d g>
     } \\ {
       <b f'>
       \once \override NoteColumn #'force-hshift = #1.7
       <b f'>
     } >>

See also

Program reference: the objects responsible for resolving collisions are NoteCollision and RestCollision.

Examples: input/regression/collision-dots.ly, input/regression/collision-head-chords.ly, input/regression/collision-heads.ly, input/regression/collision-mesh.ly, and input/regression/collisions.ly.

Bugs

When using merge-differently-headed with an upstem eighth or a shorter note, and a downstem half note, the eighth note gets the wrong offset.

There is no support for clusters where the same note occurs with different accidentals in the same chord. In this case, it is recommended to use enharmonic transcription, or to use special cluster notation (see Clusters).

6.4 Staff notation

This section describes music notation that occurs on staff level, such as key signatures, clefs and time signatures.

6.4.1 Clef

The clef indicates which lines of the staff correspond to which pitches. The clef is set with the \clef command

     
     { c''2 \clef alto g'2 }

Supported clefs include

Clef	Position
treble, violin, G, G2	G clef on 2nd line
alto, C	C clef on 3rd line
tenor	C clef on 4th line.
bass, F	F clef on 4th line
french	G clef on 1st line, so-called French violin clef
soprano	C clef on 1st line
mezzosoprano	C clef on 2nd line
baritone	C clef on 5th line
varbaritone	F clef on 3rd line
subbass	F clef on 5th line
percussion	percussion clef
tab	tablature clef

By adding _8 or ^8 to the clef name, the clef is transposed one octave down or up, respectively, and _15 and ^15 transposes by two octaves. The argument clefname must be enclosed in quotes when it contains underscores or digits. For example,

     
     \clef "G_8" c4

Commonly tweaked properties

The command \clef "treble_8" is equivalent to setting clefGlyph, clefPosition (which controls the Y position of the clef), middleCPosition and clefOctavation. A clef is printed when any of these properties are changed. The following example shows possibilities when setting properties manually.

     
     {
       \set Staff.clefGlyph = #"clefs.F"
       \set Staff.clefPosition = #2
       c'4
       \set Staff.clefGlyph = #"clefs.G"
       c'4
       \set Staff.clefGlyph = #"clefs.C"
       c'4
       \set Staff.clefOctavation = #7
       c'4
       \set Staff.clefOctavation = #0
       \set Staff.clefPosition = #0
       c'4
       \clef "bass"
       c'4
       \set Staff.middleCPosition = #4
       c'4
     }

See also

Manual: Grace notes.

Program reference: Clef.

6.4.2 Key signature

The key signature indicates the tonality in which a piece is played. It is denoted by a set of alterations (flats or sharps) at the start of the staff.

Setting or changing the key signature is done with the \key command

\key pitch type

Here, type should be \major or \minor to get pitch-major or pitch-minor, respectively. You may also use the standard mode names (also called “church modes”): \ionian, \locrian, \aeolian, \mixolydian, \lydian, \phrygian, and \dorian.

This command sets the context property Staff.keySignature. Non-standard key signatures can be specified by setting this property directly.

Accidentals and key signatures often confuse new users, because unaltered notes get natural signs depending on the key signature. For more information, see Accidentals or Accidentals and key signatures.

     
     \key g \major
     f1
     fis

Commonly tweaked properties

A natural sign is printed to cancel any previous accidentals. This can be suppressed by setting the Staff.printKeyCancellation property.

     
     \key d \major
     a b cis d
     \key g \minor
     a bes c d
     \set Staff.printKeyCancellation = ##f
     \key d \major
     a b cis d
     \key g \minor
     a bes c d

See also

Program reference: KeyCancellation, KeySignature.

6.4.3 Time signature

Time signature indicates the metrum of a piece: a regular pattern of strong and weak beats. It is denoted by a fraction at the start of the staff.

The time signature is set with the \time command

     
     \time 2/4 c'2 \time 3/4 c'2.

Commonly tweaked properties

The symbol that is printed can be customized with the style property. Setting it to #'() uses fraction style for 4/4 and 2/2 time,

     
     \time 4/4 c'1
     \time 2/2 c'1
     \override Staff.TimeSignature #'style = #'()
     \time 4/4 c'1
     \time 2/2 c'1

There are many more options for its layout. See Ancient time signatures for more examples.

\time sets the property timeSignatureFraction, beatLength and measureLength in the Timing context, which is normally aliased to Score. The property measureLength determines where bar lines should be inserted, and how automatic beams should be generated. Changing the value of timeSignatureFraction also causes the symbol to be printed.

More options are available through the Scheme function set-time-signature. In combination with the Measure_grouping_engraver, it will create MeasureGrouping signs. Such signs ease reading rhythmically complex modern music. In the following example, the 9/8 measure is subdivided in 2, 2, 2 and 3. This is passed to set-time-signature as the third argument (2 2 2 3)

     
     \score {
       \relative c'' {
         #(set-time-signature 9 8 '(2 2 2 3))
         g8[ g] d[ d] g[ g] a8[( bes g]) |
         #(set-time-signature 5 8 '(3 2))
         a4. g4
       }
       \layout {
         \context {
           \Staff
           \consists "Measure_grouping_engraver"
         }
       }
     }

See also

Program reference: TimeSignature, and Timing_translator.

Examples: input/test/compound-time.ly.

Bugs

Automatic beaming does not use the measure grouping specified with set-time-signature.

6.4.4 Partial measures

Partial measures, such as an anacrusis or upbeat, are entered using the

     
     \partial 16*5 c16 cis d dis e | a2. c,4 | b2

The syntax for this command is

\partial duration

where duration is the rhythmic length to be added before the next bar.

This is internally translated into

\set Timing.measurePosition = -length of duration

The property measurePosition contains a rational number indicating how much of the measure has passed at this point. Note that this is a negative number; \partial 4 is internally translated to mean “there is a quarter note left in the bar”.

Bugs

This command does not take into account grace notes at the start of the music. When a piece starts with graces notes in the pickup, then the \partial should follow the grace notes

     
     \grace f16
     \partial 4
     g4
     a2 g2

\partial is only intended to be used at the beginning of a piece. If you use it after the beginning, some odd warnings may occur.

6.4.5 Bar lines

Bar lines delimit measures, but are also used to indicate repeats. Normally they are inserted automatically. Line breaks may only happen on bar lines.

Special types of bar lines can be forced with the \bar command

     
     c4 \bar "|:" c4

The following bar types are available

In addition, you can specify "||:", which is equivalent to "|:" except at line breaks, where it gives a double bar line at the end of the line and a start repeat at the beginning of the next line.

To allow a line break where there is no visible bar line, use

\bar ""

This will insert an invisible bar line and allow line breaks at this point (without increasing the bar number counter).

In scores with many staves, a \bar command in one staff is automatically applied to all staves. The resulting bar lines are connected between different staves of a StaffGroup, PianoStaff, or ChoirStaff.

     
     <<
       \new StaffGroup <<
         \new Staff {
           e'4 d'
           \bar "||"
           f' e'
         }
         \new Staff { \clef bass c4 g e g }
       >>
       \new Staff { \clef bass c2 c2 }
     >>

Commonly tweaked properties

The command \bar bartype is a short cut for doing \set Timing.whichBar = bartype. Whenever whichBar is set to a string, a bar line of that type is created.

A bar line is created whenever the whichBar property is set. At the start of a measure it is set to the contents of Timing.defaultBarType. The contents of repeatCommands are used to override default measure bars.

You are encouraged to use \repeat for repetitions. See Repeats.

See also

In this manual: Repeats, System start delimiters.

Program reference: BarLine (created at Staff level), SpanBar (across staves).

6.4.6 Unmetered music

Bar lines and bar numbers are calculated automatically. For unmetered music (cadenzas, for example), this is not desirable. To turn off automatic bar lines and bar numbers, use the commands \cadenzaOn and \cadenzaOff.

     
     c4 d e d
     \cadenzaOn
     c4 c d8 d d f4 g4.
     \cadenzaOff
     \bar "|"
     d4 e d c

Bugs

LilyPond will only insert line breaks and page breaks at a barline. Unless the unmetered music ends before the end of the staff line, you will need to insert invisible bar lines

\bar ""

to indicate where breaks can occur.

6.4.7 System start delimiters

Many scores consist of more than one staff. These staves can be joined in four different ways

• The group is started with a brace at the left, and bar lines are connected. This is done with the GrandStaff context.

            
            \new GrandStaff
            \relative <<
              \new Staff { c1 c }
              \new Staff { c c }
            >>
       

  

• The group is started with a bracket, and bar lines are connected. This is done with the StaffGroup context

            
            \new StaffGroup
            \relative <<
              \new Staff { c1 c }
              \new Staff { c c }
            >>
       

  

• The group is started with a bracket, but bar lines are not connected. This is done with the ChoirStaff context.

            
            \new ChoirStaff
            \relative <<
              \new Staff { c1 c }
              \new Staff { c c }
            >>
       

  

• The group is started with a vertical line. Bar lines are not connected. This is the default for the score.

            
            \relative <<
              \new Staff { c1 c }
              \new Staff { c c }
            >>
       

  

See also

The bar lines at the start of each system are SystemStartBar, SystemStartBrace, and SystemStartBracket. Only one of these types is created in every context, and that type is determined by the property systemStartDelimiter.

Commonly tweaked properties

System start delimiters may be deeply nested,

     
     \new StaffGroup 
     \relative <<
       \set StaffGroup.systemStartDelimiterHierarchy
         = #'(SystemStartSquare (SystemStartBracket a (SystemStartSquare b)) d)
       \new Staff { c1 }
       \new Staff { c1 }
       \new Staff { c1 }
       \new Staff { c1 }
       \new Staff { c1 }
     >>

6.4.8 Staff symbol

Notes, dynamic signs, etc., are grouped with a set of horizontal lines, called a staff (plural ‘staves’). In LilyPond, these lines are drawn using a separate layout object called staff symbol.

The staff symbol may be tuned in the number, thickness and distance of lines, using properties. This is demonstrated in the example files input/test/staff-lines.ly, input/test/staff-size.ly.

In addition, staves may be started and stopped at will. This is done with \startStaff and \stopStaff.

b4 b
\override Staff.StaffSymbol #'line-count = 2
\stopStaff \startStaff
b b
\revert Staff.StaffSymbol #'line-count
\stopStaff \startStaff
b b

In combination with Frenched staves, this may be used to typeset ossia sections. An example is shown here

See also

Program reference: StaffSymbol.

Examples: input/test/staff-lines.ly, input/test/ossia.ly, input/test/staff-size.ly, input/regression/staff-line-positions.ly.

6.4.9 Writing music in parallel

Music for multiple parts can be interleaved

     
     \parallelMusic #'(voiceA voiceB) {
       r8     g'16[ c''] e''[ g' c'' e''] r8     g'16[ c''] e''[ g' c'' e''] |
       c'2                                c'2                                |
       r8     a'16[ d''] f''[ a' d'' f''] r8     a'16[ d''] f''[ a' d'' f''] |
       c'2                                c'2                                |
     }
     \new StaffGroup <<
       \new Staff \new Voice \voiceA
       \new Staff \new Voice \voiceB
     >>

This works quite well for piano music

     
     music = {
       \key c \major
       \time 4/4
       \parallelMusic #'(voiceA voiceB voiceC voiceD) {
         % Bar 1
         r8  g'16[ c''] e''[ g' c'' e''] r8  g'16[ c''] e''[ g' c''
     e''] |
         c'2                                 c'2 |
         r8  a16[ d'] f'[ a d' f']       r8  a16[ d'] f'[ a d' f'] |
         c2                                  c2 |
     
         % Bar 2
         a'8 b'      c'' d''    e'' f''    g'' a'' |
         d'4         d'         d'         d' |
         c16 d e f   d e f g    e f g a    f g a b |
         a,4         a,4        a,4        a,4 |
     
         % Bar 3 ...
       }
     }
     
     \score {
       \new PianoStaff <<
         \music
         \new Staff <<
           \voiceA \\
           \voiceB
         >>
         \new Staff {
           \clef bass
           <<
             \voiceC \\
             \voiceD
           >>
         }
       >>
     }

6.5 Connecting notes

This section deals with notation that affects groups of notes.

6.5.1 Ties

A tie connects two adjacent note heads of the same pitch. The tie in effect extends the length of a note. Ties should not be confused with slurs, which indicate articulation, or phrasing slurs, which indicate musical phrasing. A tie is entered using the tilde symbol `~'

     
     e' ~ e' <c' e' g'> ~ <c' e' g'>

When a tie is applied to a chord, all note heads whose pitches match are connected. When no note heads match, no ties will be created. Chords may be partially tied by placing the tie inside the chord,

     
     <c~ e g~ b> <c e g b>

A tie is just a way of extending a note duration, similar to the augmentation dot. The following example shows two ways of notating exactly the same concept

Ties are used either when the note crosses a bar line, or when dots cannot be used to denote the rhythm. When using ties, larger note values should be aligned to subdivisions of the measure, such as

If you need to tie a lot of notes over bars, it may be easier to use automatic note splitting (see Automatic note splitting). This mechanism automatically splits long notes, and ties them across bar lines.

When a second alternative of a repeat starts with a tied note, you have to repeat the tie. This can be achieved with \repeatTie,

Commonly tweaked properties

Ties are sometimes used to write out arpeggios. In this case, two tied notes need not be consecutive. This can be achieved by setting the tieWaitForNote property to true. The same feature is also useful, for example, to tie a tremolo to a chord. For example,

     
     \set tieWaitForNote = ##t
     \grace { c16[~ e~ g]~ } <c, e g>2
     \repeat "tremolo" 8 { c32~ c'~ } <c c,>1
     e8~ c~ a~ f~ <e' c a f>2

Ties may be engraved manually by changing the tie-configuration property. The first number indicates the distance from the center of the staff in staff-spaces, and the second number indicates the direction (1=up, -1=down).

     
     <c e g>2~ <c e g> |
     \override TieColumn #'tie-configuration =
       #'((0.0 . 1) (-2.0 . 1) (-4.0 . 1))
     <c e g>~ <c e g> |

Predefined commands

\tieUp, \tieDown, \tieNeutral, \tieDotted, \tieDashed, \tieSolid.

See also

In this manual: Automatic note splitting.

Program reference: Tie.

Examples: input/regression/tie-arpeggio.ly input/regression/tie-manual.ly

Bugs

Switching staves when a tie is active will not produce a slanted tie.

Changing clefs or octavations during a tie is not really well-defined. In these cases, a slur may be preferable.

6.5.2 Slurs

A slur indicates that notes are to be played bound or legato. They are entered using parentheses

     
     f( g a) a8 b( a4 g2 f4)
     <c e>2( <b d>2)

The direction of a slur can be specified with \slurDIR, where DIR is either Up, Down, or Neutral (automatically selected).

However, there is a convenient shorthand for forcing slur directions. By adding _ or ^ before the opening parentheses, the direction is also set. For example,

     
     c4_( c) c^( c)

Only one slur can be printed at once. If you need to print a long slur over a few small slurs, please see Phrasing slurs.

Commonly tweaked properties

Some composers write two slurs when they want legato chords. This can be achieved in LilyPond by setting doubleSlurs,

     
     \set doubleSlurs = ##t
     <c e>4 ( <d f> <c e> <d f> )

Predefined commands

\slurUp, \slurDown, \slurNeutral, \slurDashed, \slurDotted, \slurSolid.

See also

Program reference: Slur.

6.5.3 Phrasing slurs

A phrasing slur (or phrasing mark) connects notes and is used to indicate a musical sentence. It is written using \( and \) respectively

     
     \time 6/4 c'\( d( e) f( e) d\)

Typographically, the phrasing slur behaves almost exactly like a normal slur. However, they are treated as different objects. A \slurUp will have no effect on a phrasing slur; instead, use \phrasingSlurUp, \phrasingSlurDown, and \phrasingSlurNeutral.

You cannot have simultaneous phrasing slurs.

Predefined commands

\phrasingSlurUp, \phrasingSlurDown, \phrasingSlurNeutral.

See also

Program reference: PhrasingSlur.

6.5.4 Laissez vibrer ties

L.v. ties (laissez vibrer) indicate that notes must not be damped at the end. It is used in notation for piano, harp and other string and percussion instruments. They can be entered using \laissezVibrer,

<c f g>\laissezVibrer

See also

Program reference: LaissezVibrerTie LaissezVibrerTieColumn

Example files: input/regression/laissez-vibrer-tie.ly

6.5.5 Automatic beams

LilyPond inserts beams automatically

     
     \time 2/4 c8 c c c \time 6/8 c c c c8. c16 c8

When these automatic decisions are not good enough, beaming can be entered explicitly. It is also possible to define beaming patterns that differ from the defaults. See Setting automatic beam behavior for details.

Individual notes may be marked with \noBeam to prevent them from being beamed

     
     \time 2/4 c8 c\noBeam c c

See also

Program reference: Beam.

6.5.6 Manual beams

In some cases it may be necessary to override the automatic beaming algorithm. For example, the autobeamer will not put beams over rests or bar lines. Such beams are specified manually by marking the begin and end point with [ and ]

     
     {
       r4 r8[ g' a r8] r8 g[ | a] r8
     }

Commonly tweaked properties

Normally, beaming patterns within a beam are determined automatically. If necessary, the properties stemLeftBeamCount and stemRightBeamCount can be used to override the defaults. If either property is set, its value will be used only once, and then it is erased

     
     {
        f8[ r16
           f g a]
        f8[ r16
        \set stemLeftBeamCount = #1
           f g a]
     }

The property subdivideBeams can be set in order to subdivide all 16th or shorter beams at beat positions, as defined by the beatLength property.

     
     c16[ c c c c c c c]
     \set subdivideBeams = ##t
     c16[ c c c c c c c]
     \set Score.beatLength = #(ly:make-moment 1 8)
     c16[ c c c c c c c]

For more information about make-moment, see Time administration.

Line breaks are normally forbidden when beams cross bar lines. This behavior can be changed by setting allowBeamBreak.

Bugs

Kneed beams are inserted automatically when a large gap is detected between the note heads. This behavior can be tuned through the object.

Automatically kneed cross-staff beams cannot be used together with hidden staves. See Hiding staves.

Beams do not avoid collisions with symbols around the notes, such as texts and accidentals.

6.5.7 Grace notes

Grace notes are ornaments that are written out. The most common ones are acciaccatura, which should be played as very short. It is denoted by a slurred small note with a slashed stem. The appoggiatura is a grace note that takes a fixed fraction of the main note, and is denoted as a slurred note in small print without a slash. They are entered with the commands \acciaccatura and \appoggiatura, as demonstrated in the following example

     
     b4 \acciaccatura d8 c4 \appoggiatura e8 d4
     \acciaccatura { g16[ f] } e4

Both are special forms of the \grace command. By prefixing this keyword to a music expression, a new one is formed, which will be printed in a smaller font and takes up no logical time in a measure.

     
     c4 \grace c16 c4
     \grace { c16[ d16] } c2 c4

Unlike \acciaccatura and \appoggiatura, the \grace command does not start a slur.

Internally, timing for grace notes is done using a second, ‘grace’

timing. Every point in time consists of two rational numbers: one denotes the logical time, one denotes the grace timing. The above example is shown here with timing tuples

The placement of grace notes is synchronized between different staves. In the following example, there are two sixteenth grace notes for every eighth grace note

     
     << \new Staff { e4 \grace { c16[ d e f] } e4 }
        \new Staff { c4 \grace { g8[ b] } c4 } >>

If you want to end a note with a grace, use the \afterGrace command. It takes two arguments: the main note, and the grace notes following the main note.

c1 \afterGrace d1 { c16[ d] } c4

This will put the grace notes after a “space” lasting 3/4 of the length of the main note. The fraction 3/4 can be changed by setting afterGraceFraction, ie.

afterGraceFraction = #(cons 7 8)

will put the grace note at 7/8 of the main note.

The same effect can be achieved manually by doing

     
     \new Voice {
       << { d1^\trill_( }
          { s2 \grace { c16[ d] } } >>
       c4)
     }

By adjusting the duration of the skip note (here it is a half-note), the space between the main-note and the grace is adjusted.

A \grace section will introduce special typesetting settings, for example, to produce smaller type, and set directions. Hence, when introducing layout tweaks, they should be inside the grace section, for example,

     
     \new Voice {
       \acciaccatura {
         \stemDown
         f16->
         \stemNeutral
       }
       g4
     }

The overrides should also be reverted inside the grace section.

The layout of grace sections can be changed throughout the music using the function add-grace-property. The following example undefines the Stem direction for this grace, so that stems do not always point up.

\new Staff {
  #(add-grace-property 'Voice 'Stem 'direction '())
  ...
}

Another option is to change the variables startGraceMusic, stopGraceMusic, startAcciaccaturaMusic, stopAcciaccaturaMusic, startAppoggiaturaMusic, stopAppoggiaturaMusic. More information is in the file ly/grace-init.ly.

The slash through the stem in acciaccaturas can be obtained in other situations by \override Stem #'stroke-style = #"grace".

Commonly tweaked properties

Grace notes may be forced to use floating spacing,

See also

Program reference: GraceMusic.

Bugs

A score that starts with a \grace section needs an explicit \new Voice declaration, otherwise the main note and the grace note end up on different staves.

Grace note synchronization can also lead to surprises. Staff notation, such as key signatures, bar lines, etc., are also synchronized. Take care when you mix staves with grace notes and staves without, for example,

     
     << \new Staff { e4 \bar "|:" \grace c16 d4 }
        \new Staff { c4 \bar "|:" d4 } >>

This can be remedied by inserting grace skips of the corresponding durations in the other staves. For the above example

\new Staff { c4 \bar "|:" \grace s16 d4 }

Grace sections should only be used within sequential music expressions. Nesting or juxtaposing grace sections is not supported, and might produce crashes or other errors.

6.6 Expressive marks

Expressive marks help musicians to bring more to the music than simple notes and rhythms.

6.6.1 Articulations

A variety of symbols can appear above and below notes to indicate different characteristics of the performance. They are added to a note by adding a dash and the character signifying the articulation. They are demonstrated here

The meanings of these shorthands can be changed. See ly/script-init.ly for examples.

The script is automatically placed, but the direction can be forced as well. Like other pieces of LilyPond code, _ will place them below the staff, and ^ will place them above.

     
     c''4^^ c''4_^

Other symbols can be added using the syntax note\name. Again, they can be forced up or down using ^ and _, e.g.,

     
     c\fermata c^\fermata c_\fermata

Here is a chart showing all scripts available,

Commonly tweaked properties

The vertical ordering of scripts is controlled with the script-priority property. The lower this number, the closer it will be put to the note. In this example, the TextScript (the sharp symbol) first has the lowest priority, so it is put lowest in the first example. In the second, the prall trill (the Script) has the lowest, so it is on the inside. When two objects have the same priority, the order in which they are entered decides which one comes first.

     
     \once \override TextScript #'script-priority = #-100
     a4^\prall^\markup { \sharp }
     
     \once \override Script #'script-priority = #-100
     a4^\prall^\markup { \sharp }

See also

Program reference: Script.

Bugs

These signs appear in the printed output but have no effect on the MIDI rendering of the music.

6.6.2 Fingering instructions

Fingering instructions can be entered using

note-digit

For finger changes, use markup texts

     
     c4-1 c-2 c-3 c-4
     c^\markup { \finger "2 - 3" }

You can use the thumb-script to indicate that a note should be played with the thumb (e.g., in cello music)

     
     <a_\thumb a'-3>8 <b_\thumb b'-3>

Fingerings for chords can also be added to individual notes of the chord by adding them after the pitches

     
     < c-1 e-2 g-3 b-5 >4

Commonly tweaked properties

You may exercise greater control over fingering chords by setting fingeringOrientations

     
     \set fingeringOrientations = #'(left down)
     <c-1 es-2 g-4 bes-5 > 4
     \set fingeringOrientations = #'(up right down)
     <c-1 es-2 g-4 bes-5 > 4

Using this feature, it is also possible to put fingering instructions very close to note heads in monophonic music,

     
     \set fingeringOrientations = #'(right)
     <es'-2>4

See also

Program reference: Fingering.

Examples: input/regression/finger-chords.ly.

6.6.3 Dynamics

Absolute dynamic marks are specified using a command after a note c4\ff. The available dynamic marks are \ppppp, \pppp, \ppp, \pp, \p, \mp, \mf, \f, \ff, \fff, \ffff, \fp, \sf, \sff, \sp, \spp, \sfz, and \rfz.

     
     c\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff
     c2\fp c\sf c\sff c\sp c\spp c\sfz c\rfz

A crescendo mark is started with \< and terminated with \! or an absolute dynamic. A decrescendo is started with \> and is also terminated with \! or an absolute dynamic. \cr and \decr may be used instead of \< and \>. Because these marks are bound to notes, you must use spacer notes if multiple marks are needed during one note

     
     c\< c\! d\> e\!
     << f1 { s4 s4\< s4\! \> s4\! } >>

A hairpin normally starts at the left edge of the beginning note and ends on the right edge of the ending note. If the ending note falls on the downbeat, the hairpin ends on the immediately preceding barline. This may be modified by setting the hairpinToBarline property,

     
     \set hairpinToBarline = ##f
     c4\< c2. c4\!

In some situations the \espressivo articulation mark may be suitable to indicate a crescendo and decrescendo on the one note,

     
     c2 b4 a g1\espressivo

This may give rise to very short hairpins. Use minimum-length in Voice.Hairpin to lengthen them, for example

\override Voice.Hairpin #'minimum-length = #5

Hairpins may be printed with a circled tip (al niente notation) by setting the circled-tip property,

     
     \override Hairpin #'circled-tip = ##t
     c2\< c\!
     c4\> c\< c2\!

You can also use text saying cresc. instead of hairpins

     
     \setTextCresc
     c\< d e f\!
     \setHairpinCresc
     e\> d c b\!
     \setTextDecresc
     c\> d e f\!
     \setTextDim
     e\> d c b\!

You can also supply your own texts

     
     \set crescendoText = \markup { \italic "cresc. poco" }
     \set crescendoSpanner = #'dashed-line
     a'2\< a a a\!\mf

To create new dynamic marks or text that should be aligned with dynamics, see New dynamic marks.

Commonly tweaked properties

Dynamics that occur at, begin on, or end on, the same note will be vertically aligned. If you want to ensure that dynamics are aligned when they do not occur on the same note, you can increase the staff-padding property.

\override DynamicLineSpanner #'staff-padding = #4

You may also use this property if the dynamics are colliding with other notation.

Crescendi and decrescendi that end on the first note of a new line are not printed. To change this behavior, use

\override Score.Hairpin #'after-line-breaking = ##t

Text style dynamic changes (such as cresc. and dim.) are printed with a dashed line showing their extent. To surpress printing this line, use

\override DynamicTextSpanner #'dash-period = #-1.0

Predefined commands

\dynamicUp, \dynamicDown, \dynamicNeutral.

See also

Program reference: DynamicText, Hairpin. Vertical positioning of these symbols is handled by DynamicLineSpanner.

6.6.4 Breath marks

Breath marks are entered using \breathe

     
     c'4 \breathe d4

Commonly tweaked properties

The glyph of the breath mark can be tuned by overriding the text property of the BreathingSign layout object with any markup text. For example,

     
     c'4
     \override BreathingSign #'text
       = #(make-musicglyph-markup "scripts.rvarcomma")
     \breathe
     d4

See also

Program reference: BreathingSign.

Examples: input/regression/breathing-sign.ly.

6.6.5 Trills

Short trills are printed like normal articulation; see Articulations.

Long running trills are made with \startTrillSpan and \stopTrillSpan,

     
     \new Voice {
       << { c1 \startTrillSpan }
          { s2. \grace { d16[\stopTrillSpan e] } } >>
       c4 }

Trills that should be executed on an explicitly specified pitch can be typeset with the command pitchedTrill,

     
     \pitchedTrill c4\startTrillSpan fis
     f\stopTrillSpan

The first argument is the main note. The pitch of the second is printed as a stemless note head in parentheses.

Predefined commands

\startTrillSpan, \stopTrillSpan.

See also

Program reference: TrillSpanner.

6.6.6 Glissando

A glissando is a smooth change in pitch. It is denoted by a line or a wavy line between two notes. It is requested by attaching \glissando to a note

     
     c2\glissando c'
     \override Glissando #'style = #'zigzag
     c2\glissando c,

See also

Program reference: Glissando.

Example files: input/regression/glissando.ly.

Bugs

Printing text over the line (such as gliss.) is not supported.

6.6.7 Arpeggio

You can specify an arpeggio sign (also known as broken chord) on a chord by attaching an \arpeggio to a chord

     
     <c e g c>\arpeggio

A square bracket on the left indicates that the player should not arpeggiate the chord

     
     \arpeggioBracket
     <c' e g c>\arpeggio

The direction of the arpeggio is sometimes denoted by adding an arrowhead to the wiggly line

     
     \new Voice {
       \arpeggioUp
       <c e g c>\arpeggio
       \arpeggioDown
       <c e g c>\arpeggio
     }

Commonly tweaked properties

When an arpeggio crosses staves, you may attach an arpeggio to the chords in both staves and set PianoStaff.connectArpeggios

     
     \new PianoStaff <<
       \set PianoStaff.connectArpeggios = ##t
       \new Staff { <c' e g c>\arpeggio }
       \new Staff { \clef bass <c,, e g>\arpeggio }
     >>

Predefined commands

\arpeggio, \arpeggioUp, \arpeggioDown, \arpeggioNeutral, \arpeggioBracket.

See also

Notation manual: Ties, for writing out arpeggios.

Program reference: Arpeggio.

Bugs

It is not possible to mix connected arpeggios and unconnected arpeggios in one PianoStaff at the same point in time.

6.6.8 Falls and doits

Falls and doits can be added to notes using the \bendAfter command,

6.7 Repeats

Repetition is a central concept in music, and multiple notations exist for repetitions.

6.7.1 Repeat types

The following types of repetition are supported

unfold

Repeated music is fully written (played) out. This is useful when entering repetitious music. This is the only kind of repeat that is included in MIDI output.

volta

Repeats are not written out, but alternative endings (volte) are printed, left to right with brackets. This is the standard notation for repeats with alternatives. These are not played in MIDI output by default.

tremolo

Make tremolo beams. These are not played in MIDI output by default.

percent

Make beat or measure repeats. These look like percent signs. These are not played in MIDI output by default. Percent repeats must be declared within a Voice context.

6.7.2 Repeat syntax

LilyPond has one syntactic construct for specifying different types of repeats. The syntax is

\repeat variant repeatcount repeatbody

If you have alternative endings, you may add

\alternative {
  alternative1
  alternative2
  alternative3
  ...
}

where each alternative is a music expression. If you do not give enough alternatives for all of the repeats, the first alternative is assumed to be played more than once.

Standard repeats are used like this

     
     c1
     \repeat volta 2 { c4 d e f }
     \repeat volta 2 { f e d c }

With alternative endings

     
     c1
     \repeat volta 2 {c4 d e f}
     \alternative { {d2 d} {f f,} }

In the following example, the first ending is not a complete bar (it only had 3 beats). The beginning of the second ending contains the 4th beat from the first ending. This “extra”

beat in the second ending is due to the first time ending, and has nothing to do with the \partial at the beginning of the example.

     
     \new Staff {
       \partial 4
       \repeat volta 4 { e | c2 d2 | e2 f2 | }
       \alternative { { g4 g g } { a | a a a a | b2. } }
     }

Ties may be added to a second ending,

     
     c1
     \repeat volta 2 {c4 d e f ~ }
     \alternative { {f2 d} {f\repeatTie f,} }

It is possible to shorten volta brackets by setting voltaSpannerDuration. In the next example, the bracket only lasts one measure, which is a duration of 3/4.

     
     \relative c''{
       \time 3/4
       c c c
       \set Staff.voltaSpannerDuration = #(ly:make-moment 3 4)
       \repeat "volta" 5 { d d d }
       \alternative { { e e e f f f }
       { g g g } }
     }

See also

Examples:

Brackets for the repeat are normally only printed over the topmost staff. This can be adjusted by setting the voltaOnThisStaff property; see input/regression/volta-multi-staff.ly.

Bugs

A nested repeat like

\repeat ...
\repeat ...
\alternative

is ambiguous, since it is is not clear to which \repeat the \alternative belongs. This ambiguity is resolved by always having the \alternative belong to the inner \repeat. For clarity, it is advisable to use braces in such situations.

Timing information is not remembered at the start of an alternative, so after a repeat timing information must be reset by hand; for example, by setting Score.measurePosition or entering \partial. Similarly, slurs or ties are also not repeated.

Volta brackets are not vertically aligned.

6.7.3 Repeats and MIDI

With a little bit of tweaking, all types of repeats can be present in the MIDI output. This is achieved by applying the \unfoldRepeats music function. This function changes all repeats to unfold repeats.

\unfoldRepeats {
  \repeat tremolo 8 {c'32 e' }
  \repeat percent 2 { c''8 d'' }
  \repeat volta 2 {c'4 d' e' f'}
  \alternative {
    { g' a' a' g' }
    {f' e' d' c' }
  }
}
\bar "|."

When creating a score file using \unfoldRepeats for MIDI, it is necessary to make two \score blocks: one for MIDI (with unfolded repeats) and one for notation (with volta, tremolo, and percent repeats). For example,

\score {
  ..music..
  \layout { .. }
}
\score {
  \unfoldRepeats ..music..
  \midi { .. }
}

6.7.4 Manual repeat commands

The property repeatCommands can be used to control the layout of repeats. Its value is a Scheme list of repeat commands.

start-repeat

Print a |: bar line.

end-repeat

Print a :| bar line.

(volta text)

Print a volta bracket saying text: The text can be specified as a text string or as a markup text, see Text markup. Do not forget to change the font, as the default number font does not contain alphabetic characters;

(volta #f)

Stop a running volta bracket.

     
     c4
       \set Score.repeatCommands = #'((volta "93") end-repeat)
     c4 c4
       \set Score.repeatCommands = #'((volta #f))
     c4 c4

See also

Program reference: VoltaBracket, RepeatedMusic, VoltaRepeatedMusic, UnfoldedRepeatedMusic, and FoldedRepeatedMusic.

6.7.5 Tremolo repeats

To place tremolo marks between notes, use \repeat with tremolo style

     
     \new Voice \relative c' {
       \repeat "tremolo" 8 { c16 d16 }
       \repeat "tremolo" 4 { c16 d16 }
       \repeat "tremolo" 2 { c16 d16 }
     }

Tremolo marks can also be put on a single note. In this case, the note should not be surrounded by braces.

     
     \repeat "tremolo" 4 c'16

Similar output is obtained using the tremolo subdivision, described in Tremolo subdivisions.

See also

In this manual: Tremolo subdivisions, Repeats.

Program reference: Beam, StemTremolo.

Example files: input/regression/chord-tremolo.ly, input/regression/stem-tremolo.ly.

6.7.6 Tremolo subdivisions

Tremolo marks can be printed on a single note by adding ‘:[number]’ after the note. The number indicates the duration of the subdivision, and it must be at least 8. A length value of 8 gives one line across the note stem. If the length is omitted, the last value (stored in tremoloFlags) is used

     
     c'2:8 c':32 | c': c': |

Bugs

Tremolos entered in this way do not carry over into the MIDI output.

See also

In this manual: Tremolo repeats.

Elsewhere: StemTremolo.

6.7.7 Measure repeats

In the percent style, a note pattern can be repeated. It is printed once, and then the pattern is replaced with a special sign. Patterns of one and two measures are replaced by percent-like signs, patterns that divide the measure length are replaced by slashes. Percent repeats must be declared within a Voice context.

     
     \new Voice \relative c' {
       \repeat "percent" 4 { c4 }
       \repeat "percent" 2 { c2 es2 f4 fis4 g4 c4 }
     }

Measure repeats of more than 2 measures get a counter, if you switch on the countPercentRepeats property,

     
     \new Voice {
     \set countPercentRepeats = ##t
       \repeat "percent" 4 { c1 }
     }

Isolated percents can also be printed. This is done by putting a multi-measure rest with a different print function,

     
     \override MultiMeasureRest #'stencil
       = #ly:multi-measure-rest::percent
     R1

See also

Program reference: RepeatSlash, PercentRepeat, DoublePercentRepeat, DoublePercentRepeatCounter, PercentRepeatCounter, PercentRepeatedMusic.

7 Instrument-specific notation

This chapter explains how to use notation for specific instruments.

7.1 Piano music

Piano staves are two normal staves coupled with a brace. The staves are largely independent, but sometimes voices can cross between the two staves. The same notation is also used for harps and other key instruments. The PianoStaff is especially built to handle this cross-staffing behavior. In this section we discuss the PianoStaff and some other pianistic peculiarities.

Bugs

Dynamics are not centered, but workarounds do exist. See the “piano centered dynamics” template in Piano templates.

The distance between the two staves is the same for all systems in the score. It is possible to override this per system, but it does require an arcane command incantation. See input/test/piano-staff-distance.ly.

7.1.1 Automatic staff changes

Voices can be made to switch automatically between the top and the bottom staff. The syntax for this is

     \autochange ...music...

This will create two staves inside the current PianoStaff, called up and down. The lower staff will be in bass clef by default.

A \relative section that is outside of \autochange has no effect on the pitches of music, so, if necessary, put \relative inside \autochange like

     \autochange \relative ... ...

The autochanger switches on basis of the pitch (middle C is the turning point), and it looks ahead skipping over rests to switch in advance. Here is a practical example

     
     \new PianoStaff
       \autochange \relative c'
       {
         g4 a b c d r4 a g
       }

See also

In this manual: Manual staff switches.

Program reference: AutoChangeMusic.

Bugs

The staff switches may not end up in optimal places. For high quality output, staff switches should be specified manually.

\autochange cannot be inside \times.

7.1.2 Manual staff switches

Voices can be switched between staves manually, using the command

\change Staff = staffname music

The string staffname is the name of the staff. It switches the current voice from its current staff to the Staff called staffname. Typically staffname is "up" or "down". The Staff referred to must already exist, so usually the setup for a score will start with a setup of the staves,

<<
  \new Staff = "up" {
    \skip 1 * 10  % keep staff alive
    }
  \new Staff = "down" {
    \skip 1 * 10  % idem
    }
>>

and the Voice is inserted afterwards

\context Staff = down
  \new Voice { ... \change Staff = up ... }

7.1.3 Pedals

Pianos have pedals that alter the way sound is produced. Generally, a piano has three pedals, sustain, una corda, and sostenuto.

Piano pedal instruction can be expressed by attaching \sustainDown, \sustainUp, \unaCorda, \treCorde, \sostenutoDown and \sostenutoUp to a note or chord

     
     c'4\sustainDown c'4\sustainUp

What is printed can be modified by setting pedalXStrings, where X is one of the pedal types: Sustain, Sostenuto or UnaCorda. Refer to SustainPedal in the program reference for more information.

Pedals can also be indicated by a sequence of brackets, by setting the pedalSustainStyle property to bracket objects

     
     \set Staff.pedalSustainStyle = #'bracket
     c\sustainDown d e
     b\sustainUp\sustainDown
     b g \sustainUp a \sustainDown \bar "|."

A third style of pedal notation is a mixture of text and brackets, obtained by setting the pedalSustainStyle property to mixed

     
     \set Staff.pedalSustainStyle = #'mixed
     c\sustainDown d e
     b\sustainUp\sustainDown
     b g \sustainUp a \sustainDown \bar "|."

The default ‘*Ped.’ style for sustain and damper pedals corresponds to style #'text. The sostenuto pedal uses mixed style by default.

     
     c\sostenutoDown d e c, f g a\sostenutoUp

For fine-tuning the appearance of a pedal bracket, the properties edge-width, edge-height, and shorten-pair of PianoPedalBracket objects (see PianoPedalBracket in the Program reference) can be modified. For example, the bracket may be extended to the right edge of the note head

     
     \override Staff.PianoPedalBracket #'shorten-pair = #'(0 . -1.0)
     c\sostenutoDown d e c, f g a\sostenutoUp

See also

In this manual: Laissez vibrer ties

7.1.4 Staff switch lines

Whenever a voice switches to another staff, a line connecting the notes can be printed automatically. This is switched on by setting followVoice to true

     
     \new PianoStaff <<
       \new Staff="one" {
         \set followVoice = ##t
         c1
         \change Staff=two
         b2 a
       }
       \new Staff="two" { \clef bass \skip 1*2 }
     >>

See also

Program reference: VoiceFollower.

Predefined commands

\showStaffSwitch, \hideStaffSwitch.

7.1.5 Cross staff stems

Chords that cross staves may be produced by increasing the length of the stem in the lower staff, so it reaches the stem in the upper staff, or vice versa.

     
     stemExtend = \once \override Stem #'length = #22
     noFlag = \once \override Stem #'flag-style = #'no-flag
     \new PianoStaff <<
       \new Staff {
         \stemDown \stemExtend
         f'4
         \stemExtend \noFlag
         f'8
       }
       \new Staff {
         \clef bass
         a4 a8
       }
     >>

7.2 Chord names

7.2.1 Introducing chord names

LilyPond has support for printing chord names. Chords may be entered in musical chord notation, i.e., < .. >, but they can also be entered by name. Internally, the chords are represented as a set of pitches, so they can be transposed

     
     twoWays = \transpose c c' {
       \chordmode {
         c1 f:sus4 bes/f
       }
       <c e g>
       <f bes c'>
       <f bes d'>
     }
     
     << \new ChordNames \twoWays
        \new Voice \twoWays >>

This example also shows that the chord printing routines do not try to be intelligent. The last chord (f bes d) is not interpreted as an inversion.

Note that the duration of chords must be specified outside the <>.

<c e g>2

7.2.2 Chords mode

In chord mode sets of pitches (chords) are entered with normal note names. A chord is entered by the root, which is entered like a normal pitch

     
     \chordmode { es4. d8 c2 }

The mode is introduced by the keyword \chordmode.

Other chords may be entered by suffixing a colon and introducing a modifier (which may include a number if desired)

     
     \chordmode { e1:m e1:7 e1:m7 }

The first number following the root is taken to be the ‘type’ of the chord, thirds are added to the root until it reaches the specified number

     
     \chordmode { c:3 c:5 c:6 c:7 c:8 c:9 c:10 c:11 }

More complex chords may also be constructed adding separate steps to a chord. Additions are added after the number following the colon and are separated by dots

     
     \chordmode { c:5.6 c:3.7.8 c:3.6.13 }

Chord steps can be altered by suffixing a - or + sign to the number

     
     \chordmode { c:7+ c:5+.3- c:3-.5-.7- }

Removals are specified similarly and are introduced by a caret. They must come after the additions

     
     \chordmode { c^3 c:7^5 c:9^3.5 }

Modifiers can be used to change pitches. The following modifiers are supported

m

The minor chord. This modifier lowers the 3rd and (if present) the 7th step.

dim

The diminished chord. This modifier lowers the 3rd, 5th and (if present) the 7th step.

aug

The augmented chord. This modifier raises the 5th step.

maj

The major 7th chord. This modifier raises the 7th step if present.

sus

The suspended 4th or 2nd. This modifier removes the 3rd step. Append either 2 or 4 to add the 2nd or 4th step to the chord.

Modifiers can be mixed with additions

     
       \chordmode { c:sus4 c:7sus4 c:dim7 c:m6 }

Since an unaltered 11 does not sound good when combined with an unaltered 13, the 11 is removed in this case (unless it is added explicitly)

     
     \chordmode { c:13 c:13.11 c:m13 }

An inversion (putting one pitch of the chord on the bottom), as well as bass notes, can be specified by appending /pitch to the chord

     
     \chordmode { c1 c/g c/f }

A bass note can be added instead of transposed out of the chord, by using /+pitch.

     
     \chordmode { c1 c/+g c/+f }

Chords is a mode similar to \lyricmode, etc. Most of the commands continue to work, for example, r and \skip can be used to insert rests and spaces, and property commands may be used to change various settings.

Bugs

Each step can only be present in a chord once. The following simply produces the augmented chord, since 5+ is interpreted last

     
     \chordmode { c:5.5-.5+ }

7.2.3 Printing chord names

For displaying printed chord names, use the ChordNames context. The chords may be entered either using the notation described above, or directly using < and >

     
     harmonies = {
       \chordmode {a1 b c} <d' f' a'> <e' g' b'>
     }
     <<
       \new ChordNames \harmonies
       \new Staff \harmonies
     >>

You can make the chord changes stand out by setting ChordNames.chordChanges to true. This will only display chord names when there is a change in the chords scheme and at the start of a new line

     
     harmonies = \chordmode {
       c1:m c:m \break c:m c:m d
     }
     <<
       \new ChordNames {
         \set chordChanges = ##t
         \harmonies }
       \new Staff \transpose c c' \harmonies
     >>

The previous examples all show chords over a staff. This is not necessary. Chords may also be printed separately. It may be necessary to add Volta_engraver and Bar_engraver for showing repeats.

\new ChordNames \with {
  \override BarLine #'bar-size = #4
  voltaOnThisStaff = ##t
  \consists Bar_engraver
  \consists "Volta_engraver"
}
\chordmode { \repeat volta 2 {
  f1:maj7 f:7 bes:7
  c:maj7
} \alternative {
  es e
}
}

The default chord name layout is a system for Jazz music, proposed by Klaus Ignatzek (see Literature list). It can be tuned through the following properties

chordNameExceptions

This is a list that contains the chords that have special formatting.

The exceptions list should be encoded as

     { <c f g bes>1 \markup { \super "7" "wahh" } }

To get this information into chordNameExceptions takes a little manoeuvring. The following code transforms chExceptionMusic (which is a sequential music) into a list of exceptions.

     (sequential-music-to-chord-exceptions chExceptionMusic #t)

Then,

     (append
      (sequential-music-to-chord-exceptions chExceptionMusic #t)
      ignatzekExceptions)

adds the new exceptions to the default ones, which are defined in ly/chord-modifier-init.ly.

For an example of tuning this property, see also input/regression/chord-name-exceptions.ly.

majorSevenSymbol

This property contains the markup object used for the 7th step, when it is major. Predefined options are whiteTriangleMarkup and blackTriangleMarkup. See input/regression/chord-name-major7.ly for an example.

chordNameSeparator

Different parts of a chord name are normally separated by a slash. By setting chordNameSeparator, you can specify other separators, e.g.,

          
          \new ChordNames \chordmode {
            c:7sus4
            \set chordNameSeparator
              = \markup { \typewriter "|" }
            c:7sus4
          }
     

chordRootNamer

The root of a chord is usually printed as a letter with an optional alteration. The transformation from pitch to letter is done by this function. Special note names (for example, the German “H” for a B-chord) can be produced by storing a new function in this property.

chordNoteNamer

The default is to print single pitch, e.g., the bass note, using the chordRootNamer. The chordNoteNamer property can be set to a specialized function to change this behavior. For example, the base can be printed in lower case.

chordPrefixSpacer

The “m” for minor chords is usually printed right after the root of the chord. By setting chordPrefixSpacer, you can fix a spacer between the root and “m”. The spacer is not used when the root is altered.

The predefined variables \germanChords, \semiGermanChords, \italianChords and \frenchChords set these variables. The effect is demonstrated here,

There are also two other chord name schemes implemented: an alternate Jazz chord notation, and a systematic scheme called Banter chords. The alternate Jazz notation is also shown on the chart in Chord name chart. Turning on these styles is described in the input file input/test/chord-names-jazz.ly.

Predefined commands

\germanChords, \semiGermanChords. \italianChords. \frenchChords.

See also

Examples: input/regression/chord-name-major7.ly, input/regression/chord-name-exceptions.ly, input/test/chord-names-jazz.ly.

Init files: scm/chords-ignatzek.scm, and scm/chord-entry.scm.

Bugs

Chord names are determined solely from the list of pitches. Chord inversions are not identified, and neither are added bass notes. This may result in strange chord names when chords are entered with the < .. > syntax.

7.3 Vocal music

Since LilyPond input files are text, there are two issues to consider when working with vocal music:

• Song texts must be entered as text, not notes. For example, the input d should be interpreted as a one letter syllable, not the note D.
• Song texts must be aligned with the notes of their melody.

There are a few different ways to define lyrics; the simplest way is to use the \addlyrics function.

Commonly tweaked properties

Checking to make sure that text scripts and lyrics are within the margins is a relatively large computational task. To speed up processing, lilypond does not perform such calculations by default; to enable it, use

\override Score.PaperColumn #'keep-inside-line = ##t

To make lyrics avoid barlines as well, use

\layout {
  \context {
    \Lyrics
      \consists "Bar_engraver"
      \consists "Separating_line_group_engraver"
      \override BarLine #'transparent = ##t
  }
}

7.3.1 Setting simple songs

The easiest way to add lyrics to a melody is to append

\addlyrics { the lyrics }

to a melody. Here is an example,

     
     \time 3/4
     \relative { c2 e4 g2. }
     \addlyrics { play the game }

More stanzas can be added by adding more \addlyrics sections

     
     \time 3/4
     \relative { c2 e4 g2. }
     \addlyrics { play the game }
     \addlyrics { speel het spel }
     \addlyrics { joue le jeu }

The command \addlyrics cannot handle polyphony settings. For these cases you should use \lyricsto and \lyricmode.

7.3.2 Entering lyrics

Lyrics are entered in a special input mode. This mode is introduced by the keyword \lyricmode, or by using \addlyrics or \lyricsto. In this mode you can enter lyrics, with punctuation and accents, and the input d is not parsed as a pitch, but rather as a one letter syllable. Syllables are entered like notes, but with pitches replaced by text. For example,

\lyricmode { Twin-4 kle4 twin- kle litt- le star2 }

There are two main methods to specify the horizontal placement of the syllables, either by specifying the duration of each syllable explicitly, like in the example above, or by automatically aligning the lyrics to a melody or other voice of music, using \addlyrics or \lyricsto. For more details see The Lyrics context.

A word or syllable of lyrics begins with an alphabetic character, and ends with any space or digit. The following characters can be any character that is not a digit or white space. One important consequence of this is that a word can end with }. The following example is usually a mistake in the input file. The syllable includes a }, so the opening brace is not balanced

\lyricmode { twinkle}

Similarly, a period which follows an alphabetic sequence is included in the resulting string. As a consequence, spaces must be inserted around property commands

\override Score . LyricText #'font-shape = #'italic

In order to assign more than one syllable to a single note, you can surround them with quotes or use a _ character, to get spaces between syllables, or use tilde symbol (~) to get a lyric tie.

     
     \time 3/4
     \relative { c2 e4 g2 e4 }
     \addlyrics { gran- de_a- mi- go }
     \addlyrics { pu- "ro y ho-" nes- to }
     \addlyrics { pu- ro~y~ho- nes- to }

The lyric ties is implemented with the Unicode character U+203F, so be sure to have a font (Like DejaVuLGC) installed that includes this glyph.

To enter lyrics with characters from non-English languages, or with accented and special characters (such as the heart symbol or slanted quotes), simply insert the characters directly into the input file and save it with utf-8 encoding. See Text encoding for more info.

     
     \relative { e4 f e d e f e2 }
     \addlyrics { He said: “Let my peo ple go”. }

To use normal quotes in lyrics, add a backslash before the quotes. For example,

     
     \relative c' { \time 3/4 e4 e4. e8 d4 e d c2. }
     \addlyrics { "\"I" am so lone- "ly\"" said she }

The full definition of a word start in Lyrics mode is somewhat more complex.

A word in Lyrics mode begins with: an alphabetic character, _, ?, !, :, ', the control characters ^A through ^F, ^Q through ^W, ^Y, ^^, any 8-bit character with ASCII code over 127, or a two-character combination of a backslash followed by one of ‘’, , ", or ^.

To define indentifiers containing lyrics, the function lyricmode must be used.

verseOne = \lyricmode { Joy to the world the Lord is come }
\score {
  <<
    \new Voice = "one" \relative c'' {
      \autoBeamOff
      \time 2/4
      c4 b8. a16 g4. f8 e4 d c2
    }
    \addlyrics { \verseOne }
  >>
}

See also

Program reference: LyricText, LyricSpace.

7.3.3 Hyphens and extenders

Centered hyphens are entered as `--' between syllables. The hyphen will have variable length depending on the space between the syllables and it will be centered between the syllables.

When a lyric is sung over many notes (this is called a melisma), this is indicated with a horizontal line centered between a syllable and the next one. Such a line is called an extender line, and it is entered as `__'.

In tighly engraved music, hyphens can be removed. Whether this happens can be controlled with the minimum-distance (minimum distance between two syllables) and the minimum-length (threshold below which hyphens are removed).

See also

Program reference: LyricHyphen, LyricExtender.

7.3.4 The Lyrics context

Lyrics are printed by interpreting them in the context called Lyrics.

\new Lyrics \lyricmode ...

This will place the lyrics according to the durations that were entered. The lyrics can also be aligned under a given melody automatically. In this case, it is no longer necessary to enter the correct duration for each syllable. This is achieved by combining the melody and the lyrics with the \lyricsto expression

\new Lyrics \lyricsto name ...

This aligns the lyrics to the notes of the Voice context called name, which must already exist. Therefore normally the Voice is specified first, and then the lyrics are specified with \lyricsto. The command \lyricsto switches to \lyricmode mode automatically, so the \lyricmode keyword may be omitted.

The following example uses different commands for entering lyrics.

     
     <<
       \new Voice = "one" \relative c'' {
         \autoBeamOff
         \time 2/4
         c4 b8. a16 g4. f8 e4 d c2
       }
       \new Lyrics \lyricmode { Joy4 to8. the16 world!4. the8 Lord4 is come.2 }
       \new Lyrics \lyricmode { Joy to the earth! the Sa -- viour reigns. }
       \new Lyrics \lyricsto "one" { No more let sins and sor -- rows grow. }
     >>

The second stanza is not properly aligned because the durations were not specified. A solution for that would be to use \lyricsto.

The \addlyrics command is actually just a convenient way to write a more complicated LilyPond structure that sets up the lyrics.

{ MUSIC }
\addlyrics { LYRICS }

is the same as

\new Voice = "blah" { music }
\new Lyrics \lyricsto "blah" { LYRICS }

For different or more complex orderings, the best way is to setup the hierarchy of staves and lyrics first, e.g.,

\new ChoirStaff <<
  \new Voice = "soprano" { music }
  \new Lyrics = "sopranoLyrics" { s1 }
  \new Lyrics = "tenorLyrics" { s1 }
  \new Voice = "tenor" { music }
>>

and then combine the appropriate melodies and lyric lines

\context Lyrics = sopranoLyrics \lyricsto "soprano"
  the lyrics

The final input would resemble

<<\new ChoirStaff << setup the music >>
  \lyricsto "soprano" etc
  \lyricsto "alto" etc
  etc
>>

See also

Program reference: LyricCombineMusic, Lyrics.

7.3.5 Melismata

The \lyricsto command detects melismata: it only puts one syllable under a tied or slurred group of notes. If you want to force an unslurred group of notes to be a melisma, insert \melisma after the first note of the group, and \melismaEnd after the last one, e.g.,

     
     <<
       \new Voice = "lala" {
         \time 3/4
         f4 g8
         \melisma
         f e f
         \melismaEnd
         e2
       }
       \new Lyrics \lyricsto "lala" {
         la di __ daah
       }
     >>

In addition, notes are considered a melisma if they are manually beamed, and automatic beaming (see Setting automatic beam behavior) is switched off.

A complete example of a SATB score setup is in section Vocal ensembles.

Predefined commands

\melisma, \melismaEnd

See also

Program reference: Melisma_translator.

input/regression/lyric-combine-new.ly.

Bugs

Melismata are not detected automatically, and extender lines must be inserted by hand.

7.3.6 Another way of entering lyrics

Lyrics can also be entered without \lyricsto. In this case the duration of each syllable must be entered explicitly, for example,

play2 the4 game2.
sink2 or4 swim2.

The alignment to a melody can be specified with the associatedVoice property,

\set associatedVoice = #"lala"

The value of the property (here: "lala") should be the name of a Voice context. Without this setting, extender lines will not be formatted properly.

Here is an example demonstrating manual lyric durations,

     
     << \new Voice = "melody" {
          \time 3/4
          c2 e4 g2.
       }
       \new Lyrics \lyricmode {
         \set associatedVoice = #"melody"
         play2 the4 game2.
       } >>

7.3.7 Flexibility in placement

Often, different stanzas of one song are put to one melody in slightly differing ways. Such variations can still be captured with \lyricsto.

7.3.7.1 Lyrics to multiple notes of a melisma

One possibility is that the text has a melisma in one stanza, but multiple syllables in another one. One solution is to make the faster voice ignore the melisma. This is done by setting ignoreMelismata in the Lyrics context.

There is one tricky aspect: the setting for ignoreMelismata must be set one syllable before the non-melismatic syllable in the text, as shown here,

     
     <<
       \relative \new Voice = "lahlah" {
         \set Staff.autoBeaming = ##f
         c4
         \slurDotted
         f8.[( g16])
         a4
       }
       \new Lyrics \lyricsto "lahlah" {
         more slow -- ly
       }
       \new Lyrics \lyricsto "lahlah" {
         \set ignoreMelismata = ##t % applies to "fas"
         go fas -- ter
         \unset ignoreMelismata
         still
       }
     >>

The ignoreMelismata applies to the syllable “fas”, so it should be entered before “go”.

The reverse is also possible: making a lyric line slower than the standard. This can be achieved by insert \skips into the lyrics. For every \skip, the text will be delayed another note. For example,

     
     \relative { c c g' }
     \addlyrics {
       twin -- \skip 4
       kle
     }

7.3.7.2 Divisi lyrics

You can display alternate (or divisi) lyrics by naming voice contexts and attaching lyrics to those specific contexts.

     
     \score{ <<
       \new Voice = "melody" {
         \relative c' {
           c4
           <<
             { \voiceOne c8 e }
             \new Voice = "splitpart" { \voiceTwo c4 }
           >>
           \oneVoice c4 c | c
         }
       }
       \new Lyrics \lyricsto "melody" { we shall not o- ver- come }
       \new Lyrics \lyricsto "splitpart" { will }
     >> }

You can use this trick to display different lyrics for a repeated section.

     
     \score{ <<
       \new Voice = "melody" \relative c' {
         c2 e | g e | c1 |
         \new Voice = "verse" \repeat volta 2 {c4 d e f | g1 | }
         a2 b | c1}
       \new Lyrics = "mainlyrics" \lyricsto melody \lyricmode {
         do mi sol mi do
         la si do }
       \context Lyrics = "mainlyrics" \lyricsto verse \lyricmode {
        do re mi fa sol }
       \new Lyrics = "repeatlyrics" \lyricsto verse \lyricmode {
        dodo rere mimi fafa solsol }
     >>
     }

7.3.7.3 Switching the melody associated with a lyrics line

More complex variations in text underlay are possible. It is possible to switch the melody for a line of lyrics during the text. This is done by setting the associatedVoice property. In the example

the text for the first stanza is set to a melody called “lahlah”,

\new Lyrics \lyricsto "lahlah" {
  Ju -- ras -- sic Park
}

The second stanza initially is set to the lahlah context, but for the syllable “ran”, it switches to a different melody. This is achieved with

\set associatedVoice = alternative

Here, alternative is the name of the Voice context containing the triplet.

Again, the command must be one syllable too early, before “Ty” in this case.

\new Lyrics \lyricsto "lahlah" {
  \set associatedVoice = alternative % applies to "ran"
  Ty --
  ran --
  no --
  \set associatedVoice = lahlah % applies to "rus"
  sau -- rus Rex
}

The underlay is switched back to the starting situation by assigning lahlah to associatedVoice.

7.3.7.4 Specifying melismata within the lyrics

It is also possible to define melismata entirely in the lyrics. This can be done by entering _ for every note that is part of the melisma.

     
     { \set melismaBusyProperties = #'()
       c d( e) f f( e) e e  }
     \addlyrics
      { Ky -- _ _ ri __ _ _ _  e }

In this case, you can also have ties and slurs in the melody if you set melismaBusyProperties, as is done in the example above.

7.3.7.5 Lyrics independent of notes

In some complex vocal music, it may be desirable to place lyrics completely independently of notes. Music defined inside lyricrhythm disappears into the Devnull context, but the rhythms can still be used to place the lyrics.

     
     voice = {
       c''2
       \tag #'music { c''2 }
       \tag #'lyricrhythm { c''4. c''8 }
       d''1
     }
     
     lyr = \lyricmode { I like my cat! }
     
     <<
       \new Staff \keepWithTag #'music \voice
       \new Devnull="nowhere" \keepWithTag #'lyricrhythm \voice
       \new Lyrics \lyricsto "nowhere" \lyr
       \new Staff { c'8 c' c' c' c' c' c' c'
       c' c' c' c' c' c' c' c' }
     >>

7.3.8 Spacing lyrics

To increase the spacing between lyrics, set the minimum-distance property of LyricSpace.

     
     {
       c c c c
       \override Lyrics.LyricSpace #'minimum-distance = #1.0
       c c c c
     }
     \addlyrics {
       longtext longtext longtext longtext
       longtext longtext longtext longtext
     }

To make this change for all lyrics in the score, set the property in the layout.

     
     \score {
       {
       c c c c
       c c c c
       }
       \addlyrics {
       longtext longtext longtext longtext
       longtext longtext longtext longtext
       }
       \layout {
         \context {
           \Lyrics
           \override LyricSpace #'minimum-distance = #1.0
         }
       }
     }

7.3.9 More about stanzas

7.3.9.1 Adding stanza numbers

Stanza numbers can be added by setting stanza, e.g.,

     
     \new Voice {
       \time 3/4 g2 e4 a2 f4 g2.
     } \addlyrics {
       \set stanza = "1. "
       Hi, my name is Bert.
     } \addlyrics {
       \set stanza = "2. "
       Oh, che -- ri, je t'aime
     }

These numbers are put just before the start of the first syllable.

7.3.9.2 Adding dynamics marks

Stanzas differing in loudness may be indicated by putting a dynamics mark before each stanza. In Lilypond, everthing coming in front of a stanza goes into the StanzaNumber object; dynamics marks are no different. For technical reasons, you have to set the stanza outside \lyricmode:

     
     text = {
       \set stanza = \markup { \dynamic "ff" "1. " }
       \lyricmode {
         Big bang
       }
     }
     
     <<
       \new Voice = "tune" {
         \time 3/4
         g'4 c'2
       }
     \new Lyrics \lyricsto "tune" \text
     >>

7.3.9.3 Adding singer names

Names of singers can also be added. They are printed at the start of the line, just like instrument names. They are created by setting vocalName. A short version may be entered as shortVocalName.

     
     \new Voice {
       \time 3/4 g2 e4 a2 f4 g2.
     } \addlyrics {
       \set vocalName = "Bert "
       Hi, my name is Bert.
     } \addlyrics {
       \set vocalName = "Ernie "
       Oh, che -- ri, je t'aime
     }

7.3.9.4 Printing stanzas at the end

Sometimes it is appropriate to have one stanza set to the music, and the rest added in verse form at the end of the piece. This can be accomplished by adding the extra verses into a \markup section outside of the main score block. Notice that there are two different ways to force linebreaks when using \markup.

     
     melody = \relative c' {
     e d c d | e e e e |
     d d e d | c1 |
     }
     
     text = \lyricmode {
     \set stanza = "1." Ma- ry had a lit- tle lamb,
     its fleece was white as snow.
     }
     
     \book{
       \score{ <<
         \new Voice = "one" { \melody }
         \new Lyrics \lyricsto "one" \text
     	>>
         \layout { }
       }
       \markup { \column{
         \line{ Verse 2. }
         \line{ All the children laughed and played }
         \line{ To see a lamb at school. }
         }
       }
       \markup{
         \wordwrap-string #"
         Verse 3.
     
         Mary took it home again,
     
         It was against the rule."
       }
     }

7.3.9.5 Printing stanzas at the end in multiple columns

When a piece of music has many verses, they are often printed in multiple columns across the page. An outdented verse number often introduces each verse. The following example shows how to produce such output in Lilypond.

     
     melody = \relative c' {
       c c c c | d d d d
     }
      
     text = \lyricmode {
       \set stanza = "1." This is verse one.
       It has two lines.
     }
     
     \score{ <<
         \new Voice = "one" { \melody }
         \new Lyrics \lyricsto "one" \text
        >>
       \layout { }
     }
     
     \markup {
       \fill-line {
         \hspace #0.1 % moves the column off the left margin; can be removed if
             % space on the page is tight
          \column {
           \line { \bold "2."
             \column {
               "This is verse two."
               "It has two lines."
             }
           }
           \hspace #0.1 % adds vertical spacing between verses
           \line { \bold "3."
             \column {
               "This is verse three."
               "It has two lines."
             }
           }
         }
         \hspace #0.1  % adds horizontal spacing between columns; if they are
             % still too close, add more " " pairs until the result 
             % looks good
          \column {
           \line { \bold "4."
             \column {
               "This is verse four."
               "It has two lines."
             }
           }
           \hspace #0.1 % adds vertical spacing between verses
           \line { \bold "5."
             \column {
               "This is verse five."
               "It has two lines."
             }
           }
         }
       \hspace #0.1 % gives some extra space on the right margin; can
           % be removed if page space is tight
       }
     }

See also

Program reference: LyricText, StanzaNumber, VocalName.

7.3.10 Ambitus

The term ambitus denotes a range of pitches for a given voice in a part of music. It may also denote the pitch range that a musical instrument is capable of playing. Ambits are printed on vocal parts, so performers can easily determine it meets their capabilities.

Ambits are denoted at the beginning of a piece near the initial clef. The range is graphically specified by two note heads that represent the minimum and maximum pitch. To print such ambits, add the Ambitus_engraver to the Voice context, for example,

\layout {
  \context {
    \Voice
    \consists Ambitus_engraver
  }
}

This results in the following output

If you have multiple voices in a single staff and you want a single ambitus per staff rather than per each voice, add the Ambitus_engraver to the Staff context rather than to the Voice context. Here is an example,

     
     \new Staff \with {
       \consists "Ambitus_engraver"
     }
     <<
       \new Voice \with {
         \remove "Ambitus_engraver"
       } \relative c'' {
         \override Ambitus #'X-offset = #-1.0
         \voiceOne
         c4 a d e f2
       }
       \new Voice \with {
         \remove "Ambitus_engraver"
       } \relative c' {
         \voiceTwo
         es4 f g as b2
       }
     >>

This example uses one advanced feature,

\override Ambitus #'X-offset = #-1.0

This code moves the ambitus to the left. The same effect could have been achieved with extra-offset, but then the formatting system would not reserve space for the moved object.

See also

Program reference: Ambitus, AmbitusLine, AmbitusNoteHead, AmbitusAccidental.

Examples: input/regression/ambitus.ly.

Bugs

There is no collision handling in the case of multiple per-voice ambitus.

7.3.11 Other vocal issues

“Parlato” is spoken without pitch but still with rhythm; it is notated by cross noteheads. This is demonstrated in Special noteheads.

7.4 Rhythmic music

Rhythmic music is primarily used for percussion and drum notation, but it can also be used to show the rhythms of melodies.

7.4.1 Showing melody rhythms

Sometimes you might want to show only the rhythm of a melody. This can be done with the rhythmic staff. All pitches of notes on such a staff are squashed, and the staff itself has a single line

     
     \new RhythmicStaff {
       \time 4/4
       c4 e8 f g2 | r4 g r2 | g1:32 | r1 |
     }

See also

Program reference: RhythmicStaff.

Examples: input/regression/rhythmic-staff.ly.

7.4.2 Entering percussion

Percussion notes may be entered in \drummode mode, which is similar to the standard mode for entering notes. Each piece of percussion has a full name and an abbreviated name, and both can be used in input files

     
     \drums {
       hihat hh bassdrum bd
     }

The complete list of drum names is in the init file ly/drumpitch-init.ly.

See also

Program reference: note-event.

7.4.3 Percussion staves

A percussion part for more than one instrument typically uses a multiline staff where each position in the staff refers to one piece of percussion.

To typeset the music, the notes must be interpreted in a DrumStaff and DrumVoice contexts

     
     up = \drummode { crashcymbal4 hihat8 halfopenhihat hh hh hh openhihat }
     down = \drummode { bassdrum4 snare8 bd r bd sn4 }
       \new DrumStaff <<
         \new DrumVoice { \voiceOne \up }
         \new DrumVoice { \voiceTwo \down }
       >>

The above example shows verbose polyphonic notation. The short polyphonic notation, described in Basic polyphony, can also be used if the DrumVoices are instantiated by hand first. For example,

     
     \new DrumStaff <<
       \new DrumVoice = "1" { s1 *2 }
       \new DrumVoice = "2" { s1 *2 }
       \drummode {
         bd4 sn4 bd4 sn4
         <<
           { \repeat unfold 16 hh16 }
           \\
           { bd4 sn4 bd4 sn4 }
         >>
       }
     >>

There are also other layout possibilities. To use these, set the property drumStyleTable in context DrumVoice. The following variables have been predefined

drums-style

This is the default. It typesets a typical drum kit on a five-line staff

The drum scheme supports six different toms. When there are fewer toms, simply select the toms that produce the desired result, i.e., to get toms on the three middle lines you use tommh, tomml, and tomfh.

timbales-style

This typesets timbales on a two line staff

congas-style

This typesets congas on a two line staff

bongos-style

This typesets bongos on a two line staff

percussion-style

To typeset all kinds of simple percussion on one line staves.

If you do not like any of the predefined lists you can define your own list at the top of your file

     
     #(define mydrums '(
              (bassdrum     default   #f         -1)
              (snare        default   #f         0)
              (hihat        cross     #f         1)
              (pedalhihat   xcircle   "stopped"  2)
              (lowtom       diamond   #f         3)))
     up = \drummode { hh8 hh hh hh hhp4 hhp }
     down = \drummode { bd4 sn bd toml8 toml }
     
     \new DrumStaff <<
       \set DrumStaff.drumStyleTable = #(alist->hash-table mydrums)
       \new DrumVoice { \voiceOne \up }
       \new DrumVoice { \voiceTwo \down }
     >>

See also

Init files: ly/drumpitch-init.ly.

Program reference: DrumStaff, DrumVoice.

Bugs

Because general MIDI does not contain rim shots, the sidestick is used for this purpose instead.

7.4.4 Ghost notes

Ghost notes for drums and percussion may be created using the \parenthesize command detailed in Parentheses. However, the default \drummode does not include the Parenthesis_engraver plugin which allows this. You must add the plugin explicitly in the context definition as detailed in Changing context properties on the fly.

     
     \new DrumStaff \with {
       \consists "Parenthesis_engraver"
     } <<
       \context DrumVoice  = "1"  { s1 *2 }
       \context DrumVoice  = "2" { s1 *2 }
       \drummode {
         <<
           {
             hh8[ hh] <hh sn> hh16
             < \parenthesize sn > hh < \parenthesize
             sn > hh8 <hh sn> hh
           } \\ {
             bd4 r4 bd8 bd r8 bd
           }
         >>
       }
     >>

Also note that you must add chords (< > brackets) around each \parenthesize statement.

7.5 Guitar

7.5.1 String number indications

String numbers can be added to chords, by indicating the string number with \number,

See also input/regression/string-number.ly.

See also

Program reference: StringNumber.

7.5.2 Tablatures basic

Tablature notation is used for notating music for plucked string instruments. Pitches are not denoted with note heads, but by numbers indicating on which string and fret a note must be played. LilyPond offers limited support for tablature.

The string number associated to a note is given as a backslash followed by a number, e.g., c4\3 for a C quarter on the third string. By default, string 1 is the highest one, and the tuning defaults to the standard guitar tuning (with 6 strings). The notes are printed as tablature, by using TabStaff and TabVoice contexts

     
     \new TabStaff {
       a,4\5 c'\2 a\3 e'\1
       e\4 c'\2 a\3 e'\1
     }

When no string is specified, the first string that does not give a fret number less than minimumFret is selected. The default value for minimumFret is 0

e16 fis gis a b4
\set TabStaff.minimumFret = #8
e16 fis gis a b4

Commonly tweaked properties

To print tablatures with stems down and horizontal beams, initialize the TabStaff with this code:

\stemDown
\override Beam #'damping = #100000

See also

Program reference: TabStaff, TabVoice.

Bugs

Chords are not handled in a special way, and hence the automatic string selector may easily select the same string to two notes in a chord.

7.5.3 Non-guitar tablatures

You can change the tuning of the strings. A string tuning is given as a Scheme list with one integer number for each string, the number being the pitch (measured in semitones relative to middle C) of an open string. The numbers specified for stringTuning are the numbers of semitones to subtract or add, starting the specified pitch by default middle C, in string order. LilyPond automatically calculates the number of strings by looking at stringTuning.

In the next example, stringTunings is set for the pitches e, a, d, and g

     
     \new TabStaff <<
       \set TabStaff.stringTunings = #'(-5 -10 -15 -20)
       {
         a,4 c' a e' e c' a e'
       }
     >>

LilyPond comes with predefined string tunings for banjo, mandolin, guitar and bass guitar.

\set TabStaff.stringTunings = #bass-tuning

The default string tuning is guitar-tuning (the standard EADGBE tuning). Some other predefined tunings are guitar-open-g-tuning, mandolin-tuning and banjo-open-g-tuning.

See also

The file scm/output-lib.scm contains the predefined string tunings. Program reference: Tab_note_heads_engraver.

Bugs

No guitar special effects have been implemented.

7.5.4 Banjo tablatures

LilyPond has basic support for five stringed banjo. When making tablatures for five stringed banjo, use the banjo tablature format function to get correct fret numbers for the fifth string:

     
     \new TabStaff <<
       \set TabStaff.tablatureFormat = #fret-number-tablature-format-banjo
       \set TabStaff.stringTunings = #banjo-open-g-tuning
       {
         \stemDown
         g8 d' g'\5 a b g e d' |
         g4 d''8\5 b' a'\2 g'\5 e'\2 d' |
         g4
       }
     >>

A number of common tunings for banjo are predefined in LilyPond: banjo-c-tuning (gCGBD), banjo-modal-tuning (gDGCD), banjo-open-d-tuning (aDF#AD) and banjo-open-dm-tuning (aDFAD).

These tunings may be converted to four string banjo tunings using the four-string-banjo function:

\set TabStaff.stringTunings = #(four-string-banjo banjo-c-tuning)

See also

The file scm/output-lib.scm contains predefined banjo tunings.

7.5.5 Fret diagrams

Fret diagrams can be added to music as a markup to the desired note. The markup contains information about the desired fret diagram, as shown in the following example

     
     \new Voice {
       d'^\markup \fret-diagram #"6-x;5-x;4-o;3-2;2-3;1-2;"
       d' d' d'
       fis'^\markup \override #'(size . 0.75) {
         \override #'(finger-code . below-string) {
           \fret-diagram-verbose #'((place-fret 6 2 1) (barre 6 1 2)
                                    (place-fret 5 4 3) (place-fret 4 4 4)
                                    (place-fret 3 3 2) (place-fret 2 2 1)
                                    (place-fret 1 2 1))
         }
       }
       fis' fis' fis'
       c'^\markup \override #'(dot-radius . 0.35) {
         \override #'(finger-code . in-dot) {
           \override #'(dot-color . white) {
             \fret-diagram-terse #"x;3-1-(;5-2;5-3;5-4;3-1-);"
           }
         }
       }
       c' c' c'
     }

There are three different fret-diagram markup interfaces: standard, terse, and verbose. The three interfaces produce equivalent markups, but have varying amounts of information in the markup string. Details about the markup interfaces are found at Overview of text markup commands.

You can set a number of graphical properties according to your preference. Details about the property interface to fret diagrams are found at fret-diagram-interface.

See also

Examples: input/test/fret-diagram.ly

7.5.6 Right hand fingerings

Right hand fingerings in chords can be entered using note-\rightHandFinger finger

  <c-\rightHandFinger #1 e-\rightHandFinger #2 >

for brevity, you can abbreviate \rightHandFinger to something short, for example RH,

#(define RH rightHandFinger)

Commonly tweaked properties

You may exercise greater control over right handing fingerings by setting strokeFingerOrientations,

     
     #(define RH rightHandFinger)
     {
       \set strokeFingerOrientations = #'(up down)
       <c-\RH #1 es-\RH #2 g-\RH #4 > 4
       \set strokeFingerOrientations = #'(up right down)
       <c-\RH #1 es-\RH #2 g-\RH #4 > 4
     }

The letters used for the fingerings are contained in the property digit-names, but they can also be set individually by supplying \rightHandFinger with a string argument, as in the following example

     
     #(define RH rightHandFinger)
     {
       \set strokeFingerOrientations = #'(right)
       \override StrokeFinger #'digit-names = ##("x" "y" "z" "!" "@") 
       <c-\RH #5 >4
       <c-\RH "@">4  
     }

See also

Internalls: StrokeFinger

7.5.7 Other guitar issues

This example demonstrates how to include guitar position and barring indications.

     
     \clef "G_8"
     b16 d16 g16 b16 e16
     \textSpannerDown
     \override TextSpanner #'edge-text = #'("XII " . "")
       g16\startTextSpan
       b16 e16 g16 e16 b16 g16\stopTextSpan
     e16 b16 g16 d16

Stopped (X) note heads are used in guitar music to signal a place where the guitarist must play a certain note or chord, with its fingers just touching the strings instead of fully pressing them. This gives the sound a percussive noise-like sound that still maintains part of the original pitch. It is notated with cross noteheads; this is demonstrated in Special noteheads.

7.6 Bagpipe

7.6.1 Bagpipe definitions

LilyPond contains special definitions for music for the Scottish highland bagpipe; to use them, add

\include "bagpipe.ly"

at the top of your input file. This lets you add the special gracenotes common to bagpipe music with short commands. For example, you could write \taor instead of

\grace { \small G32[ d G e] }

bagpipe.ly also contains pitch definitions for the bagpipe notes in the appropiate octaves, so you do not need to worry about \relative or \transpose.

     
     \include "bagpipe.ly"
     { \grg G4 \grg a \grg b \grg c \grg d \grg e \grg f \grA g A }

Bagpipe music nominally uses the key of D Major (even though that isn't really true). However, since that is the only key that can be used, the key signature is normally not written out. To set this up correctly, always start your music with \hideKeySignature. If you for some reason want to show the key signature, you can use \showKeySignature instead.

Some modern music use cross fingering on c and f to flatten those notes. This can be indicated by cflat or fflat. Similarly, the piobaireachd high g can be written gflat when it occurs in light music.

7.6.2 Bagpipe example

This is what the well known tune Amazing Grace looks like in bagpipe notation.

     
     \include "bagpipe.ly"
     \layout {
       indent = 0.0\cm
       \context { \Score \remove "Bar_number_engraver" }
     }
     
     \header {
       title = "Amazing Grace"
       meter = "Hymn"
       arranger = "Trad. arr."
     }
     
     {
       \hideKeySignature
       \time 3/4
       \grg \partial 4 a8. d16
       \slurd d2 \grg f8[ e32 d16.]
       \grg f2 \grg f8 e
       \thrwd d2 \grg b4
       \grG a2 \grg a8. d16
       \slurd d2 \grg f8[ e32 d16.]
       \grg f2 \grg e8. f16
       \dblA A2 \grg A4
       \grg A2 f8. A16
       \grg A2 \hdblf f8[ e32 d16.]
       \grg f2 \grg f8 e
       \thrwd d2 \grg b4
       \grG a2 \grg a8. d16
       \slurd d2 \grg f8[ e32 d16.]
       \grg f2 e4
       \thrwd d2.
       \slurd d2
       \bar "|."
     }

7.7 Ancient notation

Support for ancient notation includes features for mensural notation and Gregorian Chant notation. There is also limited support for figured bass notation.

Many graphical objects provide a style property, see

• Ancient note heads,
• Ancient accidentals,
• Ancient rests,
• Ancient clefs,
• Ancient flags,
• Ancient time signatures.

By manipulating such a grob property, the typographical appearance of the affected graphical objects can be accommodated for a specific notation flavor without the need for introducing any new notational concept.

In addition to the standard articulation signs described in section Articulations, specific articulation signs for ancient notation are provided.

• Ancient articulations

Other aspects of ancient notation can not that easily be expressed in terms of just changing a style property of a graphical object or adding articulation signs. Some notational concepts are introduced specifically for ancient notation,

• Custodes,
• Divisiones,
• Ligatures.

If this all is too much of documentation for you, and you just want to dive into typesetting without worrying too much about the details on how to customize a context, you may have a look at the predefined contexts. Use them to set up predefined style-specific voice and staff contexts, and directly go ahead with the note entry,

• Gregorian Chant contexts,
• Mensural contexts.

There is limited support for figured bass notation which came up during the baroque period.

• Figured bass

Here are all suptopics at a glance:

7.7.1 Ancient note heads

For ancient notation, a note head style other than the default style may be chosen. This is accomplished by setting the style property of the NoteHead object to baroque, neomensural, mensural or petrucci. The baroque style differs from the default style only in using a square shape for \breve note heads. The neomensural style differs from the baroque style in that it uses rhomboidal heads for whole notes and all smaller durations. Stems are centered on the note heads. This style is particularly useful when transcribing mensural music, e.g., for the incipit. The mensural style produces note heads that mimic the look of note heads in historic printings of the 16th century. Finally, the petrucci style also mimicks historic printings, but uses bigger note heads.

The following example demonstrates the neomensural style

     
     \set Score.skipBars = ##t
     \override NoteHead #'style = #'neomensural
     a'\longa a'\breve a'1 a'2 a'4 a'8 a'16

When typesetting a piece in Gregorian Chant notation, the Gregorian_ligature_engraver will automatically select the proper note heads, so there is no need to explicitly set the note head style. Still, the note head style can be set, e.g., to vaticana_punctum to produce punctum neumes. Similarly, a Mensural_ligature_engraver is used to automatically assemble mensural ligatures. See Ligatures for how ligature engravers work.

See also

Examples: input/regression/note-head-style.ly gives an overview over all available note head styles.

7.7.2 Ancient accidentals

Use the style property of grob Accidental to select ancient accidentals. Supported styles are mensural, vaticana, hufnagel, and medicaea.

As shown, not all accidentals are supported by each style. When trying to access an unsupported accidental, LilyPond will switch to a different style, as demonstrated in input/test/ancient-accidentals.ly.

Similarly to local accidentals, the style of the key signature can be controlled by the style property of the KeySignature grob.

See also

In this manual: Pitches, Cautionary accidentals and Automatic accidentals give a general introduction of the use of accidentals. Key signature gives a general introduction of the use of key signatures.

Program reference: KeySignature.

Examples: input/test/ancient-accidentals.ly.

7.7.3 Ancient rests

Use the style property of grob Rest to select ancient rests. Supported styles are classical, neomensural, and mensural. classical differs from the default style only in that the quarter rest looks like a horizontally mirrored 8th rest. The neomensural style suits well for, e.g., the incipit of a transcribed mensural piece of music. The mensural style finally mimics the appearance of rests as in historic prints of the 16th century.

The following example demonstrates the neomensural style

     
     \set Score.skipBars = ##t
     \override Rest #'style = #'neomensural
     r\longa r\breve r1 r2 r4 r8 r16

There are no 32th and 64th rests specifically for the mensural or neo-mensural style. Instead, the rests from the default style will be taken. See input/test/rests.ly for a chart of all rests.

There are no rests in Gregorian Chant notation; instead, it uses Divisiones.

See also

In this manual: Rests gives a general introduction into the use of rests.

7.7.4 Ancient clefs

LilyPond supports a variety of clefs, many of them ancient.

The following table shows all ancient clefs that are supported via the \clef command. Some of the clefs use the same glyph, but differ only with respect to the line they are printed on. In such cases, a trailing number in the name is used to enumerate these clefs. Still, you can manually force a clef glyph to be typeset on an arbitrary line, as described in Clef. The note printed to the right side of each clef in the example column denotes the c' with respect to that clef.

Description	Supported Clefs	Example
modern style mensural C clef	neomensural-c1, neomensural-c2, neomensural-c3, neomensural-c4
petrucci style mensural C clefs, for use on different staff lines (the examples show the 2nd staff line C clef)	petrucci-c1, petrucci-c2, petrucci-c3, petrucci-c4, petrucci-c5
petrucci style mensural F clef	petrucci-f
petrucci style mensural G clef	petrucci-g
historic style mensural C clef	mensural-c1, mensural-c2, mensural-c3, mensural-c4
historic style mensural F clef	mensural-f
historic style mensural G clef	mensural-g
Editio Vaticana style do clef	vaticana-do1, vaticana-do2, vaticana-do3
Editio Vaticana style fa clef	vaticana-fa1, vaticana-fa2
Editio Medicaea style do clef	medicaea-do1, medicaea-do2, medicaea-do3
Editio Medicaea style fa clef	medicaea-fa1, medicaea-fa2
historic style hufnagel do clef	hufnagel-do1, hufnagel-do2, hufnagel-do3
historic style hufnagel fa clef	hufnagel-fa1, hufnagel-fa2
historic style hufnagel combined do/fa clef	hufnagel-do-fa

Modern style means “as is typeset in contemporary editions of transcribed mensural music”.

Petrucci style means “inspired by printings published by the famous engraver Petrucci (1466-1539)”.

Historic style means “as was typeset or written in historic editions (other than those of Petrucci)”.

Editio XXX style means “as is/was printed in Editio XXX”.

Petrucci used C clefs with differently balanced left-side vertical beams, depending on which staff line it is printed.

See also

In this manual: see Clef.

Bugs

The mensural g clef is mapped to the Petrucci g clef.

7.7.5 Ancient flags

Use the flag-style property of grob Stem to select ancient flags. Besides the default flag style, only the mensural style is supported

     
     \override Stem #'flag-style = #'mensural
     \override Stem #'thickness = #1.0
     \override NoteHead #'style = #'mensural
     \autoBeamOff
     c'8 d'8 e'8 f'8 c'16 d'16 e'16 f'16 c'32 d'32 e'32 f'32 s8
     c''8 d''8 e''8 f''8 c''16 d''16 e''16 f''16 c''32 d''32 e''32 f''32

Note that the innermost flare of each mensural flag always is vertically aligned with a staff line.

There is no particular flag style for neo-mensural notation. Hence, when typesetting the incipit of a transcribed piece of mensural music, the default flag style should be used. There are no flags in Gregorian Chant notation.

Bugs

The attachment of ancient flags to stems is slightly off due to a change in early 2.3.x.

Vertically aligning each flag with a staff line assumes that stems always end either exactly on or exactly in the middle between two staff lines. This may not always be true when using advanced layout features of classical notation (which however are typically out of scope for mensural notation).

7.7.6 Ancient time signatures

There is limited support for mensural time signatures. The glyphs are hard-wired to particular time fractions. In other words, to get a particular mensural signature glyph with the \time n/m command, n and m have to be chosen according to the following table

Use the style property of grob TimeSignature to select ancient time signatures. Supported styles are neomensural and mensural. The above table uses the neomensural style. This style is appropriate for the incipit of transcriptions of mensural pieces. The mensural style mimics the look of historical printings of the 16th century.

The following examples show the differences in style,

See also

This manual: Time signature gives a general introduction to the use of time signatures.

Bugs

Ratios of note durations do not change with the time signature. For example, the ratio of 1 brevis = 3 semibrevis (tempus perfectum) must be made by hand, by setting

breveTP = #(ly:make-duration -1 0 3 2)
...
{ c\breveTP f1 }

This sets breveTP to 3/2 times 2 = 3 times a whole note.

The old6/8alt symbol (an alternate symbol for 6/8) is not addressable with \time. Use a \markup instead

7.7.7 Ancient articulations

In addition to the standard articulation signs described in section Articulations, articulation signs for ancient notation are provided. These are specifically designed for use with notation in Editio Vaticana style.

     
     \include "gregorian-init.ly"
     \score {
       \new VaticanaVoice {
         \override TextScript #'font-family = #'typewriter
         \override TextScript #'font-shape = #'upright
         \override Script #'padding = #-0.1
         a\ictus_"ictus" \break
         a\circulus_"circulus" \break
         a\semicirculus_"semicirculus" \break
         a\accentus_"accentus" \break
         \[ a_"episem" \episemInitium \pes b \flexa a b \episemFinis \flexa a \]
       }
     }

Bugs

Some articulations are vertically placed too closely to the correpsonding note heads.

The episem line is not displayed in many cases. If it is displayed, the right end of the episem line is often too far to the right.

7.7.8 Custodes

A custos (plural: custodes; Latin word for ‘guard’) is a symbol that appears at the end of a staff. It anticipates the pitch of the first note(s) of the following line thus helping the performer to manage line breaks during performance.

Custodes were frequently used in music notation until the 17th century. Nowadays, they have survived only in a few particular forms of musical notation such as contemporary editions of Gregorian chant like the editio vaticana. There are different custos glyphs used in different flavors of notational style.

For typesetting custodes, just put a Custos_engraver into the Staff context when declaring the \layout block, as shown in the following example

\layout {
  \context {
    \Staff
    \consists Custos_engraver
    Custos \override #'style = #'mensural
  }
}

The result looks like this

The custos glyph is selected by the style property. The styles supported are vaticana, medicaea, hufnagel, and mensural. They are demonstrated in the following fragment

See also

Program reference: Custos.

Examples: input/regression/custos.ly.

7.7.9 Divisiones

A divisio (plural: divisiones; Latin word for ‘division’) is a staff context symbol that is used to structure Gregorian music into phrases and sections. The musical meaning of divisio minima, divisio maior, and divisio maxima can be characterized as short, medium, and long pause, somewhat like the breathmarks from Breath marks. The finalis sign not only marks the end of a chant, but is also frequently used within a single antiphonal/responsorial chant to mark the end of each section.

To use divisiones, include the file gregorian-init.ly. It contains definitions that you can apply by just inserting \divisioMinima, \divisioMaior, \divisioMaxima, and \finalis at proper places in the input. Some editions use virgula or caesura instead of divisio minima. Therefore, gregorian-init.ly also defines \virgula and \caesura

Predefined commands

\virgula, \caesura, \divisioMinima, \divisioMaior, \divisioMaxima, \finalis.

See also

In this manual: Breath marks.

Program reference: BreathingSign.

Examples: input/test/divisiones.ly.

7.7.10 Ligatures

A ligature is a graphical symbol that represents at least two distinct notes. Ligatures originally appeared in the manuscripts of Gregorian chant notation to denote ascending or descending sequences of notes.

Ligatures are entered by enclosing them in \[ and \]. Some ligature styles may need additional input syntax specific for this particular type of ligature. By default, the LigatureBracket engraver just puts a square bracket above the ligature

     
     \transpose c c' {
       \[ g c a f d' \]
       a g f
       \[ e f a g \]
     }

To select a specific style of ligatures, a proper ligature engraver has to be added to the Voice context, as explained in the following subsections. Only white mensural ligatures are supported with certain limitations.

Bugs

Ligatures need special spacing that has not yet been implemented. As a result, there is too much space between ligatures most of the time, and line breaking often is unsatisfactory. Also, lyrics do not correctly align with ligatures.

Accidentals must not be printed within a ligature, but instead need to be collected and printed in front of it.

The syntax still uses the deprecated infix style \[ music expr \]. For consistency reasons, it will eventually be changed to postfix style note\[ ... note\]. Alternatively, the file gregorian-init.ly can be included; it provides a scheme function

\ligature music expr

with the same effect and is believed to be stable.

7.7.10.1 White mensural ligatures

There is limited support for white mensural ligatures.

To engrave white mensural ligatures, in the layout block put the Mensural_ligature_engraver into the Voice context, and remove the Ligature_bracket_engraver, like this

\layout {
  \context {
    \Voice
    \remove Ligature_bracket_engraver
    \consists Mensural_ligature_engraver
  }
}

There is no additional input language to describe the shape of a white mensural ligature. The shape is rather determined solely from the pitch and duration of the enclosed notes. While this approach may take a new user a while to get accustomed to, it has the great advantage that the full musical information of the ligature is known internally. This is not only required for correct MIDI output, but also allows for automatic transcription of the ligatures.

For example,

\set Score.timing = ##f
\set Score.defaultBarType = "empty"
\override NoteHead #'style = #'neomensural
\override Staff.TimeSignature #'style = #'neomensural
\clef "petrucci-g"
\[ c'\maxima g \]
\[ d\longa c\breve f e d \]
\[ c'\maxima d'\longa \]
\[ e'1 a g\breve \]

Without replacing Ligature_bracket_engraver with Mensural_ligature_engraver, the same music transcribes to the following

Bugs

Horizontal spacing is poor.

7.7.10.2 Gregorian square neumes ligatures

There is limited support for Gregorian square neumes notation (following the style of the Editio Vaticana). Core ligatures can already be typeset, but essential issues for serious typesetting are still lacking, such as (among others) horizontal alignment of multiple ligatures, lyrics alignment and proper handling of accidentals.

The following table contains the extended neumes table of the 2nd volume of the Antiphonale Romanum (Liber Hymnarius), published 1983 by the monks of Solesmes.

Neuma aut Neumarum Elementa	Figurae Rectae	Figurae Liquescentes Auctae	Figurae Liquescentes Deminutae
1. Punctum
2. Virga
3. Apostropha vel Stropha
4. Oriscus
5. Clivis vel Flexa
6. Podatus vel Pes
7. Pes Quassus
8. Quilisma Pes
9. Podatus Initio Debilis
10. Torculus
11. Torculus Initio Debilis
12. Porrectus
13. Climacus
14. Scandicus
15. Salicus
16. Trigonus

Unlike most other neumes notation systems, the input language for neumes does not reflect the typographical appearance, but is designed to focus on musical meaning. For example, \[ a \pes b \flexa g \] produces a Torculus consisting of three Punctum heads, while \[ a \flexa g \pes b \] produces a Porrectus with a curved flexa shape and only a single Punctum head. There is no command to explicitly typeset the curved flexa shape; the decision of when to typeset a curved flexa shape is based on the musical input. The idea of this approach is to separate the musical aspects of the input from the notation style of the output. This way, the same input can be reused to typeset the same music in a different style of Gregorian chant notation.

The following table shows the code fragments that produce the ligatures in the above neumes table. The letter in the first column in each line of the below table indicates to which ligature in the above table it refers. The second column gives the name of the ligature. The third column shows the code fragment that produces this ligature, using g, a, and b as example pitches.

#	Name	Input Language
a	Punctum	\[ b \]
b	Punctum Inclinatum	\[ \inclinatum b \]
c	Punctum Auctum Ascendens	\[ \auctum \ascendens b \]
d	Punctum Auctum Descendens	\[ \auctum \descendens b \]
e	Punctum Inclinatum Auctum	\[ \inclinatum \auctum b \]
f	Punctum Inclinatum Parvum	\[ \inclinatum \deminutum b \]
g	Virga	\[ \virga b \]
h	Stropha	\[ \stropha b \]
i	Stropha Aucta	\[ \stropha \auctum b \]
j	Oriscus	\[ \oriscus b \]
k	Clivis vel Flexa	\[ b \flexa g \]
l	Clivis Aucta Descendens	\[ b \flexa \auctum \descendens g \]
m	Clivis Aucta Ascendens	\[ b \flexa \auctum \ascendens g \]
n	Cephalicus	\[ b \flexa \deminutum g \]
o	Podatus vel Pes	\[ g \pes b \]
p	Pes Auctus Descendens	\[ g \pes \auctum \descendens b \]
q	Pes Auctus Ascendens	\[ g \pes \auctum \ascendens b \]
r	Epiphonus	\[ g \pes \deminutum b \]
s	Pes Quassus	\[ \oriscus g \pes \virga b \]
t	Pes Quassus Auctus Descendens	\[ \oriscus g \pes \auctum \descendens b \]
u	Quilisma Pes	\[ \quilisma g \pes b \]
v	Quilisma Pes Auctus Descendens	\[ \quilisma g \pes \auctum \descendens b \]
w	Pes Initio Debilis	\[ \deminutum g \pes b \]
x	Pes Auctus Descendens Initio Debilis	\[ \deminutum g \pes \auctum \descendens b \]
y	Torculus	\[ a \pes b \flexa g \]
z	Torculus Auctus Descendens	\[ a \pes b \flexa \auctum \descendens g \]
A	Torculus Deminutus	\[ a \pes b \flexa \deminutum g \]
B	Torculus Initio Debilis	\[ \deminutum a \pes b \flexa g \]
C	Torculus Auctus Descendens Initio Debilis	\[ \deminutum a \pes b \flexa \auctum \descendens g \]
D	Torculus Deminutus Initio Debilis	\[ \deminutum a \pes b \flexa \deminutum g \]
E	Porrectus	\[ a \flexa g \pes b \]
F	Porrectus Auctus Descendens	\[ a \flexa g \pes \auctum \descendens b \]
G	Porrectus Deminutus	\[ a \flexa g \pes \deminutum b \]
H	Climacus	\[ \virga b \inclinatum a \inclinatum g \]
I	Climacus Auctus	\[ \virga b \inclinatum a \inclinatum \auctum g \]
J	Climacus Deminutus	\[ \virga b \inclinatum a \inclinatum \deminutum g \]
K	Scandicus	\[ g \pes a \virga b \]
L	Scandicus Auctus Descendens	\[ g \pes a \pes \auctum \descendens b \]
M	Scandicus Deminutus	\[ g \pes a \pes \deminutum b \]
N	Salicus	\[ g \oriscus a \pes \virga b \]
O	Salicus Auctus Descendens	\[ g \oriscus a \pes \auctum \descendens b \]
P	Trigonus	\[ \stropha b \stropha b \stropha a \]