[icon]

GNU LilyPond

Welcome to the home of the GNU Music Typesetter

Home
Development
WikiWikiWeb
GNU Project
Translations
LilyPond dot org

Documentation
Change Log
Small FAQ
Full FAQ
User manual
Regression Test
To do

Download Source
Stable
Development

Download Binary
RedHat i386
LinuxPPC
Debian Stable
Debian Unstable
Windows Stable
Windows Unstable

Music
Short examples
Longer examples
Mutopia Project
Other URLs

Mailing Lists
Discussion
Help
Bugs
Announcements

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.

Table of Contents

Tutorial

Introduction

LilyPond prints music from a specification that you, the user, supply. You have to give that specification using a language. This chapter is a gentle introduction to that language.

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/.1 We recommend that you experiment with writing Lilypond input yourself, to get a feel for how the program behaves.

Running LilyPond

Before we dive into describing the input language of LilyPond, we first show you through the procedure for getting notes on your screen and out of your printer.

The first step is creating an input file. Using your favorite text-editor, create test.ly containing

\header {
 title = "Test";
}

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

Unix

If you run Unix, proceed as follows: run lilypond on the file, i.e.,

  lilypond test
You will the following on your screen:
GNU LilyPond 1.3.125.
Now processing: `input/tutorial/test.ly'
Parsing...
Interpreting music...[1]
Preprocessing elements...
Calculating column positions... [2]
paper output to test.tex...

Now, run TeX2. The result should resemble this:

This is TeX, Version 3.14159 (Web2C 7.3.1)
(test.tex (/home/hanwen/usr/share/lilypond/tex/lilyponddefs.tex
(/home/hanwen/usr/share/lilypond/tex/lilypond-plaintex.tex
LilyPond Plain TeX settings) (/home/hanwen/usr/src/  ...
(/home/hanwen/usr/share/lilypond/tex/lily-ps-defs.tex) [footer empty]
(/home/hanwen/usr/share/lilypond/tex/fetdefs.tex)) [1] )
Output written on test.dvi (1 page, 3716 bytes).
Transcript written on test.log.
The result of the TeX run is a TeX "DeVice Independent" file (test.dvi).

To view the output, run Xdvi, i.e.

        xdvi test
You should will see this

along with some buttons in a window.

When you're satisfied with the result, you can print it. For printing, you have to generate a postscript file:

        dvips -o test.ps test.dvi
which looks like this:
This is dvips(k) 5.86 Copyright 1999 Radical Eye Soft ...
' TeX output 2001.01.27:1806' -> test.ps
<texc.pro><special.pro>. [1]

PostScript is a page description language, similar to PDF. Some printers can understand a postscript file directly, but the cheapers need the intervention of GhostScript, a PostScript emulator that runs on your computer instead of your printer. Most Linux distributions nowadays have GhostScript running "in the background", so any configured printer will act as a PostScript printer. Assuming this, the following command will print the file

        lpr test.ps
If this does not make your printer produce a page of music, then you should look into installing and configuring ghostscript. Refer to GhostScript's website at http://www.ghostscript.com.

There are two different routes: firstly, you can add titling to the output. This is done by a separate program called ly2dvi: this program first calls LilyPond to process the .ly file, and then runs TeX on it to produce a .dvi file with proper margin settings and titling.

        ly2dvi test.ly
After some disk-activity, you should end up with a .dvi file. 6 Secondly, you can generate PostScript directly. This is not very useful currently, but here goes:
      lilypond -f ps test.ly

[treat FAQs here, eg. about env vars.]

Windows

[todo]

The first tune

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 menuet in J. S. Bach's Klavierbüchlein. The file is included in the distribution as menuet.ly.

% lines preceded by a percent are comments which
% are 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 wide for a book
       linewidth = 14.0 \cm;
   }
}

We will analyse the input, line by line.

        % lines preceded by a percent are comments which
        % are ignored by Lilypond.
The percent sign, %, introduces a line comment. If you want to make larger comments, you can use block comments. These are delimited by %{ and %}
        \include "paper16.ly"

By default, LilyPond will use definitions for a staff that is 20 point3 high. We want smaller output (16 point staff height), so we must import the settings for that size, which is done here.
        \score {

A lilypond file combines music with directions for outputting that music. The music is combined with the output directions by putting them into a \score block.
        \notes

This makes LilyPond ready for accepting notes.
        \relative c''

As we will see, pitches are combinations of octave, note name and chromatic alteration. In this scheme, the octave is indicated by using raised quotes (') and "lowered" quotes (commas: ,). The central C is denoted by c'. The C one octave higher is c''. One and two octaves below the central C is denoted by c and c, respectively.

For pitches in a long piece you might have to type many quotes. To remedy this, LilyPond has a "relative" octave entry mode. In this mode, octaves of notes without quotes are chosen such that a note is as close as possible (graphically, on the staff) to the the preceding note. If you add a high-quote an extra octave is added. The 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;

This command changes the time signature of the current piece: a 3/4 sign is printed. This command is also used to generate bar lines in the right spots.
        \key g \major;

This command changes the current key signature to G-major. Although this command comes after the \time command, in the output, the key signature comes before the time signature: LilyPond knows about music typesetting conventions.
        \repeat "volta" 2

This command tells LilyPond that the following piece of music must be played twice. The first argument indicates the type of repeat. In this case, "volta" means that volta brackets are be used for alternatives--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

This is a note with pitch d (determined up to octaves). The relative music was started with a c'', so the real pitch of this note is d''. The 4 designates the duration of the note (it is a quarter note).
        a b

These are notes with pitch a and b. Because their duration is the same as the g, there is no need to enter the duration (You may enter it anyway, e.g. a4 b4)
        d4 g, g |

Three more notes. The | character is a `bar check'. When processing the music, LilyPond will verify that bar checks are found at the start of a measure. This can help you track down errors.

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.

        c8 d e fis

LilyPond guesses were beams can be added to eighth and shorter notes. In this case, a beam over 4 eighths is added.
        c4 d8( )c b a( )b4 c8 b a g |

The next line shows how to make a slur: the beginning and ending note of the slur is marked with an opening and closing parenthesis respectively. In the line shown above, this is done for two slurs. Slur markers (parentheses) are put between the slurred notes.
        a4 [b8 a] [g fis]

Automatic beaming can be overridden by inserting beam marks (brackets). Brackets are put around the notes you want beamed.
        g2.  |

A duration with augmentation dot is notated with the duration number followed by a period.
        }

This ends the sequential music to be repeated. LilyPond will typeset a repeat bar.
        cis'4 b8 cis a4 |

This line shows that Lily will print an accidental if that is needed: 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 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 notename r.

        d2.-\fermata

All articulations have a verbose form, like \fermata. The command \fermata is not part of the core of the language (most of the other discussed elements are), but it is a shorthand for a more complicated description of a fermata. \fermata names that description and is therefore called an identifier.
        }

Here the music ends.

        \paper {
                linewidth = 14.0\cm;
        }

This specifies a conversion from music to notation output. Most of the details of this conversions (font sizes, dimensions, etc.) have been taken care of, but to fit the output in this document, it has to be smaller. 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.4. 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 this5.

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. An assignment starts with a string. (which is unquoted, in this case). Then comes the equal sign. After the equal sign comes the expression you want to store. In this case, you want to put in strings. The information has to be quoted here, because it contains spaces. Each assignment is finished with a semicolon.
        \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 will turn automatic beams off, and use explicit beaming where needed.

        }

This ends the definition of melody. Note that there are no semicolons after assignments at top level.
        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, called \chords. There is a special mode (analogous to \lyrics and \notes mode) where you can give the names of the chords you want, instead of 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, while a minor triad is wanted. 3- modifies 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 a dot.

        d:min es4 c8:min r8

Some modifiers have predefined names, eg. 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.
        \context ChordNames \accompaniment

Normally, the notes that you enter are transformed into note heads. The 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 only exist during a run of LilyPond. Interpretation contexts that are for printing music (as opposed to playing music) are called `notation contexts'.

By default, LilyPond will create a Staff context for you. If you removed 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, not note heads. An interpretation context can also created upon explicit request. The keyword for such a request is \context. It takes two arguments. The first is the name of an interpretation context. The name is a string, it can be quoted with double quotes). The second argument is the music that should be interpreted in this context. For the previous line, we could have written \context Staff \accompaniment, and get the same effect.

        \addlyrics

The lyrics need to 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. (Besides, it looks silly.)

        \context Staff = mel {

This is the argument of \addlyrics. We instantiate a Staff context explicitly: should you chose 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 a different staff as the accompaniment. This is accomplished by giving the melody staff a different name.

        \property Staff.noAutoBeaming = ##t

An interpretation context has variables that tune its behaviour. One of the variables is noAutoBeaming. If set to ##t, which is the boolean value true, LilyPond will not try to put automatic beaming on the current staff.

LilyPond internally uses GUILE, a Scheme-interpreter6 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

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

This ends \simultaneous.
        \midi  { \tempo 4=72;}

This makes the music go to a MIDI file. MIDI is great for checking music you enter. You listen to the MIDI file: if you hear something unexpected, it's probably a typing error. \midi starts an output definition, a declaration that specifies how to output music analogous to \paper { }. 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.
        }

End the score block.

More movements

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, the following file (layout.ly)

  \version "1.3.124";
  \header { title = "Two miniatures";  }

  #(set! point-and-click #t)

  \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"; }
  }
results in something like this7

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, layout.tex and layout-1.tex. They both look like this:

        ...
  \placebox{-5  \outputscale }%
  {  8.7229  \outputscale }%
  {\magfontWXGEomMMBo\char90 }%

  \placebox{-4  \outputscale }%
  { 81.0647  \outputscale }%
        ...

ly2dvi analyses the progress indication that LilyPond spews out, and generates a file called layout_ly1.tex. This file contains formatting instructions for the title and page layout. A fragment might look like

        \geometry{width=540.602362pt,headheight=2mm, ...
        \renewcommand{\@oddfoot}{\parbox{\textwidth}{\mbox{}   ...
        \begin{document}
        \lilypondtitle{foo}%
        \makelilytitle
        \input{ly2dvi.tex}

ly2dvi runs it through LaTeX. LaTeX is a text-formatting system built on top of TeX. It's very popular in the academic world. If LaTeX is successful, this will produce a .dvi file, containing both the titling and notes. ly2dvi completes its task by deleting the two temporary files, leaving only layout.dvi.

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

\version "1.3.124";
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 uses it update the file to the latest lily version.

  \header { title = "Two miniatures";  }
This sets the titling information for the entire file.
        #(set! point-and-click #t)

This is Scheme code. It sets the variable point-and-click to the value true.

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: 8 when you view the file with Xdvi and click on a note using control-mousebutton 19, your editor will jump to the spot where that note was entered.

More information is in in 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 would put it closest to its predecessor. Besides relative, there is also absolute octave specification, and it is turned on by default. 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, either by hand (ie. composing) or by computer, absolute octaves are probably less work.

    \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 a etude-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 third 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' { c8 \stemdown c'8 \stemup }

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 it looks like incomprehensible gibberish to you, then you are right. This example has been doctored to have as many quirks as possible.

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

As you can see, this example features more voices on one staff. To make room for those voices, their notes have to be stemmed in opposite directions. These are the commands to make that happen.

The symbols that are printed, are internally represented by so-called Graphical Objects (or 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.

This statement adds a the setting 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

This statement reverts the old setting. If you do this, the effect of a \stemdown or \stemup is neutralised.

\override and \revert function like a stack: you can push values onto the grob-setting-stack with \override and you pop them with \revert.

LilyPond includes the identifiers \stemUp, \stemDown along with some more often 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 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 an 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 draws an vertical wavy line before the chord, signifying an arpeggio.

   \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. 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
This repeat print the following sequence notes eight times.
\notes \transpose c' {

Transposing can be done with \transpose. It 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 is a no-op, as central C stay 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
The rest of this melody must be in 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.
\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.

[TODO:

* arpeggio, glissando,

* \apply, \outputproperty, \translator {}, \molecule hacking.

* font-size, cadenza. rhythmic staff, multi-stanza.

* Orchestral: demonstrate Hara-Kiri, part combining, part extraction, scores, transposition, instrument names,

]

The end

That's all folks. From here, you can either try fiddling with input files, or you can read the reference manual.

Reference Manual

This document describes GNU LilyPond and its input format. This document has been revised for LilyPond 1.3.125

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 esthetic decisions. All symbols and their placement is generated from a high-level musical description. In other words, LilyPond would be best described by `music compiler' or `music to notation compiler'.

Internally, LilyPond is written in a mixture of Scheme and C++. Most of the algorithms and low-level routines are written in C++, but these low level components are glued together using Scheme data structures. LilyPond is linked to GUILE, GNU's Scheme library for extension.

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. in the same order as your eyes scan sheet music, and in the same order that you hear the notes play.
  • typesetting: in this step, the results of the interpretation, a typesetting specification, is solved.
  • the visible results ("virtual ink") is written to the output file.

These stages, involve data of a specific type: during parsing, Music objects are created. During the interpretation, context is constructed, and with this context af network of graphical objects ("grobs") is created. The 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. This manual is ordered in terms of user tasks. With each concept will be explained to which of the three parts it belongs.

LilyPond input can be classified into three types:

  • musical expressions: a musical expression is some combination of rest, notes, lyrics
  • output definitions: recipes for translating those musical expressions into performances (MIDI) or graphics (eg. PostScript).
  • declarations: by declaring and naming musical expressions, you can enter and edit them in manageable chunks.

Modifying music

FIXME: more verbose titling: music expressions? Repeat? Repeated music? Repeating music expressions?

Apply

Apply allows a Scheme-function to operate directly on the internal representation of music.

        \apply #func music
The function takes two arguments, being a function and an musical argument for that function. The function should return a music expression.

This example replaces the text string of a script. It also shows a dump of the music it processes.

#(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 { c4_"foo" }
}

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

Repeats

In order to specify repeats, use the \repeat keyword. Since repeats look and sound differently when played or printed, there are a few different variants of repeats.

unfolded
Repeated music is fully written (played) out. Useful for MIDI output.
volta
This is the normal notation: Repeats are not written out, but alternative endings (voltas) are printed, left to right.
folded
Alternative endings are written stacked. Which is unfortunately not practical for anything right now.
tremolo
Make tremolo beams.

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

  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 3 { e | c2 d2 | e2 f2 | }
    \alternative { { g4 g g } { a | a a a a | b2. } }
  }
}


As you can see, LilyPond doesn't remember the timing information, nor are slurs or ties repeated. We hope to fix this after 1.4.

It is possible to nest \repeat, although it probably is only meaningful for nested repeats.

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)
 c4 c4
    \property Score.repeatCommands = #'((volta #f))
 c4 c4

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
  }
  \paper {
    linewidth = 40*\staffspace;
  }
}

Tremolo subdivision

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 the last value is used, or the value of the tremoloFlags property if there was no last value.

  c'2:8 c':32

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

Using this mechanism pays off when you entering many tremolos, since the default argument saves a lot of typing.

Note entry

Notes mode

Note mode is introduced by the keyword \notes. In Note mode, words can only contain alphabetic characters. If word is encountered, LilyPond first checks for a notename of word. If no notename is found, then word is treated as a string.

Since combinations of numbers and dots are used for indicating durations, it is not possible to enter real numbers in this mode.

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 c through b, where 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. 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 will be accepted.

LilyPond has predefined sets of notenames 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

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' d' e' f' g' a' b' c''

  cis' dis' eis' fis' gis' ais' bis'

  ces' des' es' fes' ges' as' bes'

  cisis' eisis' gisis' aisis' beses'

  ceses' eses' geses' ases' beses'

Defining pitch names

Note names and chord modifiers can be customised 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 how to do this. Some national note names have been provided, among others: Norwegian, Swedish, German, Italian, Catalan, French, Dutch and English.

Durations

The syntax for an verbose duration specification is

 \duration scmduration

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 note, use identifiers.

c'\longa 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

As you can see, the longa is not printed. To get a longa note head, you have to use a different style of note heads. See [TODO].

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

  a'4. b'4.

You can alter the length of duration by writing `*fraction' after it. This will not affect the appearance of note heads or rests.

Notes

A note specification has the form

  pitch[octavespec][!][?][duration]

LilyPond will determine what accidentals to typeset depending on the key and context, so alteration refer to what note is heard, not to whether accidentals are printed. 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'!

Rests

Rests are entered like notes, with note name `r'. There is also a note name `s', which produces a space of the specified duration.

Skip

  \skip duration ;

Skips the amount of time specified by duration. If no other music is played, a gap will be left for the skipped time with no notes printed. It works in Note Mode or Lyrics Mode. In Note mode, this has the same effect as the spacer rest.

Music notation

Key

  \key pitch type ;

Change the key signature. type should be \major or \minor to get pitch-major or pitch-minor, respectively. The second argument is optional; the default is major keys. The \context argument can also be given as an integer, which tells the number of semitones that should be added to the pitch given in the subsequent \key commands to get the corresponding major key, e.g., \minor is defined as 3. The standard mode names \ionian, \locrian, \aeolian, \mixolydian, \lydian, \phrygian, and \dorian are also defined.

Clef changes

  \clef clefname ;

Short-cut for

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

Supported clef-names include

[todo]

Time signature

  \time numerator/denominator ;

A short-cut for doing

     \property Score.timeSignatureFraction = #'(numerator . denominator)

See the documentation of timeSignatureFraction

Partial

  \partial duration ;

Short cut for

  \property Score.measurePosition = length of duration

See the documentation of measurePosition.

Polyphony

[todo : collisiosn, rest-collisinos, voiceX identifiers, how to which contexts to instantiate.]


\shiftOff
Disable horizontal shifting of note heads that collide.
\shiftOn
Enable note heads that collide with other note heads to be shifted horiztonally. Also \shiftOnn and \shiftOnnn set different shift values.
\stemBoth
Allow stems, beams, and slurs to point either upwards or downwards, decided automatically by LilyPond.
\stemDown
Force stems, beams, and slurs to point down.
\stemUp
Force stems, beams and slurs to point up.

Spanners

Beams

Automatic beams

LilyPond will group flagged notes and generate beams autmatically, where appropriate.

This feature can be disabled by setting the Voice.noAutoBeaming property to true, which you may find necessary for the melody that goes with lyrics, eg. Automatic beaming can easily be overridden for specific cases by specifying explicit beams. This is discussed in the next subsubsection.

A large number of Voice properties are used to decide how to generate beams. Their default values appear in scm/auto-beam.scm. In general, beams can begin anywhere, but their ending location is significant. Beams can end on a beat, or at durations specified by the properties in Voice.autoBeamSettings. To end beams every quarter note, for example, you could set the property (end * * * *) to (make-moment 1 4). To end beams at every three eighth notes you would set it to (make-moment 1 8). The same syntax can be used to specify beam starting points using (begin * * * *), eg:

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

To allow different settings for different time signatures, instead of the first two asterisks * * you can specify a time signature; use (end N M * *) to restrict the definition to `N/M' time. For example, to specify beams ending only for 6/8 time you would use the property (end 6 8 * *).

To allow different endings for notes of different durations, instead of th last two asterisks you can specify a duration; use (end * * N M) to restrict the definition to beams that contain notes of `N/M' duration.

For example, to specify beam endings for beams that contain 32nd notes, you would use (end * * 1 32).

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, so if you want that, specify the begin and end point manually using [ and ]:

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

If you have specific wishes for the number of beams, you can fully control the number of beams through the properties yVoice.stemLeftBeamCount and Voice.stemRightBeamCount.

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

Adjusting beams

FIXME

Slur

Slurs connects chords and try to avoid crossing stems. A slur is started with ( and stopped with ). The starting ( appears to the right of the first note in the slur. The terminal ) appears to the left of the first note in the slur. This makes it possible to put a note in slurs from both sides:

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

Adjusting slurs

Slur attachments

The ending of a slur should whenever possible be attached to a note head. Only in some instances where beams are involved, LilyPond may attach a slur to a stem end. In some cases, you may want to override LilyPond's decision, e.g., to attach the slur to the stem end. This can be done through Voice.Slur's grob-property attachment:

  \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

Similarly, slurs can be attached to note heads even when beams are involved:

  \property Voice.Slur \set #'direction = #1
  \property Voice.Slur \set #'attachment = #'(head . head)
  g''16()g()g()g()d'()d()d()d

If a slur would strike through a stem or beam, LilyPond will move the slur away vertically (upward or downward). In some cases, this may cause ugly slurs that you may want to correct:

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

LilyPond will increase the curvature of a slur trying to stay free of note heads and stems. However, if the curvature would increase too much, the slur will be reverted to its default shape. This decision is based on Voice.Slur's grob-property beautiful value. In some cases, you may find ugly slurs beautiful, and tell LilyPond so by increasing the beautiful value:

[hoe gedefd?? wat betekent beautiful = X?]

\score {
  \notes \context PianoStaff <
    \time 6/4;
    \context Staff=up { s1 * 6/4 }
    \context Staff=down <
      \clef bass;
      \autochange Staff \context Voice
        \notes \relative c {
          d,8( a' d f a d f d a f d )a
        }
    >
  >
  \paper {
    linewidth = -1.;
    \translator {
      \VoiceContext
      Slur \override #'beautiful = #5.0
      Slur \override #'direction = #1
      Stem \override #'direction = #-1
      autoBeamSettings \override #'(end * * * *)
        = #(make-moment 1 2)
    }
    \translator {
      \PianoStaffContext
      VerticalAlignment \override #'threshold = #'(5 . 5)
    }
  }
}

Tie

A tie connects two adjacent note heads of the same pitch. When used with chords, it connects all of 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, a warning message will appear and no ties will be created.

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

[sparseTies]

Tuplets

Tuplets are made out of a music expression by multiplying their 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

[todo: document tupletSpannerDuration]

Text spanner

Ottava

Ottava

[move to trick. Not a supported feature.]

  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"

Span requests

  \spanrequest startstop type

Define a spanning request. The startstop parameter is either -1 (\start) or 1 (\stop) and type is a string that describes what should be started. Supported types are crescendo, decrescendo, beam, slur. [FIXME: many more] This is an internal command. Users should use the shorthands which are defined in the initialization file spanners.ly.

You can attach a (general) span request to a note using

  c'4-\spanrequest \start "slur"
  c'4-\spanrequest \stop "slur"

The slur syntax with parentheses is a shorthand for this.

Ornaments

Articulation

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 and script.scm. 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 above notes, with the name of the corresponding symbol appearing underneath.

Text scripts

FIXME: markup

In addition, it is possible to place arbitrary strings of text or TeX above or below notes by using a string instead of an identifier: c^"text". Fingerings can be placed by simply using digits. All of these note ornaments appear in the printed output but have no effect on the MIDI rendering of the music.

Fingerings

To save typing, fingering instructions (digits 0 to 9 are supported) and single characters shorthands exist for a few common symbols

  \textscript text style

Defines a text to be printed over or under a note. style is a string that may be one of roman, italic, typewriter, bold, Large, large, dynamic or finger.

You can attach a general textscript request using this syntax:

c4-\textscript "6" "finger"
c4-\textscript "foo" "normal"

This is equivalent to c4-6 c4-"foo".

  \script alias

Prints a symbol above or below a note. The argument is a string which points into the script-alias table defined in scm/script.scm. Usually the \script keyword is not used directly. Various helpful identifier definitions appear in script.ly.

For information on how to add scripts, consult scm/script.scm.

Grace notes

  \grace musicexpr

A grace note expression has duration 0; the next real note is assumed to be the main note.

You cannot have the grace note after the main note, in terms of duration, and main notes, but you can typeset the grace notes to the right of the main note using the property graceAlignPosition.

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 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. This behavior can be controlled with the flagStyle property.

\relative c'' {
  \grace c8 c4 \grace { [c16 c16] } c4
  \grace { \property Grace.flagStyle = "" c16 } c4
}


At present, 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 is not robust and generally kludgy. We expect it to change after LilyPond 1.4. Syntax changes might also be implemented.

Glissando

A glissando line can be requested by attaching a \glissando to a note:

  c'' \glissando c'

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

Dynamics

Dynamic marks are specified by 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.

Crescendo and Decrescendo

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 to get several marks during one note, you must use spacer notes.

  c'' \< \! c''   d'' \decr e'' \rced
  < f''1 { s4 \< \! s2 \> \! 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
  }

Bar lines

  \bar bartype;

This is a short-cut for doing

  \property Score.whichBar = bartype

You are encouraged to use \repeat for repetitions. See Repeats, and the documentation of whichBar in (lilypond-internals)LilyPond context properties.

[FIXME]

Breath marks

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

Piano music

Automatic staff changes

[\autochange]

Manual staff switches

  \translator contexttype = name

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

Usually this is used to switch staffs in Piano music, e.g.

  \translator Staff = top Music

Pedals

[todo]

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. LilyPond will connect the arpeggios in both staffs.

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

Follow Thread

[todo: different name, eg. voice line ? ]

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

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

Lyrics

Lyrics mode

Lyrics mode is introduced by the keyword \lyrics. This mode has rules that make it easy to include punctuation and diacritical marks in words: The purpose of Lyrics mode is that you can enter lyrics in TeX format or a standard encoding without needing quotes. The precise definition of this 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. Here are some examples. Not all of these words are printable by TeX.

Ah!             % a word
2B_||_!2B       % not a word because it starts with a digit
``Hello''       % not a word because it starts with `
_ _ _ _         % 4 words, each one a space

Since combinations of numbers and dots are used for indicating durations, you can not enter real numbers in this mode.

Syllables are entered like notes, with pitches replaced by text. For example, Twin-4 kle4 twin-4 kle4 enters four syllables, each with quarter note duration. Note that the hyphen has no special meaning for lyrics, and does not introduce special symbols. See section Lexical modes for a description of what is interpreted as lyrics.

Spaces can be introduced into a lyric either by using quotes (") or by using an underscore without quotes: He_could4 not4. All unquoted underscores are converted to spaces. Printing lyrics is discussed in the next section.

Printing lyrics

Lyric syllables must be interpreted within a Lyrics context for printing them. Here is a full example:

\score {
  <
    \notes \transpose c'' {
      c d e c | c d e c |
      e f g2 | e4 f g2 \bar "|.";
    }
    \context Lyrics \lyrics {
      Va-4 der Ja- cob Va- der Ja- cob
      Slaapt gij nog?2 Slaapt4 gij nog?2
    }
  >
}


You may want a continuous line after the syllables to show melismata. To achieve this effect, add a __ lyric as a separate word after the lyric to be extended. 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 _).

\score {
  <
    \notes \relative c'' {
      a4 () b () c () d | c () d () b () a | c () d () b () a
    }
    \context Lyrics \lyrics {
      foo1 __ | bar2. __ _4 | baz1 __
    }
  >
}


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 which length varies depending on the space between syllables, and which will be centered between the syllables. For example:

\score {
  <
    \notes \transpose c'' {
      c d e c | c d e c |
      e f g2 | e4 f g2 \bar "|.";
    }
    \context Lyrics \lyrics {
      Va4 -- der Ja -- cob | Va -- der Ja -- cob |
      Slaapt gij nog?2 | Slaapt4 gij nog?2
    }
  >
}


Automatic syllable durations

[explain automatic phrasing]

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

  \addlyrics musicexpr1 musicexpr2

This means that both musicexpr1 and musicexpr2 are interpreted, but that every non-command atomic music expression ("every syllable") in musicexpr2 is interpreted using timing of 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 }

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

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


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

Chords

[chords vs. simultaneous music]

Chords mode

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

Since combinations of numbers and dots are used for indicating durations, you can not enter real numbers in this mode. Dashes and carets are used to indicate chord additions and subtractions, so scripts can not be entered in Chord mode.

Entering named chords

Chord names are a way to generate simultaneous music expressions that correspond with traditional chord names. It can only be used in Chord mode (see section Lexical modes).

  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 chord additions, which 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 has two effects: It adds the specified interval and all lower odd numbered intervals to the chord, and it may lower or raise the specified interval. Intervals must be separated by a dot (.).

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- c:4.6.8
  }
}


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. This has the effect of lowering the specified note by an octave so it becomes the lowest note in the chord. If the specified 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
    }
  }


The most interesting application is printing chord names, which is explained in the next subsection.

You should not combine \relative with named chords. [FIXME]

Printing named chords

For displaying printed chord names, use the ChordNames and ChordNameVoice contexts. 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 ChordNamesVoice \scheme
    \context Staff \transpose c'' \scheme
  >
  \paper { linewidth = -1.; }
}

You can make the chord changes stand out more by setting property ChordNames.chordChanges to true. This will only display chord names when there's a change in the chords scheme, but always display the chord name after a line break:

scheme = \chords {
  c1:m \break c:m c:m c:m d
}

\score {
  \notes <
    \context ChordNames \scheme
    \context Staff \transpose c'' \scheme
  >
  \paper{
    linewidth = 40 * \staffspace;
    \translator {
      \ChordNamesContext
      chordChanges = ##t
    }
  }
}

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 added base, 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 ChordNamesVoice \scheme
    \context Staff \scheme
  >
  \paper { linewidth = -1.; }
}

To specify chord inversions, append /<notename>. To specify an added bass note, append /+<notename:

scheme = \chords {
  d1 d/a d/+gis
}

\score {
  \notes <
    \context ChordNames \scheme
    \context Staff \transpose c'' \scheme
  >
  \paper { linewidth = -1.; }
}

The chord names that LilyPond should print are fully customizable. The code to print chord names is written in Scheme. It can be found in scm/chord-name.scm. Chord names are based on Banter style naming, which is unambiguous and has a logical structure. Typical American style chord names are implemented as a variation on Banter names, they can be selected by setting property ChordName.style to american:

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

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

Writing parts

[TODO:

partcombine

rehearsal marks

bar numbering

tranposing midi property.

]

Rehearsal marks

  \mark unsigned;
  \mark string;

Prints a mark over or under the staff.

[TODO: automatic increments]

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.

Multi measure rests

Multi measure rests are entered using `R'. It is specifically meant 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.*2 \property Score.skipBars = ##t R2.*17  R2.*4

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

Page layout

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. The assignment must be terminated by a semicolon.
  • A context definition. See section Context definitions for more information on context definitions.
  • \stylesheet declaration. Its syntax is
            	\stylesheet alist
           

    See font.scm for details of alist.

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. You should use either this or stafflinethickness as a unit for distances you modify.
linewidth
Sets the width of the lines.

If set to a negative value, a single unjustified line is produced.

textheight
Sets the total height of the music on each page. Only used by ly2dvi.
interscoreline
Sets the spacing between the score lines. Defaults to 16 pt.
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. Defaults to 0.
stafflinethickness
Determines the thickness of staff lines, and also acts as a scaling parameter for other line thicknesses.

Font size

The Feta font provides musical symbols at six different sizes. These fonts are 11 point, 13 point, 16 point, 20 point, 23 point, and 26 point. The point size of a font is the height of the five lines in a staff when displayed in the font.

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

Paper size

To change the paper size, you must first set the papersize variable at top level. 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. The new paper size will not take effect if the font is not loaded and selected afterwards.

        papersize = "a4"
        \include "paper16.ly"

        \score {
                ...
                \paper { \paperSixteen }
        }

The file "paper16.ly" will now include a file named a4.ly, which will set the paper variables hsize and vsize (used by 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 barlines. If you want to have a line break where there is no barline, you can force a barline 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 imposes encourages or discourages LilyPond to make a line break at this point.

Warning do not use \penalty directly. It is rather kludgy, and slated for rewriting.

Page break

Page breaks are normally computed by TeX, so they are not under direct control. However, you can insert a commands into the .tex output to instruct TeX where to break pages. For more details, see the example file input/test/between-systems.ly

[or -> Tricks? ]

Sound

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 following list. If the selected string does not exactly match, then LilyPond uses the default piano.

[FIXME: to appendix ]

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

Tempo

  \tempo duration = perminute ;

Used to specify the tempo. For example, \tempo 4 = 76; requests output with 76 quarter notes per minute.

Music entry

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. The octave changing marks ' and , can then 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.

This distance is determined without regarding accidentals: a fisis following a ceses will be put above the ceses.

Entering scales is straightforward in relative mode.

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

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. But 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 notename. To parse the pitch as a notename, 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 or \relative sections in its argument. If you want to use relative within transposed music, you must place an additional \relative inside the \transpose.

Point and click

[todo]

Engravers

Selecting contexts

  \context contexttype [= contextname] musicexpr

Interpret musicexpr within a context of type contexttype. If the context does not exist, it will be created. The new context can optionally be given a name.

Context definitions

A notation contexts is defined by the following information

  1. A name.
  2. The LilyPond modules that do the actual conversion of music to notation. Each module is a so-called engraver .
  3. How these modules should cooperate, i.e. which "cooperation module" should be used. This cooperation module is a special type of engraver.
  4. What other contexts the context can contain,
  5. What properties are defined.

A context definition has this syntax:

  \translator {
                      translatorinit translatormodifierlist
                    }

translatorinit can be an identifier or

  \type typename ;
where typename is one of

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

translatormodifierlist is a list of items where each item is one of

  • \consists engravername ; Add engravername to the list of modules in this context. The order of engravers added with \consists is significant.
  • \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 are put there, and stay there, if a user adds or removes engravers. This command is usually not needed for end-users.

  • \accepts contextname ; Add contextname to the list of context this context can contain. 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.
  • \remove engravername ; Remove a previously added (with \consists) engraver.
  • \name contextname ; This sets name of the context, e.g. Staff, Voice. If the name is not specified, the translator won't do anything.
  • propname = value ; A property assignment.

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

Some pre-defined identifiers can simplify modification of translators. The pre-defined identifiers are:


StaffContext
Default Staff context.
RhythmicStaffContext
Default RhythmicStaff context.
VoiceContext
Default Voice context.
ScoreContext
Default Score context.
HaraKiriStaffContext
Staff context that does not print if it only contains rests. Useful for orchestral scores.11

Using these pre-defined values, you can remove or add items to the translator:

\paper {
  \translator {
    \StaffContext
    \remove Some_engraver;
    \consists Different_engraver;
  }
}

Notation Contexts

Notation contexts are objects that only exist during a run of LilyPond. During the interpretation phase of LilyPond, the Music expression contained in a \score block is interpreted in time order. This is the order in which humans read, play, and write music.

A context is an object that holds the reading state of the expression; it contains information like

  • What notes are playing at this point?
  • What symbols will be printed at this point?
  • In what style will they printed?
  • 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 a Score, StaffGroup, or ChoirStaff context (because these can all contain multiple staffs).

Contexts associated with sheet music output are called notation contexts, those for sound output are called performance contexts.

Contexts are created either manually or automatically. Initially, the top level music expression is interpreted by the top level context (the Score context). When a atomic music expression (i.e. a note, a rest, etc.), a nested set of contexts is created that can process these atomic expressions, as in this example:

\score { \notes { c4 } }

The sequential music, `{ c4 }' is interpreted by Score context. When the note c4 itself is interpreted, a set of contexts is needed that will accept notes. The default for this is a Voice context, contained in a Staff context. Creation of these contexts results in the staff being printed.

You can also create contexts manually, and you probably have to do so if you want to typeset complicated multiple part material. If a `\context name musicexpr' expression is encountered during the interpretation phase, the musicexpr argument will be interpreted with a context of type name. If you specify a name, the specific context with that name is searched.

[type vs id]

If a context of the specified type and name can not be found, a new one is created. For example,

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

Almost all music expressions inherit their interpretation context from their parent. In other words, suppose that the syntax for a music expression is

  \keyword musicexpr1 musicexpr2 ...

When the interpretation of this music expression starts, the context for musicexpr1, musicexpr2, etc. is that of the total expression.

Lastly, you may wonder, why this:

\score {
  \notes \relative c'' {
    c4 d4 e4
  }
}

doesn't result in this:

For the c4, a default Staff (with a contained Voice) context is created. After the c4 ends, no music refers to this default staff, so it would be ended, with the result shown. To prevent this inconvenient behavior, the context to which the sequential music refers is adjusted during the interpretation. So after the c4 ends, the context of the sequential music is also the default Voice context. The d4 gets interpreted in the same context as c4.

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 preset within the \translator block corresponding to the appropriate context. In this case, the syntax is

  propname = value

This assignment happens before interpretation starts, so a \property expression will override any predefined settings.

The property settings are used during the interpretation phase. They are read by the LilyPond modules where interpretation contexts are built of. These modules are called translators. Translators for notation are called engravers, and translators for sound are called performers.

Syntactic details

Top level

This section describes what you may enter at top level.

Score definition

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 no output definition is supplied, the default \paper block will be added.

Score

Paper

Midi

Header

The syntax is

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

A header describes 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, metre, arranger, piece and tagline.

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 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 this 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. Other compound music expressions include
 \repeat expr
 \transpose pitch expr
 \apply func expr
 \context type = id expr
 \times fraction expr

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

However, in some cases, LilyPond will also try to choose contexts, and use the structure of the music expression to do so. This can have undesired effects: for example, LilyPond will create a separate staff for each note if you start a \score with a chord:

  \score {
    \notes <c''4 e''>
    \paper {
      linewidth = -1.;
    }
  }

The solution is to explicitly instantiate the context you desire. In this case this is typically a Voice context

  \score {
    \notes\context Voice <c''4 e''>
    \paper {
      linewidth = -1.;
    }
  }

If you use \context Staff you will get separate stems for each note head, leading to collisions, so don't use that.

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

Semicolons are forbidden after top level assignments, but mandatory in other places. The rules about semicolons and assignments are very confusing, but when LilyPond input evolves more towards Scheme, we hope that this problem will grow smaller.

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 details

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: whereever it is allowed,

  #scheme
evaluates the specified Scheme code. If this is used at toplevel, then the result is discarded. 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).

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 to a real that is the internal representation of dimensions.

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. See Lexical modes for details on unquoted strings; their interpretation varies depending on the situation. Strings can be concatenated with the + operator.

The tokenizer accepts the following commands. They have no grammatical function, hence they can appear anywhere in the input.

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.

Main input

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.

Defining pitch names

A \paper block at top level sets the default paper block. A \midi block at top level works similarly.

Assignments

Identifier assignments may appear at top level. Assignments

Direct scheme

Scheme statements maybe issued to produce interesting side-effects.

Lexical modes

To simplify entering notes, lyrics, and chords, LilyPond has three special input modes on top of 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 expressions

\notes musicexpr
\chords musicexpr
\lyrics  musicexpr.

In each of these cases, these expressions do not add anything to the meaning of their arguments. They are just a way to indicate that the arguments should be parsed in indicated mode. The modes are treated in more detail in the sections Note entry, Lyrics and Chords.

You may nest different input modes.

Ambiguities

The grammar contains a number of ambiguities. We hope to resolve them at some time.

  • The assignment
    foo = bar
    

    can be interpreted as making a string identifier \foo containing "bar", or a music identifier \foo containing the syllable `bar'.

  • The assignment
    foo = -6
    

    can be interpreted as making an integer identifier containing -6, or a Request identifier containing the fingering `6' (with neutral direction).

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

  • (an as yet unidentified ambiguity :-)

Unsorted

[mucho todo]

Translation?

Translation property

[todo: add \set/\override/\revert]

  \property contextname.propname =  value

Sets the propname property of the context contextname to the specified value. All three arguments are strings. Depending on the context, it may be necessary to quote the strings or to leave space on both sides of the dot.

Output properties

These allow you to tweak what is happening in the back-end directly. If you want to control every detail of the output formatting, this is the feature to use. The downside to this is that you need to know exactly how the backend works. Example:

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

This selects all note heads occurring at current staff level, and sets the extra-offset of those heads to (0.5,0.75), shifting them up and right.

Use of this feature is entirely on your own risk: if you use this, the result will depend very heavily on the implementation of the backend, which we change regularly and unscrupulously.

Don't move the finger 2, only text "m.d." ...

#(define (make-text-checker text)
   (lambda (grob) (equal? text (ly-get-elt-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."
  }
  \paper { linewidth = -1.; }
}

Tricks

Manual beam settings

Conventionally, stems and beams extend to the middle staff line. This extension can be controlled through Voice.Stem's grob-property no-stem-extend:

  \grace a'8 a4
  \property Voice.Stem \set #'no-stem-extend = ##t
  \grace g8 g4 [g8 g]

The beam symbol can be tweaked through Voice.Beam's grob-properties height and staff-position, in staff-spaces.

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 = #2
  \property Voice.Beam \set #'height = #-2
  [c'8 c]

The direction of a perfectly centred beams can be controlled through Voice.Beam's grob-property default-neutral-direction

  [b''8 b]
  \property Voice.Beam \set #'default-neutral-direction = #-1
  [b b]

There are several ways to calculate the direction of a beam.

majority
number count of up or down notes
mean
mean center distance of all notes
median
mean centre distance weighted per note

You can spot the differences of these settings from these simple examples:

  [d''8 a]
  \property Voice.Beam \set #'dir-function = #beam-dir-mean
  [d a]
  \property Voice.Beam \set #'dir-function = #beam-dir-median
  [d a]

  \time 3/8;
  [d''8 a a]
  \property Voice.Beam \set #'dir-function = #beam-dir-mean
  [d a a]
  \property Voice.Beam \set #'dir-function = #beam-dir-median
  [d a a]

These beam direction functions are defined in scm/beam.scm. If your favourite algorithm isn't one of these, you can hook up your own.

Engraver hacking

No time signature, no barlines...

\score {
  \notes \relative c'' {
    a b c d
    d c b a
  }
  \paper {
    linewidth = -1.;
    \translator {
      \StaffContext
      whichBar = #""
      \remove "Time_signature_engraver";
    }
  }
}

No staff, no clef, squash pitches

\score {
  \notes { c4 c4 c8 c8 }
  \paper {
    linewidth = -1.;
    \translator {
      \StaffContext
      \remove Staff_symbol_engraver;
      \consists Pitch_squash_engraver;
      \remove Clef_engraver;
    }
  }
}

Part combiner

\score{
  \context Staff = flauti <
    \time 4/4;
    \context Voice=one \partcombine Voice
    \context Thread=one \notes\relative c'' {
      c4 d e f | b,4 d c d | r2 e4 f | c4 d e f |
      c4 r e f | c4 r e f | c4 r a r | a a r a |
      a2 \property Voice.soloADue = ##f a |
    }
    \context Thread=two \notes\relative c'' {
      g4 b d f | r2 c4 d | a c c d | a4. b8 c4 d
      c r e r | r2 s2 | a,4 r a r | a r r a |
      a2 \property Voice.soloADue = ##f a |
    }
  >
  \paper{
    linewidth = 80 * \staffspace;
    \translator{
      \ThreadContext
      \consists Rest_engraver;
    }
    \translator{
      \VoiceContext
      \remove Rest_engraver;
    }
  }
}

Markup text

Metrome hack...

[todo: hack this into C++, use \tempo]

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

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

Apply hacking

music = \notes { c'4 d'4( e'4 f'4 }

#(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))

\score {
  \context Voice {
    \music
    \apply #reverse-music \music
  }
  \paper { linewidth = -1.; }
}

Embedded TeX

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

Embedded PostScript

Arbitrary lines and curves not supported...

[TODO:] Make a direct postscript command?

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

Internals

Conversion stages

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

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

Moment

Moment is a rational number. Since GUILE doesn't support them natively, so we created our own rational data type.

moment? Function

make-moment num den Function
create the rational number num/den.

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 defintion of the "Stem" grob with the setting direction := 1. Of course there are many more ways of customizing Lily output, and since most of them involve Grobs in some form, this section explains some details of how grobs work.

What is a grob?

[TODO: document/explain interfaces]

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 node in that graph. A grob stores references to other grobs, the directed edges in the graph.

The objective of this big graph of grobs, is to specify the notation problem. The solution of this problem is a description of the printout that is in closed form, i.e. but 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, or 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. Whenever 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 (ie. 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.

Often, a grob also is associated with a symbol. However, some grobs do not print any symbols, but take care of grouping objects. For example, there is a separate grob that stacks staffs vertically, so they are not printed in overstrike. The NoteCollision is another example of an abstract grob. It only moves around chords, but doesn't print anything.

A complete list of grob types is found in (lilypond-internals)LilyPond backend

Grobs are created in the "Interpreting music" phase, by objects in LilyPond called engravers. In this phase of the translation, a load of grobs are created, and they are linked into a giant network of objects. This network of grobs forms the "specification" of the print problem. This problem is then solved: configurations, directions, dimensions, line breaks, etc. are calculated. Finally, the printing description in the form of Molecules (Molecules) is extracted from the network. These are then dumped into the output file

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

        \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, for the staccato there are two callbacks: one callback that positions the grob above or below the note head, and one callback 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. From C++, element properties can be accessed using the 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);

In GUILE, LilyPond provides

        ly-get-grob-property GROB SYMBOL
        ly-set-grob-property GROB SYMBOL VALUE

All lookup functions identify undefined properties with end-of-list (ie. '() in Scheme or SCM_EOL in C)

Properties are stored in two ways:

  • mutable properties: element properties that change from object to object. The storage of these are private to a grob. Typically this is used to store lists of pointers to other grobs
  • immutable properties: element 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 values for shared element properties are read from scm/element-description.scm.

There are two ways to manually set grob properties.

You can change immutable grob properties. This is done 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/element-description.scm. This can be undone by

        \property Voice.stem \revert #'direction

If you use this a lot, this gets old quickly. So we also have a shorthand,

        \property Context.GrobType \set #'prop = #VAL

this does a \revert followed by a \override

The second way is \outputproperty. This construct looks like

        \context ContextName \outputproperty pred #sym = #val

In this case, in every grob that satisfies pred, the property assignment sym = val is done. For example

        \outputproperty
                #(lambda (gr) (string? (ly-get-grob-property gr
                        'text)))
                #'extra-offset = #'(-1.0 . 0.0)

This shifts all elements 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.

Items and Spanners

Grobs can also be distinguished in their role in the horizontal spacing. A lot of 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.

Some items need special treatment for line breaking. For example, a clef is normally only printed at the start of a line (ie. 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 is a function taking a direction (-1, 0 or 1) and returns a cons of booleans, signifying wether this grob should be transparent and have no extent.

Grob Scheme functions

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?

Duration

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? d Function
type predicate for 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 7, with 0 corresponding to C and 7 corresponding to B. The shift is zero for a natural, negative to add flats, or positive to add sharps.

pitch-octave p Function
extract the octave from pitch p.

pitch-notename Function
extract the note name from pitch p.

pitch-alteration Function
extract the alteration from pitch p.

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

Engraver

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

Music_iterator

This data-type is a direct hook into some C++ constructor functions. It is not yet user-serviceable.

c++-function? Function
type predicate for c++-function.

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.

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:12. A molecule is an object that combines dimension information (how large is this glyph ?) with what-to-print-where.

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 onto the output file.

(refer to the C++ code for more details). All visible, i.e. non-transparant, 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.

[insert example of write your own.]

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. The unit is global staff space. is the

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

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 .afm files 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 a afm file.

Miscellaneous Scheme functions

ly-input-location? Function
type predicate

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 file named name, and return its contents in a string. This uses the lilypond search path.

dir? Function
type predicate. A direction is a -1, 0 or 1.

ly-number->string num Function
converts num without generating many decimals. It leaves a space at the end.

Invoking LilyPond

        lilypond [OPTION]... [MUDELA-FILE]...

Command Options

-f,--format=
Output format for sheet music. Choices are tex (for TeX output), ps (for PostScript) and scm (for a Scheme dump)
-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, it will do the midi output only.
-M,--dependencies
Output rules to be included in Makefile.
-o,--output=FILE
Set the default output file to FILE.
-Q,--find-old-relative
show all changes needed to convert a file to relative octave syntax.
-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.

-T,--no-timestamps
don't timestamp the output
-t,--test
Switch on any experimental features. Not for general public use.
-v,--version
Show version information
-V,--verbose
Be verbose
-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 adding `.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. 13

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-gnu-music@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://appel.lilypond.org/wiki?LilyPondBugs.

ly2dvi

ly2dvi is a Python script which creates input file for LaTeX, based on information from the output files from LilyPond. The script handles multiple files. If a LilyPond file name is specified LilyPond is run to make an output (TeX) file.

One or more LaTeX files are created, based on information found in the output (TeX) files, and latex is finally run to create one or more DVI files.

The majority of this utility came from a bourne script written by Jan Arne Fagertun name ly2dvi.

Invoking ly2dvi

        ly2dvi [options] inputfile[.ly] [....]

Options

-D,--debug
Set debug mode. There are two levels - in level one some debug info is written, in level two the command set -x is run, which echoes every command in the ly2dvi script.
-F,--headers=
Name of additional LaTeX headers file. This is included in the tex file at the end of the headers, last line before \begin{document}
-H,--Heigth=
Set paper heigth (points). Used together with width and LaTeX name of papersize in case of papersize unknown to ly2dvi.
-K,--keeplilypond
Keep LilyPond output after the run.
-L,--landscape
Set landscape orientation - portrait is the default. Use together with dvips -t landscape if you run dvips separately.
-N,--nonumber
Switch off page numbering.
-O,--orientation=
Set orientation landscape - obsolete, use -L instead.
-P,--postscript
In addition to the DVI file, also Generate a postsript file.
-W,--Width=
Set paper width (points). Used together with heigth and LaTeX name of papersize in case of papersize unknown to ly2dvi.
-d,--dependencies
Tell LilyPond to make dependencies file.
-h,--help
Print help.
-k,--keeply2dvi
Keep the LaTeX file after the run.
-l,--language=
Specify LaTeX language. (-l norsk produces \usepackage[norsk]{babel}).
-o,--output=
Set output directory.
-p,--papersize=
Specify papersize. (-p a4 produces \usepackage[a4paper]{article})
-s,--separate
Normally all output files are included into one LaTeX file. With this switch all files are run separately, to produce one DVI file for each.

Features

Ly2dvi responds to several parameters specified in the LilyPond file. They are overridden by corresponding command line options.

language="";
Specify LaTeX language
latexheaders="";
Specify additional LaTeX headers file
orientation="";
Set orientation.
paperlinewidth="";
Specify the width (pt, mm or cm) of the printed lines.
papersize="";
Specify name of papersize.

Environment

LILYPONDPREFIX
Sets the root directory of the LilyPond installation
LILYINCLUDE
Additional directories for input files.
TMP
Temporary directory name. Default is /tmp

Files

titledefs.tex is inspected for definitions used to extract additional text definitions from the LilyPond file. In the current version the following are defined:

title
The title of the music. Centered on top of the first page.
subtitle
Subtitle, centered below the title.
poet
Name of the poet, leftflushed below the below subtitle.
composer
Name of the composer, rightflushed below the subtitle.
metre
Meter string, leftflushed below the below poet.
opus
Name of the opus, rightflushed below the below composer.
arranger
Name of the arranger, rightflushed below the opus.
instrument
Name of the instrument, centered below the arranger
piece
Name of the piece, leftflushed below the instrument

$LILYPONDPREFIX/share/.lilyrc $HOME/.lilyrc ./.lilyrc are files to set up default running conditions. On Windows OS initialization files are named _lilyrc. The file syntax is as follows:

VARIABLE-NAME=VALUE

Where VARIABLE-NAME is the name of the variable documented below and VALUE is either a string, a 1, or a 0. All files are parsed, in the shown sequence. In the current version the following are allowed:

DEBUG=value
This turns off (default) or on the debug capabilities. Possible values are 0 (off) and 1 (on).
DEPENDENCIES=value
This turns off (default) or on the ability to generate a Makefile dependency list. Possible values are 0 (off) and 1 (on).
KEEPLILYPOND=value
This turns off (default) or on the ability to keep the log file associated with the LilyPond job. Possible values are 0 (off) and 1 (on).
KEEPLY2DVI=value
This turns off (default) or on the ability to keep the temporary files that are generated by the ly2dvi job. Possible values are 0 (off) and 1 (on)
LANGUAGE=value
Specify LaTeX language. Possible value is a valid LaTeX language.
LATEXHF=value
Specify additional LaTeX headers file. Possible value is a file specification.
LILYINCLUDE=value
Additional directories for input files. Possible value is a delimited directory path list.
LILYPONDPREFIX=value
This defines the LilyPond root directory. Possible value is a valid directory specification to the LilyPond distribution location.
NONUMBER=value
This turns off (default) or on the page numbering capability. Possible values are 0 (page numbering enabled) and 1 (page numbering disabled).
ORIENTATION=value
This sets the image orientation. Possible values are portrait (default) and landscape.
OUTPUTDIR=value
This defines the directory where the resultant files will be generated. Possible value is a valid directory specification. Default is the current working directory.
PAPERSIZE=value
This defines the papersize the image will be sized to fit. Possible values are a0, a1, a2, a3, a4 (default), a5, a6, a7, a8, a9, a10, b0, b1, b2, b3, b4, b5, archA, archB, archC, archD, archE, flsa, flse, halfletter, ledger, legal, letter, or note.
PHEIGHT=value
Specify paperheight (points - an inch is 72.27, a cm is 28.453 points).
POSTSCRIPT=value
This turns off (default) or on the capability of additionally generating a postscript file. Possible values are 0 (off) and 1 (on).
PWIDTH=value
Specify paperwidth (points - an inch is 72.27, a cm is 28.453 points).
SEPARATE=value
This turns off (default) or on the capability of generating multiple dvi and postscript files from multiple source files. The default is to generate a concatenation of the source files. Possible values are 0 (single file) and 1 (separate files).
TMP=value
This defines the emporary directory. Actually this is not used at the present. Possible value is a valid directory specification that is writable to the user.

Initialization Sequence

The initialization process reads inputs for several sources. Below is a list of priorities for lowest to hightest proirity.

[FIXME: should use ly2dvirc iso lilyrc]

  • Program's defaults
  • Values found in LilyPond output file
  • Environment variables
  • $LILYPONDPREFIX/share/lilypond/.lilyrc
  • $HOME/.lilyrc
  • ./.lilyrc
  • command line options

Bugs

See Bug reports. If you have found a bug, you should send a bugreport.

  • Send a copy of the input which causes the error.
  • Send a description of the platform you use.
  • Send a description of the LilyPond and ly2dvi version you use.
  • Send a description of the bug itself.
  • Send it to bug-gnu-music@gnu.org (you don't have to subscribe to this mailinglist).

Remarks

Many papersizes are now supported. Information on other sizes (LaTeX names, horizontal and vertical sizes) should be mailed to the author or to the mailing list.

Supported papersizes are:

a0, a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, archA, archB, archC, archD, archE, b0, b1, b2, b3, b4, b5, flsa, flse, halfletter, ledger, legal, letter, note

Authors

Python Version author: Jeffrey B. Reed, http://home.austin.rr.com/jbr/jeff/lilypond/

Original bourne shell version author: Jan Arne Fagertun, http://www.termo.unit.no/mtf/people/janaf/

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 [options] [files]
--output
The output file to write.
--edit
Do an inline edit of the input file. override --output
--show-rules
shows all known conversions, and exit
--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
--to=TO_PATCHLEVEL
Set the goal version of the conversion. It defaults to the latest available version.

Not all language changes are handled. Multiple output options won't work.

convert-ly is written in Python. It was written by Han-Wen Nienhuys.

Converting to LilyPond format.

midi2ly

Midi2ly translates a MIDI input file to a LilyPond source file. Midi2ly is part of the GNU LilyPond music typesetting package.

Human players usually are rhythmically not very exact when they record MIDI files. midi2ly tries to compensate for these 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 [options] 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.

etf2ly

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

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.

Report bugs to bug-gnu-music@gnu.org

Written by Han-Wen Nienhuys

[descibe abc2ly, pmx2ly, etf2ly, musedata2ly here]

Literature

If you need to know more about music notation, here are some interesting titles to read

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

gerou96
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 with a rather simplistic attitude but in most cases "good-enough" answers.

[graag zonder neertrappen.]

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

read-notation,
Gardner Read, Music Notation: a Manual of Modern Practice. Taplinger Publishing, New York (2nd edition).

This is as close to the "standard" reference work for music notation issues as one is likely to get.

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

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

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

Function Index

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.

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

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

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

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

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

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

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

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

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

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

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

  1. When we refer to filenames, they are relative to the top directory of the source package.

  2. TeX is a text-typesetting system that is especially suited for typesetting mathematics

  3. A point is the standard measure of length for printing; one point is 1/72.27 inch. [TODO: mm vs. pt]

  4. The author would welcome information about the origin of this song.

  5. The titling and font size shown may differ, since the titling in this document is not generated by ly2dvi.

  6. Scheme is a language from the LISP family. You can learn more about Scheme at http://www.scheme.org.

  7. The titling in this manual was not generated by ly2dvi, so details will differ.

  8. This feature is presently only available on X-windows using patched versions of Xdvi and emacs

  9. If you're using a patched xdvik, the command is control-mousebutton-2

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

  11. Harakiri, also called Seppuku, is the ritual suicide of the Japanese Samourai warriors.

  12. At some point LilyPond also contained Atom-objects, but they have been replaced by Scheme expressions, making the name outdated.

  13. 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 gnu-music-discuss@gnu.org.

Please send comments on these web pages to (address unknown)

Copyright (c) 1997, 1998, 1999, 2000 Han-Wen Nienhuys and Jan Nieuwenhuizen.

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

<(address unknown)>, Mon Feb 26 13:36:09 2001 CET.