GNU LilyPond

Welcome to the home of the GNU Music Typesetter

What is LilyPond

General information
Simple examples
Complex examples

Download

GNU/Linux binaries
Windows
Source code

Documentation

Tutorial
Manual
Glossary
other ...

Support

Mailing lists
Search
WikiWiki
FAQs

External sites

lilypond.org/development
lilypond.org/stable
ftp.lilypond.org
Mutopia
Other music online

GNU LilyPond

This document is also available as a gzipped postscript file.

GNU LilyPond -- The music typesetter

LilyPond produces sheet music from input files. This document describes how to use LilyPond.

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"> GNU LilyPond -- The music typesetter">Top">GNU LilyPond -- The music typesetter
Preface"> Preface">Preface">Preface
Tutorial"> Tutorial">Tutorial">Tutorial
Reference Manual"> Reference Manual">Reference%20Manual">Reference Manual
Internals"> Internals">Internals">Internals
Invoking LilyPond"> Invoking LilyPond">Invoking%20LilyPond">Invoking LilyPond
- Options">Invoking%20LilyPond">Options
- Environment variables">Invoking%20LilyPond">Environment variables
Bug reports"> Bug reports">Bug%20reports">Bug reports
ly2dvi"> ly2dvi">ly2dvi">ly2dvi
- Options">ly2dvi">Options
convert-ly"> convert-ly">convert-ly">convert-ly
lilypond-book"> lilypond-book">lilypond-book">lilypond-book
Converting to LilyPond format."> Converting to LilyPond format.">Conversion%20tools">Converting to LilyPond format.
Literature"> Literature">Literature">Literature
Index"> Index">Index">Index
Function Index"> Function Index">Function%20Index">Function Index
Refman appendix"> Refman appendix">Refman%20appendix">Refman appendix
GNU Free Documentation License"> GNU Free Documentation License">GNU%20Free%20Documentation%20License">GNU Free Documentation License

Preface

It must have been during a rehearsal of the EJE (Eindhoven Youth Orchestra), somewhere in 1995 that Jan, one of the cranked violists told Han-Wen, one of the distorted french horn players, about the grand new project he was working on. It was an automated system for printing music (to be precise, it was MPP, a preprocessor for MusiXTeX). As it happened, Han-Wen accidentally wanted to print out some parts from a score, so he started looking at the software, and he quickly got hooked. It was soon 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. The rest is, as they say, history.

You're reading the preface of the manual for LilyPond 1.4, which is in all honesty, the first release of LilyPond that combines stability, flexibility and good documentation. We hope you will have as much fun in using LilyPond as we have when hacking it.

This manual was written to help you learn LilyPond, but as you might imagine, we ourselves don't have much to learn about it. We can't really judge whether the manual is helpful for users, but maybe you can! Don't hesitate to tell us if you find any part of the manual vague, unclear or outdated.

Han-Wen and Jan

Utrecht/Amsterdam, The Netherlands, March 2001.

Tutorial

The music is described in a text file, using a simple music language. LilyPond reads that text file and generates music that you can print or view.

Therefore, creating music notation with LilyPond is done in two steps. Using a text editor, you write down the notes to print. Then, you run LilyPond to get your printed output.

This tutorial starts with a small introduction to the LilyPond music language. After this first contact, we will show you how to run LilyPond to produce printed output; you should then be able to create your first sheets of music.

The tutorial continues with a slightly more elaborate example of real music. This piece introduces and explains some finer details of LilyPond. Then, a number of more complex examples follow, that will help you to produce most complex music with LilyPond.

First steps

This section shows how easy writing music with LilyPond actually is. If you have not seen LilyPond input source before, this section is for you.

The next section has a table (see Simple legend) of all symbols that are introduced here, you may want to keep an eye on that.

Writing music with LilyPond is explained below by a number of small examples. Each example has a small piece of text; the LilyPond input that you should type, with the resulting music printed below it.

You get a simple note by typing its note name, from a through g:

c d e f g a b

***

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

a1 a2 a4 a16 a32

***

If you don't specify a duration, the previous duration is used:

a a a2 a

***

A sharp (#) is made by adding "is", a flat (b) by adding "es":

cis1 ees fisis aeses

***

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 violin
\clef bass
\clef alto
\clef tenor

***

From these commands and notes, a piece of music can be formed. A piece of music is made by enclosing it in "\notes { ... }". LilyPond then knows that music follows (and not lyrics, for example):

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

***

At this point, the piece of music is ready to be printed. This is done by combining the music with a printing command.

The printing command is the so-called "\paper" block. You will see later that the \paper block is necessary to customize all kinds of printing specifics. The music and the \paper block are combined by enclosing them in "\score { ... }". This is what a full LilyPond source file looks like:

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

***

We continue with the introduction of the remaining musical constructs.

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

r2 r4 r8 r16

***

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). The central C is c':

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

***

A tie is created by entering a tilde "~" between the notes to be tied. A tie between two notes means that the second note must not be played separately, but just makes the first note sound longer:

g'4 ~ g' a'2 ~ a'4

***

The key signature is set with the command "\key":

\key d \major
g'1
\key c \minor
g'

This example shows notes, ties, octave marks, and rests in action. Don't worry about all the quotes.

\score {
  \notes {
    \time 4/4
    \clef violin
    \key d \minor
    r4 r8 d''8 cis''4 e''
    d''8 a'4. ~ a' b'8
    cis''4 cis''8 cis'' bis'4 d''8 cis'' ~
    cis''2 r2
  }
  \paper { }
}

There are some interesting points to note in this example. Firstly, accidentals (sharps and flats) don't have to be marked explicitly: you just enter the note name, and LilyPond determines whether or not to print an accidental. Secondly, bar lines and beams are drawn automatically. Thirdly, LilyPond calculates line breaks for you; it doesn't matter where you make new lines in the source file.

The example also indicates that a piece of music written in a high register needs lots of quotes. This makes the input a bit unreadable, and is therefore also a potential source of errors.

***

The solution is to use "relative octave" mode. In practice, most music is entered using this mode.

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 type no octaviation quotes, relative mode chooses the note that is closest to the previous one, which is often just the one you need. For example: c f goes up; c g goes down:

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

***

You can make a large interval by adding octaviation quotes. Note that 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,
}

***

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

***

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

***

Beams are drawn automatically, but if you don't like the choices, you can enter beams by hand. Surround the notes to be grouped with [ and ]:

[a8 ais] [d es r d]

***

To print more than one staff, each piece of music that makes up a staff is marked by adding \context Staff before it. These staffs can be grouped inside < and >, as is demonstrated here:

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

In this example, staffA and staffB are names that are given to the staffs. For now, it doesn't matter what names you give, as long as each staff has a unique name.

***

We can typeset a melody with two staffs now:

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

Notice that the time signature is specified in one melody staff only (the top staff), but is printed on both. LilyPond knows that the time signature should be the same for all staffs.

***

Common accents can be added to a note using -., --, ->:

c-. c-- c->

***

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

c-\ff c-\mf

***

Crescendi are started with the commands \< and \>. The command \! finishes a crescendo on the following note.

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

***

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

r4 <c e g> <c f a>

***

Of course, you can combine beams and ties with chords. Notice that beam and tie markings are placed outside the chord markers:

r4 [<c8 e g> <c8 f a>] ~ <c8 f a>

When you want to combine chords with slurs and dynamics, an annoying technical detail crops up: you have type these commands next to the notes, which means that they have to be inside the < >:

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

***

A nasty technical detail also crops up when you start a score with a chord:

\score { \notes <c'1 e'1> }

***

The program can not guess that you want the notes on only one staff. To force the chord on a staff, add \context Staff like this:

\score { \notes \context Staff <c'1 e'1> }

***

This is the end of the simple tutorial. You know the basic ingredients of a music file, so this is the right moment to try your at hand at doing it yourself: try to type some simple examples, and experiment a little.

When you're comfortable with the basics, then you might want to read the rest of this chapter. It also a manual in tutorial-style, but it is much more in-depth. It will also be very intimidating if you're not familiar with the basics. It deals with some of the more advanced features of LilyPond. Topics include lyrics, chords, orchestral scores and parts, fine tuning output, polyphonic music, and integrating text and music.

Simple legend

[ ] beam

~ tie

( ) slur

' raise octave

, lower octave

< > chord

\< \! crescendo

\> \! decrescendo

Running LilyPond

You write music with LilyPond as follows: first you edit a text file containing a description of the notes. Then you run LilyPond on the file. This leaves you with an output file, which you can view or print.

In this section we explain how to run LilyPond, and view or print the output. If you have not used LilyPond before, want to test your setup of LilyPond, or try to run an example file yourself, then read this section.

The instructions that follow are for running LilyPond on Unix-like systems. Some additional instructions for running LilyPond on Windows are given at the end of this section.

You begin with opening a terminal window, and start up a text editor. For example, 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 run LilyPond, you invoke ly2dvi to compile your LilyPond source file:

ly2dvi -P test.ly

You will see the following on your screen:

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

The results of the ly2dvi run are two files, test.dvi and test.ps. The PS file (test.ps) is the one you can print. You can view the PS file using the program ghostview. If a version of ghostview is installed on your system, one of these commands will produce a window with some music notation on your screen:

  gv test.ps
  ghostview test.ps
  ggv test.ps
  kghostview test.ps

If you are satisfied with the looks of the music displayed on your screen, you can print the PS file by clicking File/Print inside ghostview.

The DVI file (test.dvi) contains the same sheet music in a different format. DVI files are more easily processed by the computer, so viewing them usually is quicker. Execute xdvi test.dvi to view the DVI file.

If your DVI viewer does not have a "Print" button, you can print the file by executing lpr test.ps.

If you can't get the examples to print, then you should look into installing and configuring ghostscript. Refer to GhostScript's website at http://www.ghostscript.com.

Windows users

Windows users start the terminal by clicking on the LilyPond icon. Notepad is sufficient for editing the LilyPond file. Viewing the PS file can be done with gsview32 test.ps. Viewing DVI files can be done with yap test.dvi. The "print" button in Yap will print files. You can also print from the command line by executing gsview32 /s test.ps

The first real tune

The rest of this tutorial will demonstrate how to use Lilypond by presenting examples of input along with resulting output. We will use English terms for notation. In case you are not familiar with those, you may consult the glossary that is distributed with LilyPond.

The examples discussed are included in the distribution, in the subdirectory input/tutorial/¹

To demonstrate what LilyPond input looks like, we start off with a full-fledged, yet simple example. It is a convoluted version of the famous minuet in J. S. Bach's Klavierbüchlein. The file is included in the distribution as minuet.ly.

% all text after a percent sign is a comment
% and is ignored by LilyPond
\include "paper16.ly"
\score {
    \notes
    \relative c'' \sequential {
            \time 3/4
            \key g \major

        \repeat "volta" 2 {
            d4 g,8 a b c d4 g, g |
            e'4 c8 d e fis g4 g, g |
            c4 d8( )c b a( )b4 c8 b a g |
            a4 [b8 a] [g fis] g2.  |
        }

        b'4 g8 a b g
        a4 d,8 e fis d |
        g4 e8 fis g d cis4 b8 cis a4 |
        a8-. b-. cis-. d-. e-. fis-.
        g4 fis e |
        fis a,  r8 cis8
        d2.-\fermata
        \bar "|."
    }
    \paper {
       % standard settings are too big and wide for a book
       indent = 1.0 \cm
       linewidth = 15.0 \cm
   }
}

We will analyse the input, line by line.

***

        % all text after a percent sign is a comment
        % and is ignored by LilyPond

Percent signs introduce comments: everything after a percent sign is ignored. You can use this to write down mental notes to yourself. You can also make longer comments by enclosing text in %{ and %}.

***

        \include "paper16.ly"

By default, LilyPond will typeset the music in a size such that each staff is 20 point (0.7 cm, or 0.27 inch) high. We want smaller output (16 point staff height), so we must import the settings for that size, which is done here.

***

        \score {

Music is printed by combining a piece of music with directions for outputting it. This combination is formed in the \score block.

***

        \notes

Prepare LilyPond for accepting notes.

***

        \relative c''

Even though a piece of music often spans a range of several octaves, it mostly moves in small intervals. LilyPond has a special entry mode to save typing in this situation. In this "relative" octave mode, octaves of notes without quotes are chosen such that a note is as close as possible (graphically, on the staff) to the preceding note. If you add a high-quote an extra octave is added. A lowered quote (a comma) will subtract an extra octave.

Because the first note has no predecessor, you have to give the (absolute) pitch of the note to start with.

***

        \sequential {

What follows is sequential music, i.e., notes that are to be played and printed after each other.

***

        \time 3/4

Set (or change) the time signature of the current piece: a 3/4 sign is printed. The time signature setting is also used to generate bar lines at the right spots.

***

        \key g \major

Set (or change) the current key signature to G-major. Although in this example, the \key command happened to be entered after the \time command, in the output the time signature will be printed after the key signature; LilyPond knows about music typesetting conventions.

***

        \repeat "volta" 2

The following piece of music is played twice. The first argument indicates the type of repeat. In this case, "volta" means that prima volta/secunda volta brackets are used for the alternative endings--if there were any.

***

The subject of the repeat is again sequential music. Since \sequential is such a common construct, a shorthand is provided: just leave off \sequential, and the result is the same.

***

        d4 g,8

Two notes. The first note is a quarter note with relative pitch d. The relative music was started with a c'', so the real pitch of this note is d''. The duration of a note is designated by a number; the 4 here represents a quarter note.

The second note is an eight note with relative pitch g,. The pitch is taken relative to the previous d'', making this note have real pitch g'. The 8 represents an eight note.

***

a b

Two more notes, with pitch a and b. Because their duration is the same as the g,8, there is no need to enter the duration, but you may enter it anyway, i.e., a4 b4

***

        d4 g, g |

Three more notes. The | character is a "bar check". LilyPond will verify that bar checks are found at the start of a measure. This can help you track down typing errors.

***

        c8 d e fis

So far, no notes were chromatically altered. Here is the first one that is: fis. LilyPond by default uses Dutch² note names, and "Fis" is the Dutch note name for "F sharp". However, there is no sharp sign in the output. The program keeps track of key signatures, and will only print accidentals if they are needed.

For groups of eighth notes and shorter, LilyPond can determine how the notes should form a beam. In this case, the 4 eights are automatically printed as a beam.

***

        c4 d8( )c b a( )b4 c8 b a g |

The beginning and ending notes of a slur are marked with parentheses, ( and ) for start and end respectively. The line above indicates two slurs. These slur markers (parentheses) are entered between the slurred notes.

***

        a4 [b8 a] [g fis]

Automatic beaming can be overridden by inserting beam marks, [ and ]. These beam markers (brackets) are put around the notes you want beamed.

***

        g2.  |

A period adds a dot to the note.

***

The end of the sequential music to be repeated. LilyPond will typeset a repeat bar.

***

        cis'4 b8 cis a4 |

Accidentals are printed whenever necessary: the first C sharp of the bar will be printed with an accidental, the second one without.

***

        a8-. b-. cis-. d-. e-. fis-.

You can enter articulation signs either in a verbose form or using a shorthand. Here we demonstrate the shorthand: it is formed by a dash and the character for the articulation to use, e.g. -. for staccato as shown above.

***

        fis a, r8 cis8

Rests are denoted by the special note name r.

***

        d2.-\fermata

All articulations have a verbose form, like \fermata. The command \fermata is not part of the core of the language, but it is a shorthand for a more complicated description of a fermata symbol. \fermata names that description and is therefore called an identifier.

***

        \bar "|."
        }

Here the music ends. LilyPond does not automatically typeset an end bar, we must explicitly request one, using "|.".

***

        \paper {
                % standard settings are too big and wide for a book
                indent = 1.0\cm
                linewidth = 15.0\cm
        }

The \paper block specifies how entered music should be converted to notation output. Most of the details of the conversion (font sizes, dimensions, etc.) have been taken care of, but to fit the output in this document, it has to be narrower. We do this by setting the line width to 14 centimeters (approximately 5.5 inches).

***

The last brace ends the \score block.

Lyrics and chords

In this section we show how to typeset a song. This file is included as flowing.ly.

\header {
        title = "The river is flowing"
        composer = "Traditional"
}
\include "paper16.ly"
melody = \notes \relative c' {
        \partial 8
        \key c \minor
        g8 |
        c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
        c4 c8 d [es () d] c4 | d4 es8 d c4.
        \bar "|."
}

text = \lyrics {
        The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
        ri -- ver is flo -- wing down to the sea.
}

accompaniment =\chords {
        r8
        c2:3- f:3-.7 d:min es4 c8:min r8
        c2:min f:min7 g:7^3.5 c:min }

\score {
        \simultaneous {
          %\accompaniment
          \context ChordNames \accompaniment

          \addlyrics
            \context Staff = mel {
              \property Staff.noAutoBeaming = ##t
              \property Staff.automaticMelismata = ##t
              \melody
            }
            \context Lyrics \text
        }
        \midi  { \tempo 4=72 }
        \paper { linewidth = 10.0\cm }
}

The result would look this.³

The river is flowing

Traditional

Again, we will dissect the file line by line.

***

        \header {

Information about the music you are about to typeset goes into a \header block. The information in this block is not used by LilyPond, but it is passed into the output. ly2dvi uses this information to print titles above the music.

***

        title = "The river is flowing"
        composer = "Traditional (?)"

the \header block contains assignments. In each assignment, a variable is set to a value. Lexically, both the variable name and the assigned value are strings. The values have to be quoted here, because they contain spaces. The variable names could also be put within quotes but it is not necessary.

***

        \include "paper16.ly"

Smaller size for inclusion in a book.

***

        melody = \notes \relative c' {

The structure of the file will be the same as the previous one, a \score block with music in it. To keep things readable, we will give names to the different parts of music, and use the names to construct the music within the score block.

***

        \partial 8

The piece starts with an anacrusis of one eighth.

***

        \key c \minor

The key is C minor: we have three flats.

***

        c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
        c4 c8 d [es () d] c4 | d4 es8 d c4.
        \bar "|."

We use explicit beaming. Since this is a song, we turn automatic beams off, and use explicit beaming where needed.

***

This ends the definition of melody.

***

        text = \lyrics {

Another identifier assignment. This one is for the lyrics. Lyrics are formed by syllables that have duration, and not by notes. To make LilyPond parse words as syllables, switch it into lyrics mode with \lyrics. Again, the brace after \lyrics is a shorthand for \sequential {.

***

  The4 ri -- ver is flo- __ wing,  flo -- wing and gro -- wing, the
  ri- ver is flo- __ wing down to the sea.
}

The syllables themselves are separated by spaces. You can get syllable extenders by entering __, and centered hyphens with --. We enter the syllables as if they are all quarter notes in length (hence the 4), and use a feature to align the syllables to the music, which obviously isn't all quarter notes.

***

        accompaniment =\chords {

We'll put chords over the music. To enter them, there is a special mode analogous to \lyrics and \notes mode, where you can give the names of the chords you want, instead of listing the notes comprising the chord.

***

r8

There is no accompaniment during the anacrusis.

***

        c2:3- f:3-.7

A chord is started by the tonic of the chord. The first one lasts a half note. An unadorned note creates a major triad. Since a minor triad is wanted, 3- is added to modify the third to be small. 7 modifies (adds) a seventh, which is small by default to create the f a c es chord. Multiple modifiers must be separated by dots.

***

        d:min es4 c8:min r8

Some modifiers have predefined names, e.g. min is the same as 3-, so d-min is a minor d chord.

***

        c2:min f:min7 g:7^3.5 c:min }

A named modifier min and a normal modifier 7 do not have to be separated by a dot. Tones from a chord are removed with chord subtractions. Subtractions are started with a caret, and they are also separated by dots. In this example, g:7^3.5 produces a minor seventh. The brace ends the sequential music.

***

        \score {
                \simultaneous {

We assemble the music in the \score block. Melody, lyrics and accompaniment have to sound at the same time, so they should be \simultaneous.

***

        %\accompaniment

Chord mode generates notes grouped in \simultaneous music. If you remove the comment sign, you can see the chords in normal notation: they will be printed as note heads on a separate staff. To print them as chords names, they have to be interpreted as being chords, not notes. This is done with the following command:

***

        \context ChordNames \accompaniment

Normally, the notes that you enter are transformed into note heads. Note heads alone make no sense, they need surrounding information: a key signature, a clef, staff lines, etc. They need context. In LilyPond, these symbols are created by objects called `interpretation contexts'. Interpretation contexts exist for generating notation (`notation context') and for generating sound (`performance context'). These objects only exist during a run of LilyPond.

By default, LilyPond will create a Staff context for you. If you would remove the % sign in the previous line, you would see that mechanism in action.

We don't want that default here, because we want chord names. The command above explicitly creates an interpretation context of ChordNames type to interpret the music \accompaniment.

***

        \addlyrics

The lyrics should be aligned with the melody. This is done by combining both with \addlyrics. \addlyrics takes two pieces of music (usually a melody and lyrics, in that order) and aligns the syllables of the second piece under the notes of the first piece. If you would reverse the order, the notes would be aligned on the lyrics, which is not very useful, and looks silly.

***

        \context Staff = mel {

The first argument of \addlyrics is the melody. We instantiate a Staff context explicitly: should you choose to remove the comment before the "note heads" version of the accompaniment, the accompaniment will be on a nameless staff. The melody has to be on staff different from the accompaniment. This is accomplished by giving the melody and accompaniment staffs different names.

***

        \property Staff.noAutoBeaming = ##t

An interpretation context has variables, called properties, that tune its behavior. One of the variables is noAutoBeaming. Setting this Staff's property to ##t, which is the boolean value true, turns the automatic beaming mechanism off for the current staff.

LilyPond internally uses GUILE, a Scheme-interpreter. Scheme is a language from the LISP family. You can learn more about Scheme at http://www.scheme.org. It is used to represent data throughout the whole program. The hash-sign (#) accesses GUILE directly: the code following the hash-sign is evaluated as Scheme. The boolean value true is #t in Scheme, so for LilyPond true looks like ##t.

If Scheme scares you, don't worry. You don't need to know Scheme to create beautiful sheet music.

***

        \property Staff.automaticMelismata = ##t

Similarly, we don't want to print a syllable when there is a slur. This sets up \addlyrics to not put lyrics under each separate note while there is a slur.

***

          \melody
        }

Finally, we put the melody on the current staff. Note that the \property directives and \melody are grouped in sequential music, so the property settings are done before the melody is processed.

***

        \context Lyrics \text

The second argument of \addlyrics is the text. The text also should not land on a Staff, but on a interpretation context for syllables, extenders, hyphens etc. This context is called Lyrics.

***

        \midi  { \tempo 4=72}

MIDI (Musical Instrument Digital Interface) is a standard for connecting and recording digital instruments. So a MIDI file is like a tape recording of an 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. Whenever you hear something weird, you probably hear a typing error.

Syntactically, \midi is similar to \paper { }, since it also specifies an output method. You can specify the tempo using the \tempo command, in this case the tempo of quarter notes is set to 72 beats per minute.

***

        \paper { linewidth = 10.0\cm }

We also want notation output. The linewidth is short so the piece will be set in two lines.

More movements

[FIXME: merge here with, or move this to: Other ways to run LilyPond]

You probably ran ly2dvi on the last example, and ended up with a viewable .dvi file. However, between there are a few steps of which LilyPond is only one. To enhance your understanding of what's happening under the hood when you run ly2dvi, we explain what programs are run.

ly2dvi is a program that calls a number of programs in sequence. The first thing it does, is running LilyPond on the input file. After some calculations, a .tex is produced. The contents of this file are very low-level instructions.

For example, consider the following file (miniatures.ly)

\version "1.4.0"
\header {
  title = "Two miniatures"
  tagline = "small is beautiful"
}

#(set! point-and-click line-column-location)

\paper { linewidth = -1.0 }

\score {
    \notes { c'4 d'4 }
    \header {
        opus = "Opus 1."
        piece = "Up" }
}
\score {
    \notes { d'4 c'4 }
    \header {
        opus = "Opus 2."
        piece = "Down" }
}

The titling in this manual was not generated by ly2dvi, so we can't exactly show what it would look like, but the result should resemble this:

Two miniatures

Opus 1.

Up

Opus 2.

Down

This file is produced by ly2dvi in a few stages, with the help of text formatting tools. LilyPond produces two output files, miniatures.tex and miniatures-1.tex. Both files contain only graphical music notation. ly2dvi looks at what output LilyPond produces, and adds page layout and titling to those files. The result is a DVI file called miniatures.dvi.

Next, now we'll look at the example line by line to explain new things.

***

\version "1.4.0"

Lilypond and its language are still under development, and occasionally, details of the syntax are changed. This fragment indicates for which version the input file was written. When you compile this file, the version number will be checked, and you will get a warning when the file is too old.

This version number is also used by the convert-ly program (See convert-ly), which is used to update the file to the latest lily version.

***

  \header {
    title = "Two miniatures"  }

This sets the titling information for the entire file.

***

    tagline = "small is beautiful"

A signature line is printed at the bottom of the last page. This signature is produced from the tagline field of \header. Many people find the default "Lily was here, version number" too droll. If that is the case, assign something else to tagline, as shown above.

***

        #(set! point-and-click line-column-location)

This piece of Scheme code sets the Scheme variable point-and-click to the value line-column-location (which itself is a Scheme procedure).

Editing input files can be quite complicated if you're working with large files: if you're digitizing existing music, you have to synchronize the .ly file, the sheet music on your lap and the sheet music on the screen. The point-and-click mechanism makes it easy to find the origin of an error in the LY file: when you view the file with Xdvi and click on a note, your editor will jump to the spot where that note was entered. For more information, see Point and click.

***

  \paper {

The \score blocks that follow in the file don't have \paper sections, so the settings of this block are substituted: A paper block at top level, i.e. not in a \score block sets the default page layout.

***

  linewidth = -1.0 }

The variable linewidth normally sets the length of the systems on the page. However, a negative value has a special meaning. If linewidth is less than 0, no line breaks are inserted into the score, and the spacing is set to natural length: a short phrase takes up little space, a longer phrase more space.

***

  \score {
    \notes { c'4 d'4 }

In previous examples, notes were specified in relative octaves, i.e. each note was put in the octave that is closest to its predecessor. Besides relative, there is also absolute octave specification, which you get when you don't specify \relative. In this input mode, the central C is denoted by c'. Going down, you get c c, c,, etc. Going up, you get c'' c''' etc.

When you're copying music from existing sheet music, relative octaves are probably the easiest to use: it's less typing work and errors are easily spotted. However, if you write LilyPond input directly, either by hand (i.e. composing) or by computer, absolute octaves may be easier to use.

***

    \header {

The \header is normally at the top of the file, where it sets values for the rest of the file. If you want to typeset different pieces from one file (for example, if there are multiple movements, or if you're making an exercise book), you can put different \score blocks into the input file. ly2dvi will assemble all LilyPond output files into a big document. The contents of \header blocks specified within each score, are used for the titling of each movement.

***

        opus = "Opus 1."
        piece = "Up" }

For example, the Opus number is put at the right, and the piece string will be at the left.

A piano excerpt

Our fourth subject is a piece of piano music. The fragment in the input file is a piano reduction of the G major Sinfonia by Giovanni Battista Sammartini. It was composed around 1740. It's in the source package under the name sammartini.ly.

\include "paper16.ly"

stemDown = \property Voice.Stem \override #'direction = #-1
stemUp = \property Voice.Stem \override #'direction = #1
stemBoth = \property Voice.Stem \revert #'direction

viola = \notes \relative c' \context Voice = viola {
    <c4-\f-\arpeggio g' c>
    \stemDown g'8. b,16
    s1 s2. r4
    g
}

oboes = \notes \relative c'' \context Voice = oboe {
    \stemUp s4  g8. b,16 c8 r <e'8.^\p g> <f16 a>
    \grace <e8( g> <d4 )f> <c2 e>
    \times 2/3 { <d8 \< f> <e g> <f a> }
    <
        { \times 2/3 { a8 g c } \! c2 }
        \context Voice = oboeTwo {
            \stemDown
            \grace {
                \property Grace.Stem \override #'direction = #-1
                [f,16 g] }
            f8 e e2
        }
    >
    \stemBoth
    \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
    [<d ( f> < )f8. a>] <)b,8 d> r [<d16( f> <f8. )a>] <b,8 d> r  |
    [<c16( e>  < )e8. g>] <c8 e,>
}

hoomPah = \repeat unfold 8 \notes
    \transpose c' { \stemUp c8 \stemBoth \stemDown c'8 \stemBoth }

bassvoices = \notes \relative c' {
    c4 g8. b,16
    \autochange Staff \hoomPah
    \translator Staff = down
    \stemDown [c8 c'8] r4
    <g d'> r4
    < {\stemUp r2 <e4 c'> <c8 g'> }
        \context Voice = reallyLow  {\stemDown g2 ~ | g4 c8 } >
}

\score {
    \context PianoStaff \notes <
        \context Staff = up < \time 2/2
            \viola
            \oboes
        >
        \context Staff = down < \time 2/2 \clef bass
            \bassvoices
        >
    >
    \midi { }
    \paper {
        indent = 0.0
        linewidth = 15.0 \cm }
}

If this looks like incomprehensible gibberish to you, you are right. This example has been doctored to have as many quirks as possible.

As you can see, this example features multiple voices on one staff. To make room for those voices, their notes have to be stemmed in opposite directions.

Printed symbols are internally represented by so-called Graphical Objects (more colloquially: Grobs). These statements concern the grob called `Stem'. Each grob is described by a bunch of settings. These setting determine the fonts, offsets, sub-routines to be called on the grob, etc. The initial values of these settings are set in the Scheme file scm/grob-description.scm.

***

  stemDown = \property Voice.Stem \override #'direction = #-1

Set a property for all Stem grobs in the current Voice: direction is set to -1, which encodes down. The setting remains in effect until it is reverted.

***

 \property Voice.Stem \revert #'direction

Revert the to the previous setting. The effect of precisely one \stemDown or \stemUp is neutralized.

LilyPond includes the identifiers \stemUp, \stemDown along with some other commonly used formatting instructions, but to explain how it works, we wrote our own here. Of course, you should use predefined identifiers like these if possible: then you will be affected less by the implementation changes we occasionally make.

***

viola = \notes \relative c'  \context Voice = viola {

In this example, you can see multiple parts on a staff. Each part is associated with one notation context. This notation context handles stems and dynamics (among others). The type name of this context is Voice. For each part we have to make sure that there is precisely one Voice context, so we give it a unique name (`viola').

***

<c4-\f-\arpeggio g' c>

The delimiters < and > are shorthands for \simultaneous { and }. The expression enclosed in < and > is a chord.

\f places a forte symbol under the chord. The forte applies to the whole chord, but the syntax requires that commands like forte and arpeggio are attached to a note, so here we attach them to the first note.

\arpeggio typesets an arpeggio sign (a wavy vertical line) before the chord.

***

   \stemDown

***

        g'8. b,16

Relative octaves work a little differently with chords. The starting point for the note following a chord is the first note of the chord. So the g gets an octave up quote: it is a fifth above the starting note of the previous chord (the central C).

***

s1 s2. r4

s is a spacer rest. It does not print anything, but it does have the duration of a rest. It is useful for filling up voices that temporarily don't play. In this case, the viola doesn't come until one and a half measure later.

***

oboes = \notes \relative c'' \context Voice = oboe {

Now comes a part for two oboes. They play homophonically, so we print the notes as one voice that makes chords. Again, we insure that these notes are indeed processed by precisely one context with \context.

***

\stemUp s4  g8. b,16 c8 r <e'8.-\p g> <f16 a>

\stemUp is a reference to the \property \override command defined above.

***

\grace <e8 g> < d4 f> <c2 e>

\grace introduces grace notes. It takes one argument, in this case a chord.

***

\times 2/3

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 in this case the fraction is 2/3.

***

{ <d8 \< f> <e g> <f a> }

The piece of music to be `tripletted' is sequential music containing three notes. On the first chord, a crescendo is started with \<. To be precise, the crescendo start is syntactically attached to the preceding note, the d.

***

At this point, the homophonic music splits into two rhythmically different parts. We can't use a sequence of chords to enter this, so we make a `chord' of sequences to do it. We start with the upper voice, which continues with upward stems:

***

 { \times 2/3 { a8 g c } \! c2 }

The crescendo is ended at the half note by the escaped exclamation mark \!.

***

\context Voice = oboeTwo {
\stemDown

We can't share stems with the other voice, so we have to create a new Voice context. We give it the name oboeTwo to distinguish it from the other context. Stems go down in this voice.

***

\grace {

When a grace section is processed, a Grace context is created. This context acts like a miniature score of its own. It has its own time bookkeeping, and you can make notes, beams, slurs etc. Here we fiddle with a property and make a beam. The argument of \grace is sequential music.

***

\property Grace.Stem \override #'direction = #-1
[f,16 g] }

Normally, grace notes are always stem up, but in this case, the upper voice interferes, so we set the stems down here.

As far as relative mode is concerned, the previous note is the c'''2 of the upper voice, so we have to go an octave down for the f.

***

  f8 e e2
} >

This ends the two-part section.

***

\stemBoth
\grace <c,8( e> <)b8. d8.-\trill> <c16 e> |

\stemBoth ends the forced stem directions. From here, stems are positioned as if it were single part music.

The bass has a little hoom-pah melody to demonstrate parts switching between staffs. Since it is repetitive, we use repeats:

***

hoomPah  =  \repeat unfold 8

The unfolded repeat prints the notes in its argument as if they were written out in full eight times.

***

\notes \transpose c' {

Transposing can be done with \transpose, which takes two arguments. The first specifies what central C should be transposed to. The second is the to-be-transposed music. As you can see, in this case, the transposition has no effect, as central C stays at central C.

The purpose of this no-op is circumventing relative mode. Relative mode can not be used together with transposition, so \relative will leave the contents of \hoomPah alone. We can use it without having to worry about getting the motive in a wrong octave.

***

bassvoices = \notes \relative c' {
c4 g8. b,16
\autochange Staff \hoomPah

Voices can switch between staffs. The easiest way to get this, is to use \autochange. This command looks at the pitch of each note, and if necessary, will cross to the other staff. For this to work, the two staffs must be called "up" and "down".

***

        \translator Staff = down

We want the remaining part of this melody on the lower staff, so we do a manual staff switch here.

***

\context Voice = reallyLow  {\stemDown g2 ~ | g4 c8 } >

After skipping some lines, we see ~. This mark makes ties. Note that ties and slurs are different things. A tie can only connect two note heads of the same pitch, whereas a slur can connect many chords with one curve.

***

\context PianoStaff

A special context is needed to get cross staff beaming right. This context is called PianoStaff.

***

\context Staff = bottom < \time 2/2 \clef bass

The bottom staff must have a different clef.

***

indent = 0.0

To make some more room on the line, the first (in this case the only) line is not indented. The line still looks very cramped, but that is due to the page layout of this document.

An orchestral score

Our last two examples show a way to setup the music for an orchestral score. When typesetting a piece for several instruments, you'll want to create a conductor's full score, alongside several individual parts.

LilyPond is well suited for this task. We will declare the music for each instrument individually, giving the music of each instrument its own name. These pieces of music are then combined in different \score blocks to produce different combinations of the score.

This orchestral score example consists of three input files. In the first file, os-music.ly, we define the music for all instruments. This file will be used both for producing the score and the separate parts.

If you were to run LilyPond on this file, no printable output would be produced.

% os-music.ly
\header {
  title = "Zo, goed lieverd?"
  subtitle = "How's, this babe?"
  composer = "JCN"
  opus = "1"
  piece = "Laid back"
}
global = {
  \time 2/4
  \skip 2*4 \bar "|."
}
Key = \notes \key as \major
flautoI = \notes\relative c'' {
  f8 g f g f g f g
  bes as bes as bes as bes as
}
flautoII = \notes\relative c'' {
  as8 bes as bes R1 d4 ~ d
}
tromboI = \notes\relative c'' {
  c4. c8 c8 c4. es4 r as, r
}
tromboII = \notes\relative c'' {
  as4. as8 as8 as4. R1*1/2 as4 es'
}
timpani = \notes\relative c, {
  \times 2/3 { f4 f f }
  \times 4/5 { as8 as as as as }
  R1
}
corno = \notes\relative c' {
   bes4 d f, bes d f, bes d
}

We will not go through the input line by line, but only indicate and explain the new elements.

***

global = {
  \time 2/4
  \skip 2*4 \bar "|.";
}

Declare setting to be used globally. The \skip command produces no output, but moves forward in time: in this case, the duration of a half note (2), and that four times (*4). This brings us to the end of the piece, and we can set the end bar.

***

Key = \notes \key as \major

Declare the key signature of the piece and assign it to the identifier Key. Later on, we'll use \Key for all staffs except those for transposing instruments.

The full score

The second file, os-score.ly reads the definitions of the first (os-music.ly), and defines the \score block for the full conductor's score.

% os-score.ly
\include "os-music.ly"
\include "paper13.ly"

#(set! point-and-click line-column-location)
#(define text-flat '((font-relative-size . -2)
         (music "accidentals--1")))

\score {
  <
    \global
    \property Score.BarNumber \override #'padding = #3
    \context StaffGroup = woodwind <
      \context Staff = flauti <
        \property Staff.midiInstrument = #"flute"
        \property Staff.instrument = "2 Flauti"
        \property Staff.instr = "Fl."
        \Key
        \context Voice=one { \voiceOne \flautoI }
        \context Voice=two { \voiceTwo \flautoII }
      >
    >
    \context StaffGroup = timpani <
      \context Staff = timpani <
        \property Staff.midiInstrument = #"timpani"
        \property Staff.instrument = #'(lines "Timpani" "(C-G)")
        \property Staff.instr = #"Timp."
        \clef bass
        \Key
        \timpani
      >
    >
    \context StaffGroup = brass <
      \context Staff = trombe <
  	\property Staff.midiInstrument = #"trumpet"
        \property Staff.instrument = #`(lines "2 Trombe" "(C)")
        \property Staff.instr = #`(lines "Tbe." "(C)")
        \Key
        \context Voice=one \partcombine Voice
          \context Thread=one \tromboI
          \context Thread=two \tromboII
      >
      \context Staff = corni <
        \property Staff.midiInstrument = #"french horn"
        \property Staff.instrument = #`(lines "Corno"
          (columns "(E" ,text-flat ")"))
        \property Staff.instr = #`(lines "Cor."
          (columns "(E" ,text-flat ")"))
        \property Staff.transposing = #3
        \notes \key bes \major
        \context Voice=one \corno
      >
    >
  >
  \paper {
    indent = 15 * \staffspace
    linewidth = 60 * \staffspace
    textheight = 90 * \staffspace
    \translator{
      \HaraKiriStaffContext
    }
  }
  \midi {
    \tempo 4 = 75
  }
}

Zo, goed lieverd?

How's, this babe?

Opus 1.

LAID BACK

***

\include "os-music.ly"

First, we need to include the music definitions we made in os-music.ly.

***

#(set! point-and-click line-column-location)

In a large orchestral score like this you're bound to make some small mistakes, so we enable point and click (See Point and click) editing.

***

#(define text-flat '((font-relative-size . -2)
         (music "accidentals--1")))

When naming the tuning of the french horn, we'll need a piece of text with a flat sign. LilyPond has a mechanism for font selection and kerning called Scheme markup text (See Text markup). The flat sign is taken from the music font, and its name is accidentals--1 (The sharp sign is called accidentals-1). The default font is too big for text, so we select a relative size of -2.

***

  <
    \global

Of course, all staffs are simultaneous and use the same global settings.

***

    \property Score.BarNumber \override #'padding = #3

LilyPond prints bar numbers at the start of each line, but unfortunately, they end up a bit too close to the staff in this example. A bar number internally is a Grob called BarNumber. BarNumber Grobs can be manipulated through their side-position-interface. One of the properties of a side-position-interface that can be tweaked is the padding: the amount of extra space that is put between this Grob and other Grobs. We set the padding to three staff spaces.

You can find information on all these kind of properties in LilyPond's automatically generated documentation in LilyPond Internals.

***

    \context StaffGroup = woodwind <
      \context Staff = flauti <

A new notation context: the StaffGroup. StaffGroup can hold one or more Staffs, and will print a big bracket at the left of the score. Start a new staff group for the woodwind section (just the flutes in this case). Immediately after that, we start the staff for the two flutes, that also play simultaneously.

***

        \property Staff.midiInstrument = #"flute"

Specify the instrument for MIDI output (see MIDI instrument names).

***

        \property Staff.instrument = "2 Flauti"
        \property Staff.instr = "Fl."

And define the instrument names to be printed in the margin, instrument for the first line of the score, instr for the rest of the score.

***

        \Key

The flutes play in the default key.

***

        \context Voice=one { \voiceOne \flautoI }
        \context Voice=two { \voiceTwo \flautoII }

Last come the actual flute parts. Remember that we're still in simultaneous mode. We name both voices differently, so that LilyPond will actually create two Voice contexts. The flute parts are simple, so we specify manually which voice is which: \voiceOne forces the direction of stems, beams, slurs and ties up, \voiceTwo sets directions down.

***

      >
    >

Close the flutes staff and woodwind staff group.

***

        \property Staff.instrument = #'(lines "Timpani" "(C-G)")

The timpani staff only shows a new piece of scheme markup, it sets two lines of text.

***

        \context Voice=one \partcombine Voice
          \context Thread=one \tromboI
          \context Thread=two \tromboII

You have seen the notation contexts Staff and Voice, but here's a new one: Thread. One or more Threads can be part of a Voice. The Thread takes care of note heads and rests, the Voice combine note heads onto a stem.

For the trumpets we use the automatic part combiner (see Automatic part combining) to combine the two simultaneous trumpet parts onto the trumpet staff. Each trumpet gets its own Thread context, which must be named one and two). The part combiner makes these two threads share a Voice when they're similar, and splits the threads up when they're different.

***

      	\property Staff.instrument = #`(lines "Corno"
          (columns "(E" ,text-flat ")"))

The french horn has the most complex scheme markup name, made up of two lines of text. The second line has three elements (columns), the (E, the flat sign text-flat that we defined before and a final ")". Note that we use a backquote instead of an ordinary quote at the beginning of the Scheme expression to be able to access the text-flat identifier, `unquoting' it with a ,.

***

        \property Staff.transposing = #3

The french horn is to be tuned in E-flat, so we tell the MIDI backend to transpose this staff by three steps.

Note how we can choose different tuning for entering, printing and playing, using \transpose and the MIDI Staff property transposing.

***

        \notes \key bes \major

Therefore, it has a different key.

***

    indent = 15 * \staffspace
    linewidth = 60 * \staffspace

We specify a big indent for the first line and a small linewidth for this tutorial.

***

Usually, LilyPond's predefined setup of notation contexts (Thread, Voice, Staff, Staffgroup, Score) is just fine. But in this case, we want a different type of Staff context.

    \translator{
      \HaraKiriStaffContext
    }

In orchestral scores, it often happens that one instrument has only rests during one line of the score. The HaraKiriStaffContext can be used as a regular StaffContext drop-in and will take care of the automatic removing of empty staffs.

Extracting an individual part

The third file, os-flute-2.ly also reads the definitions of the first (os-music.ly), and defines the \score block for the second flute part.

\include "os-music.ly"
\include "paper16.ly"

\score {
  \context Staff <
    \property Score.skipBars = ##t
    \property Staff.midiInstrument = #"flute"
    \global
    \Key
    \flautoII
  >
  \header {
    instrument = "Flauto II"
  }
  \paper {
    linewidth = 80 * \staffspace
    textheight = 200 * \staffspace
  }
  \midi {
    \tempo 4 = 75
  }
}

Zo, goed lieverd?

How's, this babe?

Flauto II

Opus 1.

LAID BACK

Because we separated the music definitions from the \score instantiations, we can easily define a second score with the music of the second flute. This then is the part for the second flute player. Of course, we make separate parts for all individual instruments.

***

    \flautoII

In this individual part the second flute has a whole staff for itself, so we don't want to force stem or tie directions.

***

  \header {
    instrument = "Flauto II"
  }

The \header definitions were also read from os-music.ly, but we need to set the instrument for this particular score.

***

    \property Score.skipBars = ##t

In the conductor's full score, all bars with rests are printed, but for the individual parts, we want to contract pieces of consecutive empty bars. LilyPond will do this if Score's skipBars property to true.

Other ways to run LilyPond

Until now, you have been using ly2dvi to invoke LilyPond. There are three other routes. Firstly, there is a script called lilypond-book, that allows you to freely mix LilyPond input with Texinfo or \LaTeX input. For example, this manual was written using lilypond-book. It is discussed below and in lilypond-book.

Secondly, you can generate PostScript directly. This is useful if you can not or do not want to run TeX on your system. To obtain direct PostScript output, invoke LilyPond as follows:

lilypond -f ps test.ly

You have to set some environment variables to view or print this output. More information can be found in Invoking LilyPond. Since the direct Postscript generation has some problems, it is recommended to use ly2dvi.

Thirdly, if you want to do special things with your output, you can run invoke LilyPond directly:

lilypond test.ly

to produce plain TeX output. Note that LaTeX will not work on the resulting test.tex. You must run plain TeX on it.

Integrating text and music

Sometimes, you might want to use music examples in a text that you are writing. For example, if you are writing 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 wordprocessor. However, there is a also an automated procedure:

If you use 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. lilypond-book is described fully in lilypond-book, but here we show a small example. Since the example also contains explanatory text, we won't comment on the contents.

\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, a number of things happened: a
\verb+\score+ block was added, and the line width was set to natural
length. You can specify many more options using  \LaTeX style options
in brackets:

\begin[verbatim,11pt,singleline,
  fragment,relative,intertext="hi there!"]{lilypond}
  c'4 f bes es
\end{lilypond}

\texttt{verbatim} also shows the LilyPond code, \texttt{11pt} selects
the default music size, \texttt{fragment} adds a score block,
\texttt{relative} uses relative mode for the fragment, and
\texttt{intertext} specifies what to print between the
\texttt{verbatim} code and the music.

If you include large examples into the text, it may be more convenient
to put the example in a separate file:

\lilypondfile[printfilename]{sammartini.ly}

The \texttt{printfilename} option adds the file name to the output.

\end{document}

Under Unix, you can view the results as follows.

$ cd input/tutorial
$ lilypond-book --outdir=out/ lilbook.tex
lilypond-book (GNU LilyPond) 1.3.146
Reading `/home/hanwen/usr/src/lilypond-1.3.146/input/tutorial/lilbook.tex'
Reading
`/home/hanwen/usr/src/lilypond-1.3.146/input/tutorial/sammartini.ly'
lots of stuff deleted
Writing `out/lilbook.latex'
$ cd out
$ latex lilbook.latex
lots of stuff deleted
$ xdvi lilbook

Notice the outdir option to lilypond-book. Running lilypond-book and running latex creates a lot of temporary files, and you wouldn't want those to clutter up your working directory. Hence, we have them created in a separate subdirectory.

The result more or less looks 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, a number of things happened: a \score block was added, and the line width was set to natural length. You can specify many more options using LaTeX style options in brackets:

  c'4 f bes es

hi there!

verbatim also shows the LilyPond code, 11pt selects the default music size, fragment adds a score block, relative uses relative mode for the fragment, and intertext specifies what to print between the verbatim code and the music.

If you include large examples into the text, it may be more convenient to put the example in a separate file:

../.././input/tutorial/sammartini.ly:

The printfilename option adds the file name to the output.

End of tutorial

That's all folks. From here, you can either try fiddling with input files, or you can read the reference manual. You can find more example files in input and input/test. You can also look at some real music. The website http://www.mutopiaproject.org has many examples of real music typeset by LilyPond.

Reference Manual

This document describes GNU LilyPond and its input format. The last revision of this document was made for LilyPond 1.4.1. It supposes a passing familiarity with how LilyPond input works. New users are encouraged to study the tutorial first.

The reference manual is ordered according to different tasks. More details on the property setting mechanisms and context handling is provided in Tuning output and Interpretation context. The syntactical details are described at the end of the manual.

Overview

The purpose of LilyPond is explained informally by the term `music typesetter'. This is not a fully correct name: not only does the program print musical symbols, it also makes aesthetic decisions. Symbols and their placements are generated from a high-level musical description. In other words, LilyPond would be best described by `music compiler' or `music to notation compiler'.

LilyPond is linked to GUILE, GNU's Scheme library for extension programming. The Scheme library provides the glue that holds together the low-level routines and separate modules which are written in C++.

When lilypond is run to typeset sheet music, the following happens:

GUILE Initialization: various scheme files are read
parsing: first standard ly initialization files are read, and then the user ly file is read.
interpretation: the music in the file is processed "in playing order", i.e. the order that you use to read sheet music, or the order in which notes are played. The result of this step is a typesetting specification.
typesetting: The typesetting specification is solved: positions and formatting is calculated.
the visible results ("virtual ink") are written to the output file.

During these stages different types of data play the the main role: during parsing, Music objects are created. During the interpretation, contexts are constructed, and with these contexts a network of graphical objects ("grobs") is created. These grobs contain unknown variables, and the network forms a set of equations. After solving the equations and filling in these variables, the printed output (in the form of molecules) is written to an output file.

These threemanship of tasks (parsing, translating, typesetting) and data-structures (music, context, graphical objects) permeates the entire design of the program.

Note entry

The most basic forms of music are notes. We discuss how you enter them here. Notes on their own don't form valid input, but for the sake of brevity we omit obligatory lint such as \score blocks and \paper declarations.

Notes

A note specification has the form

  pitch[!][?][duration]

The alteration refers to what note is heard, not to whether an accidental is printed. This is done depending on the key and context. A reminder accidental can be forced by adding an exclamation mark ! after the pitch. A cautionary accidental, i.e., an accidental within parentheses can be obtained by adding the question mark `?' after the pitch.

  cis' d' e' cis'  c'? d' e' c'!

The grob for a note head is called NoteHead .

Pitches

The verbose syntax for pitch specification is

  \pitch scmpitch

scmpitch is a pitch scheme object, see Pitch data type.

In Note and Chord mode, pitches may be designated by names. The default names are the Dutch note names. The notes are specified by the letters a through g (where the octave is formed by notes ranging from c to b). The pitch c is an octave below middle C and the letters span the octave above that C.

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

LilyPond has predefined sets of note names for various other languages. To use them, simply include the language specific init file. For example: \include "english.ly". The available language files and the 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

For polyphonic music, it can be convenient to specify the rest position directly. You can do that by entering a note, with the keyword \rest appended, e.g. Rest collisions will leave these rests alone.

a'4\rest d'4\rest

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'

Rests

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

r1 r2 r4 r8

The grob is Rest . Whole bar rests centered in the bar are specified using R, see Multi measure rests.

Skips

An invisible rest, or skip, can be entered like a note with note name `s':

a2 s4 a4 s1 a4

Actually, this is a shorthand for the \skip command, and it is only available in Note mode and Chord mode.

In Lyrics mode, you can use `" "' and `_':

<
  \context Lyrics \lyrics { lah2 di4 " " dah2 _4 di }
  \notes\relative c'' { a2 a4 a a2 a4 a }
>

The unabbreviated `\skip duration' also works outside of note mode:

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

Durations

The syntax for a verbose duration specification is

 \duration scmduration

Here, scmduration is a Scheme object of type Duration. See Duration for more information.

In Note, Chord, and Lyrics mode, durations may be designated by numbers and dots: durations are entered as their reciprocal values. For notes longer than a whole you must use identifiers.

 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

To get a longa note head, you have to use mensural note heads. This is accomplished by setting the style property of the NoteHead grob to mensural. There is also a note head style baroque which gives mensural note heads for \longa and \breve but standard note heads for shorter notes.

 \property Voice.NoteHead \set #'style = #'mensural
 a'\longa

If the duration is omitted then it is set to the previous duration entered. At the start of parsing a quarter note is assumed. The duration can be followed by dots (`.') to obtain dotted note lengths.

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

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

Ties

A tie connects two adjacent note heads of the same pitch. When used with chords, it connects all the note heads whose pitches match. Ties are indicated using the tilde symbol `~'. If you try to tie together chords which have no common pitches then no ties will be created.

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

If you dislike the amount of ties created for a chord, you set Voice.sparseTies to true, resulting in a smaller number of ties:

  \property Voice.sparseTies = ##t
  <c' e' g'> ~ <c' e' g'>

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

The name of the tie grob is Tie . It is usually created in the Voice context.

BUGS

At present, the tie is implemented as a separate thing, temporally located in between the notes. There is also no way to convert between tied notes, dotted notes and plain notes.

Tieing only a subset of the note heads of a chord 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.

Tuplets

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

  \times fraction musicexpr

The duration of musicexpr will be multiplied by the fraction. In print, 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, thus saving typing work.

\property Voice.tupletSpannerDuration = #(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 you set it to the Scheme function fraction-tuplet-formatter, Lilypond will print num:den instead.

The typesetting of brackets and numbers is controlled by the properties tuplet-bracket-visibility and tuplet-number-visibility.

\property Voice.TupletBracket \set #'tuplet-bracket-visibility = ##t
\times 2/3{c'8 d e} \times 2/3{d4 e8}
\property Voice.TupletBracket \set #'tuplet-bracket-visibility = #'if-no-beam
\times 2/3{c d e} \times 2/3{d4 e8}
\property Voice.TupletBracket \set #'tuplet-bracket-visibility = ##f
\times 2/3{c d e} \times 2/3{d4 e8}
\property Voice.TupletBracket \set #'tuplet-number-visibility = ##f
\times 2/3{c d e} \times 2/3{d4 e8}
\property Voice.TupletBracket \set #'tuplet-number-visibility = #'if-no-beam
\times 2/3{c d e} \times 2/3{d4 e8}

Tuplet brackets are printed as TupletBracket grobs

Defining pitch names

Note names and chord modifiers can be customized for nationalities. The syntax is as follows.

   \pitchnames scheme-alist
   \chordmodifiers scheme-alist

See ly/nederlands.ly and ly/chord-modifiers.ly for specific examples on how to do this.

Easy Notation note heads

A entirely different type of note head is the "easyplay" note head: a note head that includes a note name. It is used in some publications by Hal-Leonard Inc. music publishers.

\include "paper23.ly"
\score {
  \notes { c'2 e'4 f' | g'1 }
  \paper { \translator { \EasyNotation } }
}

Note that EasyNotation overrides a Score context. You probably will want to print it with magnification to make it more readable, see Output scaling.

If you view the result with Xdvi, then staff lines will show through the letters. Printing the postscript file obtained either by using dvips or the -f ps option of lilypond produces the correct result.

Staff notation

Key signature

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, see the generated documentation for KeySignature .

The printed signature is a KeySignature grob.

Clef

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

  \clef clefname

Shortcut for

  \property Staff.clefGlyph = glyph associated with clefname
  \property Staff.clefPosition = clef Y-position for clefname
  \property Staff.clefOctavation = extra transposition of clefname

Any change in these properties creates a clef (a Clef grob).

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.

Supported associated glyphs (for Staff.clefGlyph) are:

clefs-C: modern style C clef
clefs-F: modern style F clef
clefs-G: modern style G clef
clefs-vaticana_do: Editio Vaticana style do clef
clefs-vaticana_fa: Editio Vaticana style fa clef
clefs-medicaea_do: Editio Medicaea style do clef
clefs-medicaea_fa: Editio Medicaea style fa clef
clefs-mensural1_c: modern style mensural C clef
clefs-mensural2_c: historic style small mensural C clef
clefs-mensural3_c: historic style big mensural C clef
clefs-mensural1_f: historic style traditional mensural F clef
clefs-mensural2_f: historic style new mensural F clef
clefs-mensural_g: historic style mensural G clef
clefs-hufnagel_do: historic style hufnagel do clef
clefs-hufnagel_fa: historic style hufnagel fa clef
clefs-hufnagel_do_fa: historic style hufnagel combined do/fa clef
clefs-percussion: modern style percussion clef

Modern style means "as is typeset in current editions." Historic style means "as was typeset or written in contemporary historic editions". Editio XXX style means "as is/was printed in Editio XXX."

Time signature

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

  \time n/d

Internally, this is a shortcut for doing

\property Score.timeSignatureFraction = #'(n . d)
\property Score.beatLength = #(make-moment 1 d)
\property Score.measureLength = #(make-moment n d)

These properties timeSignatureFraction determine where bar lines should be inserted, and how automatic beams should be generated.

Changing the value of timeSignatureFraction also causes a fraction to be printed. This grob is TimeSignature .

The actual symbol that's printed can be customized with the style property.

\time 3/4 s2
\property Staff.TimeSignature \override #'style = #'C
\time 4/4 s2
\property Staff.TimeSignature \override #'style = #'()
\time 4/4 s2
\property Staff.TimeSignature \override #'style = #'C
\time 2/2 s2

There are many more options for the layout of this grob. They are selected through the style grob property.

See input/test/time.ly for examples.

Partial

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

  \partial duration

Internally, this is a shortcut for

  \property Score.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. The property Score.timing can be used to switch off this automatic timing

c'2.
\property Score.timing = ##f
c2
\property Score.timing = ##t
c4 c4 c4

The identifiers \cadenzaOn and \cadenzaOff can be used as shortcuts.

Bar lines

  \bar bartype

This is a shortcut for doing

  \property Score.whichBar = bartype

The following bar types are available

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

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

Whenever whichBar is set to a string, a bar line of that type is created. whichBar is usually set automatically: at the start of a measure it is set to defaultBarType. The contents of repeatCommands is used to override default measure bars.

whichBar can also be set directly, using \property or \bar . These settings take precedence over the automatic whichBar settings. BarLine grobs are created by the Bar_engraver .

Polyphony

Polyphonic parts, i.e. parts with more than one voice on a staff can be typeset with LilyPond.

The easiest way to enter such fragments, is the Scheme function voicify-music. It will split chords using the separator \\, to make multiple voices. You can use it for small, short-lived voices (make a chord of voices) or for single chords:

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

The function voicify-music instantiates Voice

contexts, bearing the names "1", "2", etc.

To explicity typeset polyphonic music, instantiate a separate Voice context for each part, and assign a stem direction to each part.

\context Staff
< \context Voice = VA { \stemUp b'4 a' g' f' e' }
  \context Voice = VB { \stemDown g'4 g' g' g' g' } >

When there are more than two voices on a staff, you must also indicate which voice should moved horizontally in case of a collision. This can be done with the identifiers \shiftOff, \shiftOn, \shiftOnn, etc. (which sets the grob property horizontal-shift in NoteColumn ).

  \context Staff \notes\relative c''<
       \context Voice=one {
       \shiftOff \stemUp e4
       }
       \context Voice=two {
          \shiftOn \stemUp cis
       }
       \context Voice=three {
         \shiftOnn \stemUp ais
       }
       \context Voice=four {
          \shiftOnnn \stemUp fis
       }
  >

The most convenient way is to use the identifiers \voiceOne through \voiceFour, which also set slur and tie directions in the correct manner.

\relative c''
\context Staff < \context Voice = VA { \voiceOne cis2 b  }
  \context Voice = VB { \voiceThree b4 ais ~ ais4 gis4 }
  \context Voice = VC { \voiceTwo fis4~  fis4 f ~ f  } >

Normally, note heads with a different number of dots are not merged, but if you set the grob property merge-differently-dotted, they are:

  \context Staff <
  \context Voice = VA { \voiceOne
     g'8 g'8
     \property Staff.NoteCollision \override #'merge-differently-dotted = ##t
     g'8 g'8
  }
  \context Voice = VB { \voiceTwo [g'8. f16] [g'8. f'16] }
  >

LilyPond also vertically shifts rests that are opposite of a stem.

\context Staff <
\context Voice {  \stemUp c''4  }
\context Voice =VB { r4 }
>

Note head collisions (horizontal shifting of note heads) are handled by the NoteCollision grob. RestCollision

handles vertical shifting of rests.

BUGS

Resolving collisions is a very intricate subject, and LilyPond only handles a few situations. When it can not cope, you are advised to use force-hshift of the NoteColumn grob and staff-position of the Rest grob to override typesetting decisions.

Beaming

Beams are used to group short notes into chunks that are aligned with the metrum. LilyPond guesses where beams should be inserted. If you're not satisfied with the automatic beaming, you can specify which patterns to beam automatically. In specific cases, you can also enter the beams explicitly.

Automatic beams

In normal time signatures, automatic beams can start on any note but can only end in a few positions within the measure: beams can end on a beat, or at durations specified by the properties in Voice.autoBeamSettings. The defaults for autoBeamSettings are defined in scm/auto-beam.scm.

The value of autoBeamSettings is changed using \override and unset using \revert:

\property Voice.autoBeamSettings \override #'(BE P Q N M) = dur
\property Voice.autoBeamSettings \revert #'(BE P Q N M)

Here, BE is the symbol begin or end. It determines whether the rule applies to begin or end-points. The quantity P/Q refers to the length of the beamed notes (and `

*
*

' designates notes of any length), N/M refers to a time signature (wildcards, `* *' may be entered to designate all time signatures).

For example, if you want automatic beams to end on every quarter note, you can use the following:

\property Voice.autoBeamSettings \override
    #'(end * * * *) = #(make-moment 1 4)

Since the duration of a quarter note is 1/4 of a whole note, it is entered as (make-moment 1 4).

The same syntax can be used to specify beam starting points. In this example, automatic beams can only end on a dotted quarter note.

\property Voice.autoBeamSettings \override
    #'(end * * * *) = #(make-moment 3 8)

In 4/4 time signature, this means that automatic beams could end only on 3/8 and on the fourth beat of the measure (after 3/4, that is 2 times 3/8 has passed within the measure).

You can also restrict rules to specific time signatures. A rule that should only be applied in N/M time signature is formed by replacing the second asterisks by N and M. For example, a rule for 6/8 time exclusively looks like

\property Voice.autoBeamSettings \override
    #'(begin * * 6 8) =  ...

If you want a rule to apply to certain types of beams, you can use the first pair of asterisks. Beams are classified according to the shortest note they contain. For a beam ending rule that only applies to beams with 32nd notes (and no shorter notes), you would use (end 1 32 * *).

If a score ends while an automatic beam has not been ended and is still accepting notes, this last beam will not be typeset at all.

Automatic beaming is on by default, but can be switched off by setting Voice.noAutoBeaming to true. You you may find this necessary for a melody that goes with lyrics.

BUGS

It is not possible to specify beaming parameters for beams with mixed durations, that differ from the beaming parameters of all separate durations, i.e., you'll have to specify manual beams to get:

It is not possible to specify beaming parameters that act differently in different parts of a measure. This means that it is not possible to use automatic beaming in irregular meters such as 5/8.

Manual beams

In some cases it may be necessary to override LilyPond's automatic beaming algorithm. For example, the auto beamer will not beam over rests or bar lines, If you want that, specify the begin and end point manually using a [ before the first beamed note and a ] after the last note:

  \context Staff {
    r4 [r8 g' a r8] r8 [g | a] r8
  }

Whenever an manual beam is busy, the automatic beamer will not produce anything.

Normally, beaming patterns within a beam are determined automatically. When this mechanism fouls up, the properties Voice.stemLeftBeamCount and Voice.stemRightBeamCount. can be used to control the beam subdivision on a stem. If you set either property, it's value will be used only once, and then it is erased.

  \context Staff {
    [f8 r16 f g a]
    [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a]
  }

The beam symbol (grob Beam , both for automatic and manual beams) can be tweaked through grob-properties height and staff-position. These specify vertical location and vertical span. Both are measured in half staff-spaces, staff-position=0 corresponds to the middle staff line.

Set height to zero, to get horizontal beams:

  \property Voice.Beam \set #'direction = #1
  \property Voice.Beam \set #'height = #0
  [a'8 e' d c]

Here's how you'd specify a weird looking beam that instead of being horizontal, falls two staff spaces:

  \property Voice.Beam \set #'staff-position = #4
  \property Voice.Beam \set #'height = #-4
  [c8 c]

Expressive marks

Slurs

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

  f'()g'()a' [a'8 b'(] a'4 g'2 )f'4

Slurs avoid crossing stems, and are generally attached to note heads. However, in some situations with beams, slurs may be attached to stem ends. If you want to override this layout you can do this through the Slur 's grob-property attachment. It's value is a pair of symbols, specifying the attachment type of the left and right end points.

  \property Voice.Slur \set #'direction = #1
  \property Voice.Stem \set #'length = #5.5
  g'8(g)g4
  \property Voice.Slur \set #'attachment = #'(stem . stem)
  g8(g)g4

If a slur would strike through a stem or beam, the slur will be moved away upward or downward. If this happens, attaching the slur to the stems might look better:

  \property Voice.Stem \set #'direction = #1
  \property Voice.Slur \set #'direction = #1
  d32( d'4 )d8..
  \property Voice.Slur \set #'attachment = #'(stem . stem)
  d,32( d'4 )d8..

Similarly, the curvature of a slur is adjusted to stay clear of note heads and stems. When that would increase the curvature too much, the slur is reverted to its default shape. The threshold for this decision is in Slur 's grob-property beautiful. It is loosely related to the enclosed area between the slur and the notes. Usually, the default setting works well, but in some cases you may prefer a curved slur when LilyPond decides for a vertically moved one. You can indicate this preference by increasing the beautiful value:

  \property Voice.Beam \override #'direction = #-1
  \property Voice.Slur \override #'direction = #1
  c16( a' f' a a f a, )c,
  c( a' f' a a f d, )c
  \property Voice.Slur \override #'beautiful = #5.0
  c( a' f' a a f d, )c

BUGS

beautiful is an arbitrary parameter in the slur formatter. Useful values can only be determined by trial and error.

Phrasing slurs

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

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

Typographically, the phrasing slur behaves almost exactly like a normal slur. The grob associated with it is PhrasingSlur .

Breath marks

Breath marks are entered using \breathe. The result is a BreathingSign grob.

Note that the skip does not produce any output, not even transparent output.

BUGS

The current layout of the default comma style breath marks could be improved and more optional symbols should be added to the font.

Tempo

Metronome settings can be entered as follows:

  \tempo duration = perminute

For example, \tempo 4 = 76 requests output with 76 quarter notes per minute.

BUGS

The tempo setting is not printed, but is only used in the MIDI output. You can trick lily into producing a metronome mark, though. Details are in Text markup.

Text spanners

Some textual indications, e.g. rallentando or accelerando, often extend over many measures. This is indicated by following the text with a dotted line. You can create such texts using text spanners. The syntax is as follows:

\spanrequest \start "text"
\spanrequest \stop "text"

LilyPond will respond by creating a TextSpanner grob (typically in Voice context). The string to be printed, as well as the style is set through grob properties.

An application--or rather, a hack--is to fake octavation indications.

 \relative c' {  a''' b c a
  \property Voice.TextSpanner \set #'type = #'dotted-line
  \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5)
  \property Voice.TextSpanner \set #'edge-text = #'("8va " . "")
  \property Staff.centralCPosition = #-13
  a\spanrequest \start "text" b c a \spanrequest \stop "text" }

Ornaments

Articulations

A variety of symbols can appear above and below notes to indicate different characteristics of the performance. These symbols can be added to a note with `note-\name'. Numerous symbols are defined in script.ly. Symbols can be forced to appear above or below the note by writing `note^\name' and `note_\name' respectively. Here is a chart showing symbols on notes, with the name of the corresponding symbol appearing underneath.

To save typing work, some shorthands are available:

Fingering instructions can also be entered in this shorthand.

      c'4-1 c'4-2 c'4-3 c'4-4

You can add scripts by editing scm/script.scm. This file contains a table, listing script definitions and aliases. The following syntax accesses a script definition from the table:

  \script alias

Usually the \script keyword is not used directly. Various helpful identifier definitions appear in script.ly.

Grobs for these objects are Script and Fingering .

BUGS

All of these note ornaments appear in the printed output but have no effect on the MIDI rendering of the music.

Unfortunately, there is no support for adding fingering instructions or ornaments to individual note heads. Some hacks exist, though. See input/test/script-horizontal.ly.

Text scripts

In addition, it is possible to place arbitrary strings of text or markup text (see Text markup) above or below notes by using a string: c^"text".

By default, these indications do not influence the note spacing, but if Voice.textNonEmpty is set to true the widths will be taken into account. The identifier \fatText is defined in the standard includes.

\relative c' { c4^"longtext" \fatText c4_"longlongtext" c4 }

Text scripts are created in form of TextScript grobs, in Voice context. Text markup describes how to change the font or access special symbols in text scripts.

Grace notes

Grace notes are ornaments that are written out, but do not take up any logical time in a measure. LilyPond has limited support for grace notes. The syntax is as follows.

  \grace musicexpr

When grace music is interpreted, a score-within-a-score is set up: musicexpr has its own time bookkeeping, and you could (for example) have a separate time signature within the grace notes. While in this score-within-a-score, you can create notes, beams, slurs, etc. Unbeamed eighth notes and shorter by default have a slash through the stem.

\relative c'' {
  \grace c8 c4 \grace { [c16 c16] } c4
  \grace { \property Grace.Stem \override #'flag-style = #'() c16 } c4
}

A grace note expression has duration 0; the next real note is assumed to be the main note. If you want the note to appear after the main note, set Voice.graceAlignPosition to 1.

BUGS

At present, slurs or ties from the grace notes to the following notes are not supported. Also, nesting \grace notes is not supported. The following may cause run-time errors:

  \grace { \grace c32 c16 } c4

Since the meaning of such a construct is unclear, we don't consider this a loss. Similarly, juxtaposing two \grace sections is syntactically valid, but makes no sense and may cause runtime errors. Ending a staff or score with grace notes may also generate a run-time error, since there will be no main note to attach the grace notes to.

The present implementation of grace notes is not robust and generally kludgey. We expect it to change after LilyPond 1.4. Syntax changes might also be implemented.

Glissando

A glissando line (grob Glissando ) can be requested by attaching a \glissando to a notte:

  c'-\glissando c'

BUGS

Printing of an additional text (such as gliss.) must be done manually.

Dynamics

Absolute dynamic marks are specified using an identifier after a note: c4-\ff. The available dynamic marks are: \ppp, \pp, \p, \mp, \mf, \f, \ff, \fff, \fff, \fp, \sf, \sff, \sp, \spp, \sfz, and \rfz.

  c'\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff
  c2\sf c\rfz

A crescendo mark is started with \cr and terminated with \rc (the textual reverse of cr). A decrescendo mark is started with \decr and terminated with \rced. There are also shorthands for these marks. A crescendo can be started with \< and a decrescendo can be started with \>. Either one can be terminated with \!. Note that \! must go before the last note of the dynamic mark whereas \rc and \rced go after the last note. Because these marks are bound to notes, if you want several marks during one note, you have to use spacer notes.

  c'' \< \! c''   d'' \decr e'' \rced
  < f''1 { s4 s4 \< \! s4 \> \! s4 } >

You can also use a text saying cresc. instead of hairpins. Here is an example how to do it:

  \context Voice {
    \property Voice.crescendoText = "cresc."
    \property Voice.crescendoSpanner = #'dashed-line
    a'2\mf\< a a \!a
  }

For everyday use, we recommend the identifiers \cresc, endcresc, \dim and \enddim.

Dynamics are grobs of DynamicText and Hairpin . They are put together on DynamicLineSpanner to align them vertically.

Repeats

To specify repeats, use the \repeat keyword. Since repeats should work differently when played or printed, there are a few different variants of repeats.

unfold: Repeated music is fully written (played) out. Useful for MIDI output, and entering repetitive music.
volta: This is the normal notation: Repeats are not written out, but alternative endings (voltas) are printed, left to right.
fold: Alternative endings are written stacked. This has limited use but may be used to typeset two lines of lyrics in songs with repeats, see input/star-spangled-banner.ly.
tremolo: Make tremolo beams.
percent: Make beat or measure repeats. These look like percent signs.

Repeat syntax

The syntax for repeats is

  \repeat variant repeatcount repeatbody

If you have alternative endings, you may add

 \alternative { alternative1
            alternative2
            alternative3 ... }

where each alternative is a music expression.

Normal notation repeats are used like this:

  c'1
  \repeat volta 2 { c'4 d' e' f' }
  \repeat volta 2 { f' e' d' c' }

With alternative endings:

  c'1
  \repeat volta 2 {c'4 d' e' f'}
  \alternative { {d'2 d'} {f' f} }

Folded repeats look like this:

  c'1
  \repeat fold 2 {c'4 d' e' f'}
  \alternative { {d'2 d'} {f' f} }

If you don't give enough alternatives for all of the repeats, then the first alternative is assumed to be repeated often enough to equal the specified number of repeats.

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

BUGS

Notice that timing information is not remembered at the start of an alternative, so you have to reset timing information after a repeat, e.g. using a bar-check (See Bar check), setting Score.measurePosition or entering \partial. Slurs or ties are also not repeated.

It is possible to nest \repeats, although this probably is only meaningful for unfolded repeats.

Folded repeats offer little more over simultaneous music. However, it is to be expected that more functionality - especially for the MIDI backend - will be implemented at some point in the future.

Volta repeats are printed over all staffs in a score. You must turn them off explicitly, for example by doing

  \property Staff.VoltaBracket = \turnOff

in all but the top staff.

Manual repeat commands

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

'start-repeat: Print a |: bar line
'stop-repeat: Print a :| bar line
(volta . text): Print a volta bracket saying text.
(volta . #f): Stop a running volta bracket

 c''4
    \property Score.repeatCommands = #'((volta "93") end-repeat)
 c''4 c''4
    \property Score.repeatCommands = #'((volta #f))
 c''4 c''4

Repeats brackets are VoltaBracket grobs.

Tremolo repeats

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

\score {
  \context Voice \notes\relative c' {
    \repeat "tremolo" 8 { c16 d16 }
    \repeat "tremolo" 4 { c16 d16 }
    \repeat "tremolo" 2 { c16 d16 }
    \repeat "tremolo" 4 c16
  }
}

Tremolo beams are Beam grobs. Single stem tremolos are StemTremolo .

BUGS

At present, the spacing between tremolo beams is not regular, since the spacing engine does not notice that not all notes are printed.

Tremolo subdivisions

Tremolo marks can be printed on a single note by adding `:[length]' after the note. The length must be at least 8. A length value of 8 gives one line across the note stem. If the length is omitted, then then the last value (stored in Voice.tremoloFlags) is used.

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

BUGS

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

Measure repeats

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

 \context Voice { \repeat  "percent" 4  { c'4 }
    \repeat "percent" 2 { c'2 es'2 f'4 fis'4 g'4 c''4 }
}

The signs are represented by these grobs: RepeatSlash and PercentRepeat and DoublePercentRepeat .

BUGS

You can not nest percent repeats, e.g. by filling in the first measure with slashes, and repeating that measure with percents.

Rhythmic music

Rhythmic staffs

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

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

Piano music

Piano music is an odd type of notation. Piano staffs are two normal staffs coupled with a brace. The staffs are largely independent, but sometimes voices can cross between the two staffs. The PianoStaff is especially built to handle this cross-staffing behavior. In this section we discuss the PianoStaff and some other pianistic peculiarities.

Automatic staff changes

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

        \autochange contexttype musicexp

This will switch the interpretation context of musicexp between a contexttype named up and down. Typically, you use Staff for contexttype. The autochanger switches on basis of pitch (central C is the turning point), and it looks ahead skipping over rests to switch rests in advance.

\score { \notes \context PianoStaff <
  \context Staff = "up" {
    \autochange Staff \context Voice = VA < \relative c' {
       g4 a  b c d r4 a g } > }
  \context Staff = "down" {
       \clef bass
       s1*2
} > }

Note how spacer rests are used to prevent the bottom staff from terminating too soon.

Manual staff switches

Voices can be switched between staffs manually, using the following command:

  \translator Staff = staffname music

The string staffname is the name of the staff. It switches the current voice from its current staff to the Staff called staffname. Typically staffname is "up" or "down".

The formal definition of this construct is obtuse, but for the sake of completeness we give it here.

  \translator contexttype = name

Formally, this construct is a music expression indicating that the context which is a direct child of the context of type contexttype should be shifted to a context of type contexttype and the specified name.

Pedals

Piano pedal instruction can be expressed using \sustainDown, \sustainUp, \unaCorda, \treCorde, \sostenutoDown and \sostenutoUp.

These identifiers are shorthands for spanner commands of the types Sustain , UnaCorda and Sostenuto :

c''4 \spanrequest \start "Sustain" c''4
c''4 \spanrequest \stop "Sustain"

The symbols that are printed can be modified by setting pedalXStrings, where X is one of the pedal types. Refer to the generated documentation of PianoPedal for more information.

BUGS

Currently, brackets are not supported, only text markings (i.e. `*Ped' style).

Arpeggio

You can specify an arpeggio sign on a chord by attaching an \arpeggio to a note of the chord.

  \context Voice <c\arpeggio e g c>

When an arpeggio crosses staffs in piano music, you attach an arpeggio to the chords in both staffs, and set PianoStaff.connectArpeggios.

  \context PianoStaff <
    \property PianoStaff.connectArpeggios = ##t
    \context Voice = one  { <c'\arpeggio e g c> }
    \context Voice = other { \clef bass  <c,,\arpeggio e g>}
  >

This command creates Arpeggio grobs. Cross staff arpeggios are PianoStaff.Arpeggio. Arpeggio

BUGS

It is not possible to mix connected arpeggios and unconnected arpeggios at the same time.

Voice follower lines

Whenever a voice switches to another staff a line connecting the notes can be printed automatically. This is enabled if the property PianoStaff.followVoice is set to true:

  \context PianoStaff <
    \property PianoStaff.followVoice = ##t
    \context Staff \context Voice {
      c1
      \translator Staff=two
      b2 a
    }
    \context Staff=two {\clef bass \skip 1*2 }
  >

The associated grob is VoiceFollower .

Lyrics

Lyrics mode

To print lyrics, you must first make a music expression from the lyric text. That music expression can be printed by selecting an appropriate context.

You can enter lyrics in a special input mode of LilyPond. This mode is called Lyrics mode, and it is introduced by the keyword \lyrics. The purpose of this mode is that you can enter lyrics as plain text, punctuation and accents without any hassle.

Syllables are entered like notes, with pitches replaced by text. For example, Twin- kle twin- kle enters four syllables. Note that the hyphen has no special meaning for lyrics, and does not introduce special symbols.

Spaces can be introduced into a lyric either by using quotes: "He could"4 not4 or by using an underscore without quotes: He_could4 not4. All unquoted underscores are converted to spaces.

The precise definition of this mode can be found in Lyrics mode definition.

Printing lyrics

Lyrics are printed by interpreting them in the Lyrics context.

\addlyrics \notes \relative c' {
        \time 7/4
        \property Staff.automaticMelismata = ##t
        d'2 c4 b16 ( a g a b a b ) c a2
        b2 c4 b8 ( a16 g ) a4 g2 }
    \context Lyrics \lyrics {
       Join us now __ and
       share the soft -- ware; }

Notes and syllable durations are matched automatically. This is accomplished using \addlyrics, which is documented in Automatic syllable durations. Setting automaticMelismata in the melody staff will cause slurs to be interpreted as melismata.

The Lyric syllables are LyricsVoice.LyricSyllable grobs.

As you can see, extender lines are entered as __. This will create an extender, a line that extends over the entire duration of the lyric. This line will run all the way to the start of the next lyric, so you may want to shorten it by using a blank lyric (using _). The grob for this symbol is LyricsVoice.LyricExtender.

If you want to have hyphens centered between syllables (rather than attached to the end of the first syllable) you can use the special `--' lyric as a separate word between syllables. This will result in a hyphen whose length varies depending on the space between syllables. It will be centered between the syllables. The grob for this symbol is LyricsVoice.LyricHyphen.

Automatic syllable durations

If you have lyrics that are set to a melody, you can copy the rhythm of that melody into the lyrics using \addlyrics. The syntax for this is

  \addlyrics musicexpr1 musicexpr2

Both musicexpr1 and musicexpr2 are interpreted, but every music event ("every syllable") in musicexpr2 is interpreted only when there are events in musicexpr1.

If the property automaticMelismata is set in the context of musicexpr1, no lyrics will be put on slurred or tied notes.

\addlyrics
\transpose c'' {
  \property Voice.automaticMelismata = ##t
  c8 () cis d8. e16 f2
}
\context Lyrics \lyrics {
 do4 re mi fa }

If you want the lyric lines to be above the melody staff, or in some other, more complex configuration, then build that configuration first using simultaneous music, and use \addlyrics after that.

\notes <
  \context Lyrics = LA { s1 }
  \context Staff = SA { s1 }
  \addlyrics
        \context Staff = SA \relative c' { c4 e g g }
        \context Lyrics  = LA \lyrics { geen ge -- don -- der } >

For \addlyrics you should use a single rhythm melody, and single rhythm lyrics (a constant duration is the obvious choice). If you do not, you can get undesired effects when using multiple stanzas:

\addlyrics
\transpose c'' {
  c8 () cis d8. e16 f2
}
\context Lyrics \lyrics
< { do4 re fa sol }
  { do8 re fa sol } >

It is valid (but probably not very useful) to use notes instead of lyrics for musicexpr2.

More stanzas

If you have multiple stanzas printed underneath each other, the vertical groups of syllables should be aligned around punctuation. LilyPond can do this if you tell it which lyric lines belong to which melody.

To this end, give the Voice context an identity, and set the LyricsVoice to a name starting with that identity followed by a dash. In the following example, the Voice identity is duet, and the identities of the LyricsVoices are duet-1 and duet-2.

\score {
\addlyrics
  \notes \relative c'' \context Voice = duet { \time 3/4
     g2 e4 a2 f4 g2.  }
  \lyrics \context Lyrics <
  \context LyricsVoice = "duet-1" {
    \property LyricsVoice . stanza = "Bert"
    Hi, my name is bert.    }
  \context LyricsVoice = "duet-2" {
    \property LyricsVoice . stanza = "Ernie"
    Ooooo, ch\'e -- ri, je t'aime. }
  >
}

You can add stanza numbers by setting LyricsVoice.Stanza (for the first system) and LyricsVoice.stz for the following systems. Notice how you must surround dots with spaces in \lyrics mode.

Chords

LilyPond has support for both entering and printing chords. Chords are characterized by a set of pitches. They are internally stored as simultaneous music expressions. This means you can enter chords by name and print them as note head, enter them as notes and print them as chord names, or (the most common case) enter them by name, and print them as name.

twoWays = \notes \transpose c'' {
  \chords {
    c1 f:sus4 bes/f
  }
  <c e g>
  <f bes c'>
  <f bes d'>
  }

\score {
   < \context ChordNames \twoWays
     \context Voice \twoWays > }

Note that this example also shows that the chord printing routines do not attempt to be intelligent. If you enter f bes d, it does not interpret this as an inversion.

Chords mode

Chord mode is a mode where you can input sets of pitches using common names. It is introduced by the keyword \chords. It is similar to note mode, but words are also looked up in a chord modifier table (containing maj, dim, etc).

Dashes and carets are used to indicate chord additions and subtractions, so articulation scripts can not be entered in Chord mode.

The syntax for named chords is as follows:

  tonic[duration][-modifiers][^subtractions][/inversion][/+bass].

tonic should be the tonic note of the chord, and duration is the chord duration in the usual notation. There are two kinds of modifiers. One type is formed by chord additions. Additions are obtained by listing intervals separated by dots. An interval is written by its number with an optional + or - to indicate raising or lowering by half a step. Chord additions have two effects: they adds the specified interval and all lower odd numbered intervals to the chord, and they may lower or raise the specified interval.

Throughout these examples, chords have been shifted around the staff using \transpose.

\transpose c'' {
  \chords {
    c1  c:3-       c:7     c:8
    c:9 c:9-.5+.7+ c:3-.5-
  }
}

The second type of modifier that may appear after the : is a named modifier. Named modifiers are listed in the file chord-modifiers.ly. The available modifiers are m and min which lower the 3rd half a step, `aug' which raises the 5th, `dim' which lowers the 5th, `maj' which adds a raised 7th, and `sus' which replaces the 5th with a 4th.

\transpose c'' {
  \chords {
    c1:m c:min7 c:maj c:aug c:dim c:sus
  }
}

Chord subtractions are used to eliminate notes from a chord. The notes to be subtracted are listed after a ^ character, separated by dots.

  \transpose c'' {
    \chords {
      c1^3 c:7^5.3 c:8^7
    }
  }

Chord inversions can be specified by appending `/' and the name of a single note to a chord. In a chord inversion, the inverted note is transposed down until it is the lowest note in the chord. If the note is not in the chord, a warning will be printed.

  \transpose c''' {
    \chords {
      c1 c/e c/g c:7/e
    }
  }

Bass notes can be added by `/+' and the name of a single note to a chord. This has the effect of adding the specified note to the chord, lowered by an octave, so it becomes the lowest note in the chord.

  \transpose c''' {
    \chords {
      c1 c/+c c/+g c:7/+b
    }
  }

BUGS

Implementation details are quite gory. For example c:4 not only adds a fourth, but also removes the third.

Printing named chords

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

scheme = \notes {
  \chords {a1 b c} <d f g>  <e g b>
}
\score {
  \notes<
    \context ChordNames \scheme
    \context Staff \transpose c'' \scheme
  >
}

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

scheme = \chords {
  c1:m c:m \break c:m c:m d
}
\score {
  \notes <
    \context ChordNames {
        \property ChordNames.chordChanges = ##t
        \scheme }
    \context Staff \transpose c'' \scheme
  > }

LilyPond examines chords specified as lists of notes to determine a name to give the chord. LilyPond will not try to identify chord inversions or an added bass note, which may result in strange chord names when chords are entered as a list of pitches:

scheme = \notes {
  <c'1 e' g'>
  <e' g' c''>
  <e e' g' c''>
}

\score {
  <
    \context ChordNames \scheme
    \context Staff \scheme
  >
}

By default, a chord name system proposed by Harald Banter (See Literature) is used. The system is very regular and predictable. Typical American style chord names may be selected by setting the style property of the ChordNames.ChordName grob to 'american. Similarly 'jazz selects Jazz chordnames.

Routines that determine the names to be printed are written in Scheme, and may be customized by the user. The code can be found in scm/chord-name.scm. Here's an example showing the differences in chord name styles:

scheme = \chords {
  c1 c:5^3 c:4^3 c:5+
  c:m7+ c:m5-.7
  c:5-.7 c:5+.7
  c:9^7
}

\score {
  \notes <
    \context ChordNames = banter \scheme
    \context ChordNames = american {
      \property ChordNames.ChordName \override
        #'style = #'american \scheme }
    \context ChordNames = jazz {
      \property ChordNames.ChordName \override
        #'style = #'jazz \scheme }
    \context Staff \transpose c'' \scheme
  >
}

Writing parts

Orchestral music involves some special notation, both in the full score, as in the individual parts. This section explains how to tackle common problems in orchestral music.

Rehearsal marks

  \mark unsigned
  \mark string
  \mark \default

This command prints a rehearsal mark above the system. You can provide a number, a string or a markup text as argument. If you use \default, the value of property rehearsalMark is used and automatically incremented.

\relative c'' {
  c1 \mark "A2"
  c1 \mark \default
  c1 \mark \default
  c1 \mark "12"
  c1 \mark #'(music "scripts-segno")
  c1
}

The grob is RehearsalMark in Score context. See input/test/boxed-molecule.ly if you need boxes around the marks.

Bar numbers

Bar numbers are BarNumber grobs. They are printed at the start of the line. The number itself is a property that can be set by modifying the currentBarNumber property, i.e.

  \property Score.currentBarNumber = #217

If you want boxed bar numbers, see the example file input/test/boxed-molecule.ly.

BUGS

It is not possible to have bar numbers printed at regular intervals

Instrument names

You can specify an instrument name for a staff by setting Staff.instrument and Staff.instr. This will print a string before the start of the staff. For the first start, instrument is used, for the next ones instr is used.

  \property Staff.instrument = "ploink " { c''4 }

You can also use markup texts to construct more complicated instrument names:

#(define text-flat
  '((font-relative-size . -2 ) (music "accidentals--1")))

\score { \notes {
  \property Staff.instrument = #`((kern . 0.5) (lines
    "2 Clarinetti" (columns "     (B" ,text-flat ")")))
    c'' 4 }
}

BUGS

When you put a name on a grand staff or piano staff the width of the brace is not taken into account. You must add extra spaces to the end of the name to avoid a collision.

Transpose

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

  \transpose pitch musicexpr

This means that middle C in musicexpr is transposed to pitch.

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

\context Staff {
  \clef "F"
  { \key e \major c d e f }
  \clef "G"
  \transpose des'' { \key e \major c d e f }
  \transpose cis'' { \key e \major c d e f }
}

If you want to use both \transpose and \relative, then you must use \transpose first. \relative will have no effect music that appears inside a \transpose.

Sound output transposing instruments

When you want to make a MIDI file from a score containing transposed and untransposed instruments, you have to instruct LilyPond the pitch offset (in semitones) for the transposed instruments. This is done using the transposing property. It does not affect printed output.

        \property Staff.instrument = #"Cl. in B-flat"
        \property Staff.transposing = #-2

Multi measure rests

Multi measure rests are entered using `R'. It is specifically meant for full bar rests and for entering parts: the rest can expand to fill a score with rests, or it can be printed as a single multimeasure rest This expansion is controlled by the property Score.skipBars. If this is set to true, Lily will not expand empty measures, and the appropriate number is added automatically.

 \time 3/4 r2. | R2. | R2.*2 \property Score.skipBars = ##t R2.*17  R2.*4

Notice that the R2. is printed as a whole rest, centered in the measure.

The grob for this object is MultiMeasureRest .

BUGS

Currently, there is no way to automatically condense multiple rests into a single multimeasure rest.

Automatic part combining

Automatic part combining is used to merge two parts of music onto a staff in an intelligent way. It is aimed primarily at typesetting orchestral scores. When the two parts are identical for a period of time, only one is shown. In places where the two parts differ, they are typeset as separate voices, and stem directions are set automatically. Also, solo and a due parts can be identified and marked.

The syntax for part combining is

  \partcombine context musicexpr1 musicexpr2

where the pieces of music musicexpr1 and musicexpr2 will be combined into one context of type context. The music expressions must be interpreted by contexts whose names should start with one and two.

The most useful function of the part combiner is to combine parts into one voice, as common for wind parts in orchestral scores:

  \context Staff <
    \context Voice=one \partcombine Voice
      \context Thread=one \relative c'' {
        g a () b r
      }
      \context Thread=two \relative c'' {
        g r4 r f
      }
  >

Notice that the first g appears only once, although it was specified twice (once in each part). Stem, slur and tie directions are set automatically, depending whether there is a solo or unisono. The first part (with context called one) always gets up stems, and `solo', while the second (called two) always gets down stems and `Solo II'.

If you just want the merging parts, and not the textual markings, you may set the property soloADue to false.

  \context Staff <
    \property Staff.soloADue = ##f
    \context Voice=one \partcombine Voice
      \context Thread=one \relative c'' {
        b4 a c g
      }
      \context Thread=two \relative c'' {
        d,2 a4 g'
      }
  >

There are a number of other properties that you can use to tweak the behavior of part combining, refer to the automatically generated documentation of Thread_devnull_engraver and Voice_devnull_engraver . Look at the documentation of the responsible engravers, Thread_devnull_engraver , Voice_devnull_engraver and A2_engraver .

BUGS

In soloADue mode, when the two voices play the same notes on and off, the part combiner may typeset a2 more than once in a measure.

Hara kiri staffs

In orchestral scores, staff lines that only have rests are usually removed. This saves some space. LilyPond also supports this through the hara kiri⁴ staff. This staff commits suicide when it finds itself to be empty after the line-breaking process. It will not disappear when it contains normal rests, you must use multi measure rests.

The hara kiri staff is specialized version of the Staff

context. It is available as the context identifier \HaraKiriStaffContext. Observe how the second staff in this example disappears in the second line.

\score  {
  \notes \relative c' <
    \context Staff = SA { e4 f g a \break c1 }
    \context Staff = SB { c4 d e f \break R1 }
  >
  \paper {
    linewidth = 6.\cm
    \translator { \HaraKiriStaffContext }
  }
}

Custodes

A custos (plural: custodes; latin word for `guard') is a staff context symbol that appears at the end of a staff line. It anticipates the pitch of the first note(s) of the following line and thus helps the player or singer to manage line breaks during performance, thus enhancing readability of a score.

\score {
  \notes { c'1 \break
        \property Staff.Custos \set #'style = #'mensural
        d' }
  \paper {
    \translator {
      \StaffContext
      \consists Custos_engraver
    }
  }
}

Custodes were frequently used in music notation until the 17th century. There were different appearances for different notation styles. Nowadays, they have survived only in special forms of musical notation such as via the editio vaticana dating back to the beginning of the 20th century.

For typesetting custodes, just put a Custos_engraver into the Staff context when declaring the \paper block. In this block, you can also globally control the appearance of the custos symbol by setting the custos style property. Currently supported styles are vaticana, medicaea, hufnagel and mensural.

\paper {
  \translator {
      \StaffContext
      \consists Custos_engraver
      Custos \override #'style = #'mensural
  }
}

The property can also be set locally, for example in a \notes block:

\notes {
  \property Staff.Custos \override #'style = #'vaticana
  c'1 d' e' d' \break c' d' e' d'
}

Tuning output

LilyPond tries to take as much formatting as possible out of your hands. Nevertheless, there are situations where it needs some help, or where you want to override its decisions. In this section we discuss ways to do just that.

Formatting is internally done by manipulating so called grobs (graphic objects). Each grob carries with it a set of properties (grob properties) specific to that object. For example, a stem grob has properties that specify its direction, length and thickness.

The most direct way of tuning the output is by altering the values of these properties. There are two ways of doing that: first, you can temporarily change the definition of a certain type of grob, thus affecting a whole set of objects. Second, you can select one specific object, and set a grob property in that object.

Tuning groups of grobs

A grob definition is a Scheme association list, that is stored in a context property. By assigning to that property (using plain \property), you can change the resulting grobs.

c'4 \property Voice.Stem  = #'((meta . ((interfaces . ())))) c'4

The \property assignment effectively empties the definition of the Stem object. One of the effects is that the recipe of how it should be printed is erased, with the effect of rendering it invisible. The above assignment is available as a standard identifier, for the case that you find this useful:

  \property Voice.Stem = \turnOff

This mechanism is fairly crude, since you can only set, but not modify, the definition of a grob. For this reason, there is a more advanced mechanism.

The definition of a grob is actually a list of default grob properties. For example, the definition of the Stem grob (available in scm/grob-description.scm), defines the following values for Stem

        (thickness . 0.8)
        (beamed-lengths . (0.0 2.5 2.0 1.5))
        (Y-extent-callback . ,Stem::height)
        ...

You can add a property on top of the existing definition, or remove a property, thus overriding the system defaults:

c'4 \property Voice.Stem \override #'thickness = #4.0
c'4 \property Voice.Stem \revert #'thickness
c'4

You should balance \override and \revert. If that's too much work, you can use the \set shorthand. It performs a revert followed by an override. The following example gives exactly the same result as the previous one.

c'4 \property Voice.Stem \set #'thickness = #4.0
c'4 \property Voice.Stem \set #'thickness = #0.8
c'4

If you use \set, you must explicitly restore the default.

Formally the syntax for these constructions is

\property context.grobname \override symbol = value
\property context.grobname \set symbol = value
\property context.grobname \revert symbol

Here symbol is a Scheme expression of symbol type, context and grobname are strings and value is a Scheme expression.

If you revert a setting which was not set in the first place, then it has no effect. However, if the setting was set as a system default, it may remove the default value, and this may give surprising results, including crashes. In other words, \override and \revert, must be carefully balanced.

These are examples of correct nesting of \override, \set, \revert.

A clumsy but correct form:

  \override \revert \override \revert \override \revert

Shorter version of the same:

  \override \set \set  \revert

A short form, using only \set. This requires you to know the default value:

  \set \set \set \set to default value

If there is no default (i.e. by default, the grob property is unset), then you can use

  \set \set \set \revert

For the digirati, the grob description is an Scheme association list. Since a Scheme list is a singly linked list, we can treat it as a stack, and \override and \revert are just push and pop operations. This pushing and popping is also used for overriding automatic beaming settings.

BUGS

LilyPond will hang or crash if value contains cyclic references. The backend is not very strict in type-checking grob properties. If you \revert properties that are expected to be set by default, LilyPond may crash.

Some grobs are created at the moment that their context is created. An example of such a grob is the staff itself (i.e. the horizontal lines). You can not change the appearance of the staff symbol by manipulating \property Staff.StaffSymbol. At the moment that \property Staff is interpreted, a Staff context is made, and the StaffSymbol is created before any \override is effective. You can deal with this either overriding properties in a \translator definition, or by using \outputproperty.

Tuning per grob

A second way of tuning grobs is the more arcane \outputproperty feature. The syntax is as follows:

\outputproperty predicate symbol = value

Here predicate is a Scheme function taking a grob argument, and returning a boolean. This statement is processed by the Output_property_engraver . It instructs the engraver to feed all grobs that it sees to predicate. Whenever the predicate returns true, the grob property symbol will be set to value.

You will need to combine this statement with \context to select the appropriate context to apply this to.

Here are some random examples.

In the following example, all note heads occurring at current staff level, are shifted up and right by setting their extra-offset property.

\relative c'' { c4
  \context Staff \outputproperty
  #(make-type-checker 'note-head-interface)
  #'extra-offset = #'(0.5 . 0.75)
  <c8 e g> }

In this example, the predicate checks the text grob property, to shift only the `m.d.' text, but not the fingering instruction "2".

#(define (make-text-checker text)
   (lambda (grob) (equal? text (ly-get-grob-property grob 'text))))

\score {
  \notes\relative c''' {
    \property Voice.Stem \set #'direction = #1
    \outputproperty #(make-text-checker "m.d.")
      #'extra-offset = #'(-3.5 . -4.5)
    a^2^"m.d."
  }
}

BUGS

If possible, avoid this feature: the semantics are not very clean, and the syntax and semantics are up for rewrite.

What to tune?

This all tells you how to tune grobs, but you don't know what variables to set? The question is not answered in this part of the manual (although you may encounter some examples.).

Grob properties are tied directly to the implementation of LilyPond, and they are thus a moving target. Documentation of such variables is in the automatically generated documentation. Description of properties are generated from the source code for each version. This documentation is therefore more up to date. It should be available from the same place where you got this manual.

To decide how to tune a grob, you need to find the following information

which grob to modify
which property to modify
which context the grob comes from.

Included with the automatically generated documentation is a master list of grobs. Selecting a grob will take you to an overview of the properties available for that grob.

There is also a master list of contexts. Selecting one takes you to an overview of that context which lists which grob types are created there.

Font selection

Most graphics in LilyPond are composed of characters of fonts. You can alter the characteristics of the font by setting certain grob properties. The mechanism that is used for this resembles LaTeX's New Font Selection Scheme. Within this scheme, a font is entirely characterized by its font name.

For each grob that uses fonts (in other words, each grob that supports font-interface) a font-name must be selected before it can be printed. The font name is selected by looking at a number of grob properties:

font-family: A symbol indicating the general class of the typeface. Supported are roman (Computer Modern), braces (for piano staff braces), music (the standard music font), dynamic (font for dynamic signs) and typewriter
font-shape: A symbol indicating the shape of the font, there are typically several font shapes available for each font family. Choices are italic, caps and upright
font-series: A symbol indicating the series of the font. There are typically several font series for each font family and shape. Choices are medium and bold.
font-relative-size: A number indicating the size relative the standard size. For example, with 20pt staff height, relative size -1 corresponds to 16pt staff height, and relative size +1 corresponds to 23 pt staff height.
font-design-size: A number indicating the design size of the font.
This is a feature of the Computer Modern Font: each point size has a slightly different design. Smaller design sizes are relatively wider, which enhances readability. Scalable type faces such TrueType and Adobe Type1 usually come as "one design fits all sizes".
font-name: The name of the font, without the design size, e.g. cmr, cmti, etc. Setting this overrides font-family, font-shape and font-series.

The font is selected by taking the first font that satisfies all qualifiers specified. You can override any of these fields through \override and \revert. The special value * matches any value for that qualifier.

  \property Lyrics.LyricText \override #'font-series = #'bold
  \property Lyrics.LyricText \override #'font-shape = #'*

There are also pre-cooked font selection qualifiers. These are selected through the grob property font-style. For example, the style finger selects family number and relative size -3. Styles available include volta, finger, tuplet, timesig, mmrest, script, large, Large and dynamic.

The style sheets and tables for selecting fonts are located in scm/font.scm. Refer to this file for more information.

BUGS

Relative size is not linked to any real size.

There is no mechanism to select magnification of particular fonts, meaning that you don't have access to continuously scaled fonts. You can scale the entire output, of course, see Output scaling.

There is no style sheet provided for other fonts besides the TeX family.

Text markup

LilyPond has an internal mechanism to typeset texts. You can form text markup expressions by composing scheme expressions in the following way.

 \relative c' {
    \fatText
    a^#"upright"
    b_#'(bold "bold")
    c^#'(italic "italic")
    d_#'((bold italic) "ff")
    e^#'(dynamic "ff")
    f_#'(lines "one" (bold "two"))
    g^#'(music "noteheads-2" ((raise . 2.4) "flags-u3"))
  }

Normally, the Scheme markup text is stored in the text property of a grob. Formally, it is defined as follows:

text: string | (head? text+)
head: markup | (markup+)
markup-item: property | abbrev
property: (key . value)
abbrev: columns lines roman music bold italic named super sub
        overstrike text finger volta timesig mmrest mark script
        large Large dynamic

The markup is broken down and converted into a list of grob properties, which are prepended to the property list. The key-value pair is a grob property. A list of properties available is included in the generated documentation for Text_interface .

The following abbreviations are currently defined:

columns: horizontal mode: set all text on one line (default)
lines: vertical mode: set every text on a new line
roman: select roman font
music: selects the Feta font (the standard font for music notation glyphs), and uses named lookup
bold: select bold series
italic: select italic shape
named: lookup by character name
text: plain text lookup (by character value)
super: superscript
sub: subscript
overstrike: the next text or character overstrikes this one
finger: select fingering number fontstyle
volta: select volta number fontstyle
timesig: select time signature number fontstyle
mmrest: select multi measure rest number fontstyle
mark: select mark number fontstyle
script: select scriptsize roman fontstyle
large: select large roman fontstyle
Large: select Large roman fontstyle
dynamic: select dynamics fontstyle

One practical application of complicated markup is to fake a metronome marking:

#(define note '(columns
  (music "noteheads-2" ((kern . -0.1) "flags-stem"))))
#(define eight-note `(columns ,note ((kern . -0.1)
  (music ((raise . 3.5) "flags-u3")))))
#(define dotted-eight-note
  `(columns ,eight-note (music "dots-dot")))

\score {
  \notes\relative c'' {
    a1^#`((columns (font-relative-size . -1)) ,dotted-eight-note " = 64")
  }
  \paper {
    linewidth = -1.
    \translator{
      \ScoreContext
      TextScript \override #'font-shape = #'upright
    }
  }
}

Invisible grobs

You can imagine a number of situations where you would want to make certain grobs not show up in the output. There may be aesthetic reasons, to make the output resemble an (old) manuscript as close as possible, or to make lessons or exercises for students.

Grobs can be made invisible in a number of ways:

Here's an example with blanked-out notes and stems:

blanknotes = {
  \property Voice.NoteHead \override
    #'transparent = ##t
  \property Voice.Stem \override
    #'transparent = ##t }

unblanknotes = {
  \property Voice.NoteHead \revert #'transparent
  \property Voice.Stem \revert #'transparent }

\score {
  \notes\relative c'' {
    \time 6/4
    a b c b \blanknotes c \unblanknotes d
  }
}

This method makes the grobs invisible but they still take the normal space. To remove all traces of the grob, you can redefine the function typesetting them:

\score {
  \notes\relative c'' {
    \key c \minor
    \time 6/4
    as bes c bes c d \break
    \property Staff.KeySignature \override #'molecule-callback = #'()
    as bes c bes c d
  }
  \paper{linewidth=5.0\cm indent=0}
}

A very rigorous way of removing grobs from the whole score is to remove the engraver that creates them. For example,

\score {\notes { c'4 d'8 e'8 g2 }
  \paper { \translator {
     \VoiceContext
     \remove Stem_engraver
  } }
}

Dirty tricks

It is possible to use TeX commands in the strings, but this should be avoided because it makes it impossible for LilyPond to compute the exact length of the string, which may lead to collisions. Also, TeX commands won't work with direct PostScript output (see PostScript output).

  a'^"3 $\\times$ \\`a deux"

You can also use raw PostScript commands embedded in text scripts. This offers ultimate flexibility, but requires you to learn PostScript. Currently, embedded PostScript will not work with direct PostScript output. Note that all dimensions that you use are in staff space.

\score {
  \notes \relative c'' {
    a-#"\\embeddedps{3 4 moveto 5 3 rlineto stroke}"
    -#"\\embeddedps{ [ 0 1 ] 0 setdash 3 5 moveto 5 -3 rlineto stroke}"
    b-#"\\embeddedps{3 4 moveto 0 0 1 2 8 4 20 3.5 rcurveto stroke}"
    s2
    a'1
  }
  \paper { linewidth = 70*\staffspace }
}

Page layout

The page layout is the combined product of LilyPond formatting notation, and (La)TeX putting the notation on a page, including page breaks. The part of LilyPond is documented here.

Paper block

The most important output definition is the \paper block, for music notation. The syntax is

  \paper { [paperidentifier] items }

where each of the items is one of

An assignment.
A context definition. See Interpretation context for more information on context definitions.
\stylesheet declaration. Its syntax is
```
        	\stylesheet alist
       
```
See scm/font.scm for details of alist.
an \elementdescriptions declaration.
```
                \elementdescriptions alist
        
```
See scm/grob-description.scm for details of alist. This command is not user-serviceable.

Paper variables

The paper block has some variables you may want to use or change:

indent: The indentation of the first line of music.
staffspace: The distance between two staff lines, calculated from the center of the lines.
linewidth: Sets the width of the lines.
If set to a negative value, a single unjustified line is produced. The shorthand \singleLine defines a default paper block that produces a single line.
textheight: Sets the total height of the music on each page. Only used by ly2dvi.
interscoreline: Sets the spacing between systems. The default is 16pt.
interscorelinefill: If set to a positive number, the distance between the score lines will stretch in order to fill the full page. In that case interscoreline specifies the minimum spacing.
Not set by default.
stafflinethickness: Determines the thickness of staff lines, and also acts as a scaling parameter for other line thicknesses.

You may enter these dimension using units (cm, in, mm, pt), or relative to another dimension

        linewidth = 20.0 * \staffspace
        indent  = 0.5 \cm

Definitions for these sizes are the files paperSZ.ly, where SZ is one of 11, 13, 16, 20, 23 and 26. If you include any of these files, the identifiers paperEleven, paperThirteen, paperSixteen, paperTwenty, paperTwentythree, and paperTwentysix are defined respectively. The default \paper block is also set.

The font definitions are generated using a Scheme function. For more details, see the file scm/font.scm.

Paper size

To change the paper size, you must first set the papersize paper variable variable. Set it to the strings a4, letter, or legal. After this specification, you must set the font as described above. If you want the default font, then use the 20 point font.

        \paper {papersize = "a4" }
        \include "paper16.ly"

The file paper16.ly will now include a file named a4.ly, which will set the paper variables hsize and vsize (used by Lilypond and ly2dvi)

Line break

Line breaks are normally computed automatically. They are chosen such that the resulting spacing has low variation, and looks neither cramped nor loose.

Occasionally you might want to override the automatic breaks; you can do this by specifying \break. This will force a line break at this point. Do remember that line breaks can only occur at places where there are bar lines. If you want to have a line break where there is no bar line, you can force an invisible bar line by entering \bar "". Similarly, \noBreak forbids a line break at a certain point.

The \break and \noBreak commands are defined in terms of the penalty command:

  \penalty int

This encourages or discourages LilyPond to make a line break at this point.

BUGS

The scaling of the \penalty argument is not well-defined. The command is rather kludgey, and slated for rewriting.

Page break

Page breaks are normally computed by TeX, so they are not under direct control of LilyPond. However, you can insert a commands into the .tex output to instruct TeX where to break pages, by inserting the command \newpage

  \newpage

Output scaling

[TODO]

dvips ...

pstops ...

BUGS

There is no mechanism to select magnification of particular fonts, meaning that you don't have access to continuously scaled fonts.

Output formats

LilyPond can output processed music in different output formats.

TeX output

LilyPond will use TeX by default. Even if you want to produce PostScript output for viewing or printing, you should normally have LilyPond produce TeX first. The .tex output must be processed by TeX (not LaTeX) to generate a .dvi. Then, Dvips is used to generate PostScript. Alternatively, ly2dvi can be used to generate the .dvi for you.

BUGS

Titling is not generated unless you use ly2dvi.

PostScript output

LilyPond can produce PostScript directly, without going through TeX. Currently, this is mainly useful if you cannot use TeX, because direct PostScript output has some problems; see Bugs below.

$ lilypond -fps foo.ly
GNU LilyPond 1.3.144
Now processing: `foo.ly'
Parsing...
Interpreting music...[3]
Preprocessing elements...
Calculating column positions...
paper output to foo.ps...

$ cat /usr/share/lilypond/pfa/feta20.pfa foo.ps | lpr

BUGS

Text font selection is broken.

The .ps file does not contain the .pfa font files. To print a .ps created through direct postscript output, you should prepend the necessary .pfa files to LilyPond's .ps output, or upload them to the printer before printing.

The line height calculation is broken, you must set lineheight in the paperblock if you have more than one staff in your score, e.g.

  ...
  \paper {
    % Set line height to 40 staff spaces
    lineheight = 40
  }

Scheme output

In the typesetting stage, LilyPond builds a page description, which is then written to disk in postscript, TeX or ASCII art. Before it is written, the page description is represented as Scheme expressions. You can also dump these Scheme expressions to a file, which may be convenient for debugging output routines. This is done with the Scheme output format

$ lilypond -fscm foo.ly
GNU LilyPond 1.3.144
Now processing: `foo.ly'
Parsing...
Interpreting music...[3]
Preprocessing elements...
Calculating column positions...
paper output to foo.scm...

$ head -4 foo.scm
;;; Usage: guile -s x.scm > x.tex
 (primitive-load-path 'standalone.scm)
; (scm-tex-output)
 (scm-ps-output)

$ guile -s foo.scm > foo.tex

ASCIIScript output

LilyPond can output ASCII Art. This is a two step process, LilyPond produces an ASCII description file, dubbed ASCIIScript (extension .as). ASCIIScript has a small and simple command set that includes font selection, character and string printing and line drawing commands. The program as2text is used to translate an .as file to text.

To produce ASCII Art, you must include an ASCII Art paper definition file in your .ly, one of:

\include "paper-as5.ly"
\include "paper-as9.ly"

Here's an example use for ASCII Art output (the example file as-email.ly is included in the LilyPond distribution), the staff symbol has been made invisible:

$ lilypond -fas as-email.ly
GNU LilyPond 1.3.144
Now processing: `as-email.ly'
Parsing...
Interpreting music...[3]
Preprocessing elements...
Calculating column positions... [2]
paper output to as-email.as...

$ as2text as-email.as 2>/dev/null
          |\
          |/     |##|##|      |  |  |  |  |
         /|      |  |  | |    |\ |\ |\ |\ |\ |
        / |_  3  |  |  | | 5  | )| )| )| )| )|
       | /| \ 8 *  *  *  | 8 *  *  *  *  *   |
        \_|_/            |                   |
        *_|

                                               lily

BUGS

The ASCII Art fonts are far from complete and not very well designed. It's easy to change the glyphs, though; if you think you can do better, have a look at mf/*.af.

Lots of resizable symbols such as slurs, ties and tuplets are missing.

The poor looks of most ASCII Art output and its limited general usefulness gives ASCII Art output a low priority; it may be dropped in future versions.

Sound

LilyPond can produce MIDI output. The performance lacks lots of interesting effects, such as swing, articulation, slurring, etc., but it is good enough for proof-hearing the music you have entered. Ties, dynamics and tempo changes are interpreted.

Dynamic marks, crescendi and decrescendi translate into MIDI volume levels. Dynamic marks translate to a fixed fraction of the available MIDI volume range, crescendi and decrescendi make the the volume vary linearly between their two extremities. The fractions be adjusted by overriding the absolute-volume-alist defined in scm/midi.scm.

For each type of musical instrument (that MIDI supports), a volume range can be defined. This gives you basic equalizer control, which can enhance the quality of the MIDI output remarkably. You can add instruments and ranges or change the default settings by overriding the instrument-equalizer-alist defined in scm/midi.scm.

Both loudness controls are combined to produce the final MIDI volume.

BUGS

It is currently not possible to use the percussion channel (generally channel 10 of a MIDI file).

MIDI block

The MIDI block is analogous to the paper block, but it is somewhat simpler. The \midi block can contain:

a \tempo definition
context definitions

Assignments in the \midi block are not allowed.

Context definitions follow precisely the same syntax as within the \paper block. Translation modules for sound are called performers. The contexts for MIDI output are defined in ly/performer.ly.

MIDI instrument names

The MIDI instrument name is set by the Staff.midiInstrument property or, if that property is not set, the Staff.instrument property. The instrument name should be chosen from the list in MIDI instruments.

BUGS

If the selected string does not exactly match, then LilyPond uses the default (Grand Piano). It is not possible to select an instrument by number.

Music entry

When entering music with LilyPond, it is easy to introduce errors. This section deals with tricks and features that help you enter music, and find and correct mistakes.

Relative

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. To prevent these errors, LilyPond features octave entry.

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

Entering music that changes octave frequently is easy in relative mode.

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

And 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. However, other notes within the second chord are determined by looking at the immediately preceding note.

  \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

Whenever a bar check is encountered during interpretation, a warning message is issued if it doesn't fall at a measure boundary. This can help you find errors in the input. Depending on the value of barCheckNoSynchronize, the beginning of the measure will be relocated, so this can also be used to shorten measures.

A bar check is entered using the bar symbol, |:

  \time 3/4 c2 e4 | g2.

Failed bar checks are most often 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 (See Skipping corrected music)). Bar

Point and click

Point and click lets you find notes in the input by clicking on them in the Xdvi window. This makes it very easy to find input that causes some error in the sheet music.

To use it, you need the following software

Installation

plain Xdvi version 22.36 or newer.
Note that most TeX distributions ship with xdvik, which is a different and less well maintained program. To find out which xdvi you are running, try xdvi --version or xdvi.bin --version.
emacs

Xdvi must be configured to find the TeX fonts and music fonts. Refer to the Xdvi documentation for more information.

Using it

Add one of these lines to the top of your .ly file. The first one is for line location only. The second one is more convenient, but requires patching emacsclient and server.el.

#(set! point-and-click line-location)

In the emacs startup file (usually ~/.emacs), add the following

(server-start)

Make sure that the environment variable XEDITOR is set to

emacsclient --no-wait +%l %f

The second one, that also specifies the column, only works if you have patched your emacsclient and server, and have compiled your .ly file using the line-column-location setting.

When viewing, control-mousebutton 1 will take you to the originating spot in the .ly file. Control-mousebutton 2 will show all clickable boxes.

Column location

If you want emacs to jump to the exact spot (and not just the line) on a click, you must enable column positioning. To do so, you need to patch emacsclient. Apply emacsclient.patch (included with the source package) to emacsclient.c and server.el from the emacs source code. Recompile and stick the recompiled emacsclient into a bin directory, and put server.el into a elisp directory (e.g. ~/usr/share/emacs/). Add the following to your .emacs init file, before invoking server-start.

 (setq load-path (cons "~/usr/share/emacs" load-path))

Set XEDITOR to emacsclient --no-wait +%l:%c %f

At the top of the ly file, replace the set! line with the following line

#(set! point-and-click line-column-location)

BUGS

When you convert the TeX file to PostScript using dvips, it will complain about not finding src:X:Y files. Those complaints are harmless, and can be ignored.

When using line-column-location, the cursor will be one off; it will not jump to the exact note that you clicked, but to the next one.

[FIXME]

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. You can use this to skip over the parts of a score that you have already 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 }

Interpretation context

Interpretation contexts are objects that only exist during a run of LilyPond. During the interpretation phase of LilyPond (when it prints "interpreting music"), the music expression in a \score block is interpreted in time order. This is the same order that humans hear and play the music.

During this interpretation, the interpretation context holds the state for the current point within the music. It contains information like

What notes are playing at this point?
What symbols will be printed at this point?
What is the current key signature, time signature, point within the measure, etc.?

Contexts are grouped hierarchically: A Voice context is contained in a Staff context (because a staff can contain multiple voices at any point), a Staff context is contained in Score , StaffGroup , or ChoirStaff context.

Contexts associated with sheet music output are called notation contexts, those for sound output are called performance contexts. The default definitions of the standard notation and performance contexts can be found in ly/engraver.ly and ly/performer.ly, respectively.

Creating contexts

Contexts for a music expression can be selected manually, using the following music expression.

  \context contexttype [= contextname] musicexpr

This instructs lilypond to interpret musicexpr within the context of type contexttype and with name contextname. If this context does not exist, it will be created.

\score {
  \notes \relative c'' {
    c4 <d4 \context Staff = "another" e4> f
  }
}

In this example, the c and d are printed on the default staff. For the e, a context Staff called another is specified; since that does not exist, a new context is created. Within another, a (default) Voice context is created for the e4. When all music referring to a context is finished, the context is ended as well. So after the third quarter, another is removed.

Default contexts

Most music expressions don't need an explicit \context declaration: they inherit the notation context from their parent. Each note is a music expression, and as you can see in the following example, only the sequential music enclosing the three notes has an explicit context.

\score { \notes \context Voice = goUp { c'4 d' e' } }

There are some quirks that you must keep in mind when dealing with defaults:

First, every top level music is interpreted by the Score context, in other words, you may think of \score working like

        \score {
                \context Score music
        }

Second, contexts are created automatically to be able to interpret the music expressions. Consider the following example.

\score { \context Score \notes { c'4 (  d' )e' } }

The sequential music is interpreted by the Score context initially (notice that the \context specification is redundant), but when a note is encountered, contexts are setup to accept that note. In this case, a Thread, Voice and Staff are created. The rest of the sequential music is also interpreted with the same Thread, Voice and Staff context, putting the notes on the same staff, in the same voice.

This is a convenient mechanism, but do not expect opening chords to work without \context. For every note, a separate staff is instantiated.

\score { \notes <c'4 es'> }

Of course, if the chord is preceded by a normal note in sequential music, the chord will be interpreted by the Thread of the preceding note:

\score { \notes { c'4 <c'4 es'> }  }

Context properties

Notation contexts have properties. These properties are from the .ly file using the following expression:

  \property contextname.propname =  value

Sets the propname property of the context contextname to the specified Scheme expression value. All propname and contextname are strings, which are typically unquoted.

Properties that are set in one context are inherited by all of the contained contexts. This means that a property valid for the Voice context can be set in the Score context (for example) and thus take effect in all Voice contexts.

Properties can be unset using the following expression:

  \property contextname.propname \unset

This removes the definition of propname in contextname. If propname was not defined in contextname (but was inherited from a higher context), then this has no effect.

BUGS

The syntax of \unset is asymmetric: \property \unset is not the inverse of \property \set.

Engravers and performers

[TODO]

Basic building blocks of translation are called engravers; they are special C++ classes.

Changing context definitions

The most common way to define a context is by extending an existing context. You can change an existing context from the paper block, by first initializing a translator with an existing context identifier:

\paper {
  \translator {
    context-identifier
  } }

Then you can add and remove engravers using the following syntax:

 \remove engravername
 \consists engravername

Here engravername is a string, the name of an engraver in the system.

\score {  \notes {
        c'4 c'4 }
  \paper {
    \translator  { \StaffContext
        \remove Clef_engraver
       } } }

You can also set properties in a translator definition. The syntax is as follows:

 propname = value
 propname \set  grob-propname = pvalue
 propname \override grob-propname =  pvalue
 propname \revert grob-propname

propname is a string, grob-propname a symbol, value and pvalue are Scheme expressions. These type of property assignments happen before interpretation starts, so a \property command will override any predefined settings.

To simplify editing translators, all standard contexts have standard identifiers called nameContext, e.g. StaffContext, VoiceContext, see ly/engraver.ly.

Defining new contexts

If you want to build a context from scratch, you must also supply the following extra information:

A name, specified by \name contextname.
A cooperation module. This is specified by \type typename.

This is an example:

\translator 
  \type "Engraver_group_engraver"
  \name "SimpleStaff"
  \alias "Staff"
  \consists "Staff_symbol_engraver"
  \consists "Note_head_engraver"
  \consistsend "Axis_group_engraver"

The argument of \type is the name for a special engraver that handles cooperation between simple engravers such as Note_head_engraver and Staff_symbol_engraver . Alternatives for this engraver are the following:

Engraver_group_engraver: The standard cooperation engraver.
Score_engraver: This is cooperation module that should be in the top level context, and only the top level context.
Grace_engraver_group This is a special: cooperation module (resembling Score_engraver ) that is used to create an embedded `miniscore'.

Other modifiers are

\alias alternate-name This specifies a different name. In the above example, \property Staff.X = Y will also work on SimpleStaffs
\consistsend engravername Analogous to \consists, but makes sure that engravername is always added to the end of the list of engravers.
Some engraver types need to be at the end of the list; this insures they stay there even if a user adds or removes engravers. End-users generally don't need this command.
\accepts contextname Add contextname to the list of contexts this context can contain in the context hierarchy. The first listed context is the context to create by default.
\denies. The opposite of \accepts. Added for completeness, but is never used in practice.
\name contextname This sets the type name of the context, e.g. Staff , Voice . If the name is not specified, the translator won't do anything.

In the \paper block, it is also possible to define translator identifiers. Like other block identifiers, the identifier can only be used as the very first item of a translator. In order to define such an identifier outside of \score, you must do

\paper {
  foo = \translator { ... }
}
\score {
  \notes {
    ...
  }
  \paper {
    \translator { \foo ... }
  }
}

Syntactic details

This section describes details that were too boring to be put elsewhere.

Top level

This section describes what you may enter at top level.

Score

The output is generated combining a music expression with an output definition. A score block has the following syntax:

  \score { musicexpr outputdefs }

outputdefs are zero or more output definitions. If none is supplied, the default \paper block will be added.

Default output

Default values for the \paper and \midi block are set by entering such a block at the top level.

Header

A header describes bibliographic information of the file's contents. It can also appear in a \score block. Tools like ly2dvi can use this information for generating titles. Key values that are used by ly2dvi are: title, subtitle, composer, opus, poet, instrument, meter, arranger, piece and tagline.

The syntax is

  \header { key1 = val1
             key2 = val2 ... }

It is customary to put the \header at the top of the file.

Default output

A \midi or \paper block at top level sets the default paper block for all scores that lack an explicit paper block.

Identifiers

All of the information in a LilyPond input file, is internally represented as a Scheme value. In addition to normal Scheme data types (such as pair, number, boolean, etc.), LilyPond has a number of specialized data types,

Input
c++-function
Music
Identifier
Translator_def
Duration
Pitch
Score
Music_output_def
Moment (rational number)

LilyPond also includes some transient object types. Objects of these types are built during a LilyPond run, and do not `exist' per se within your input file. These objects are created as a result of your input file, so you can include commands in the input to manipulate them, during a lilypond run.

Grob: short for Graphical object. See Grobs.
Molecule: device-independent page output object, including dimensions. Produced by some Grob functions See Molecules
Translator: object that produces audio objects or Grobs. This is not yet user accessible.
Font_metric: object representing a font. (See Font metrics)

Music expressions

Music in LilyPond is entered as a music expression. Notes, rests, lyric syllables are music expressions, and you can combine music expressions to form new ones, for example by enclosing a list of expressions in \sequential { } or < >. In the following example, a compound expression is formed out of the quarter note c and a quarter note d:

\sequential { c4 d4 }

The two basic compound music expressions are simultaneous and sequential music.

  \sequential { musicexprlist }
  \simultaneous { musicexprlist }

For both, there is a shorthand:

  { musicexprlist }

for sequential and

  < musicexprlist >

for simultaneous music. In principle, the way in which you nest sequential and simultaneous to produce music is not relevant. In the following example, three chords are expressed in two different ways:

  \notes \context Voice {
    <a c'> <b  d' > <c' e'>
    < { a b  c' } { c' d' e' } >
  }

Other compound music expressions include

 \repeat expr
 \transpose pitch expr
 \apply func expr
 \context type = id expr
 \times fraction expr

Manipulating music expressions

The \apply mechanism gives you access to the internal representation of music. You can write Scheme-functions that operate directly on it. The syntax is

        \apply #func music

This means that func is applied to music. The function func should return a music expression.

This example replaces the text string of a script. It also shows a dump of the music it processes, which is useful if you want to know more about how music is stored.

#(define (testfunc x)
        (if (equal? (ly-get-mus-property x 'text) "foo")
                (ly-set-mus-property x 'text "bar"))
        ;; recurse
        (ly-set-mus-property x 'elements
          (map testfunc (ly-get-mus-property x 'elements)))
        (display x)
        x
)
\score { \notes
  \apply #testfunc { c'4_"foo" }
}

For more information on what is possible, see the automatically generated documentation.

Directly accessing internal representations is dangerous: the implementation is subject to changes, so you should avoid this feature if possible.

A final example is a function that reverses a piece of music in time:

#(define (reverse-music music)
  (let* ((elements (ly-get-mus-property music 'elements))
         (reversed (reverse elements))
         (span-dir (ly-get-mus-property music 'span-direction)))
    (ly-set-mus-property music 'elements reversed)
    (if (dir? span-dir)
        (ly-set-mus-property music 'span-direction (- span-dir)))
    (map reverse-music reversed)
    music))

music = \notes { c'4 d'4( e'4 f'4 }

\score { \context Voice {
    \music
    \apply #reverse-music \music
  }
}

More examples are given in the distributed example files in input/test/.

Span requests

Notational constructs that start and end on different notes can be entered using span requests. The syntax is as follows:

  \spanrequest startstop type

This defines a spanning request. The startstop parameter is either -1 (\start) or 1 (\stop) and type is a string that describes what should be started. Much of the syntactic sugar is a shorthand for \spanrequest, for example,

  c'4-\spanrequest \start "slur"
  c'4-\spanrequest \stop "slur"

Among the supported types are crescendo, decrescendo, beam, slur. This is an internal command. Users are encouraged to use the shorthands which are defined in the initialization file spanners.ly.

Assignments

Identifiers allow objects to be assigned to names during the parse stage. To assign an identifier, you use name=value and to refer to an identifier, you precede its name with a backslash: `\name'. value is any valid Scheme value or any of the input-types listed above. Identifier assignments can appear at top level in the LilyPond file, but also in \paper blocks.

An identifier can be created with any string for its name, but you will only be able to refer to identifiers whose names begin with a letter, being entirely alphabetical. It is impossible to refer to an identifier whose name is the same as the name of a keyword.

The right hand side of an identifier assignment is parsed completely before the assignment is done, so it is allowed to redefine an identifier in terms of its old value, e.g.

foo = \foo * 2.0

When an identifier is referenced, the information it points to is copied. For this reason, an identifier reference must always be the first item in a block.

\paper  {
  foo = 1.0
  \paperIdent % wrong and invalid
}

\paper {
  \paperIdent % correct
  foo = 1.0 }

Lexical modes

To simplify entering notes, lyrics, and chords, LilyPond has three special input modes in addition to the default mode: note, lyrics and chords mode. These input modes change the way that normal, unquoted words are interpreted: for example, the word cis may be interpreted as a C-sharp, as a lyric syllable `cis' or as a C-sharp major triad respectively.

A mode switch is entered as a compound music expression

\notes musicexpr
\chords musicexpr
\lyrics musicexpr.

In each of these cases, these expressions do not add anything to the meaning of their arguments. They just instruct the parser in what mode to parse their arguments. The modes are treated in more detail in Lyrics and Chords.

Different input modes may be nested.

Ambiguities

The grammar contains a number of ambiguities. We hope to resolve them at some time.

The assignment
```
foo = bar
```
is interpreted as the string identifier assignment. However, it can also be interpreted as making a string identifier \foo containing "bar", or a music identifier \foo containing the syllable `bar'.
If you do a nested repeat like
```
\repeat ...
\repeat ...
\alternative
```
then it is ambiguous to which \repeat the \alternative belongs. This is the classic if-then-else dilemma. It may be solved by using braces.
The parser is not sophisticated enough to distinguish at the right time between c4*2 / 3 and c4*2 / g (in chord mode).
[checkme]

Lexical details

Even more boring details, now on lexical side of the input parser.

Comments

A one line comment is introduced by a % character. Block comments are started by %{ and ended by %}. They cannot be nested.

Direct Scheme

LilyPond contains a Scheme interpreter (the GUILE library) for internal use. In some places, Scheme expressions also form valid syntax: wherever it is allowed,

  #scheme

evaluates the specified Scheme code. Example:

  \property Staff.TestObject \override #'foobar =  #(+ 1 2)

\override expects two Scheme expressions, so there are two Scheme expressions. The first one is a symbol (foobar), the second one an integer (namely, 3).

In-line scheme may be used at the top level. In this case the result is discarded.

Scheme is a full-blown programming language, and a full discussion is outside the scope of this document. Interested readers are referred to the website http://www.schemers.org/ for more information on Scheme.

Keywords

Keywords start with a backslash, followed by a number of lower case alphabetic characters. These are all the keywords.

apply arpeggio autochange spanrequest commandspanrequest
simultaneous sequential accepts alternative bar breathe
char chordmodifiers chords clef cm consists consistsend
context denies duration dynamicscript elementdescriptions
font grace header in lyrics key mark pitch
time times midi mm name pitchnames notes outputproperty
override set revert partial paper penalty property pt
relative remove repeat addlyrics partcombine score
script stylesheet skip textscript tempo translator
transpose type

Integers

Formed from an optional minus sign followed by digits. Arithmetic operations cannot be done with integers, and integers cannot be mixed with reals.

Reals

Formed from an optional minus sign and a sequence of digits followed by a required decimal point and an optional exponent such as -1.2e3. Reals can be built up using the usual operations: `+', `-', `*', and `/', with parentheses for grouping.

A real constant can be followed by one of the dimension keywords: \mm \pt, \in, or \cm, for millimeters, points, inches and centimeters, respectively. This converts the number a number that is the internal representation of that dimension.

Strings

Begins and ends with the " character. To include a " character in a string write \". Various other backslash sequences have special interpretations as in the C language. A string that contains no spaces can be written without the quotes. Strings can be concatenated with the + operator.

Main input

The \maininput command is used in init files to signal that the user file must be read. This command cannot be used in a user file.

File inclusion

  \include filename

Include filename. The argument filename may be a quoted string (an unquoted string will not work here!) or a string identifier. The full filename including the .ly extension must be given,

Version information

  \version string

Specify the version of LilyPond that a file was written for. The argument is a version string in quotes, for example "1.2.0". This is used to detect invalid input, and to aid convert-ly a tool that automatically upgrades input files. See See convert-ly for more information on convert-ly.

Internals

When translating the input to notation, there are number of distinct phases. We list them here:

Parsing:

The LY file is read, and converted to a list of Scores, which each contain Music and paper/midi-definitions. Here Music, Pitch and Duration objects are created.

Interpreting music

All music events are "read" in the same order as they would be played (or read from paper). At every step of the interpretation, musical events are delivered to interpretation contexts, which use them to build Grobs (or MIDI objects, for MIDI output).

In this stage Music_iterators do a traversal of the Music structure. The music events thus encountered are reported to Translators, a set of objects that collectively form interpretation contexts.

Prebreaking

At places where line breaks may occur, clefs and bars are prepared for a possible line break.

Preprocessing

In this stage, all information that is needed to determine line breaking is computed.

Break calculation:

The lines and horizontal positions of the columns are determined.

Breaking

Relations between all grobs are modified to reflect line breaks: When a spanner, e.g. a slur, crosses a line-break, then the spanner is "broken into pieces", for every line that the spanner is in, a copy of the grob is made. A substitution process redirects all grob-reference so that each spanner grob will only reference other grobs in the same line.

Outputting:

All vertical dimensions and spanning objects are computed, and all grobs are output, line by line. The output is encoded in the form of Molecules

The data types that are mentioned here are all discussed in this section.

Input location

Input location objects point to a location in the input file. This location is used to generate error messages and to enable the point and click output.

ly-input-location? obj Function

Type predicate, return true if obj is an input location.

Moment

Moment is a rational number. Since GUILE doesn't support them natively, so we created our own rational data type.

moment? obj Function

Type predicate, return true if obj is a moment.

make-moment num den Function

create the rational number num/den.

Duration

A duration is a musical duration, i.e. a length of time described by a power of two (whole, half, quarter, etc.) and a number of augmentation dots.

make-duration length dotcount Function

length is the negative logarithm (base 2) of the duration: 1 is a half note, 2 is a quarter note, 3 is an eighth note, etc. The number of dots after the note is given by dotcount.

duration? obj Function

Type predicate, return true if obj is a duration.

Pitch data type

make-pitch octave note shift Function

octave is specified by an integer, zero for the octave containing middle C. note is a number from 0 to 6, with 0 corresponding to C and 6 corresponding to B. The shift is zero for a natural, negative for flats, or positive for sharps.

pitch-octave p Function

extract the octave from pitch p.

pitch-notename p Function

extract the note name from pitch p.

pitch-alteration p Function

extract the alteration from pitch p.

pitch-semitones p Function

calculate the number of semitones of p from central C.

Pitch::transpose t p Function

Transpose p by the amount t, where t is the pitch that central C is transposed to.

Music

Music is the data type that music expressions are stored in. The data type does not yet offer many manipulations.

ly-get-mus-property m sym Function

Get the property sym of music expression m.

ly-set-mus-property m sym val Function

Set property sym in music expression m to val.

ly-make-music name Function

Make a music object/expression of type name. Warning: this interface will likely change in the near future.

music? obj Function

Type predicate, return true if obj is a music object.

ly-music-name music Function

Print the name of music.

Music_iterator

Music_iterator is an object type that traverses the Music structure and reports the events it finds to interpretation contexts. It is not yet user-serviceable.

c++-function? obj Function

Type predicate, return true if obj is a c++-function. Music_iterator are created from schemified C++ constructors. Such a constructor is a c++-function.

Translator

Translators are the building blocks of contexts. They are not yet user accessible.

ly-get-trans-property tr sym Function

retrieve the value of sym from context tr

ly-set-trans-property tr sym val Function

set value of property sym in context tr to val.

Grobs

This section is about Grobs (short for Graphical Objects), which are formatting objects used to create the final output. This material is normally the domain of LilyPond gurus, but occasionally, a normal user also has to deal with grobs.

The most simple interaction with Grobs are when you use \override:

        \property Voice.Stem \override #'direction = #1

This piece of lily input causes all stem objects to be stem-up henceforth. In effect, you are telling lilypond to extend the definition of the `Stem' grob with the setting direction := 1.

What is a grob?

In music notation, lots of symbols are related in some way. You can think of music notation as a graph where nodes are formed by the symbols, and the arcs by their relations. A grob is a node in that graph. The directed edges in the graph are formed by references to other grobs (i.e. pointers). This big graph of grobs specifies the notation problem. The solution of this problem is a description of the printout in closed form, i.e. a list of values. These values are Molecules. (see Molecules)

All grobs have an X and Y-position on the page. These X and Y positions are stored in a relative format, so they can easily be combined by stacking them, hanging one grob to the side of another, and coupling them into a grouping-grob.

Each grob has a reference point (a.k.a. parent): the position of a grob is stored relative to that reference point. For example the X-reference point of a staccato dot usually is the note head that it applies to. When the note head is moved, the staccato dot moves along automatically.

If you keep following offset reference points, you will always end up at the root object. This root object is called Line_of_score, and it represents a system (i.e. a line of music).

All grobs carry a set of grob-properties. In the Stem example above, the property direction is set to value 1. The function that draws the symbol (Stem::brew_molecule) uses the value of direction to determine how to print the stem and the flag. The appearance of a grob is determined solely by the values of its properties.

A grob is often associated with a symbol, but some grobs do not print any symbols. They take care of grouping objects. For example, there is a separate grob that stacks staffs vertically. The NoteCollision is also an abstract grob: it only moves around chords, but doesn't print anything.

A complete list of grob types is found in the generated documentation.

Callbacks

Offsets of grobs are relative to a parent reference point. Most positions are not known when an object is created, so these are calculated as needed. This is done by adding a callback for a specific direction.

Suppose you have the following code in a .ly file.

        #(define (my-callback gr axis)
                (*  2.0 (get-grob-property gr 'direction))
        )

....

        \property Voice.Stem \override #'Y-offset-callbacks = #(list
                        my-callback)

When the Y-offset of a Stem object is needed, LilyPond will automatically execute all callbacks for that object. In this case, it will find my-callback, and execute that. The result is that the stem is translated by two staff spaces in its direction.

(note: Y-offset-callbacks is also a property)

Offset callbacks can be stacked, i.e.

        \property .... \override #'Y-offset-callbacks = #(list
                callback1 callback2 callback3)

The callbacks will be executed in the order callback3 callback2 callback1. This is used for quantized positioning: the staccato dot is above or below a note head, and it must not be on a staff-line. To achieve this, the staccato dot has two callbacks: one that positions the grob above or below the note head, and one that rounds the Y-position of the grob to the nearest open space.

Similarly, the size of a grob are determined through callbacks, settable with grob properties X-extent-callback and Y-extent-callback. There can be only one extent-callback for each axis. No callback (Scheme value #f) means: "empty in this direction". If you fill in a pair of numbers, that pair hard-codes the extent in that coordinate.

Setting grob properties

Grob properties are stored as GUILE association lists, with symbols as keys. In GUILE you can access these using functions described in Section Grob Scheme functions. From C++, grob properties can be accessed using these functions:

  SCM  get_grob_property (SCM) const;
  void set_grob_property (const char * , SCM val);
  void set_immutable_grob_property (const char * , SCM val);
  void set_immutable_grob_property (SCM key, SCM val);
  void set_grob_property (SCM , SCM val);
  void set_grob_pointer (const char*, SCM val);
  SCM  remove_grob_property (const char* nm);

All lookup functions identify undefined properties with end-of-list (i.e. '() in Scheme or SCM_EOL in C)

Properties are stored in two ways:

mutable properties. Grob properties that change from object to object. The storage of these are private to a grob. For example pointers to other grobs are always stored in the mutable properties.
immutable properties. Grob properties that are shared across different grobs of the same type. The storage is shared, and hence it is read-only. Typically, this is used to store function callbacks, and default settings. They are initially read from scm/grob-description.scm.

You can change immutable grob properties with the \override syntax:

        \property Voice.Stem \override #'direction = #1

This will push the entry '(direction . 1) on the immutable property list for stems, in effect overriding the setting from scm/grob-description.scm. This can be undone by

        \property Voice.stem \revert #'direction

There is also a shorthand,

        \property Context.GrobType \set #'prop = #VAL

this does a \revert followed by a \override

You can change mutable properties with \outputproperty. This construct looks like

        \context ContextName \outputproperty pred #sym = #val

In this case, in every grob that satisfies pred, the grob property sym is set to val. For example

        \outputproperty
                #(lambda (gr) (string? (ly-get-grob-property gr
                        'text)))
                #'extra-offset = #'(-1.0 . 0.0)

This shifts all grobs that have a text property one staff space to the left. This mechanism is rather clumsy to use, but it allows you tweak any setting of any grob.

Grob interfaces

Grob properties form a name space where you can set variables per object. Each object however, may have multiple functions. For example, consider a dynamic symbol, such \ff (fortissimo). It is printed above or below the staff, it is a dynamic sign, and it is a kind of text.

To reflect this different functions of a grob, procedures and variables are grouped into so-called interfaces. The dynamic text for example supports the following interfaces:

font-interface: The glyph is built from characters from a font, hence the font-interface. For objects supporting font-interface, you can select alternate fonts by setting font-style, font-point-size, etc.
dynamic-interface: Dynamic interface is not associated with any variable or function in particular, but this makes it possible to distinguish this grob from other similar grobs (like TextScript), that have no meaning of dynamics.
text-interface: This interface is for texts that are to be set using special routines to stack text into lines, using kerning, etc.
general-grob-interface: This interface is supported by all grob types.

Items and Spanners

Grobs can also be distinguished in their role in the horizontal spacing. Many grobs define constraints on the spacing by their sizes. For example, note heads, clefs, stems, and all other symbols with a fixed shape. These grobs form a subtype called Item.

Other grobs have a shape that depends on the horizontal spacing. For example, slur, beam, tie, etc. These grobs form a subtype called Spanner. All spanners have two span-points (these must be Items), one on the left and one on the right. The left bound is also the X-reference point of the spanner.

Some items need special treatment for line breaking. For example, a clef is normally only printed at the start of a line (i.e. after a line break). To model this, `breakable' items (clef, key signature, bar lines, etc.) are copied twice. Then we have three versions of each breakable item: one version if there is no line break, one version that is printed before the line break (at the end of a system), one version that is printed after the line break.

Whether these versions are visible and take up space, is determined by the outcome of the visibility-lambda. This grob property is a function taking a direction (-1, 0 or 1) as argument. It returns a cons of booleans, signifying whether this grob should be transparent and have no extent.

Grob Scheme functions

Grob properties can be manipulated from Scheme. In practice, most manipulations are coded in C++ because of tradition.

ly-get-grob-property g sym Function

Get the value of a value in grob g of property sym. It will return '() (end-of-list) if g doesn't have sym set.

ly-set-grob-property g sym val Function

Set sym in grob g to value val

ly-get-spanner-bound spanner dir Function

Get one of the bounds of spanner. dir may be -1 for left, and 1 for right.

ly-grob? g Function

Typecheck: is g a grob?

Molecules

The objective of any typesetting system is to put ink on paper in the right places. For LilyPond, this final stage is left to the TeX and the printer subsystem. For lily, the last stage in processing a score is outputting a description of what to put where. This description roughly looks like

        PUT glyph AT (x,y)
        PUT glyph AT (x,y)
        PUT glyph AT (x,y)

you merely have to look at the tex output of lily to see this. Internally these instructions are encoded in Molecules.⁵ A molecule is what-to-print-where information that also contains dimension information (how large is this glyph?).

Conceptually, Molecules can be constructed from Scheme code, by translating a Molecule and by combining two molecules. In BNF notation:

Molecule  :: COMBINE Molecule Molecule
           | TRANSLATE Offset Molecule
           | GLYPH-DESCRIPTION
           ;

If you are interested in seeing how this information is stored, you can run with the -f scm option. The scheme expressions are then dumped in the output file.

All visible, i.e. non-transparent, grobs have a callback to create a Molecule. The name of the property is molecule-callback, and its value should be a Scheme function taking one argument (the grob) and returning a Molecule. Most molecule callbacks are written in C++, but you can also write them in Scheme. An example is provided in input/regression/molecule-hacking.ly.

molecule? m Function

type predicate.

ly-combine-molecule-at-edge mol1 axis dir mol2 padding Function

Construct a molecule by putting mol2 next to mol1. axis can be 0 (x-axis) or 1 (y-axis), dir can be -1 (left or down) or 1 (right or up). padding specifies extra space to add in between measured in global staff space.

ly-get-molecule-extent! mol axis Function

Return a pair of numbers signifying the extent of mol in axis direction (0 or 1 for x and y axis respectively).

ly-set-molecule-extent! mol axis extent Function

Set the extent (extent must be a pair of numbers) of mol in axis direction (0 or 1 for x- and y-axis respectively).
Note that an extent (A . B) is an interval and hence A is smaller than B, and is often negative.

Font metrics

The font object represents the metric information of a font. Every font that is loaded into LilyPond can be accessed via Scheme.

LilyPond only needs to know the dimension of glyph to be able to process them. This information is stored in font metric files. LilyPond can read two types of font-metrics: TeX Font Metric files (TFM files) and Adobe Font Metric files (AFM files). LilyPond will always try to load AFM files first since they are more versatile.

ly-get-default-font gr Function

This returns the default font for grob gr.

ly-find-glyph-by-name font name Function

This function retrieves a Molecule for the glyph named name in font. The font must be available as an AFM file.

Miscellaneous Scheme functions

ly-warn msg Function

Scheme callable function to issue the warning msg.

ly-version Function

Return the current lilypond version as a list, e.g. (1 3 127 uu1).

ly-gulp-file name Function

Read the file named name, and return its contents in a string. The file is looked up using the lilypond search path.

dir? Function

type predicate. A direction is a -1, 0 or 1, where -1 represents left or down and 1 represents right or up.

ly-number->string num Function

converts num to a string without generating many decimals. It leaves a space at the end.

set-lily-option sym val Function

Set a global option for the program. Supported options include

midi-debug
If set to true, generate human readable MIDI

This function is useful to call from the command line: lilypond -e "(set-lily-option 'midi-debug #t)"

Invoking LilyPond

Usage:

        lilypond [OPTION... FILE...

To have LilyPond read from stdin, use a dash - for FILE.

Options

-e,--evaluate=code

Evaluates the Scheme code before parsing .ly files. Multiple -e options may be given. They will be evaluated sequentially.

-f,--format=format

Output format for sheet music. Choices are tex (for TeX output), ps (for PostScript), scm (for a Scheme dump), and as (for ASCII-art).

For processing both the TeX and the PostScript output, you must have appropriate environment variables set. For TeX, you have to set MFINPUTS and TEXINPUTS to point to the directory containing LilyPond metafont and .tex files. For processing PostScript output with Ghostscript you have to set GS_FONTPATH to point to the directory containing LilyPond PFA files.

Scripts to do this are included in buildscripts/out/lilypond-profile (for sh shells) and buildscripts/out/lilypond-login (for C-shells), and should normally be run as part of your login process.

-h,--help

Show a summary of usage.

--include, -I=directory

Add directory to the search path for input files.

-i,--init=file

Set init file to file (default: init.ly).

-m,--no-paper

Disable TeX output. If you have a \midi definition midi output will be generated.

-M,--dependencies

Output rules to be included in Makefile.

-o,--output=FILE

Set the default output file to FILE.

-s,--safe

Disallow untrusted \include directives, in-line Scheme evaluation, backslashes in TeX, code.

WARNING: the --safe option has not been reviewed for a long time; do not rely on it for automatic invocation (e.g. over the web). Volunteers are welcome to do a new audit.

-v,--version

Show version information

-V,--verbose

Be verbose: show full paths of all files read, and give timing information.

-w,--warranty

Show the warranty with which GNU LilyPond comes. (It comes with NO WARRANTY!)

When invoked with a filename that has no extension, LilyPond will try to add .ly as an extension first.

When LilyPond processes filename.ly it will produce filename.tex as output (or filename.ps for PostScript output). If filename.ly contains more than one \score block, then LilyPond will output the rest in numbered files, starting with filename-1.tex. Several files can be specified; they will each be processed independently. ⁶

Environment variables

LILYINCLUDE: additional directories for finding lilypond data. The format is like the format of PATH.
LILYPONDPREFIX: This specifies a directory where locale messages and data files will be looked up by default. The directory should contain subdirectories called ly/, ps/, tex/, etc.
LANG: selects the language for the warning messages of LilyPond.

Bug reports

LilyPond development moves quickly, so if you have a problem, it is wise to check if it has been fixed in a newer release. If you think you found a bug, please send in a bugreport including the following information:

a sample input which causes the error. Without this, we can not verify your problem.
(and you will do us a favor if send a small sample file)
which LilyPond version you use. Without this, we can not verify your problem.
A description of the platform you use (i.e., operating system, system libraries, whether you downloaded a binary release)
If necessary, send a description of the bug itself.

You can send the report to bug-lilypond@gnu.org. This is a mailinglist, but you don't have to be subscribed to it. You may also enter the bug in the LilyPond wiki, at http://www.lilypond.org/wiki?LilyPondBugs.

ly2dvi

ly2dvi is a Python script that creates a nicely titled output file from an input file for LaTeX. It can create a DVI or PS file. It works by running LilyPond on the input files, creating a LaTeX wrapper around the output, and running LaTeX (and optionally dvips).

Invoking ly2dvi

        ly2dvi [OPTION]... FILE...

Options

-k,--keep: Keep the temporary directory including LilyPond and ly2dvi output files. The temporary directory is created in the current directory as ly2dvi.dir.
-d,--dependencies: Write makefile dependencies for every input file.
-h,--help: Print usage help.
-I,--include=DIR: Add DIR to LilyPond's include path.
-m,--no-paper: Produce MIDI output only.
--no-lily: Do not run LilyPond; useful for debugging ly2dvi.
-o,--output=FILE: Generate output to FILE. The extension of FILE is ignored.
-P,--postscript: Also generate PostScript output, using dvips.
-s,--set=KEY=VAL: Add KEY= VAL to the settings, overriding those specified in the files. Possible keys: language, latexheaders, latexpackages, latexoptions, papersize, pagenumber, linewidth, orientation, textheight.
-v,--version: Show version information
-V,--verbose: Be verbose
-w,--warranty: Show the warranty with which GNU LilyPond comes. (It comes with NO WARRANTY!)

Titling layout

Ly2dvi extracts the following header fields from the LY files to generate titling:

title: The title of the music. Centered on top of the first page.
subtitle: Subtitle, centered below the title.
poet: Name of the poet, left flushed below the subtitle.
composer: Name of the composer, right flushed below the subtitle.
meter: Meter string, left flushed below the poet.
opus: Name of the opus, right flushed below the composer.
arranger: Name of the arranger, right flushed below the opus.
instrument: Name of the instrument, centered below the arranger
piece: Name of the piece, left flushed below the instrument
head: A text to print in the header of all pages. It is not called header, because \header is a reserved word in LilyPond.
copyright: A text to print in the footer of the first page. Default is to print the standard footer also on the first page.
footer: A text to print in the footer of all but the last page.
tagline: Line to print at the bottom of last page. The default text is "Lily was here, version-number".

Additional parameters

Ly2dvi responds to several parameters specified in a \paper section of the LilyPond file. They can be overridden by supplying a --set command line option.

language: Specify LaTeX language: the babel package will be included. Default: unset.
Read from the \header block.
latexheaders: Specify additional LaTeX headers file.
Normally read from the \header block. Default value: empty
latexpackages: Specify additional LaTeX packages file. This works cumulative, so you can add multiple packages using multiple -s=latexpackages options. Normally read from the \header block. Default value: geometry.
latexoptions: Specify additional options for the LaTeX \documentclass. You can put any valid value here. This was designed to allow ly2dvi to produce output for double-sided paper, with balanced margins and pagenumbers on alternating sides. To achieve this specify twoside
orientation: Set orientation. Choices are portrait or landscape. Is read from the \paper block, if set.
textheight: The vertical extension of the music on the page. It is normally calculated automatically, based on the paper size.
linewidth: The music line width. It is normally read from the \paper block.
papersize: The paper size (as a name, e.g. a4). It is normally read from the \paper block.
pagenumber: If set to no, no page numbers will be printed.

Environment variables

LANG: selects the language for the warning messages of Ly2dvi and LilyPond.

Bugs

Cannot generate TeX or PostScript only. Send bugreports to to bug-lilypond@gnu.org.

Authors

Han-Wen Nienhuys.

Earlier incarnations of ly2dvi were written by Jeffrey B. Reed (Python version), and Jan Arne Fagertun (Bourne shell version)

convert-ly

Convert-ly sequentially applies different conversions to upgrade a Lilypond input file. It uses \version statements in the file to detect the old version number.

Invoking convert-ly

        convert-ly [OPTION]... [FILE]...

-a,--assume-old: If version number cannot be determined, apply all conversions.
-e,--edit: Do an inline edit of the input file. Overrides --output.
-f,--from=from-patchlevel: Set the level to convert from. If this is not set, convert-ly will guess this, on the basis of \version strings in the file.
-o,--output=file: Set the output file to write.
-n,--no-version: Normally, convert-ly adds a \version indicator to the output. Specifying this option suppresses this.
-s, --show-rules: Show all known conversions and exit.
--to=to-patchlevel: Set the goal version of the conversion. It defaults to the latest available version.
-h, --help: Print usage help

Example

Upgrade all lilypond files to 1.3.150:

        convert-ly -e --to=1.3.150 `find -name '*.ly'`

Bugs

Not all language changes are handled. Multiple output options won't work.

Authors

convert-ly is written in Python. It was written by Han-Wen Nienhuys. Report bugs to bug-lilypond@gnu.org

lilypond-book

lilypond-book runs Lilypond on fragments of lilypond in a LaTeX or texinfo file, and includes the results into a document that can be processed with LaTeX, makeinfo or texi2dvi. The result is a text document containing formatted music integrated.

More precisely, if a LaTeX file contains

        \begin{lilypond}
        CONTENTS
        \end{lilypond}

        \lilypond{CONTENTS}

then LilyPond is run on CONTENTS. lilypond-book puts the result back into the latex file. When you run the result through latex, you get a document that mixes text and music. lilypond-book will insert line width and font size definitions before CONTENTS, so the music samples will match the layout of your document.

Very often, if you mix music and text, the music is only a few notes or at most a few bars. This music should be as short as possible and not stretched to be aligned to the right margin. lilypond-book does this automatically if you don't use a \score block in CONTENTS. For example: \lilypond{\context Voice <c' e' g'> }.

You can also use lilypondfile to include another file:

        \lilypondfile{foo.ly}

All three forms can take several options. They are specified in brackets as follows:

       \lilypondfile[options, go, here]{ ..  }
       \begin[options, go, here]{lilypond} .. \end{lilypond}
       \lilypond[options, go,here]{ .. }

In the texinfo version, bitmaps of the music are also generated, so you can make a HTML document with embedded music.

TeXinfo reference

You specify the lilypond code like this:

@lilypond[options, go, here]
 YOUR LILYPOND CODE
@end lilypond
@lilypond[option, go, here]{ YOUR LILYPOND CODE }
@lilypondfile[options, go,here]{filename}

lilypond-book knows the default margins, and a few paper sizes. One of these commands should be in the beginning of the document:

@afourpaper
@afourlatex
@afourwide
@smallbook

@pagesizes are not yet supported.

Examples

Two simple examples. First a complete block:

@lilypond[26pt]
c' d' e' f' g'2 g'
@end lilypond

produces this music:

Then the short version:

@lilypond[11pt]{<c' e' g'>}

and its music:

LaTeX reference

You specify the lilypond code like this:

\begin[option, go, here]{lilypond}
 YOUR LILYPOND CODE
\end{lilypond}

\lilypondfile[options, go,here]{filename}

\lilypond{ YOUR LILYPOND CODE }

Lilypond-book know about the \onecolumn and \twocolumn commands, the geometry package and all the standard paper sizes.

The music will be surrounded by \preLilypondExample and \postLilypondExample. The variables are defined to nothing by default, and the user can redefine them to whatever he wants.

Examples

\begin[26pt]{lilypond}
c' d' e' f' g'2 g'2
\end{lilypond}

produces this music:

Then the short version:

\lilypond[11pt]{<c' e' g'>}

and its music:

Options

eps: This will create the music as eps graphics and include it into the document with the \includegraphics command. It works in LaTeX only.
This enables you to place music examples in the running text (and not in a separate paragraph). To avoid that LaTeX places the music on a line of its own, there should be no empty lines between the normal text and the lilypond environment. For inline music, you probably also need a smaller music font size (eg. 11 pt or 13 pt)
verbatim: CONTENTS is copied into the source enclosed in a verbatim block, followed by any text given with the intertext option, then the actual music is displayed. This option does not work with the short version of the lilypond blocks:
@lilypond{ CONTENTS } and \lilypond{ CONTENTS }
intertext="text": Used in conjunction with verbatim option: this puts text between the code and the music.
filename=FILENAME: Save the lilypond code to FILENAME. By default, a hash value of the code is used.
11pt
13pt
16pt
20pt
26pt
singleline: Produce a single naturally spaced, unjustified line. (i.e.: linewidth = -1).
multiline: The opposite of singleline: justify and break lines.
fragment
nofragment: Override lilypond-book auto detection of what type of code is in the lilypond block, voice contents or complete code.
printfilename: Prints the file name before the music example. Useful in conjunction with \lilypondfile.
relative, relative N: Use relative octave mode. By default, notes are specified relative central C. The optional integer argument specifies how many octaves higher (positive number) or lower (negative number) to place the starting note.

Invocation

When you run lilypond-book it will generate lots of small files that Lilypond will process. So to avoid all the garbage in your source directory, you should either change to a temporary directory, or use the --outdir command line options:

cd out && lilypond-book ../yourfile.tex

lilypond-book --outdir=out yourfile.tex

For latex input, the file to give to latex has extension .latex. TeXinfo input will be written to a file with extension .texi.

If you use --outdir, you should also cd to that directory before running LaTeX or makeinfo. This may seem a little kludgey, but both Latex and makeinfo expect picture files (the music) to be in the current working directory. Moreover, if you do this, LaTeX will not clutter you normal working directory with output files.

If you want to add titling from the \header section of the files, you should add the following to the top of your LaTeX

\input titledefs.tex
\def\preLilypondExample{\def\mustmakelilypondtitle{}}

Command line options

-f, --format=

Specify the document type to process, latex or texi. lilypond-book usually figure this out automatically.

--default-music-fontsize=szpt

Set the fontsize to use for lilypond if no fontsize is given as option.

--force-music-fontsize=szpt

Force all lilypond to use this fontsize, overriding options given to \begin{lilypond}

-I DIR, --include=DIR

Add DIR to the include path.

-M, --dependencies

Write dependencies to filename.dep

--dep-prefix=PREF

prepend PREF before each -M dependency

-n, --no-lily

don't run lilypond, but do generate the .ly files

--no-pictures

don't generate pictures when processing texinfo.

--read-lys

don't write ly files. This way you can do

 lilypond-book file.tely
 convert-ly
 lilypond-book --read-lys

[TODO not a useful option unless you can undump the input file]

--outname=FILE

The name of LaTeX file to output. If this option is not given, the output name is derived from the input name.

--outdir=DIR

place generated files in DIR.

--version

print version information

--help

Print a short help message

lilypond-book is written in python 1.5, so you have to install python.

Bugs

The LaTeX \includeonly{...} command is ignored.

The TeXinfo command pagesize is on the TODO list for Lilypond 1.4, but changing the linewidth in other ways will not give you a straight right margin.

Almost all LaTeX commands that change margins and line widths are ignored.

Since there is no finder's fee which doubles every year, there is no need to wait for the prize money to grow. So send a bug report today if you need this one of these options.

Authors

Han-Wen Nienhuys, http://www.cs.uu.nl/~hanwen Tom Cato Amundsen

Converting to LilyPond format.

midi2ly

Midi2ly translates a MIDI input file to a LilyPond source file. MIDI (Music Instrument Digital Interface) is a standard for digital instruments: it specifies cabling, a serial protocol and a file format.

The MIDI file format is a de facto standard format for exporting music from other programs, so this capability may come in useful when you want to import files from a program that has no converter for its native format.

It is possible to record a MIDI file using a digital keyboard, and then convert it to .ly. However, human players are not rhythmically exact enough to make a MIDI to LY conversion trivial. midi2ly tries to compensate for these timing errors, but is not very good at this. It is therefore not recommended to use midi2ly for human-generated midi files. Correcting the quantization mistakes of the human player takes a lot of time.

Hackers who know about signal processing are invited to write a more robust midi2ly.

Invoking midi2ly

        midi2ly [OPTION]... MIDI-FILE

Options

-b, --no-quantify,: Write exact durations, e.g.: `a4*385/384'.
-D, --debug,: Print lots of debugging stuff.
-h, --help,: Show a summary of usage.
-I, --include=DIR,: Add DIR to search path.
-k, --key=ACC[:MINOR],: Set default key. ACC > 0 sets number of sharps; ACC < 0 sets number of flats. A minor key is indicated by ":1".
-n, --no-silly,: Assume no plets or double dots, assume smallest (reciprocal) duration 16.
-o, --output=FILE,: Set FILE as default output.
-p, --no-plets,: Assume no plets.
-q, --quiet,: Be quiet.
-s, --smallest=N,: Assume no shorter (reciprocal) durations than N.
-v, --verbose,: Be verbose.
-w, --warranty,: Show the warranty with which midi2ly comes. (It comes with NO WARRANTY!)
-x, --no-double-dots,: Assume no double dotted notes.

Report bugs to bug-lilypond@gnu.org.

Written by janneke@gnu.org.

etf2ly

ETF (Enigma Transport Format) is a format used by Coda Music Technology's Finale product. This program will convert part of an ETF file to a ready-to-use LilyPond file.

Invoking etf2ly

Usage:

        etf2ly [OPTION]... ETF-FILE

Convert ETF to LilyPond.

Options

-h,--help: this help
-o,--output=FILE: set output filename to FILE
-v,--version: version information

BUGS

Known: articulation scripts are buggy. Empty measures confuse etf2ly.

Written by hanwen@cs.uu.nl.

Report bugs to bug-lilypond@gnu.org.

abc2ly

ABC is a fairly simple ASCII based format. It is described at http://www.gre.ac.uk/~c.walshaw/abc2mtex/abc.txt.

Invoking abc2ly

        abc2ly [OPTION]... ABC-FILE

Convert ABC to LilyPond.

There is a rudimentary facility for adding lilypond code to the ABC source file. If you say:

        %%LY voices \property Voice.noAutoBeaming=##t

This will cause the text following the keyword "voices" to be inserted into the current voice of the lilypond output file.

Similarly:

        %%LY slyrics more words

will cause the text following the "slyrics" keyword to be inserted into the current line of lyrics.

Options

-h,--help: this help
-o,--output=FILE: set output filename to FILE
-v,--version: version information

BUGS

The ABC standard is not very "standard". For extended features (eg. polyphonic music) different conventions exist.

Multiple tunes in one file cannot be converted.

ABC synchronizes words and notes at the beginning of a line; abc2ly does not.

abc2ly ignores the ABC beaming.

Written by hanwen@cs.uu.nl.

Report bugs to bug-lilypond@gnu.org.

pmx2ly

PMX is a MusiXTeX preprocessor written by Don Simons, see http://icking-music-archive.sunsite.dk/Misc/Music/musixtex/software/pmx/.

Report bugs to bug-lilypond@gnu.org.

Invoking pmx2ly

        pmx2ly [OPTION]... PMX-FILE

Convert PMX to LilyPond.

Options

-h,--help: this help
-o,--output=FILE: set output filename to FILE
-v,--version: version information

Report bugs to bug-lilypond@gnu.org.

Written by hanwen@cs.uu.nl.

musedata2ly

Musedata (http://www.musedata.org/) is an electronic library of classical music scores, currently comprising about 800 composition dating from 1700 to 1825. The music is encoded in so-called Musedata format (http://www.ccarh.org/publications/books/beyondmidi/online/musedata). musedata2ly converts a set of musedata files to one .ly file, and will include a \header field if a .ref file is supplied

Invoking musedata2ly

        musedata2ly [OPTION]... MUSEDATA-FILE

Convert Musedata to LilyPond.

Options

-h,--help: print help
-o,--output=file: set output filename to file
-v,--version: version information
-r,--ref=reffile: read background information from ref-file REFFILE

Report bugs to bug-lilypond@gnu.org.

Written by hanwen@cs.uu.nl.

mup2ly

MUP (Music Publisher) is a shareware music notation program by Arkkra Enterprises. It is also the name of the input format. Mup2ly will convert part of a Mup file to a ready-to-use LilyPond file.

Invoking mup2ly

        mup2ly [OPTION]... MUP-FILE

Convert Mup to LilyPond.

Options

-d,--debug: show what constructs are not converted, but skipped.
D, --define=NAME[=EXP]: define macro NAME with opt expansion EXP
-E,--pre-process: only run the pre-processor
-h,--help: print help
-o,--output=FILE: write output to FILE
-v,--version: version information
-w,--warranty: print warranty and copyright. Mup2ly comes with absolutely NO WARRANTY.

BUGS

Currently, only plain notes (pitches, durations), voices and staffs are converted.

Written by janneke@gnu.org, based on pmx2ly.

Report bugs to bug-lilypond@gnu.org.

Literature

If you need to know more about music notation, here are some interesting titles to read. The source archive includes a more elaborate BibTeX bibliography of over 100 entries in Documentation/bibliography/. It is also available online from the lilypond website.

Banter 1987: Harald Banter, Akkord Lexikon. Schott's Söhne 1987. Mainz, Germany ISBN 3-7957-2095-8
Comprehensive overview of commonly used chords. Suggests (and uses) a unification for all different kinds of chord names.
Gerou 19xx: Tom Gerou and Linda Lusk, Essential Dictionary of Music Notation. Alfred Publishing, Van Nuys CA ISBN 0-88284-768-6
A concise, alphabetically ordered list of typesetting and music (notation) issues which covers most of the normal cases.
Hader 1948,: Karl Hader, Aus der Werkstatt eines Notenstechers. Waldheim-Eberle Verlag, Vienna 1948.
Hader was the chief-engraver of the Waldheim-Eberle music publishers. This beautiful booklet was intended as an introduction for laymen on the art of engraving. It contains a step by step, in-depth explanation of how to cut and stamp music into zinc plates. It also contains a few compactly formulated rules on musical orthography. This book is out of print.
Read 1968: Gardner Read, Music Notation: a Manual of Modern Practice. Taplinger Publishing, New York (2nd edition).
A standard work on music notation.
Ross 1987,: Ted Ross, Teach yourself the art of music engraving and processing. Hansen House, Miami, Florida 1987
This book is about engraving, i.e. professional typesetting. It contains directions on good typesetting, but the sections on reproduction technicalities, how to use pens and history are interesting.
Stone 1980: Kurt Stone, Music Notation in the Twentieth Century Norton, New York 1980.
The most important book on notation in recent years: it describes music notation for modern serious music, but starts out with a thorough overview of existing traditional notation practices.
Wanske 1988,: Helene Wanske, Musiknotation -- Von der Syntax des Notenstichs zum EDV-gesteuerten Notensatz. Schott-Verlag, Mainz 1988. ISBN 3-7957-2886-x
I. A very thorough overview of engraving practices of various craftsmen. It includes detailed specs of characters, dimensions etc. II. a thorough overview of a anonymous (by now antiquated) automated system. EDV means E(lektronischen) D(aten)v(erarbeitung), electronic data processing.

Index

%: Comments
': Pitches
(begin * * * *): Beaming
(end * * * *): Beaming
*: Integers
+: Integers
,: Pitches
-: Integers
.: Durations
/: Integers, Chords mode
/+: Chords mode
<: Music expressions
>: Music expressions
?: Notes
[: Beaming
\!: A piano excerpt
\"!: Dynamics
\<: Dynamics, A piano excerpt
\>: Dynamics
\addlyrics: Automatic syllable durations, Lyrics and chords
\addlyrics and slurs: Lyrics and chords
\aeolian: Key signature
\alternative: Repeat syntax
\arpeggio: Arpeggio
\autochange: A piano excerpt
\bar: Bar lines
\chordmodifiers: Defining pitch names
\chords: Lexical modes
\clef: Clef
\cm: Reals
\context: Creating contexts
\cr: Dynamics
\decr: Dynamics
\dorian: Key signature
\duration: Durations
\f: Dynamics
\fermata: The first real tune
\ff: Dynamics
\fff: Dynamics
\ffff: Dynamics
\fp: Dynamics
\glissando: Glissando
\grace: Grace notes, A piano excerpt
\header: Top level, Lyrics and chords
\header in LaTeX documents: lilypond-book
\in: Reals
\include: File inclusion, The first real tune
\ionian: Key signature
\key: Key signature, The first real tune
\locrian: Key signature
\lydian: Key signature
\lyrics: Lexical modes, Lyrics mode
\maininput: Main input
\major: Key signature
\mark: Rehearsal marks
\mf: Dynamics
\minor: Key signature
\mixolydian: Key signature
\mm,: Reals
\mp: Dynamics
\newpage: Page break
\notes: Lexical modes, Relative
\outputproperty: Tuning per grob
\override: Tuning groups of grobs
\p: Dynamics
\partial: Time signature, Lyrics and chords
\penalty: Line break
\phrygian: Key signature
\pitch: Pitches
\pitchnames: Defining pitch names
\pp: Dynamics
\ppp: Dynamics
\property: Context properties
\property: Lyrics and chords
\pt: Reals
\rc: Dynamics
\rced: Dynamics
\relative: Relative
\repeat: Repeats
\revert: Tuning groups of grobs
\rfz: Dynamics
\script: Articulations
\sequential: Music expressions
\set: Tuning groups of grobs
\sf: Dynamics
\sff: Dynamics
\sfz: Dynamics
\simultaneous: Music expressions, Lyrics and chords
\sp: Dynamics
\spp: Dynamics
\start: Span requests
\stop: Span requests
\tempo: Tempo
\time: Time signature, The first real tune
\times: Tuplets
\translator: Manual staff switches
\transpose: Transpose
\unset: Context properties
\version: Version information
]: Beaming
A2_engraver: Automatic part combining
accessing Scheme: Lyrics and chords
Adjusting slurs: Slurs
afm file: Font metrics
alteration, chromatic: The first real tune
ambiguities: Ambiguities
anacrusis: Time signature, Lyrics and chords
Arpeggio: Arpeggio
arpeggio: A piano excerpt
articulation: The first real tune
articulations: Articulations
Articulations: Articulations
ascii art: ASCIIScript output
ascii script: ASCIIScript output
ASCIIScript output: ASCIIScript output
Assignments: Assignments
assignments: Lyrics and chords
Atom: Molecules
aug: Chords mode
augmentation dot: The first real tune
autobeam: Beaming
automatic beam generation: Beaming
automatic beaming, turning off: Lyrics and chords
Automatic beams: Beaming
automatic lyric durations: Automatic syllable durations
automatic part combining: Automatic part combining
Automatic staff changes: Automatic staff changes
Automatic syllable durations: Automatic syllable durations
automaticMelismata: Automatic syllable durations
automaticMelismata: Lyrics and chords
Bach, Johann Sebastian: The first real tune
bar check: Bar check
Bar check: Bar check
bar check: The first real tune
Bar lines: Bar lines
bar numbers: Bar numbers
Bar_engraver: Bar lines
Bar_line_engraver: Bar lines
barCheckNoSynchronize: Bar check
BarLine: Bar lines
BarNumber: Bar numbers
Beam: Tremolo repeats, Beaming
beams, manual: Beaming
beats per minute: Tempo
block comment: Comments, The first real tune
breaking lines: Line break
breaking pages: Page break
BreathingSign: Breath marks
broken arpeggio: Arpeggio
bug reports: Bug reports
bugs: Bug reports
cautionary accidental: Notes
ChoirStaff: Interpretation context
chord modifier: Lyrics and chords
chord names: Printing named chords
ChordNames: Printing named chords
chords: Printing named chords
Chords: Chords
chords: Lyrics and chords
Chords mode: Chords mode
chords, starting with: Default contexts
chromatic alteration: The first real tune
Clef: Clef
combining lyrics and melody: Lyrics and chords
command line options: Invoking LilyPond
comment: The first real tune
comments: Comments
concatenate: Strings
condensing rests: Multi measure rests
context: Lyrics and chords
context definition: Changing context definitions, MIDI block
context selection: Creating contexts
context variables: Lyrics and chords
convert-ly: Version information
crescendo: Dynamics, A piano excerpt
cross staff: Voice follower lines
cross staff voice: A piano excerpt
cross staff voice, automatic: A piano excerpt
currentBarNumber: Bar numbers
Custodes: Custodes
Custos: Custodes
Custos_engraver: Custodes
decrescendo: Dynamics
default-neutral-direction: Beaming
defaultBarType: Bar lines
defining pitch names: Defining pitch names
dim: Chords mode
dimensions: Reals
diminuendo: Dynamics
direct PostScript output: PostScript output
dotted note: The first real tune
DoublePercentRepeat: Measure repeats
duration: Durations
DVI file: Running LilyPond
DynamicLineSpanner: Dynamics
Dynamics: Dynamics
dynamics: A piano excerpt
DynamicText: Dynamics
easy notation: Easy Notation note heads
embedded tex: Dirty tricks
engraver: Internals, Changing context definitions
Engraver_group_engraver: Defining new contexts
entering notes: Pitches
errors, finding: The first real tune
evaluating Scheme: Lyrics and chords
explicit context: Default contexts
extender: Printing lyrics
extenders, lyric: Lyrics and chords
extra-offset: Tuning per grob
file searching: Invoking LilyPond
Fingering: Articulations
fingering: Articulations
follow voice: Voice follower lines
followVoice: Voice follower lines
font magnification: Font selection
font selection: Font selection
font size: Font Size
font-interface: Font selection
font-style: Font selection
footer: ly2dvi
forte: A piano excerpt
ghostscript: Easy Notation note heads
GhostScript: Running LilyPond
Glissando: Glissando
Grace context: A piano excerpt
Grace music: Grace notes
grace notes: Grace notes, A piano excerpt
Grace_engraver_group: Defining new contexts
graceAlignPosition: Grace notes
grammar: Ambiguities
grob description: Tuning groups of grobs
GUILE: Direct Scheme, Lyrics and chords
Hairpin: Dynamics
Hal Leonard: Easy Notation note heads
header: ly2dvi
Header: Top level
hufnagel clefs: Clef
hyphen: Printing lyrics
hyphens, lyric: Lyrics and chords
identifier: The first real tune
identifier assignment: Lyrics and chords
Identifiers: Identifiers
indent: Paper variables
input mode: Lexical modes
instrument names: MIDI instrument names
integers: Integers
interpretation context: Lyrics and chords
interpreting music: Internals
interscoreline: Paper variables
interscorelinefill: Paper variables
invisible grobs: Invisible grobs
Invoking LilyPond: Invoking LilyPond
Key: Key signature
key signature, setting: The first real tune
keySignature: Key signature
KeySignature: Key signature
Keywords: Keywords
Lexical modes: Lexical modes
lilypond-book and titling: lilypond-book
line breaks: Line break
line comment: Comments, The first real tune
linewidth: Paper variables
LISP: Lyrics and chords
loudness: A piano excerpt
lpr: Running LilyPond
ly2dvi: Top level
ly2dvi: Running LilyPond
lyric extender: Printing lyrics
Lyric hyphen: Printing lyrics
lyric mode: Lyrics mode
Lyrics: Printing lyrics
lyrics: Printing lyrics, Lyrics and chords
lyrics and melody, combining: Lyrics and chords
Lyrics mode: Lyrics mode
Main input: Main input
maj: Chords mode
manual beaming: Lyrics and chords
manual staff switches: Manual staff switches
mark: Rehearsal marks
markup text: Text markup
measure lines: Bar lines
measure numbers: Bar numbers
measure repeats: Measure repeats
measure, partial: Time signature
Medicaea, Editio: Clef
melisma: Printing lyrics
melismata: Lyrics and chords
meter: Time signature
metronome mark: Text markup
metronome marking: Tempo
MIDI: Invoking LilyPond
MIDI block: MIDI block
mode, chords: Lyrics and chords
mode, input: Lexical modes
modifier, chord: Lyrics and chords
Molecule: Molecules
Multi measure rests: Multi measure rests
MultiMeasureRest: Multi measure rests
Music entry: Music entry
music expressions: Music expressions
named modifier: Lyrics and chords
notation context: Lyrics and chords
Note entry: Note entry
note names, Dutch: Pitches
Note specification: Pitches
Note_head_engraver: Defining new contexts
NoteCollision: Polyphony
NoteColumn: Polyphony
NoteHead: Notes
octaves, choosing: The first real tune
options, command line: Invoking LilyPond
ornaments: Grace notes, Articulations
Ornaments: Ornaments
ornaments: A piano excerpt
Output description: Molecules
Output_property_engraver: Tuning per grob
page breaks: Page break
page layout: ly2dvi
Page layout: Page layout
page size: Paper size
Paper block: Paper block
paper size: Paper size
Paper size: Paper size
paper types, engravers, and pre-defined translators: Defining new contexts
Paper variables: Paper variables
papersize: Paper size
parenthesized accidental: Notes
part combiner: Automatic part combining
Partial: Time signature
partial measure: Time signature
Pedals: Pedals
percent repeats: Measure repeats
PercentRepeat: Measure repeats
phrasing: More stanzas
phrasing marks: Phrasing slurs
phrasing slurs: Phrasing slurs
PhrasingSlur: Phrasing slurs
PianoStaff: Piano music
pitch: The first real tune
Pitch names: Pitches
pitch names, defining: Defining pitch names
pitches: Pitches
point, printer's: The first real tune
polyphony: Polyphony
PostScript: Running LilyPond
PostScript output: PostScript output, Other ways to run LilyPond
prebreaking: Internals
preprocessing: Internals
printing chord names: Printing named chords
Printing output: Running LilyPond
properties, unsetting: Context properties
R: Multi measure rests
r: Durations
real numbers: Reals
Rehearsal marks: Rehearsal marks
RehearsalMark: Rehearsal marks
Relative: Relative
relative: The first real tune
relative mode and transposing: A piano excerpt
relative octave specification: Relative
reminder accidental: Notes
repeat bars: Bar lines
repeatCommands: Manual repeat commands
repeatCommands: Bar lines
repeats: Repeats
RepeatSlash: Measure repeats
reporting bugs: Bug reports
Rest: Rests
RestCollision: Polyphony
Rests: Rests
s: Durations
Scheme: Direct Scheme, Lyrics and chords
Scheme output: Scheme output
Scheme, in-line code: Direct Scheme
Score: Top level, Context properties, Interpretation context, Rehearsal marks, Easy Notation note heads
score definition: Top level
Score_engraver: Defining new contexts
Script: Articulations
scripts: Articulations
search path: Invoking LilyPond
sequential music: Music expressions
Sequential music: Music expressions
sequential music: The first real tune
setting context variables: Lyrics and chords
shorten measures: Time signature
Simultaneous music: Music expressions
Skip: Skips
skipTypesetting: Bar check
Slur: Slurs
slurs: Slurs
Sostenuto: Pedals
Sound: Sound
Span requests: Span requests
Staff: Defining new contexts, Interpretation context, Custodes, Hara kiri staffs, Automatic staff changes
Staff notation: Staff notation
staff size setting: The first real tune
staff switch: A piano excerpt
staff switch, automatic: A piano excerpt
staff switch, manual: Manual staff switches
staff switching: Voice follower lines
Staff.instrument: MIDI instrument names
Staff.midiInstrument: MIDI instrument names
Staff_symbol_engraver: Defining new contexts
StaffGroup: Interpretation context
stafflinethickness: Paper variables
staffspace: Paper variables
stanza numbering: More stanzas
starting with chords: Default contexts
Stem: Tuning groups of grobs
stemBoth: A piano excerpt
stemLeftBeamCount: Beaming
stemRightBeamCount: Beaming
StemTremolo: Tremolo repeats
string: Strings
subscript: Articulations
superscript: Articulations
sus: Chords mode
Sustain: Pedals
switches: Invoking LilyPond
syllables, entering: Lyrics and chords
Syntactic details: Syntactic details
Tempo: Tempo
TeX: Other ways to run LilyPond
TeX output: TeX output
text markup: Text markup
Text scripts: Text scripts
Text spanners: Text spanners
textheight: Paper variables
TextScript: Text scripts
TextSpanner: Text spanners
Thread_devnull_engraver: Automatic part combining
Tie: Ties
tie: A piano excerpt
ties: Ties
Time signature: Time signature
time signature, setting: The first real tune
TimeSignature: Time signature
titles: ly2dvi
titling and lilypond-book: lilypond-book
tonic: Lyrics and chords
Top level: Top level
translator definition: Changing context definitions
Transpose: Transpose
transposing: Sound output for transposing instruments
transposing: A piano excerpt
transposition of pitches: Transpose
tremolo beams: Tremolo repeats
tremolo marks: Tremolo subdivisions
tremoloFlags: Tremolo subdivisions
trill: A piano excerpt
triplets: Tuplets, A piano excerpt
tuplet: A piano excerpt
tuplet formatting: Tuplets
TupletBracket: Tuplets
tupletNumberFormatFunction: Tuplets
tuplets: Tuplets
UnaCorda: Pedals
unfolded \repeat: A piano excerpt
upbeat: Time signature
Vaticana, Editio: Clef
Viewing music: Running LilyPond
Voice: Defining new contexts, Context properties, Interpretation context, Text scripts, Text spanners, Polyphony, Ties
Voice.autoBeamSettings: Beaming
Voice.noAutoBeaming: Beaming
Voice_devnull_engraver: Automatic part combining
VoiceFollower: Voice follower lines
VoltaBracket: Manual repeat commands
web site: Top
whichBar: Bar lines
whole rests for a full measure: Multi measure rests
Xdvi: Easy Notation note heads
xdvi: Running LilyPond
|: Bar check, Time signature, The first real tune
~: Ties, A piano excerpt

Function Index

c++-function?: Music_iterator
dir?: Miscellaneous Scheme functions
duration?: Duration
ly-combine-molecule-at-edge: Molecules
ly-find-glyph-by-name: Font metrics
ly-get-default-font: Font metrics
ly-get-grob-property: Grob Scheme functions
ly-get-molecule-extent!: Molecules
ly-get-mus-property: Music
ly-get-spanner-bound: Grob Scheme functions
ly-get-trans-property: Translator
ly-grob?: Grob Scheme functions
ly-gulp-file: Miscellaneous Scheme functions
ly-input-location?: Input location
ly-make-music: Music
ly-music-name: Music
ly-number->string: Miscellaneous Scheme functions
ly-set-grob-property: Grob Scheme functions
ly-set-molecule-extent!: Molecules
ly-set-mus-property: Music
ly-set-trans-property: Translator
ly-version: Miscellaneous Scheme functions
ly-warn: Miscellaneous Scheme functions
make-duration: Duration
make-moment: Moment
make-pitch: Pitch data type
molecule?: Molecules
moment?: Moment
music?: Music
pitch-alteration: Pitch data type
pitch-notename: Pitch data type
pitch-octave: Pitch data type
pitch-semitones: Pitch data type
Pitch::transpose: Pitch data type
set-lily-option: Miscellaneous Scheme functions

Refman appendix

Lyrics mode definition

The definition of lyrics mode is ludicrous, and this will remain so until the authors of LilyPond acquire a deeper understanding of character encoding, or someone else steps up to fix this.

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

Subsequent characters of a word can be any character that is not a digit and not white space. One important consequence of this is that a word can end with `}', which may be confusing. However, LilyPond will issue a warning. Any _ character which appears in an unquoted word is converted to a space. This provides a mechanism for introducing spaces into words without using quotes. Quoted words can also be used in Lyrics mode to specify words that cannot be written with the above rules.

American Chords

\include "english.ly"

scheme = \chords {
  c         % Major triad
  cs:m      % Minor triad
  df:m5-    % Diminished triad
  c:5^3     % Root-fifth chord
  c:4^3     % Suspended fourth triad
  c:5+      % Augmented triad
  c:2^3     % "2" chord
  c:m5-.7-  % Diminished seventh
  c:7+      % Major seventh
  c:7.4^3   % Dominant seventh suspended fourth
  c:5+.7    % Augmented dominant seventh
  c:m5-.7   % "Half" diminished seventh
  c:5-.7    % Dominant seventh flat fifth
  c:5-.7+   % Major seventh flat fifth
  c:m7+     % Minor-major seventh
  c:m7      % Minor seventh
  c:7       % Dominant seventh
  c:6       % Major sixth
  c:m6      % Minor sixth
  c:9^7     % Major triad w/added ninth
  c:6.9^7   % Six/Nine chord
  c:9       % Dominant ninth
  c:7+.9    % Major ninth
  c:m7.9    % Minor ninth
}

\score {
  \notes <
    \context ChordNames \scheme
    \context Staff \transpose c'' \scheme
  >
  \paper {
    \translator {
      \ChordNamesContext
      ChordName \override #'word-space = #1
      ChordName \override #'style = #'american
    }
  }
}

Jazz chords

Similarly, Jazz style chord names are implemented as a variation on American style names:

scheme = \chords {
  % major chords
  c
  c:6		% 6 = major triad with added sixth
  c:maj		% triangle = maj
  c:6.9^7	% 6/9
  c:9^7		% add9

  % minor chords
  c:m		% m = minor triad
  c:m.6		% m6 = minor triad with added sixth
  c:m.7+	% m triangle = minor major seventh chord
  c:3-.6.9^7	% m6/9
  c:m.7		% m7
  c:3-.9	% m9
  c:3-.9^7	% madd9

  % dominant chords
  c:7		% 7 = dominant
  c:7.5+	% +7 = augmented dominant
  c:7.5-	% 7b5 = hard diminished dominant
  c:9		% 7(9)
  c:9-		% 7(b9)
  c:9+		% 7(#9)
  c:13^9.11 	% 7(13)
  c:13-^9.11 	% 7(b13)
  c:13^11	% 7(9,13)
  c:13.9-^11	% 7(b9,13)
  c:13.9+^11	% 7(#9,13)
  c:13-^11	% 7(9,b13)
  c:13-.9-^11	% 7(b9,b13)
  c:13-.9+^11	% 7(#9,b13)

  % half diminished chords
  c:m5-.7		% slashed o = m7b5
  c:9.3-.5-	% o/7(pure 9)

  % diminished chords
  c:m5-.7-	% o = diminished seventh chord
}

\score {
  \notes <
    \context ChordNames \scheme
    \context Staff \transpose c'' \scheme
  >
  \paper {
    \translator {
      \ChordNamesContext
      ChordName \override #'word-space = #1
      ChordName \override #'style = #'jazz
    }
  }
}

MIDI instruments

"acoustic grand"            "contrabass"           "lead 7 (fifths)"
"bright acoustic"           "tremolo strings"      "lead 8 (bass+lead)"
"electric grand"            "pizzicato strings"    "pad 1 (new age)"
"honky-tonk"                "orchestral strings"   "pad 2 (warm)"
"electric piano 1"          "timpani"              "pad 3 (polysynth)"
"electric piano 2"          "string ensemble 1"    "pad 4 (choir)"
"harpsichord"               "string ensemble 2"    "pad 5 (bowed)"
"clav"                      "synthstrings 1"       "pad 6 (metallic)"
"celesta"                   "synthstrings 2"       "pad 7 (halo)"
"glockenspiel"              "choir aahs"           "pad 8 (sweep)"
"music box"                 "voice oohs"           "fx 1 (rain)"
"vibraphone"                "synth voice"          "fx 2 (soundtrack)"
"marimba"                   "orchestra hit"        "fx 3 (crystal)"
"xylophone"                 "trumpet"              "fx 4 (atmosphere)"
"tubular bells"             "trombone"             "fx 5 (brightness)"
"dulcimer"                  "tuba"                 "fx 6 (goblins)"
"drawbar organ"             "muted trumpet"        "fx 7 (echoes)"
"percussive organ"          "french horn"          "fx 8 (sci-fi)"
"rock organ"                "brass section"        "sitar"
"church organ"              "synthbrass 1"         "banjo"
"reed organ"                "synthbrass 2"         "shamisen"
"accordion"                 "soprano sax"          "koto"
"harmonica"                 "alto sax"             "kalimba"
"concertina"                "tenor sax"            "bagpipe"
"acoustic guitar (nylon)"   "baritone sax"         "fiddle"
"acoustic guitar (steel)"   "oboe"                 "shanai"
"electric guitar (jazz)"    "english horn"         "tinkle bell"
"electric guitar (clean)"   "bassoon"              "agogo"
"electric guitar (muted)"   "clarinet"             "steel drums"
"overdriven guitar"         "piccolo"              "woodblock"
"distorted guitar"          "flute"                "taiko drum"
"guitar harmonics"          "recorder"             "melodic tom"
"acoustic bass"             "pan flute"            "synth drum"
"electric bass (finger)"    "blown bottle"         "reverse cymbal"
"electric bass (pick)"      "skakuhachi"           "guitar fret noise"
"fretless bass"             "whistle"              "breath noise"
"slap bass 1"               "ocarina"              "seashore"
"slap bass 2"               "lead 1 (square)"      "bird tweet"
"synth bass 1"              "lead 2 (sawtooth)"    "telephone ring"
"synth bass 2"              "lead 3 (calliope)"    "helicopter"
"violin"                    "lead 4 (chiff)"       "applause"
"viola"                     "lead 5 (charang)"     "gunshot"
"cello"                     "lead 6 (voice)"

GNU Free Documentation License

Version 1.1, March 2000

Copyright © 2000 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA  02111-1307, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

PREAMBLE
The purpose of this License is to make a manual, textbook, or other written document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you".
A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License.
The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License.
A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque".
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only.
The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.
VERBATIM COPYING
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
COPYING IN QUANTITY
If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
MODIFICATIONS
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five).
3. State on the Title page the name of the publisher of the Modified Version, as the publisher.
4. Preserve all the copyright notices of the Document.
5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
8. Include an unaltered copy of this License.
9. Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
11. In any section entitled "Acknowledgments" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgments and/or dedications given therein.
12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
13. Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version.
14. Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section.
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.
You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
COMBINING DOCUMENTS
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgments", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements."
COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate.
TRANSLATION
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail.
TERMINATION
You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

  Copyright (C)  year  your name.
  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 the Invariant Sections being list their titles, with the
  Front-Cover Texts being list, and with the Back-Cover Texts being list.
  A copy of the license is included in the section entitled ``GNU
  Free Documentation License''.

If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being list"; likewise for Back-Cover Texts.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.

Footnotes

When we refer to filenames, they are relative to the top directory of the source package.
Note names are available in several languages, but we find the Dutch names quite convenient.
The titling and font size shown may differ, since the titling in this document is not generated by ly2dvi.
Hara kiri, also called Seppuku, is the ritual suicide of the Japanese Samourai warriors.
At some point LilyPond also contained Atom-objects, but they have been replaced by Scheme expressions, making the name outdated.
The status of GUILE is not reset across invocations, so be careful not to change any default settings from within Scheme .

Go back to index of LilyPond.

Please send GNU LilyPond questions and comments to lilypond-user@gnu.org.

Please send comments on these web pages to lilypond@packages.debian.org

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.

This page was built from LilyPond-1.4.12 (stable-branch) by

Anthony Fok <lilypond@packages.debian.org>, Tue Mar 12 01:34:59 2002 HKT.

GNU LilyPond

Welcome to the home of the GNU Music Typesetter

GNU LilyPond

GNU LilyPond -- The music typesetter

Table of Contents

Preface

Tutorial

First steps

Simple legend

Running LilyPond

Windows users

The first real tune

Lyrics and chords

More movements

A piano excerpt

An orchestral score

The full score

Extracting an individual part

Other ways to run LilyPond

Integrating text and music

End of tutorial

Reference Manual

Overview

Note entry

Notes

Pitches

Rests

Skips

Durations

Ties

Tuplets

Defining pitch names

Easy Notation note heads

Staff notation

Key signature

Clef

Time signature

Partial

Unmetered music

Bar lines

Polyphony

Beaming

Automatic beams

Manual beams

Expressive marks

Slurs

Phrasing slurs

Breath marks

Tempo

Text spanners

Ornaments

Articulations

Text scripts

Grace notes

Glissando

Dynamics

Repeats

Repeat syntax

Manual repeat commands

Tremolo repeats

Tremolo subdivisions

Measure repeats

Rhythmic music

Rhythmic staffs

Piano music

Automatic staff changes

Manual staff switches

Pedals

Arpeggio

Voice follower lines

Lyrics

Lyrics mode

Printing lyrics

Automatic syllable durations

More stanzas

Chords

Chords mode

Printing named chords

Writing parts

Rehearsal marks