GNU LilyPond

This document is also available in gzipped PostScript and PDF.

This file documents GNU LilyPond.

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

A further source of information is the website, which can be found at http://www.lilypond.org/. The website contains on-line copies of this and other documentation.

We would like to dedicate this program to all the friends that we met through music.
Han-Wen and Jan

GNU LilyPond -- The music typesetter
Preface
- Preface to version 1.8
- Preface to version 1.6
Introduction
Tutorial
Notation manual
Literature
Technical manual
Invoking LilyPond
lilypond-book manual
Converting from other formats
Index
Reference manual details
Cheat sheet
GNU Free Documentation License

Preface

Preface to version 1.8

If you are familiar with LilyPond version 1.6, then version 1.8 will no offer no big surprises. The only conspicuous change is in the way that formatted text is entered. There is now a new syntax that is more friendly, more versatile and extensible. We hope you like it. In general, development on version 1.8 has been focused on improving the design of various internal mechanisms. This includes chord name formatting and entry code, music expression storage, and integration between LilyPond and Scheme. These changes may not be evident directly, but they make the program more robust and more flexible, which translates into fewer bugs and more adjustment options.

Special thanks for version 1.8 go out to Juergen Reuter for lots of work on the ancient notation engine, and to Amy Zapf for pushing us to rewrite the chord name support.

Han-Wen and Jan,

Utrecht/Eindhoven, The Netherlands, April/May 2003.

Preface to version 1.6

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 e-mail 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 is 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 that use LilyPond, and produce impressive pieces of sheet music. Seeing that still 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 bugreports. So first and foremost, we would like to thank all users that sent us bugreports, gave suggestions or contributed in any other way to LilyPond.

We would also like to thank the following people: Mats Bengtsson for the incountable number of questions he answered on the mailing list, and Rune Zedeler for his energy in finding and fixing bugs. Nicola Bernardini for inviting us to his workshop on music publishing, which was truly a masterclass, and Heinz Stolba and James Ingram for teaching us there.

Playing and printing music is more than 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.

Introduction

There are a lot of programs that let you print sheet music with a computer. Unfortunately, most of them do not do good job. Most computer printouts have a bland, mechanical look, and are unpleasant to play from. If you agree with us on that, then you will like LilyPond: we have tried to capture the original look of hand-engraved music in a program: we have tuned our algorithms, font-designs, and program settings to make the output match that of the old editions that we love to see and love to play from.

Music notation and engraving

Making sheet music may seem trivial, "you print 5 lines, and then put in the notes at different heights", but as you learn more of it, the opposite turns out to be true. One has to master two difficult tasks. First, one has to master music notation: the science of knowing which symbols to use for what. Second, one has to master music engraving: the art of placing symbols such that the result looks pleasing.

A fragment of neume notation

Common music notation has its roots in the medieval time. In this time, monks started to write down hints that indicated how their sacred music was sung. These hints, neumes, gradually became simpler, and at some point became the note heads. Lines were added to the neumes, to indicate a reference pitch, which later became the staff. Over many centuries, improvements and extensions were added, while other concepts disappeared. For example, the neume notation did not have an explicit notion of rhythm, but it did have custodes, symbols at the end of the line to indicate the starting pitch of the next line. Mensural notation, a notation where each note head takes a fixed amount of time, came into being together with the rise of counterpoint in the early renaissance. The graphic language of notation is still under development; the innovations of contemporary music require still newer and more complex notations.

The term music engraving derives from the traditional process of music printing. Only a few decades ago, sheet music was made by cutting and stamping the music into zinc or pewter plates, in mirror image. The plate would be inked, and 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 corrections was cumbersome, so engraving had to be done correctly in one go. Of course, this was a highly specialized skill, much more so than the traditional process of printing books. In the traditional German system of craftsmanship six years of full-time training, more than any other craft, were required before a student could call himself a master of the art. After that many more years of practical experience were needed to become an established music engraver. Even today, with the use of high-speed computers and advanced software, music requires lots of manual fine tuning before it is acceptable for publication.

Sheet music is performance material: everything is done to aid the musician in letting him perform better. Music often is far away from its reader--it might be on a music stand. To make it clearly readable, traditionally printed sheet music always uses bold symbols, on heavy staff lines, and is printed on large sheets of paper. This "strong" look is also present in the horizontal spacing. To minimize the number of page breaks, (hand-engraved) sheet music is spaced very tightly. Yet, by a careful distribution of white space, the feeling of balance is retained, and a clutter of symbols is avoided.

Notation and engraving in LilyPond

Common music notation encompasses such a wide scope of music, and therefore inherently is complex: there are many rules, and for every rule there are exceptional situations where they do not apply. The result is that LilyPond cannot support each and every form of notation in existence. Rather, we focus on a specific style and idiom: we take inspiration from late-romantic music printed at the beginning of the 20th century. Most of the contemporary music after that, and most of the music going back to 17th century can be written in this idiom. That is not a fundamental limit, though. There is support for some modern notation like clusters, and older notation, such as white mensural and gregorian notation, is being worked on.

We have used these observations in designing LilyPond. The images below show the flat symbol. On the left, a scan from a Henle edition, which was made by a computer, and in the center is the flat from a hand engraved Bärenreiter edition of the same music. The left scan illustrates typical flaws of computer print: the symbol is much lighter, the staff lines are thinner, and the glyph has a straight layout with sharp corners. By contrast, the Bärenreiter has a bold and almost voluptuous rounded look. Our flat symbol is designed after, among others, this one. It is tuned it to harmonize with the thickness of our staff lines, which are also much thicker than Henle's lines.

Henle (2000) Bärenreiter (1950) LilyPond Feta font (2003)

In spacing, the distribution of space should reflect the durations between notes. However, adhering with mathematical precision to the duration will lead to a poor result. Shown here is an example of a motive, printed twice. It is printed using exact mathematical spacing, and with some corrections. Can you spot which fragment is which?

The fragment only uses quarter notes: notes that are played in a constant rhythm. The spacing should reflect that. Unfortunately, the eye deceives us a little: not only does it notice the distance between note heads, it also takes into account the distance between consecutive stems. As a result, the notes of an up-stem/down-stem combination should be put farther apart, and the notes of a down-up combination should be put closer together, all depending on the combined vertical positions of the notes. The first two measures are printed with this correction, the last two measures without. The notes in the last two measures form down-stem/up-stems clumps of notes.

Typography and program architecture

Producing good engraving requires skill and knowledge. As the previous examples show, there is a lot of subtlety involved in music engraving, and unfortunately, only a small fraction of these details are documented. Master engraver must learn all these details from experience or from other engravers, which is why it takes so long to become a master. As an engraver gets older and wiser, he will be able to produce better and more complex pieces. A similar situation is present when putting typographical knowledge into a computer program. It is not possible to come up with a definitive solution for a problem at the first try. Instead, we start out with simple solution that might cover 75% of the cases, and gradually refine that solution over the course of months or years, so 90 or 95 % of the cases are handled.

This has an important implication for the design of the program: at any time, almost every piece of formatting code must be considered as temporary. When the need arises, it is to be replaced a solution that will cover even more cases. is A "plug-in" architecture is a clean way to accomplish this. This is an architecture where new pieces of code can be inserted in the program dynamically. In such a program, a new solution can be developed along-side the existing code. For testing, it is plugged in, but for production use, the old solution is used. The new module can be perfected separately until it is better than the existing solution, at which point it replaces the old one.

Until that time, users must have a way to deal with imperfections: these 25%, 10% or 5% of the cases that are not handled automatically. In these cases, a user must be able to override formatting decisions. A way to accomplish this, is to store decisions in generic variables, and let the user manipulate these variables. For example, consider the following fragment of notation:

The position of the forte symbol is slightly awkward, because it is next to the low note, whereas dynamics should be below notes in general. This may be remedied by inserting extra space between the high note and the `f', as shown in this example:

This was achieved with the following input statement:

        \once \property Voice. DynamicLineSpanner  \override #'padding = #4.0

It increases the amount of space (padding) between the note and the dynamic symbol to 4.0 (which is measured in staff space, so 4.0 equals the height of a staff). The keyword \once indicates that this is a tweak: it is only done one time.

Both design aspects, a plug-in architecture, and formatting variables, are built on top of GUILE, an interpreter for the programming language Scheme, which is a member of the LISP family. Variables are stored as Scheme objects, and attached to graphical objects such as note heads and stems. The variables are a means to adjust formatting details in individual cases, but they are used in a more general manner.

Consider the case of a publisher that is not satisfied with the in the default layout, and wants heavier stems. Normally, they are 1.3 times the thickness of staff lines, but suppose that their editions require them to be twice the thickness of the staff lines. The same mechanism can be used to adjust a setting globally. By issuing the following command, the entire piece is now formatted with thicker stems:

         \property Score.Stem \override #'thickness = #2.0

In effect, by setting these variables, users can define their own layout styles.

"Plug-ins" are also implemented using Scheme. A formatting "plug-in" takes the form of a function written in Scheme (or a C++ function made available as a Scheme function), and it is also stored in a variable. For example, the placement of the forte symbol in the example above is calculated by the function Side_position_interface::aligned_side. If we want to replace this function by a more advanced one, we could issue

         \property Voice.DynamicLineSpanner \override #'Y-offset-callbacks
            = #`(,gee-whiz-gadget)

Now, the formatting process will trigger a call to our new gee-whiz-gadget function when the position of the f symbol has to be determined.

The full scope of this functionality certainly is intimidating, but there is no need to fear: normally, it is not necessary to define style-sheets or rewrite formatting functions. In fact, LilyPond gets a lot of formatting right automatically, so adjusting individual layout situations is not needed often at all.

Music representation

Our premise is that LilyPond is a system that does music formatting completely automatically. Under this assumption, the output does not have to be touched up. Consequently, an interactive display of the output, where it is possible to reposition notation elements, is superfluous. This implies that the program should be a batch program: the input is entered in a file, which then is compiled, i.e. put through the program. The final output is produced as a file ready to view or print. The compiler fills in all the details of the notation, those details should be left out of the input file. In other words, the input should mirror the content as closely as possible. In the case of music notation the content is the music itself, so that is what the input should consist of.

On paper this theory sounds very good. In practice, it opens a can of worms. What really is music? Many philosophical treatises must have been written on the subject. Instead of losing ourselves in philosophical arguments over the essence of music, we have reversed the question to yield a more practical approach. Our assumption is that the printed score contains all of the music of piece. We build a program that uses some input format to produce such a score. Over the course of time, the program evolves. While this happens, we can remove more and more elements of the input format: as the program improves, it can fill in irrelevant details of the input by itself. At some (hypothetical) point, the program is finished: there is no possibility to remove any more elements from the syntax. What we have left is by definition exactly the musical meaning of the score.

There are also more practical concerns. Our users have to key in the music into the file directly, so the input format should have a friendly syntax: a quarter note C is entered as c4, the code r8. signifies a dotted eighth rest. Notes and rests form the simplest musical expressions in the input syntax. More complex constructs are produced by combining them into compound structures. This is done in much the same way that complex mathematical formulas are built from simple expressions such as numbers and operators.

In effect, the input format is a language, and the rules of that language can be specified succinctly with a so-called context-free grammar. The grammar formally specificies what types of input form valid `sentences'. Reading such languages, and splitting them into grammatical structures is a problem with standard solutions. Moreover, they make the format easier to understand: a concise formal definition permits a simple informal description.

The user-interface of LilyPond is its syntax. That part is what users see most. As a results, some users think that music representation is a very important or interesting problem. In reality, less than 10% of the source code of the program handles reading and representing the input, and they form the easy bits of the program. In our opinion, producing music notation, and formatting it prettily are much more interesting and important than music representation: solving these problems takes up most of the bulk of the code, and they are the most difficult things to get right.

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 plain 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 PostScript or HTML output files. This makes it easy to mix music and text in documents.

About this manual

The manual is divided into the following chapters:

Tutorial gives a gentle introduction into typesetting music. First time users should start here.
The Notation manual discusses topics grouped by notation construct. Once you master the basics, this is the place to lookup details.
The Literature chapter lists useful reference books on notation and engraving.
The Technical manual discusses the general design of the program, and how to extend its functionality.
The chapter Invoking LilyPond explains how to run LilyPond and its helper programs.

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 a big HTML 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), then it is advisable to consult the glossary as well. The glossary explains musical terms, and includes translations to various languages. It is a separate document.

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 (available here)
The program reference is a set of heavily crosslinked HTML pages, which documents the nit-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 thicknesses, distances, etc, can be changed in input files. There are a huge number of formatting options, and all of them are described in the generated documentation. Each section of the notation manual has a See also subsection, which refers to the the generated documentation. In the HTML document, these subsections have clickable links.
Templates (available here)
After you have gone through the tutorial, in theory you should be able to write input files. In practice, writing files from scratch turns out to be intimidating. To give you a headstart, we have collected a number of often-used formats in example files. These files can be used as a start, by copying the template, and adding notes in the appropriate places.
Various input examples (available here)
These small files show various tips and tricks, and are available as a big HTML document, with pictures and explanatory texts included.
The regression test (available here)
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 excercise the program. The format is like the tips and tricks document.

In all HTML documents that have music fragments embedded, the LilyPond input that was used to produce that image can be viewed by clicking the image.

The location of the documentation files that are mentioned here can vary from system to system. On occasion, this manual refers to initialization and example files. Throughout this manual, we refer to input files relative to the top-directory of the source archive. For example, input/test/bla.ly may refer to the file lilypond-1.7.19/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/.

Tutorial

Using LilyPond comes down to encoding music in an input file. After entering the music, the program is run on the file producing output which can be viewed or printed. In this tutorial, we will show step by step how to enter such files, by showing fragments of input and the corresponding output. At the end of every section, a paragraph will list where to find further information on the topics discussed.

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. For example, consider the following input:

       c'^\markup { \bold \huge { Click on this image! } }

with the following output:

By cutting and pasting the full input into a test file, you have a starting template for experiments. If you like learning in this way, you will probably want to print out or bookmark the Cheat sheet, which is a table listing all commands for quick reference.

This tutorial starts with a short introduction to the LilyPond music language. After this first contact, we will show you how to to produce printed output, normally using the program ly2dvi. You should then be able to create and print your first sheets of music.

First steps

We start off by showing how very simple music is entered in LilyPond: you get a note simply by typing its note name, from a through g. So if you enter

     c d e f g a b

then the result looks like this:

The length of a note is specified by adding a number, 1 for a whole note, 2 for a half note, and so on:

     a1 a2 a4 a16 a32

If you do not specify a duration, the previous one is used:

     a4 a a2 a

Rests are entered just like notes, but with the name "r":

          r2 r4 r8 r16

Add a dot . after the duration to get a dotted note:

     a2. a4 a8. a16

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

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

The clef can be set using the \clef command:

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

Notes and commands like \clef and \time , are enclosed in \notes {...}. This indicates that music (as opposed to lyrics) follows:

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

Now the piece of music is almost ready to be printed. The final step is to combine the music with a printing command.

The printing command is the so-called \paper block. The \paper block is used to customize printing specifics, but we accept the defaults for now. The music and the \paper block are combined by enclosing them in \score { ... }. The following is a complete and valid input file.

     \score {
       \notes {
         \time 3/4
         \clef bass
         c2 e4 g2.
         f4 e d c2 r4
       }
       \paper { }
     }

During the rest of the tutorial, we will often leave out \score and \paper, for clarity. However, both must be present when feeding the file to LilyPond.

More elaborate information on entering pitches and durations is in Pitches and Durations. Clefs are fully explained in Clef. Time signatures and other timing commands are described in Time signature.

Running LilyPond

In the last section we explained what kind of things you could enter in a LilyPond file. In this section we explain what commands to run and how to view or print the output. If you have not used LilyPond before, want to test your setup, or want to run an example file yourself, read this section. The instructions that follow are for Unix-like systems. Some additional instructions for Microsoft Windows are given at the end of this section.

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:

          \score {
            \notes { c'4 e' g' }
          }

LilyPond is the program that computes the sheet music. All other things, such as adding titles, page breaking and other page layout, are done by a small wrapper program called ly2dvi. ly2dvi calls LilyPond to render the music, and then adds the titling and page layout instructions. To process test.ly with ly2dvi, proceed as follows:

          ly2dvi -p test.ly

You will see something resembling:

          GNU LilyPond 1.8.0
          Now processing: `/home/fred/ly/test.ly'
          Parsing...
          Interpreting music...[1]
            ... more interesting stuff ... 
          PDF output to `test.pdf'...
          DVI output to `test.dvi'...

The result of the ly2dvi is the file test.pdf.³ One of the following commands should put the PDF on your screen:

            gv test.pdf
            ghostview test.pdf
            ggv test.pdf
            kghostview test.pdf
            xpdf test.pdf
            gpdf test.pdf
            acroread test.pdf
            gsview32 test.pdf

If the music on your screen looks good, you can print it by clicking File/Print inside your viewing program.

On Windows, the same procedure should work, the terminal is started by clicking on the LilyPond or Cygwin icon. Any text editor (such as NotePad, Emacs or Vim) may be used to edit the LilyPond file.

To view the PDF file, try the following:

If your system has a PDF viewer installed, open C:\Cygwin\home\your-name in the explorer and double-click test.pdf.
If you prefer the keyboard, you can also try the list of commands shown before. If none work, go to http://www.cs.wisc.edu/~ghost/ to install the proper software.

The commands for formatting and printing music on all platforms are detailed in Invoking LilyPond.

More about pitches and accidentals

A sharp (#) is made by adding is, a flat (b) by adding es. As you might expect, a double sharp or double flat is made by adding isis or eses:⁴

     cis1 ees fisis aeses

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

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

A tie is created by adding a tilde "~" to the first note being tied:

          g4-~ g a2-~ a4

This example shows the key signature, accidentals and ties in action:

          \score {
            \notes {
              \time 4/4
              \key g \minor
              \clef violin
              r4 r8 a8 gis4 b
              g8 d4.-~ d e'8
              fis4 fis8 fis8 eis4  a8 gis-~
              gis2 r2
            }
            \paper { }
          }

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

Accidentals (sharps and flats) do not have to be marked explicitly: you just enter the pitch of the note, and an accidental is printed only when necessary. The flip side of this mechanism, is that you have to mark notes as sharp or flat, even when they do not get accidentals. For example, in this example:

no note gets an explicit accidental, but still you enter

     \clef bass
     \key cis \major
     cis dis eis fis gis ais bis

Adding all alterations explicitly might require some more effort when typing, but the advantage is that transposing is easier. It also makes it possible to use different conventions for when to print accidentals.

Beams are drawn automatically, but if you do not like where they are put, they can be entered by hand. Mark the first note to be beamed with [ and the last one with ]:

          a8-[ ais-] d-[ es r d-]

Rests are described in full detail in Rests.

The notation manual discusses ties in Ties.

Octave entry

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

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

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

       \key a \major
       \time 6/8
       cis''8. d''16 cis''8 e''4 e''8
       b'8. cis''16 b'8 d''4 d''8

This example shows that music in a high register needs lots of quotes. This makes the input less readable, and it is a source of errors. The solution is to use "relative octave" mode. In practice, this is the most convenient way to copy existing music. To use relative mode, add \relative before the piece of music. You must also give a note from which relative starts, in this case c''. If you do not use octavation quotes (i.e. do not add ' or , after a note), relative mode chooses the note that is closest to the previous one. For example, c f goes up while c g goes down:

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

Since most music has small intervals, in relative mode pieces can be written almost without using octavation quotes. In relative mode, the Mozart example is entered as

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

Larger intervals are made by adding octavation quotes. Quotes or commas do not determine the absolute height of a note; the height of a note is relative to the previous one. For example: c f, goes down; f, f are both the same; c' c are the same; and c g' goes up:

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

Here is an example of the difference between relative mode and "normal" (non-relative) mode:

          \relative a {
          \clef bass
            a d a e d c' d'
          }

          \clef bass
            a d a e d c' d'

Combining music into compound expressions

To print more than one staff, each piece of music that makes up a staff is marked by adding \context Staff before it. These Staff's are then grouped inside \simultaneous { and }, as is demonstrated here:

          \simultaneous {
            \context Staff = staffA { \clef violin c'' }
            \context Staff = staffB { \clef bass c }
          }

In this example, \simultaneous indicates that both music fragments happen at the same time, and must be printed stacked vertically. The notation < .. > can also be used as a shorthand for \simultaneous { .. }.

\context introduces a "notation context". To understand this concept, imagine that you are performing a piece of music. When you perform the music, you combine the symbols printed at a certain point with contextual information. For example, without knowing the current clef, and the accidentals in the last measure, it would be impossible to determine the pitch of a note. In other words, this information forms context that helps you decipher a score. LilyPond produces notation from music, so in effect, it does the inverse of reading scores. Therefore, it also needs to keep track of contextual information. This information is maintained in "notation contexts." There are several types of contexts, e.g. Staff, Voice and Score, but also Lyrics and ChordNames. Prepending \context to a chunk of music indicates what kind of context to use for interpreting it.

By specifying different names (in this case staffA and staffB), two different contexts are created, leading to two staves. It does not matter which names they are given, as long as they are different. If they get the same name, the chunks of music are assumed to belong on the same staff, and will be printed like that.

We can now typeset a melody with two staves:

          \score {
            \notes
            < \context Staff = staffA {
                \time 3/4
                \clef violin
                \relative c'' {
                  e2-( d4 c2 b4 a8-[ a-]
                  b-[ b-] g-[ g-] a2.-) }
              }
              \context Staff = staffB {
                 \clef bass
                 c2 e4  g2.
                 f4 e d c2.
              }
            >
            \paper {}
          }

The example shows how small chunks of music, for example, the notes c2, e4, etc. of the second staff, are combined to form a larger chunk by enclosing it in braces. Again, a larger chunk is formed by prefix \context Staff to it, and that chunk is combined with < >. This mechanism is similar with mathematical formulas: in a formula, a so-called expression is formed by combining simpler expressions into larger expressions. For example,

1
1 + 2
(1 + 2) * 3
((1 + 2) * 3) / (4 * 5)

is a sequence of expressions, where each expression is contained in the next one. The simplest expressions are numbers and operators (like +, * and /). Parentheses are used to group expressions. In LilyPond input, a similar mechanism is used. Here, the simplest expressions are notes and rests. By enclosing expressions in

<
>

and { }, more complex music is formed. The \context also forms new expressions; prepending it to a music expression yields a new expression.

Like mathematical expressions, music expressions can be nested arbitrarily deep, e.g.

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

When spreading expressions over multiple lines, it is customary to use an indent that indicates the nesting level. Formatting music like this eases reading, and helps you insert the right amount of closing braces at the end of an expression. For example,

     \score {
       \notes <
         {
           ...
         }
         {
           ...
         }
       >
     }

Adding articulation marks to notes

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

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

Similarly, fingering indications can be added to a note using a dash (`-') and the digit to be printed:

       c-3 e-5 b-2 a-1

Dynamic signs are made by adding the markings to the note:

          c-\ff c-\mf

Crescendi and decrescendi are started with the commands \< and \>. The command \! finishes a crescendo on the note it is attached to:

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

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

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

A slur is different from a tie. A tie simply makes the first note sound longer, and can only be used on pairs of notes with the same pitch. Slurs indicate the articulations of notes, and can be used on larger groups of notes. Slurs and ties are also nested in practice:

If you need two slurs at the same time (one for articulation, one for phrasing), you can also make a phrasing slur with \( and \).

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

More information on fingering, articulation, slurs, phrasing slurs, and dynamics can be found in Fingering instructions, Articulations, Slurs, Phrasing slurs, and Dynamics, respectively.

Combining notes into chords

Chords can be made by surrounding pitches with << and >>:

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

You can combine beams and ties with chords. Beam and tie markings must be placed outside the chord markers:

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

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

Basic rhythmical commands

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

       \partial 8
       f8 c2 d e

Tuplets are made with the \times keyword. It takes two arguments: a fraction and a piece of music. The duration of the piece of music is multiplied by the fraction. Triplets make notes occupy 2/3 of their notated duration, so a triplet has 2/3 as its fraction:

       \times 2/3 { f8 g a }
       \times 2/3 { c r c }

Grace notes are also made by prefixing a note, or a set of notes with a keyword. In this case, the keyword is \grace:

       c4 \grace b16-( c4-)
       \grace { d16-( e } d4-)

More information on grace notes, tuplets and upsteps are in Grace notes, Tuplets and Partial measures.

Commenting input files

Comments are pieces of the input that are ignored. There are two types of comments. A line comments is introduced by %: after that, the rest of that line is ignored. Block comments span larger sections of input. Anything that is enclosed in %{ and %} is ignored too. The following fragment shows possible uses for comments:

       % notes for twinkle twinkle follow:
       c4 c   g' g  a a
     
       %{
     
         This line, and the notes below
         are ignored, since they are in a
         block comment.
     
         g g f f e e d d c2
       %}

Printing lyrics

Lyrics are entered by separating each syllable with a space, and surrounding them with \lyrics { ... }, for example,

       \lyrics { I want to break free }

Like notes, lyrics are also a form of music, but they must not be printed on a staff, which is the default way to print music. To print them as lyrics, they must be marked with \context Lyrics:

       \context Lyrics  \lyrics { I want to break free }

The melody for this song is as follows:

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

      \addlyrics
         \notes { ... }
         \context Lyrics ...

The final result is

     \score  {
      \notes {
       \addlyrics
        \relative c' {
          \partial 8
          c8
          \times 2/3 { f g g } \times 2/3 { g4-( a2-) }
        }
        \context Lyrics  \lyrics { I want to break free }
      }
      \paper{ }
     }

This melody ends on a melisma, a single syllable ("free") sung to more than one note. This is indicated with a extender line. It is entered as two underscores, i.e.

       \lyrics { I want to break free __ }

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

       Twin -- kle twin -- kle

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

A lead sheet

In popular music, it is common to denote accompaniment as chord-names. Using them in LilyPond has two parts, just like lyrics: entering the chords (with \chords), and printing them (with \context ChordNames).

Chord names are entered by starting chords mode (with \chords). In chords mode, you can enter chords with a letter (indicating the root of the chord), and a durations following that:

       \chords { c2 f4. g8 }

The result of \chords is a list of chords, and is equivalent to entering chords with <<...>>.

Other chords can be created by adding modifiers, after a colon. The following example shows a few common modifiers:

       \chords { c2 f4:m g4:maj7 gis1:dim7 }

Printing chords is done by adding \context ChordNames before the chords thus entered:

      \context ChordNames \chords { c2 f4.:m g4.:maj7 gis8:dim7 }

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

     \score {
       <
         \context ChordNames \chords { chords }
         \addlyrics
           \notes the melody
           \context Lyrics \lyrics { the text }
       >
       \paper { }
     }

A complete list of modifiers, and other options for layout are in the reference manual section Chords.

Listening to output

MIDI (Musical Instrument Digital Interface) is a standard for connecting and recording digital instruments. A MIDI file is like a tape recording of a MIDI instrument. The \midi block makes the music go to a MIDI file, so you can listen to the music you entered. It is great for checking the music: octaves that are off, or accidentals that were mistyped, stand out very much when listening to the musical transcription.

\midi can be used in similarly to \paper { }, for example,

     \score {
         ..music..
         \midi  { \tempo 4=72 }
         \paper  { }
     }

Here, the tempo is specified using the \tempo command. In this case the tempo of quarter notes is set to 72 beats per minute. More information on auditory output is in the Sound section in the notation manual.

Titling

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

       \header {
         title = "Eight miniatures"
         composer = "Igor Stravinsky"
         tagline = "small is beautiful"
       }
     
       \score { ... }

When the file is processed by ly2dvi, the title and composer specified are printed above the music. The `tagline' is a short line printed at bottom of the last page, which normally says "Lily was here, version ...". In the example above, it is replaced by the line "small is beautiful".

Normally, the \header is put at the top of the file. However, for a document that contains multiple pieces (e.g. a etude book, or part with multiple movements), then the header can be put into the \score block as follows; in this case, the name of each piece will be printed before each movement:

       \header {
         title = "Eight miniatures"
         composer = "Igor Stravinsky"
         tagline = "small is beautiful"
       }
     
       \score { ...
         \header { piece = "Adagio" }
       }
       \score { ...
         \header { piece = "Menuetto" }
       }

More information on titling can be found in Invoking ly2dvi.

Single staff polyphony

When different melodic lines are combined on a single staff, these 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 stems down.

Entering such parts is done by entering each voice as a sequence (with { .. }), and combining those 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. It is useful for filling up voices that temporarily do not play:

       < { a4 g2 f4-~ f4 } \\
         { s4 g4 f2 f4 } >

Again, these expressions can be nested arbitrarily:

More features of polyphonic typesetting are in the notation manual in Polyphony.

Piano staves

Piano music is always typeset in two staves connected by a brace. Printing such a staff is done similar to the polyphonic example in Combining music into compound expressions:

      < \context Staff = up { ... }
        \context Staff = down { ... }
      >

but now this entire expression must be interpreted as a PianoStaff:

      \context PianoStaff < \context Staff ... >

Here is a full-fledged example:

More information on formatting piano music is in Piano music.

Setting variables

When the music is converted from notes to print, it is interpreted from left-to-right order, similar to what happens when we read music. During this step, context-sensitive information, such as the accidentals to print, and where barlines must be placed, are stored in variables. These variables are called translation properties. The properties can also be manipulated from input files. Consider this input:

     \property Staff.autoBeaming = ##f

It sets the property named autoBeaming in the current staff to ##f, which means `false'. This property controls whether beams are printed automatically:

       c8 c c c
       \property Staff.autoBeaming = ##f
       c8 c c c

LilyPond includes a built-in programming language, namely, a dialect of Scheme. The argument to \property, ##f, is an expression in that language. The first hash-mark signals that a piece of Scheme code follows. The second hash character is part of the boolean value true (#t). Values of other types may be entered as follows:

a string, enclosed in double quotes, for example,

            \property Staff.instrument = #"French Horn"

a boolean: either #t or #f, for true and false respectively, e.g.

            \property Voice.autoBeaming = ##f
            \property Score.skipBars = ##t

a number, such as

            \property Score.currentBarNumber = #20

a symbol, which is introduced by a quote character, as in

            \property Staff.crescendoSpanner = #'dashed-line

a pair, which is also introduced by a quote character, like in the following statements, which set properties to the pairs (-7.5, 6) and (3, 4) respectively:

            \property Staff.minimumVerticalExtent  = #'(-7.5 . 6)
            \property Staff.timeSignatureFraction  = #'(3 . 4)

There are many different properties, and not all of them are listed in this manual. However, the internal documentation lists them all in the All translation properties, and most properties are demonstrated in one of the tips-and-tricks examples.

Fine tuning layout

Sometimes it is necessary to change music layout by hand. When music is formatted, layout objects are created for each symbol. For example, every clef and every note head is represented by a layout object. These layout objects also carry variables, which we call layout properties. By changing these variables from their values, we can alter the look of a formatted score:

       c4
       \property Voice.Stem \override #'thickness = #3.0
       c4 c4 c4

In the example shown here, the layout property thickness (a symbol) is set to 3 in the Stem layout objects of the current Voice. As a result, the notes following \property have thicker stems.

In most cases of manual overrides, only a single object must be changed. This can be achieved by prefixing \once to the \property statement, i.e.

      \once \property Voice.Stem \set #'thickness = #3.0

Some overrides are so common that predefined commands are provided as a short cut. For example, \slurUp and \stemDown. These commands are described in the Notation manual, under the sections for slurs and stems respectively.

The exact tuning possibilities for each type of layout object are documented in the internal documentation of the respective object. However, many layout objects share properties, which can be used to apply generic tweaks. We mention a couple of these:

The extra-offset property, which has a pair of numbers as value, moves around objects in the printout. The first number controls left-right movement; a positive number will move the object to the right. The second number controls up-down movement; a positive number will move it higher. The unit of these offsets are staff-spaces. The extra-offset property is a low-level feature: the formatting engine is completely oblivious to these offsets.
In the following example example, the second fingering is moved a little to the left, and 1.8 staff space downwards:
```
          \stemUp
          f-5
          \once \property Voice.Fingering
            \set #'extra-offset = #'(-0.3 . -1.8)
          f-5
          
```
Setting the transparent property will make an object be printed in `invisible ink': the object is not printed, but all its other behavior is retained. The object still takes 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 happen between notes of the same voice. By introducing a tie in a different voice, and blanking a stem in that voice, the tie appears to cross voices:
```
          \context Staff < {
                \once \property Voice.Stem \set #'transparent = ##t
                b8~ b8
            } \\ {
                 b-[ g8-]
            } >
          
```
The padding property for objects with side-position-interface can be set to increase distance between symbols that are printed above or below notes. We only give an example; a more elaborate explanation is in Constructing a tweak:

More specific overrides are also possible. The notation manual discusses in depth how to figure out these statements for yourself, in Tuning output.

Organizing larger pieces

When all of the elements discussed earlier are combined to produce larger files, the \score blocks get a lot bigger, because the music expressions are longer, and, in the case of polyphonic and/or orchestral pieces, more deeply nested.

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

       namedMusic = \notes { ...

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

     seufzer  = \notes {
       dis'8 e'8
     }
     \score { \notes {
       \seufzer \seufzer \seufzer
     } }

The name of an identifier should only have alphabetic characters only, and no numbers, underscores or dashes. The assignment should be outside of the \score block.

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:

       \score {
         \notes { c4^\name }
         \paper {
           \aFivePaper
           linewidth = \width
         }
       }

More information on the possible uses of identifiers is in the technical manual, in Scheme datatypes.

An orchestral part

In orchestral music, all notes are printed twice: both in a part for the musicians, and in a full score for the conductor. Identifiers can be used to avoid double work: the music is entered once, and stored in variable. The contents of that variable is then used to generate both the part and the score.

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

     hornNotes = \notes \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"
     }
     \score {
       \notes \transpose c' f \hornNotes
     }

The \include command substitutes the contents of the file at this position in the file, so that hornNotes is defined afterwards. The code \transpose f c' indicates that the argument, being \hornNotes, should be transposed by a fifth downwards: sounding f is denoted by notated c', which corresponds with 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, and 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, the next rest takes 3 measures in 2/4 time:

       R2*3

When printing the part, the following skipBars property must be set to false, to prevent the rest from being expanded in three one bar rests:

       \property Score.skipBars = ##t

Prepending the rest and the property setting above, leads to the following result:

The score is made by combining all of the music in a \score block, assuming that the other voice is in bassoonNotes, in the file bassoon-music.ly:

     \include "bassoon-music.ly"
     \include "horn-music.ly"
     
     \score {
       \simultaneous {
         \context Staff = hornStaff \hornNotes
         \context Staff = bsnStaff \bassoonNotes
       } }

This would lead to the simple score depicted below:

More in-depth information on preparing parts and scores is in the notation manual, in Orchestral music.

Integrating text and music

Sometimes you might want to use music examples in a text that you are writing (for example, a musicological treatise, a songbook, or (like us) the LilyPond manual). You can make such texts by hand, simply by importing a PostScript figure into your word processor. However, there is an automated procedure to reduce the amount of work.

If you use HTML, LaTeX, or Texinfo, you can mix text and LilyPond code. A script called lilypond-book will extract the music fragments, run LilyPond on them, and put back the resulting notation. This program is fully described in lilypond-book manual. Here we show a small example; since the example contains also explanatory text, we will not comment it further:

     \documentclass[a4paper]{article}
     \begin{document}
     
     In a lilypond-book document, you can freely mix music and text. For
     example:
     \begin{lilypond}
       \score { \notes \relative c' {
          c2 g'2 \times 2/3 { f8 e d } c'2 g4
       } }
     \end{lilypond}
     
     Notice that the music line length matches the margin settings of the
     document.
     
     If you have no \verb+\score+ block in the fragment,
     \texttt{lilypond-book} will supply one:
     
     \begin{lilypond}
       c'4
     \end{lilypond}
     
     In the example you see here, two things happened: a
     \verb+\score+ block was added, and the line width was set to natural
     length. You can specify  options by putting them in brackets:
     
     \begin[26pt,verbatim]{lilypond}
       c'4 f16
     \end{lilypond}
     
     If you want to include large examples into the text, it is more
     convenient to put it in a separate file:
     
     \lilypondfile{screech-boink.ly}
     
     \end{document}

Under Unix, you can view the results as follows:

     $ cd input/tutorial
     $ mkdir -p out/
     $ lilypond-book --outdir=out/ lilbook.tex
     lilypond-book (GNU LilyPond) 1.7.23
     Reading `input/tutorial/lilbook.tex'
     Reading `input/screech-boink6.ly'
     lots of stuff deleted
     Writing `out/lilbook.latex'
     $ cd out
     $ latex lilbook.latex
     lots of stuff deleted
     $ xdvi lilbook

Running lilypond-book and running latex creates a lot of temporary files, and you would not want those to clutter up your working directory. The outdir option to lilypond-book creates the temporary files in a separate subdirectory out.

The result looks more or less like this:

In a lilypond-book document, you can freely mix music and text. For example:

Notice that the music line length matches the margin settings of the document.

If you have no \score block in the fragment, lilypond-book will supply one:

In the example you see here, two things happened: a score block was added, and the line width was set to natural length. You can specify options by putting them in brackets:

       c'4 f16

If you want to include large examples into the text, it is more convenient to put it in a separate file:

Notation manual

Note entry

This chapter describes all the different types of notation supported by LilyPond. It is intended as a reference for users that are already somewhat familiar with using LilyPond.

Notes

A note is printed by specifying its pitch and then its duration: ⁵

       cis'4 d'8 e'16 c'16

Pitches

The most common syntax for pitch entry is used in \chords and \notes mode. In Note and Chord mode, pitches may be designated by names. The notes are specified by the letters a through g, while the octave is formed with notes ranging from c to b. The pitch c is an octave below middle C and the letters span the octave above that C:

     \clef bass
       a,4 b, c d e f g a b c' d' e' \clef treble f' g' a' b' c''

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. These names are the Dutch note names. In Dutch, aes is contracted to as in Dutch, but both forms are accepted. Similarly, both es and ees are accepted.

There are predefined sets of note names for various other languages. To use them, include the language specific init file. For example: \include "english.ly". 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
     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

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:

       c' c'' es' g' as' gisis' ais'

There is also a verbose syntax for pitch specification:

       \pitch scmpitch

where scmpitch is a Scheme object of the Pitch type.

Predefined commands

Notes can be hidden and unhidden with the following commands:

\hideNotes, \unHideNotes.

Chromatic alterations

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 (an accidental within parentheses) can be obtained by adding the question mark `?' after the pitch:

       cis' cis' cis'! cis'?

The automatic production of accidentals can be tuned in many ways. For more information, refer to Accidentals.

Chords

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

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 are discussed in Multi measure rests.

A rest's vertical position may be explicitly specified by entering a note with the \rest keyword appended. This makes manual formatting in polyphonic music easier. Rest collision testing will leave these rests alone:

     a'4\rest d'4\rest

Skips

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

     a2 s4 a4 \skip 1 a4

The s syntax is only available in Note mode and Chord mode. In other situations, you should use the \skip command:

     \score {
       \context Staff <
         { \time 4/8 \skip 2 \time 4/4 }
         \notes\relative c'' { a2 a1 }
       >
     }

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

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

     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. The duration can be followed by dots (`.') in order to obtain dotted note lengths:

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

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:

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

Durations can also be produced using the verbose syntax \duration Scheme object:

      c'\duration #(ly:make-duration 4 1)

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, \dotsBoth.

Bugs

In dense chords, dots can overlap.

Stems

Whenever a note is found, a Stem object is created automatically. For whole notes and rests, stem objects are also created, but in those cases, the stem is invisible.

Predefined commands

\stemUp, \stemDown, \stemBoth.

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.

In its meaning a tie is just a way of extending a note duration, similar to the augmentation dot; in the following example there are two ways of notating exactly the same concept:

If you need to tie a lot of notes over bars, it may be easier to use automatic note splitting (See Automatic note splitting).

Predefined commands

\tieUp, \tieDown, \tieBoth, \tieDotted, \tieSolid.

Bugs

Tieing only a subset of the note heads of a pair of chords is not supported in a simple way. It can be achieved by moving the tie-engraver into the Thread context and turning on and off ties per Thread.

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

Formatting of ties is a difficult subject. The results are often not optimal.

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. In the sheet music, 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

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

     \property Voice.tupletSpannerDuration = #(ly:make-moment 1 4)
     \times 2/3 { c'8 c c c c c }

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

Predefined commands

\tupletUp, \tupletDown, \tupletBoth.

Bugs

Nested tuplets are not formatted automatically. In this case, outer tuplet brackets should be moved manually.

Easy Notation note heads

The `easy play' note head includes a note name inside the head. It is used in music aimed at beginners:

     \score {
       \notes { c'2 e'4 f' | g'1 }
       \paper { \translator { \EasyNotation } }
     }

The EasyNotation variable overrides a Score context. You probably will want to print it with magnification or a large font size to make it more readable. To print with magnification, you must create a DVI file (with ly2dvi) and then enlarge it with something like dvips -x 2000 file.dvi. See the dvips documentation for more details. To print with a larger font, see Font Size.

If you view the result with Xdvi, then staff lines will show through the letters. Printing the PostScript file obtained with ly2dvi does produce the correct result.

Easier music entry

When entering music it is easy to introduce errors. This section deals with tricks and features of the input language that help when entering music, and find and correct mistakes. Some features of the input language ease entering music, but also have other applications. They are not described in this section.

It is also possible to use external programs, for example GUI interfaces, or MIDI transcription programs, to enter or edit music. Refer to the website for more information. Finally, there are tools make debugging easier, by linking the input file and the output shown on screen. See Point and click for more information.

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: a single error puts the rest of the piece off by one octave:

       \relative startpitch musicexpr

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

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 must be specified that will act as the predecessor of the first note of musicexpr.

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 the \relative contains a note name. To parse the pitch as a note name, you have to be in note mode, so there must be a surrounding \notes keyword (which is not shown here).

The relative conversion will not affect \transpose, \chords or \relative sections in its argument. If you want to use relative within transposed music, you must place an additional \relative inside the \transpose.

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. Depending on the value of barCheckSynchronize, the beginning of the measure will be relocated.

In the next example, the second bar check will signal an error:

       \time 3/4 c2 e4 | g2 |

Failed bar checks are caused by entering incorrect durations. Incorrect durations often completely garble up the score, especially if it is polyphonic, so you should start correcting the score by scanning for failed bar checks and incorrect durations. To speed up this process, you can use skipTypesetting, described in the next section.

Skipping corrected music

The property Score.skipTypesetting can be used to switch on and off typesetting completely during the interpretation phase. When typesetting is switched off, the music is processed much more quickly. This can be used to skip over the parts of a score that have already been checked for errors:

     \relative c'' { c8 d
     \property Score.skipTypesetting = ##t
       e f g a g c, f e d
     \property Score.skipTypesetting = ##f
     c d b bes a g c2 }

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:

       \paper { \translator {
           \ThreadContext
           \remove "Note_heads_engraver"
           \consists "Completion_heads_engraver"
       } }

which will make long notes tied in the following example:

       \time 2/4
       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.

Bugs

Not all durations (especially those containing tuplets) can be represented exactly; the engraver will not insert tuplets.

Staff notation

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

Staff symbol

Notes, dynamic signs, etc. are grouped with a set of horizontal lines, into a staff (plural `staves'). In our system, these lines are drawn using a separate layout object called staff symbol.

This object is created whenever a Staff context is created. The appearance of the staff symbol cannot be changed by using \override or \set. At the moment that \property Staff is interpreted, a Staff context is made, and the StaffSymbol is created before any \override is effective. Properties can be changed in a \translator definition, or by using \outputproperty.

Bugs

If a staff is ended halfway a piece, the staff symbol may not end exactly on the barline.

Key signature

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

Syntax

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. The standard mode names \ionian, \locrian, \aeolian, \mixolydian, \lydian, \phrygian, and \dorian are also defined.

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

Bugs

The ordering of a key cancellation is wrong when it is combined with repeat bar lines. The cancellation is also printed after a line break.

Clef

The clef indicates which lines of the staff correspond to which pitches.

Syntax

The clef can be set or changed with the \clef command:

       \key f\major  c''2 \clef alto g'2

Supported clef-names include:

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

By adding _8 or ^8 to the clef name, the clef is transposed one octave down or up, respectively. Argument clefname must be enclosed in quotes when it contains underscores or digits. For example,

     	\clef "G_8"

This command is equivalent to setting clefGlyph, clefPosition (which controls the Y position of the clef), centralCPosition and clefOctavation. A clef is printed when any of these properties are changed.

Ottava brackets

"Ottava" brackets introduce an extra transposition of an octave for the staff. They are created by invoking the function set-octavation:

     \relative c''' {
       a2 b
       #(set-octavation 1)
       a b
       #(set-octavation 0)
       a b }

Internally the set-octavation function sets the properties ottavation (eg. to "8va") and centralCPosition.

Bugs

set-octavation will get confused when clef changes happen during an octavation bracket.

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.

Syntax

The time signature is set or changed by the \time command:

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

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. There are many more options for its layout. See input/test/time.ly for more examples.

This command 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 { \notes \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
        }
        \paper {
            raggedright = ##t
            \translator { \StaffContext
              \consists "Measure_grouping_engraver"
        }}}

Bugs

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

Partial measures

Partial measures, for example in upsteps, are entered using the \partial command:

     \partial 16*5  c'16 c4 |   a'2. ~ a'8. a'16 | g'1

The syntax for this command is

       \partial duration

This is internally translated into

       \property Timing.measurePosition = -length of duration

The property measurePosition contains a rational number indicating how much of the measure has passed at this point.

Unmetered music

Bar lines and bar numbers are calculated automatically. For unmetered music (e.g. cadenzas), this is not desirable. By setting Score.timing to false, this automatic timing can be switched off.

Predefined commands

\cadenzaOn, \cadenzaOff.

Bar lines

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

Syntax

Special types of barlines can be forced with the \bar command:

        c4 \bar "|:" c4

The following bar types are available:

     c4
     \bar "|" c
     \bar "" c
     \bar "|:" c
     \bar "||" c
     \bar ":|" c
     \bar ".|" c
     \bar ".|." c
     \bar "|."

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:

     < \context StaffGroup <
       \context Staff = up { e'4 d'
          \bar "||"
          f' e' }
       \context Staff = down { \clef bass c4 g e g } >
     \context Staff = pedal { \clef bass c2 c2 } >

The command \bar bartype is a short cut for doing \property Score.whichBar = bartype Whenever whichBar is set to a string, a bar line of that type is created. At the start of a measure it is set to defaultBarType. The contents of repeatCommands are used to override default measure bars.

Property whichBar can also be set directly, using \property or \bar. These settings take precedence over the automatic whichBar settings.

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

Polyphony

The easiest way to enter fragments with more than one voice on a staff is to split chords using the separator \\. You can use it for small, short-lived voices or for single chords:

     \context Voice = VA \relative c'' {
      c4 < { f d e  } \\ { b c2 } > c4 < g' \\ b, \\  f' \\ d >
     }

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.

This can also be done by instantiating Voice contexts by hand, and using \voiceOne, up to \voiceFour to assign a stem directions and horizontal shift for each part:

     \relative c''
     \context Staff < \context Voice =

GNU LilyPond -- The music typesetter

Table of Contents

Preface

Preface to version 1.8

Preface to version 1.6

Introduction

Music notation and engraving

Notation and engraving in LilyPond

Typography and program architecture

Music representation

Example applications

About this manual

Tutorial

First steps

Running LilyPond

More about pitches and accidentals

Octave entry

Combining music into compound expressions

Adding articulation marks to notes

Combining notes into chords

Basic rhythmical commands

Commenting input files

Printing lyrics

A lead sheet

Listening to output

Titling

Single staff polyphony

Piano staves

Setting variables

Fine tuning layout

Organizing larger pieces

An orchestral part

Integrating text and music

Notation manual

Note entry

Notes

Pitches

Predefined commands

See also

Chromatic alterations

Chords

Rests

See also

Skips

See also

Durations

Predefined commands

See also

Bugs

Stems

Predefined commands

Ties

Predefined commands

See also

Bugs

Tuplets

Predefined commands

See also

Bugs

Easy Notation note heads

Easier music entry

Relative octaves

Bar check

Skipping corrected music

Automatic note splitting

Bugs

Staff notation

Staff symbol

Bugs

Key signature

Syntax

Bugs

See also

Clef

Syntax

See also

Ottava brackets

See also

Bugs

Time signature