This document is not up to date. All rendered examples of course are current, but the rest probably isn't. Adjusting the tutorial was considered more important than writing the reference manual. We apologize for the inconvenience.
This document describes the the GNU LilyPond input format, which is an effective language for defining music. We call this language (rather arrogantly) The Musical Definition Language or Mudela, for short. (If anybody comes up with a better name, we'd gladly take this. Gourlay already uses Musical Description Language, G-Sharp Score Definition Language. ISO standard 10743 defines a Standard Music Description Language. We're not being original here.)
The first aim of Mudela is to define a piece of music, being complete from both from a musical typesetting, as from a musical performing point of view.
The Musical Definition Language (Mudela), has a logical structure, making use of identifiers, that allows for flexible input, and definition reuse. See the documentation file MANIFESTO, included with the LilyPond sources for reasons and design considerations.
The below is included for explanatory purposes only (i.e., for a complete and up-to-date definition, see lily/parser.yy and lily/lexer.ll).
As a related note, you should take a look at the examples and the init files, as this document does not cover every aspect of Mudela yet, and may be out of date. (Ok, I am being pessimistic here. This just is a disclaimer. Docs usually are written after the program itself.) This document intends to give an idea of how it works. It is not a guide on how to use it.
The de-facto extension of Mudela is .ly. Files may be included by
entering \include
at the start of a line:
\include "a_file.ly"
Line comments are introduced by a
%
.
Block comments are delimited
by
%{
and
%}
.
They do not nest.
Occasionally, small changes in syntax across different versions of Mudela might give syntax errors. To warn you about possible incompatibilities, you can specify the Mudela version for which the inputfile was written,
\version "0.0.50";
A Python-script which tries to convert to newer versions (convert-mudela) is included in the LilyPond distribution.
Keywords are preceded by a backslash: \
. They contain
alphabetic characters only.
Mudela uses the brace, `{
' and `}
' for most hierarchical
structures. For chords the <
and the >
are used as
nesting braces.
"I am a string" -1.2e3 % a real 12 % an int
When assigning identifiers you use
string = ...
If you reuse identifiers, then the previous contents will be thrown away after the right hand is evaluated, e.g.
bla = \melodic { \bla }is legal
When using identifiers they have to be escaped:
oboe = \melodic { ... } \score{ \melodic { \oboe }}
The left-hand part of the assignment is really a string, so
"Foo bar 4 2 " = \melodic { .. }
is also a valid assignment (but you would have trouble referencing to it)
The general structure consists of declarations:
IDENTIFIER = \TYPE{ <type specific data> }and instantiations:
\TYPE{ <type specific data> }
(Currently, \score
is the only type that can be instantiated
at top level.)
Most instantiations that use an IDENTIFIER are specified as follows:
\TYPE{ \IDENTIFIER [...] }
Some exceptions on this rule have been made to prevent inputting Mudela becoming tedious
To simplify different aspects of music definition (entering the notes and manipulating them) Mudela has a number of different input "modes":
At the start of parsing, Mudela assumes normal mode. In Normal mode, a word is looked up in the following order:
word
"string"
\word
\melodic
. In Note mode, a word is looked up in the following
order:
word
"string"
\word
In Note mode a word is considered to have alphabetic characters only,
so the underscore (_) is invalid. If you accidently mistype a
notename, the parser will assume that you are entering a string (and
it will most likely complain that you should be in \lyric
mode to
do lyrics)
\lyric
. Because of the various control characters that can
appear in lyrics, e.g., foreign language accents, the inputting a
string containing these has been made very easy.
In Lyrics mode, a word is looked up in the following order:
word
"string"
\word
In Lyric mode every sequence of non-digit and non-white characters starting with an alphabetic character or the _ is considered a word.
a&@&@&TSI|{[ % a word 1THtrhortho % not a "word" Leise Fl\"u\ss{}teren meine Sapfe % 4 words _ _ _ _ % 4 words: 4 spaces
These modes are of a lexical nature. Normal and Note mode largely
resemble each other, save the possibility of entering Reals,
meaning of _
and the resolution of words
Durations are entered as their reciprocal values
![]() |
Notice that you only have to specify the duration when it changes: Lily assumes a note has the same duration as the previous one.
Now we can already write a little tune
![]() |
As you'll probably have guessed,
the vertical bar |
may be used to mark
measures.
In the scale shown above
we left-out the last c note of the next octave.
Postfixing the pitch with a quote '
produces a note by one octave higher
![]() |
Postfixing the pitch with a comma, ,
produces a note by one octave lower
![]() |
A tie connects two adjacent note heads
![]() |
Whereas a slur rather connects `chords', and tries to avoid crossing stems
![]() |
And of course, such a (legato) slur can span several notes
![]() |
A beam is
![]() |
Here's a beamed triplet
![]() |
a triplet without a beam
![]() |
and a combination
![]() |
Abbreviations
![]() |
![]() |
Lily has predefined sets of notenames for various languages (These are Dutch, English, German, Italian and Swedish. Simply include the language specific init file language.ly.). The default set are the ones we like best are the Dutch notenames.
A sharp is formed by adding is
![]() |
and a flat is formed by adding es
![]() |
With the obvious names for double sharps
and double flats
There are two special `notenames', the rest
![]() |
and the space
![]() |
![]() |
and a clef-change
![]() |
![]() |
![]() |
Note how Mudela allows you to
convey a musical message and doesn't force you to produce a list of typesetting commands.
If the music has a cis
, you type a cis
.
Depending on the key and context of the note
Lily will determine what accidentals to typeset.
A reminder accidental can be forced by
using an exclamation mark !
on a pitch a reminder accidental
![]() |
Here's a simple chord
![]() |
here are a few
![]() |
and similarly voices
A Mudela file needs some red tape
Lyrics are entered like notes, with pitches substituted by text.
All syllables are entered separately, separated by whitespace
Twin-4 kle4 twin-4 kle4 ...
Two syllables or words that compose a single duration entry are bound together using an underscore
He_could4 not4
![]() |
The computer savy user may be interested in a more formal specification. We can capture what have learned about forming sentences in Mudela in a context-free grammar.
Music | : Note |
| Rest |
|
| { MusicList } |
|
| < MusicList > |
|
| Command |
|
| \type string = string Music |
|
; |
|
MusicList | : empty |
| MusicList Music |
|
; |
In mathematics you can form expressions by combining expressions, which are ultimately some kind of atom or terminal symbol. The same goes for Mudela: there are some basic building blocks, and by combining those you create complex music.
You can combine music in three ways:
{
and }
), then you form another kind of music called
sequential music
with those pieces.
The duration of sequential composition is the sum of the durations of its elements
{ c c g g a a g2 } % twinkle twinkle { { c c g g} { a a g2 } }
<
and >
. This is called simultaneous music.
The duration of a simultaneous composition is the union of the durations
of its elements Example:
<a4 {cis8 cis8} e'4> % a-major chord
\transpose d % from c to the d that's almost one octave down { e4 f4 } % the horizontal music
\type
\property
\translator
\relative
Of course you can also combine these three mechanisms.
{ c <c e> <c e g> <c e g \transpose d' dis > } % 4 increasing chords
A duration always starts with the duration type (1,2,4 etc), and then any optional multipliers/dots. `Gregrorian' durations can be entered as follows
c'\breve gis'\longa
A time signature specification has this form:
\time 3/4 ;
Rhythmic grouping is a concept closely associated with this. For example, in a 5/8 time signature, the counts are grouped 2+3. In Mudela this is entered as
\grouping 8*2 8*3 ;
You can start the piece with a partial measure, the command takes a duration as an argument
\partial 16*3;
Make the piece start with a upstep lasting 1 3/4 quarter notes.
These commands constitute `Music', and have a duration of 0.
By default the same accidentals are valid for all octaves, but
this can be changed with the property specialaccidentals
.
The identifier \specialkey
sets the property for the Staff. A
key with two flats in one octave and three
sharps in the next can be declared with
\specialkey \accidentals bes es fis' cis' gis';
Sometimes you only need to print a small fragment of music, perhaps something much like one of the examples in this document. Back in section 1.4 we told you that the music you enter should be encapsulated in something like:
\score< \melodic\relative c{ d } \paper{ } \midi{ } >where the only interesting information is this particular example is
dThe rest of the above example was already nicknamed `red tape'. You may easily get bored if you have to provide this same red tape for every fragmenty you try (Of course, in most cases your favourite text editor (TM) will help you out.).
Luckily there's a trick around this, and it's called .fly files. If you use the extension .fly for Mudela file foo, LilyPond will embed your foo.fly in (Or something very similar. If you want to know exactly, see init/init.fly):
\score< \melodic\relative c{ <<foo.ly>> } \paper{ } \midi{ }
Here's how it works. If you run LilyPond on your file bar.ly, you may notice that she starts-off by reading quite a number of files before she actually reaches your bar.ly. There's no magic going on, Lily by default reads an initialisation file (init/init.ly). In the initialisation process a lot of things are defined that you'll need for normal operation, such as notenames and various other mudela shortcuts, engraver and perforer definitions, font sizes, musical dimensions and paper sizes. When you use the extension .fly, Lily just starts reading another initialisation file (init/init.fly), that includes the red tape for you too.