This document is written in Yodl and should foremost produce nice LaTeX output. In other formats, such as html, some things will look a bit different, while other things will be simply left out. Therefore, the authoritive version of this document is the PostScript version, produced via LaTeX. As you know, no gifs due to patent problems, but the PNG images should be viewable with any current browser .
LilyPond is a program that can print music from a specification that you, the user, supply. Using LilyPond may be a bit quaint in the beginning, because you have to give that specification using a language. This document is a gentle introduction to that language, which is called Mudela, an abbreviation for Music Definition Language.
We will demonstrate the working of Mudela by presenting examples of input alongside with the resulting output. We will comment on these examples using English terms for notation, so if you are not familiar with these terms, you should consult the glossary that is distributed with LilyPond: it contains a list of musical terms along with explanations and translations in some other languages.
To demonstrate what LilyPond input looks like, we start off with a full fledged, yet simple, example. It is a convoluted version of one of the menuets in J. S. Bach's Clavierbuchlein.
Before we will discuss the contents of the above, it would be best if
you would try to enter and save this text with a text editor, compile
it with LilyPond and view the output. Details of this procedure may
vary from system to system. On a Unix system, you should enter the
input in a file ending in .ly, such as menuet.ly. To
create the output, one would issue ly2dvi menuet
.
ly2dvi is a little program that does the job of calling the LilyPond and TeX and adjusting page margins.
If all goes well, this will create the output file menuet.dvi.
To view this output, issue the command xdvi menuet
. Now that we
are familiar with the procedure to view the output, we will analyse
the input itself, line by line.
% lines preceded by a percent are comments.The percent sign, `
%
', introduces a line comment. If you want
make larger comments, you can use block comments. These are delimited
by `%{
' and `%}
'
\input "paper16.ly"
By default, LilyPond will use definitions for a staff of 20 point (A point is the standard measure of length for printing. One point is 1/72.27 inch.)
high. If you want smaller output (e.g., 16 point), you have to import
the settings for that size. You can do this by including a file.
\include "file"
is replaced by the contents of file
.
LilyPond will inspect the standard search to look for the requested
file.
\score {A mudela file combines music with directions for outputting that music. The music is combined with the output directions by putting them into a
\score
block.
\notesThis 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 central C is denoted
by c
and c,
respectively.
If you have to indicate the pitches in a long piece that is written in either a high or very low octave, you would have to type very many quotes. To remedy this, LilyPond has a so-called ``relative'' octave entry mode. In this mode, notes without quotes are chosen in such an octave that they are the closest to the preceding note. If you add a high-quote an extra octave is added. The lowered quote will substract an extra octave. Because the first note obviously has no predecessor, you have to give the (absolute) pitch of the note to start with.
{ % sequential music followsThe brace indicates that what follows is sequential music, i.e., notes that are to be played and printed after each other. This is in contrast with simultaneous music: notes that are to be played like a chord. You should be careful not to confuse this brace with the one coming after
\score
.
\time 3/4; % set the time signature.This command changes the time signature of the current piece: this prints a 3/4 sign. The 3/4 value is also used to generate bar lines in the right spots.
\key g;This command changes the current key to G-major. Although this command comes after the
\time
command, in the
output, the key comes before the time signature: LilyPond knows about
music typesetting conventions.
\repeat "semi" 2 {This command tells LilyPond that the enclosed piece of music must be played twice.
d4This is a
d
note. The relative music was started with a
c''
, the real pitch of this note is d''
. The 4
designates the duration of the note (it is a quarter note). a bThese are notes with pitch
a'
and b'
. Because their
duration is the same as the g
, there is no need to enter the
duration (It is not illegal to enter it anyway. You would then enter
a8 b8
) d4 g, g |Three more notes: The
|
is a ``barcheck''. When processing the
music, LilyPond will check that barchecks are found at the start of
a bar. This can help you track down notes you forgot to enter.
e'4 c8 d e fisSo far, no notes were chromatically altered. Here is the first one that is:
fis
. Mudela 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.
c4 d8( )c b a( )b4 c8 b a g |The next line shows something new: In mudela, one enters a slur by marking the beginning and ending note of the slur with an opening and closing parenthesis respectively. In the line shown above this is done for two slurs. Note that parentheses (slur markers) are between the notes. As you can see, parentheses do not have to nest.
a4 b8 a g fis g2. |A duration that is to be augmented with a duration dot, is notated with a duration number followed by periods, as many as you want augmentation dots.
}The end of the repeated music. LilyPond will typset 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 will be printed with an accidental, the second one without.
a8-. b-. cis-. d-. e-. fis-. % try some super and subscripts.There is more to music than pitches and rhythms. An important aspect is articulation. You can enter articulation signs either in an abbreviated form, by a dash and the the character for the articulation to use, e.g.
-.
for staccato as shown above.
fis a, r8 cis8Rests are denoted by the special notename
r
. You can also make
an invisible rest by using the special notename s
.
d2.-\fermataAll 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 an abbreviation of a more complicated description of a fermata.
\fermata
names that description and is therefore called an
identifier.
}This ends the sequential music.
\paper { linewidth = 10.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 10 centimeter (approximately 4 inches).
}The last brace ends the
\score
block.
There are a couple of things to note here. The input format tries to capture the meaning of music, and not notation. Therefore the format contains musical concepts like pitches and durations, instead of symbols and positions. Second, the format tries to be context-free: a note will sound the same regardless of the current time signature, the key etc.
The purpose of LilyPond informally is explained by the term `music typesetter'. As you may have figured out by now, this is not a really adequate name: not only does the program print musical symbols, it also tries to make esthetic decisions, and it also generates both the symbols and the decisions from a high-level musical description. In other words, the function of LilyPond would be best described by `music compiler' or `music to notation compiler'.
As you can see, the most interesting part of the input is music itself, in this case the sequence of notes. We will therefore focus on entering music for now. Consequently, when we mean
\score { \notes { XXXX } \paper { } }we will leave out the the repetitive details for now and only print
XXXX
.
The basic building block of music is the note. We lightly touched
notes in the previous example. Here comes the full explanation A note
is made of a pitch and a duration. The pitch of the central C is
written as c'
. This is in line with musicological notation;
there this pitch is transcribed as c1 or c'. A
quarter-note duration is written as 4
. So, to print a quarter
note whose pitch is central C, you enter the following c'4
.
The duration of a note is specified as a number: a whole note is
denoted by 1, a half note by 2, a quarter by 4, and so on. If you
want to augment a duration with a dot, simply affix a period to the
number. You can also print notes longer than a whole. You do this by
using identifiers (\breve
and \longa
):
Here are some random notes to show how it works.
c'\longa c'\breve c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64 c'2. c'8. c'16
The pitch c'
consists of two parts: one part for the note name,
and one for the octave. The letter specifies which note name to use:
note names simply are the letters a
to g
. The number of
apostrophes specifies the octave to use: the central C is denoted by
c'
. (By convention, the A above central C at concert
pitch is the tone that is used to tune instruments. Its frequency is
about 440 Hz.) The C which is an eighth higher (the C in the
``two-line octave'') is denoted by c''
: every octave adds a
quote. A note name without quotes designates the pitch below c'
(the C in the ``small octave''). If you want to go down even further,
commas (sunken apostrophes) should be added, e.g., the C in the
``contra octave'' is expressed as c,,
.
This example demonstrates pitches
![]() |
We have so far ignored chromatically altered pitches. The names `a' to `g' for entering pitches are convenient: they are short, pronounceable and they resemble the words for pitches in normal musical vocabulary.
Enter flats and sharps. In English there is no standard terse word for C sharp or C flat. For this reason, mudela uses a different, non-English convention for entering altered pitches: a note is made sharp by adding the suffix `--is' to its name, and flat by adding the suffix `--es'. For a double sharp another `--is' suffix is added, for flats another `--es' suffix. (Variations on this convention are used in a number of germanic languages, notably Dutch, German, Swedish, and Norwegian.) The names for the alterations of C are given in Table 3.3.
English | LilyPond |
c double flat | ceses |
c flat | ces |
c natural | c |
c sharp | cis |
c double sharp | cisis |
Throughout this document we will continue to use these names. (
Mudela defaults to Dutch notenames. To make (Dutch) pronunciation
easier, the a-flat and e-flat are contracted to as
and
es
. Similarly, the a double flat and e double flat are
contracted to ases
and eses
. For consistency, the dutch
names also include aes
, aeses
, ees
and
eeses
)
If you are not comfortable with these names, you can make your own.
Note names for different languages are included with the example
initialisation files, amongst others English (C sharp is abbreviated
to cs
), Italian, Swedish and Norwegian. If you want to use
these names, issue \include "LANGUAGE.ly"
where you could
substitute italiano
, deutsch
etc. for LANGUAGE. You
should include these files at toplevel, i.e., before opening a
\score
block.
The previous examples all notes that were to be played sequentially, one note following the other. You can also use LilyPond to typeset chords. You do this by expressing in mudela simultaneous music, i.e., notes that are to be played concurrently.
>
) and smaller-than (<
) signs instead. For example, a
D-major chord is expressed as
![]() |
Chords can be entered in the music in the same places that notes can. As an example we give a snippet of ``Twinkle Twinkle Little Star'' in chords. The chords may seem slightly unconventional, but they only serve to show how chords work. We've aligned the chords in the input on their starting beat to help you reading it. This layout does not influence the typesetting result in any way.
There is one thing to note, in sequences of chords, the (relative) pitch of a is taken with reference to the first note of the previous chord.
You can nest simultaneous and sequential music in any way you want, e.g.,
![]() |
As you can see, LilyPond has difficulty typesetting this elegantly. To adequately solve this, you have to persuade LilyPond to make separate stems for both sequential music lists. This is a topic that is covered in Section 10.
[Chords and relative mode]
In the previous section we have been talking more about `stacked notes'
rather than `chords'.
If you need to enter a lot of chords that have proper names, you can use
the \chords
mode as an alternative:
![]() |
A more common problem is the typesetting of chord names. LilyPond has
a special kind of staff for this, the ChordNames
staff.
The ChordNames
staff accepts music like a normal staff,
but typesets only the name of each chord:
![]() |
Because the ChordNames staff accepts normal music, it can be transposed, and you may enter it any way you like, either as chords or as notes.
Music can have articulation, dynamics (louder and softer), etc. These aspecs have notation, so LilyPond can print those. We'll start out by explaining how to obtain the smallest grains of nuance: the articulation of a single note. Articulation is entered by writing a dash and the name of the desired articulation mark. You have to add a backslash in front of the name to distinguish it from the name of a note.
Typing a lot of staccato notes in this syntax will get tedious very quickly. Therefore, Mudela has handy abbreviations for articulation marks such as staccato and tenuto. They are shown in the following example:
Text and digits for fingering can be entered in the same manner: add a dash and the text or digit to be printed:
Dynamic markings are another way to add a nuance to a note. They are entered by adding the name for the dynamic sign after the note. You should not enter a dash between the name and the note. (This is inconsistent. We hope that this will be fixed in a later version of the language.)
Music typesetting does not use fixed symbols only. A lot of symbols are variable: they run from one note to another. In LilyPond terminology, such a symbol is called a spanner. To print a spanner, you have to attach a marker to the note that begins it and to the one that ends it. These are the spanners that are entered like this:
![]() |
The slur is flexible: you can nest slurs, (This is inconsistent when compared to the syntax for articulation hints. This will be fixed some time, we hope.) and you can connect a note with a slur on both the left and the right side:
![]() |
The starting marker for the beam is the opening bracket, the ending marker is the closing bracket. The brackets have to be around the beamed notes. (Strictly speaking, a beam is not a musical concept: beaming doesn't change the meaning of music, it only clarifies the rhythmic structure. One might argue that beams should not be present in a music representation language. Unfortunately, LilyPond is not smart enough to insert beams into music on its own.
LilyPond does have code that guesses what the pattern should look
like, so that you don't have to specify the beaming for complicated
patterns. Alas, the algorithm used is not foolproof
yet: [c8. c32 c32]
will produce incorrect results.)
The brackets themselves have no duration, so they are grammatically equivalent to the barcheck.
~
', in analogy
with TeX's tie (which ties together words with a space), The tie is
similar to the slur: it looks like a slur, but a slur connects whole
chords, whereas the tie connects note heads.
The following example demonstrates the use of ties:
![]() |
Since the tie is thought to be inbetween the notes, it has no duration, and is grammatically equivalent to the barcheck.
\<
, and for the decrescendo
\>
. Both have \!
as the ending marker.
This example shows a trick: by attaching the markings to space rests that run parallel to the whole note, you can have dynamic markings within a note.
It is your job to make sure that each spanner that you start, also ends. If it doesn't, then Bad Things are likely to happen. If you end spanners that are not started, LilyPond will warn you about illegal ending markers.
Music notation constructs with no duration, like clefs and key signatures, can be entered by inserting various commands between the music. The general form of these commands is
\keyword argument argument ... ;
\bar
bartype
bartype
is a string that
describes what kind of bar line to print.
The command `\bar "empty"
' does not create any visible bar
line, but it tells LilyPond to allow a linebreak at that position.
The `\bar
' command prints the specified symbol where you enter
it. If you give a `\bar
' command at the end of a measure then
the specified symbol replaces the automatic bar line.
The \bar
command does not affect metric structure.
\cadenza
togglevalue
\cadenza 1
' turns off the
automatically generated bar lines. They are switched on again with
`\cadenza 0
'. Then a bar line is printed, and LilyPond will act
as if you are again at the start of a measure.
This is useful when typesetting music without a meter (such as an ad libitum cadenza).
\clef
clefname
\key
pitch
type
type
argument is an integer. Useful values are
available as the predefined identifiers \major
and
\minor
. Omitting the second argument gives major keys. The
key of C-minor can thus be specified as `\key es
' or
`\key c \minor
'.
\keysignature
pitchlist
This command changes the current key signature. Unlike the
`\key
' command, this command can produce arbitrary key
signatures, which can be useful for unconventional keys or modes. The
key signature is given in the form of a list of notes. The notes will
be printed in the key signature in the order that they appear on the
list. For example, the key of C-minor can be specified as
`\keysignature bes es as
'. The command `\keysignature fis
es bis
' provides a more exotic example.
\time
numerator
/
denominator
\partial
duration
duration
argument has the same form as the duration of a
note.
The `\partial
' command cannot be used to generate partial
measures in the middle of the music.
Example:
The commands described above do not give music that you could hear, but within the language, they are "Music": they are grammatically equivalent to notes, so they can appear in the same places as notes.
In Section 9 it was explained that there are more ways to notate a simple chord: as a single voice on a single staff or in multiple staffs (and we'll soon see, that you can typeset it as multiple voices on a staff). Obviously the concept of staff is not really something musical. But what is it then?
The most simplistic explanation is: a staff is a graphic peculiarity of the notation system. In other words, a staff is a picture of five lines on which one can print note heads. We will call this view on the concept of staff `staff symbol' from now on.
But there is more to a staff than the symbol. A staff contains---besides a staff symbol--- more components:
As you can see, you can still make out the general form of the melody and the rhythm that is to be played, but the notation is difficult to read. Moreover, the musical information is not complete. The stress pattern in the notes can't be deduced from this output. For this, we need a time signature:
Technically speaking you can find out where the strong and weak beats are, but it is difficult to find them quickly. Bar lines help you in finding the location of the notes within the measure:
We can remedy part of the difficulties with reading pitches by adding a staff symbol:
This makes the output decidedly easier to read, but you still don't know what the pitches of the notes above are. So this is still not enough. But suppose you see the following notation:
Now you know the pitch of the notes: you look at the start of the line and see a clef, and with this clef, you can determine the notated pitches. You have found the context in which the notation is to be interpreted!
So the context determines the relationship between a piece of music and its notation: you, the reader, use context to deduce music from notation. Because LilyPond writes notation, context works the other way around for LilyPond: with context a piece of music can be converted to notation.
We see that a staff forms context, and that context is needed to
convert between notation and music. In LilyPond we turn around this
reasoning: LilyPond has a notion of notation context, and the staff is
an example of a notation context. In fact, the arguments of the
\context
command (Staff, GrandStaff) were all names of different
contexts. A notation context is a conversion between music and
notation.
We make one final observation before listing the standard notation contexts: a score can contain many staffs and a staff can contain many voices. This suggests that notation contexts are objects that can contain other notation contexts.
The following is a list in alfabetic order of the contexts that are supported by LilyPond. Each notation context is characterised by its name, the notation elements it creates, and the contexts that it can contain.
GrandStaff
context contains Staff
contexts, and it adds a brace to the output at the
left. (The GrandStaff is limited, LilyPond can not do
cross staff beaming and slurring.)
A GrandStaff
context can contain Staff
s. Typically, it
will contain two Staff
s, one treble staff, and one bass
staff. The bar lines of the contained staffs are connected
vertically.
Lyrics
context deals with
typesetting lyrics. This topic will be covered in
Section 11.
Score
context is the toplevel context: no context
can contain a Score
context. The Score
context handles
the administration of time signatures. It also makes sure that
items such as clefs, time signatures, and key-signatures are aligned
in columns across staffs.
The Score
can contain Staff
, StaffGroup
,
Lyrics
, GrandStaff
and RhythmicStaff
contexts.
RhythmicStaff
context is like the staff,
but much simpler: the notes are printed on one line, and pitches are
ignored. RhythmicStaff
can contain Voice
contexts.
Staff
context handles clefs, bar lines, keys,
accidentals. A Staff
context can contain Voice
contexts.
StaffGroup
context contains
Staff
or Lyrics
contexts, and prints a bracket at the
left. The bar lines in the participating staffs are connected.
Voice
context is a context that corresponds to a
voice on a staff. This context handles the conversion of noteheads,
dynamic signs, stems, beams, super- and subscripts, slurs, ties and rests
If you are familiar with structured documents, you might see the analogy of a context with a stylesheet: a stylesheet is neither presentation nor information, but rather a recipe how a specific piece of information should be presented. The big difference with stylesheets is that in music notation the elements provided by context are essential to understanding what is notated.
The notions of ``current clef'' and ``current position within the
measure'' are all properties of notation contexts. Commands like
\clef
and \cadenza
change these properties, and this
explains why they are fundamentally different from musical expressions
like notes and rests.
A notation context is not a primitive element of LilyPond: in Section 14 it will be explained how you can form your own notation contexts.
Now we explain how to typeset music that runs in multiple staffs. Consider the following---unrealistic---example:
In this example the music consists of two notes. The above would sound the same if it were written as a single chord on a single staff, i.e.,
The Mudela construct for multiple staffs reflects the similarity between the two examples: to get multiple staffs in Mudela you enter a chord, with an additional instruction to tell LilyPond that the chord does not represent notes stacked together, but staffs stacked together.
If a piece of music is to be interpreted as a staff, then this can be
expressed with the \context
construct. The following input says
``the quarter note with pitch e should be put on a staff.''
\context Staff e'4The same can be done for the other note, i.e.,
\context Staff g4If you want to stack these staffs, you must create a chord of both:
< \context Staff e'4 \context Staff g4 >
This looks reasonable, but the effect of this input is not what you might expect:
Since there are no names specified for the desired staffs, LilyPond
thinks your wishes are fullfilled by putting the g
on the same
staff as the e
. The correct solution is to label both staffs
with different names, for example trebleStaff
and
bassStaff
. This makes LilyPond distinguish between them, and
create two staffs:
The names that you choose do not matter as long as they are
different. This is almost right, except for the brace at the left and
the clef of the second staff. If you want a brace, then you have to
tell LilyPond that the chord you formed is to be interpreted as a
so-called grand staff. This is also done with the \context
command. The bass clef is made with a clef command:
In the section on notation contexts we explained that a notation
context can have properties that influence the conversion from music
to notation. A simple example of such a property is the clef: the
type of a clef helps determines the vertical position of note heads in
a staff. Some of these properties can be modified by commands such as
\clef
and \time
. But notation contexts can have other
properties, that are settable in
a generic fashion. We will demonstrate this feature by printing
multiple voices on a staff.
Printing more than one voice on a staff is like printing multiple staffs stacked together. This suggests that the template to follow is this:
\context Staff < \context Voice = one ... \context Voice = two ... >On the ellipsis there should be music going from left to right, in other words, notes enclosed in braces. Let us try the following counterpoint:
As you can see the result is not perfect. The notes on the last two beats look like plain chords and not like separate voices. What really happened was that the stems of the upper and lower voices were printed on top of each other.
To remedy this, engravers traditionally make the stems of the lower voice point down, and the stems of the upper up, as shown in Figure 10.
Surely the direction of a single stem is a property of the stem as a
graphical object. But the fact that all of the stems in a voice point
in the same direction is not directly graphical. Since this is a
property shared by all the stems in the voice, this property is a
property of the context Voice
. The context Voice
has an
attribute whose value is the direction to use for stems. You can
change it to `up' by issuing the following phrase:
\property "Voice"."verticalDirection" = "1"
This command should be read as ``change the property called
verticalDirection
within the current Voice
context to the value
-1
.'' For the property verticalDirection
the value 1
means
`up', and -1
means `down'. So, the
proper way to code the polyphonic example is given in
Figure 10.
![]() |
As you can see, this property also controls the directions of slurs.
Other properties can also be set, and they can be within different
contexts. In general, you can set a property by specifying
\property
contexttype
.
propertyname
=
value
. Both contexttype
, propertyname
and value
should be strings.
The effect of a property is pretty much hardwired into the implementation (and thus subject to change), so we will not deal with all the possible properties in detail. Among other characteristics that can be set are the layout of slurs and beams. The initialisation file property.ly and the reference manual contain explanations of all properties.
Since a lyrics can have durations like notes, we consider them to be music too. Entering lyrics in mudela has two aspects. First, you have to enter the text, i.e., the syllables along with their durations. After this, you have to specify how to convert these to graphics.
Lyrics consist of syllables, which are strings together with
durations. For entering lyrics we have to instruct LilyPond that what
we enter are not note names but strings. This instruction is the
keyword \lyrics
. After entering this keyword you can enter a
musical construct---sequential music, simultaneous music, \context
entries, etc.--- but with syllables instead of pitches. For example:
\lyrics { 'got8 me on my knees4, Le-8 lie! }Next comes the conversion to notation. LilyPond can't (yet) figure out that lyrics need different treatment than notes. As a result, the default conversion will try to put the text you entered as note heads onto a staff, and this will fail. This default must be overridden with a
\context
keyword. Printing syllables of text in a line is
done by a context called Lyrics
. You can select this context
with the \context
keyword. Here is a simple example with output:
The result is technically correct, but it needs a melody to make it perfor0mable:
The strings that makes up each syllable in the lyrics block are
passed along to TeX verbatim, so if you are proficient with TeX
you can do various nifty things. Keep in mind that a syllable
either starts with a letter (a character in the range `a
' to
`z
' or `A
' to `Z
'), or it is a string enclosed
double quotes. It ends with either a number for the duration, or a space.
These tricks are demonstrated in the following example:
Back in Section 2 we said we would ignore
toplevel constructions (e.g., \score
) until a later moment.
Now we will look at these constructions.
Mudela allows you to name constructs of the language. This is done by
using an identifier. Generally you can define an
identifier by entering identifierName = ...
where there can be
a variety of things on the ellipsis.
When you refer
to the abbreviated entity, you must precede identifierName
with a backslash, i.e., \identifierName
. For example:
You can also see identifiers in action within the \paper
block:
the value -1.0
is assigned to linewidth
. Within the
\paper
block, identifiers are not used as abbreviation only:
assigning to some identifiers can influence the output: in this case,
the music line is printed at natural width.
Recall the properties of a context, that could be set with
\property
. It is a very general mechanism to tune the output of
the music, that is neatly separated from the real music.
Unfortunately, it is not convenient to type or read, and the precise
effect of a setting property isn't always apparent from its
definition. To remedy this, we can use an identifier to capture the
meaning of a \property
.
Several abbreviations like \stemup
are defined in the standard
initialisation file property.ly. Setting or changing context
properties can have a similar effect as the commands that were
discussed in Section 7. Don't be fooled by the
similarity in appearance between a declared property-setting entry and
a real command like \clef
or \bar
. Real commands are
hardcoded into the language and they have to be terminated by
semicolons.
You get output by combining music with definition a conversion to output. LilyPond currently supports one other conversion besides notation: the conversion from abstract music to sound. You can have LilyPond play the music that you entered. The format that is used for this output is MIDI. The result is not very pretty, but it is useful for prooflistening your files: typing errors stand out when you listen, especially if they involve accidentals.
The only information that you need to enter is the
tempo (Unfortunately, at this time, this the only thing that can be
tuned.). The syntax for the tempo is \tempo
duration
=
beatsperminute
;, for example:
\score { ...music... \midi { \tempo 4 = 76; } }
As was promised, we will now take a dive into the more wizardrous parts of LilyPond: redefining (notation) contexts. We previously explained that a context
This characterization almost automatically explains what the definition of a context should look like:
\paper
block
LilyPond can create notation for a large number of symbols. This code
is split up into basic building blocks. Each building block is called
an engraver, and an engraver generally handles only one notation
construct: the Clef_engraver
takes care of the clefs, the
Time_signature_engraver
takes care of printing time signatures,
etc.
A notation context is formed by a group of engravers. A special class
in LilyPond---the Engraver_group_engraver
---allows engravers to
cooperate in a group, thus forming a notation context. A variant of
this grouping object is the Line_group_engraver_group
, which
puts the output of all the engravers (clefs, bars, etc) into a
compound object, so that these symbols can be treated as a whole.
The following definition shows a simplified Staff context:
\translator { \context "Line_group_engraver_group"; \name Staff ; \consists "Bar_engraver"; \consists "Clef_engraver"; \consists "Key_engraver"; \consists "Local_key_engraver"; \consists "Time_signature_engraver"; \consists "Staff_symbol_engraver"; defaultClef = treble; \accepts "Voice"; }This context, named Staff, puts its graphic objects into a compound object (a so-called ``Line group''). At Staff level, bars, clefs, keys, accidentals, time signatures and the staff symbol are handled. A staff can contain a Voice context. You can also preset properties of contexts: for instance, the clef that is printed upon starting a Staff, is the treble clef.
As a practical example, we will show how to typeset polymetric music,
i.e., music where the meter can differ for each staff. The solution
is not very complicated: normally all timing information (time
signature, rhythmic grouping) is synchronised across each staff. This
is done by having only one administration for timing information: in
the default configuration there is only one Timing_engraver
, in
the Score
context.
All staffs use the information in the Timing_engraver
for
generating bar lines and time signatures. So, we can have different
timing for every staff, by moving the Timing_engraver
into the
Staff context.
You can also declare contexts, and reference them. This is useful in
combination with \remove "..."
: \remove
does the opposite
of \consists
.
The context definitions provided as a default are in the standard initialisation file engraver.ly.
In Section 9, we have shown you how to make multiple staffs, and explained that you have to label every staff (or more precisely: different contexts), to make sure that new ones are created when you need them. In this section, the real power of this mechanism will be unveiled.
By naming other contexts that you create, you can reference other
contexts than the current context from within the music. For example,
from within the music that you enter for staff One
, one could
enter a small piece of music, and send it to staff Two
, e.g.,
The mechanism of context selection can be used to fabricate an Urtext (Urtext is the German word for `original text'. The Urtext edition of a piece of music, is an edition that reflects the original writing of the composer. Such editions are useful for musicologists, and performers that want to perform authentic interpretations. However, for mere mortals, the Urtext can be hard to read. It might not contain fingering and beaming, and typically it is full of footnotes. Moreover, common interpretations may have emerged---after the composer died. For this reason, the music that can be had as Urtext usually is also available in enhanced and edited editions. ) and an edited edition from one source. We will use the first few bars of J. S. Bach's first Cello suite to demonstrate this. The example makes heavy use of space rests; here they are used as a placeholder to attach articulation marks to.
The slurs that you define should be put on the music that is defined
by the \bach
identifier. By labeling a Voice
context, and
directing both the articulation and the notes to that same Voice
context, the articulation is put over the right notes.
One of the things that you can do with music is transposing it.
If you want to transpose a piece of music, then you should prefix it
with the keyword \transpose
along with the pitch (relative to
the central C, i.e., c'
) for the transposition. (the
\context Staff
is to make sure that no separate staffs are created
for the \scale
and \transpose cis' \scale
part.)
We have seen that contexts can be nested. This means that they form a
tree. It is possible to edit this tree: for example, a Voice
context can be taken out of a Staff
context, and put into
another. This has the effect of the voice switching staffs (something
that often happens in keyboard music). The syntax for this operation
with these particular contexts is \translator Staff = newStaffName
.
The effect is analogous to the first example in section
15, but with the \translator
construction it
is possible to split the real music and the commands that determine in
which staff the music is printed. For example:
If you want to switch staffs you are in the middle of a slur or a beam, you should take special precautions. In the paper block, you must tell how far the staffs will be apart:
![]() |
as LilyPond cannot determine the interstaff distance.
The notes in a triplet take 2/3 of their notated duration. The syntax for triplet in LilyPond reflects this. To make a triplet, you enter
![]() |
Since tuplet brackets are printed by the Voice context, a Voice
context must exist before \times
is interpreted. To ensure this,
a context is instantiated explicitly with \context Voice
. You
don't need this, if a Voice context is already instantiated, like in
the following example:
![]() |
Of course, you can also use different ratios, and use beamed notes or rests:
If you make a tuplet of beamed notes, where the beam is as wide as the bracket, the bracket is omitted.
A repeated piece of music can consist of two parts: one part to be repeated, and optionally, a list of alternative endings:
![]() |
The number repeat-count
defines how many times the piece should be
played. You may leave out the \alternative
part. There must not
be more alternative endings than the repeat-count
.
A less intuitive form may be needed for lyrics, when there are
a couple alternatives, but nothing is repeated. The \repeat
command
must be present, but it may specify an empty music list:
![]() |
Please send GNU LilyPond questions and comments to gnu-music-discuss@gnu.org.
Please send comments on these web pages to
(address unknown),
send other FSF & GNU inquiries and questions to
Copyright (c) 1997, 1998, 1999 Han-Wen Nienhuys and Jan Nieuwenhuizen.
Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.