This file documents GNU LilyPond.

Copyright 1999–2003 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

1 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

Preface

Preface to version 2.0

Due to personal circumstances, Han-Wen was able to do a lot more on LilyPond during the past months. A testament to that is the quick release of version 2.0, less than two months after 1.8. We have taken the opportunity to make a few radical changes to the syntax: note attributes, like articulation, dynamics and fingerings are now post-fix exclusively. This makes entering scores easier: you never have to think about the order of the attributes. With version 2.0, we have a new and improved platform for working on notation and typography features for coming versions,

Due to other personal circumstances, Jan was not able to do more than packaging for Cygwin. The good news is that we now have a nearly fool-proof installation for Windows. He will be back for serious hacking in 2.1.

Han-Wen and Jan

Utrecht/Eindhoven, The Netherlands, September 2003.

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.

2 Introduction

There are a lot of programs that let you print sheet music with a computer, but 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. We have tuned our algorithms, font-designs, and program settings to make the program produce prints that match the quality of the old editions we love to see and love to play from.

2.1 Notation in LilyPond

Printing sheet music consists of two non-trivial 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.

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 (note heads on a 5-line staff) has not changed, the details still change to express the innovations of contemporary notation. Hence, it encompasses some 500 years of music. Its applications range from monophonic melodies to monstruous counterpoint 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 make a strict distinction between notation, what symbols to use, and engraving, where to put them. Anything related to the second question is considered “engraving” (i.e. typography).

For tackling the first problem, notation, we have broken up the problem into digestible (and programmable) chunks: every type of symbol is handled by a separate program module, a so-called plug-in. Each plug-in are completely modular and independent, so each can be developed and improved separately. When put together, the plug-ins can solve the music notation program in cooperation. People that put graphics to musical ideas are called copyists or engravers, so by analogy, each plug-in is also engraver.

In the following example, we see how we start out with a note head 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 heads is seen, a stem object is created, and attached 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 head, 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. In polyphonic notation, many voices can share a staff: Similarly, more Staff contexts can be put into a single Score context.

2.2 Engraving in LilyPond

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.

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.

2.3 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 engravers 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. 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. To accomplish this we store decisions in generic variables, and let the user manipulate thosed. 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.

2.4 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, rigid definitions 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.

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

2.6 About this manual

The manual is divided into the following chapters:

• Tutorial gives a gentle introduction to 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 look up details.
• The Literature list contains a set of useful reference books, for those who wish to know more 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.
• The lilypond-book manual explains the details behind creating documents with in-line music examples (like this manual).
• The chapter 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. In addition, this section explains how to upgrade input files from previous versions of LilyPond.

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), 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 (lilypond-internals).

  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.

  After you have gone through the tutorial, 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: simply copy the template, and add notes in the appropriate places.

• Various input examples. These small files show various tips and tricks, and are 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 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/.

3 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, and illustrate the process with 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. You should then be able to create and print your first sheets of music.

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

     \paper { }

The \paper block is used to customize printing specifics. The customization commands go between { and }, but for now, we accept the defaults. The music and the \paper block are combined by enclosing them in \score { ... }, so 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 { }
     }

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

For more elaborate information on

entering pitches and durations

see Pitches and Durations.

Clefs

see Clef

Time signatures and other timing commands

see Time signature.

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

To process test.ly, proceed as follows:

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

            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 try to enter one of the commands from the list shown before in the terminal. 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.

3.3 More about pitches

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

     cis1 ees fisis aeses

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

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

Key signatures together with the pitch (including alterations) are used together to determine when to print accidentals. This is a feature that often causes confusion to newcomers, so let us explain it in more detail:

LilyPond has a sharp distinction between musical content and layout. The alteration (flat, natural or sharp) of a note is part of the pitch, and is therefore musical content. Whether an accidental (a flat, natural or sharp sign) is a 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.

For example, in this example:

no note gets an explicit accidental, but still you enter

     \key d \major
     d cis fis

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

     \key as \major
     d

Adding all alterations explicitly might require some more effort when typing, but the advantage is that transposing is easier, and music can be printed according to different conventions. See Accidentals for some examples how accidentals can be printed according to different rules.

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

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]
     

For more information on

Rests

see Rests.

Ties

see Ties.

Accidentals

see Accidentals

Key signature

see Key signature

Beams

see Beaming

3.4 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, pieces can be written almost without octavation quotes in relative mode. The previous 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.

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

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:

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'
     

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

3.5 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 {
            \new Staff { \clef violin c'' }
            \new Staff { \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 { .. }.

The command \new introduces a “notation context”. To understand this concept, imagine that you are performing a piece of music. When you are playing, 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 \new to a chunk of music indicates what kind of context to use for interpreting it, and ensures that the argument is interpreted with a fresh instance of the context indicated.

We can now typeset a melody with two staves:

          \score {
            \notes
            << \new Staff {
                \time 3/4
                \clef violin
                \relative c'' {
                  e2( d4 c2 b4 a8[ a]
                  b[ b] g[ g] a2.) }
              }
              \new Staff {
                 \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 \new Staff to it, and that chunk is combined with << >>. This mechanism is similar with 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)

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

For more information on context see the Technical manual description in Interpretation context.

3.6 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 looks like a tie, but it has a different meaning. A tie simply makes the first note sound longer, and can only be used on pairs of notes with the same pitch. Slurs indicate the articulations of notes, and can be used on larger groups of notes. Slurs and ties 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\)
     

For more information on

fingering

see Fingering instructions

articulations

see Articulations

slurs

see Slurs

phrasing slurs

see Phrasing slurs

dynamics

see Dynamics

fingering

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

3.7.1 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 keywords are \appoggiatura and \acciaccatura

       c4 \appoggiatura b16 c4
       c4 \acciaccatura b16 c4

For more information on

grace notes

see Grace notes,

tuplets

see Tuplets,

upsteps

see Partial measures.

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

3.8 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 \new Lyrics:

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

The final result is

     \score  {
      \notes {
       \addlyrics
        \relative c' {
          \partial 8
          c8
          \times 2/3 { f g g } \times 2/3 { g4( a2) }
        }
        \new 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 an 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.

3.9 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 \new 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.

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

3.11 Titling

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

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

When the file is processed by the lilypond wrapper script, then 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 “Engraved by LilyPond, 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. an etude book, or an orchestral 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 lilypond.

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

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

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

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

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

Here is a full-fledged example:

More information on formatting piano music is in Piano music.

3.14 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 context 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 at this point in the music 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)
       

• a list, which is also introduced by a quote character. In the following example, the breakAlignOrder property is set to a list of symbols:

              \property Score.breakAlignOrder =
                #'(left-edge time-signature key-signatures)
       

There are many different properties, and not all of them are listed in this manual. However, the program reference lists them all in the section Context-properties (lilypond-internals), and most properties are demonstrated in one of the tips-and-tricks examples.

3.15 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 program reference 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:

              c4 << {
                  \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:

              c2\fermata
              \property Voice.Script \set #'padding = #3
              b2\fermata
       

  

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

3.16 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. Such large expressions can become unwieldy.

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

       namedMusic = \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 two times by using variable substitution:

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

The name of an identifier should 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.

3.17 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.lyinc"
     \header {
       instrument = "Horn in F"
     }
     \score {
       \notes \transpose f c' \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.lyinc"
     \include "horn-music.lyinc"
     
     \score {
       \simultaneous {
         \new Staff \hornNotes
         \new Staff \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.

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

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:

4 Notation manual

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.

4.1 Note entry

The basic elements of any piece of music are the notes. This section is about basic notation elements notes, rests and related constructs, such as stems, tuplets and ties.

4.1.1 Notes

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

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

4.1.2 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, but both forms are accepted. Similarly, both es and ees are accepted.

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

       ceses4
       ceseh
       ces
       ceh
       c
       cih
       cis
       cisih
       cisis

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

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'

Predefined commands

Notes can be hidden and unhidden with the following commands:

\hideNotes, \unHideNotes.

See also

bla

NoteEvent (lilypond-internals), and NoteHead (lilypond-internals).

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

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

4.1.5 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

See also

RestEvent (lilypond-internals), and Rest (lilypond-internals).

4.1.6 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 {
       \new 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.

See also

SkipEvent (lilypond-internals).

4.1.7 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

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.

See also

Dots (lilypond-internals), and DotColumn (lilypond-internals).

Bugs

In dense chords, dots can overlap.

4.1.8 Stems

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

Predefined commands

\stemUp, \stemDown, \stemBoth.

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

Predefined commands

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

See also

TieEvent (lilypond-internals), NewTieEvent (lilypond-internals), Tie (lilypond-internals), and Automatic note splitting.

If you want less ties created for a chord, see input/test/tie-sparse.ly.

For tieing only a subset of the note heads of a pair of chords, see input/regression/tie-chord-partial.ly.

Bugs

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.

4.1.10 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

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.

See also

TupletBracket (lilypond-internals), and TimeScaledMusic (lilypond-internals).

Bugs

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

4.1.11 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 (lilypond-internals) 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 lilypond) 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 does produce the correct result.

4.2 Easier music entry

When entering music it is easy to introduce errors. This section deals with tricks and features of the input language that were added solely to help entering music, and find and correct mistakes.

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.

4.2.1 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