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 .
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. For a complete and up-to-date definition, see lily/parser.yy, lily/lexer.ll, and the init files.
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.
When invoked with a filename that has no extension, LilyPond will try adding a .fly extension first, and a .ly extension second. If the filename ends with .fly, LilyPond processes the file as music using init.fly. In this case, LilyPond does something like:
\score { \notes\relative c { \input "yourfile.fly" } \paper{} \midi{} }If you invoke LilyPond with a file foo.
ext
that doesn't
have the .ly extension then LilyPond will look for a file called
init.ext
and process this file. The file
init.ext
must contain the \maininput
keyword or LilyPond
will not read the user specified file.
When LilyPond processes filename.ly it will produce filename.tex as
output. If filename.ly contains a second \paper
keyword, then
LilyPond will produce filename-1.tex as well. Subsequent \paper
keywords will produces sequentially numbered file names. Several files can be
specified; they will each be processed independently.
A Mudela file consists of keywords with arguments and identifier
assignments separated by spaces, tabs or newlines. Semicolons are
used by some keywords and are inconsistantly required in other
circumstances. A one line comment is introduced by a %
character. Block comments are started by %{
and ended by
%}
. They cannot be nested.
Mudela supports several types:
-1.2e3
. Reals can be built up using the usual operations:
+
, -
, *
, and /
, with parentheses for grouping.
"
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
Section 2.3 for details on unquoted strings; their
interpretation varies depending on the situation. On the right side
of identifier assignments and within the \header
keyword,
strings can be concatenated using the +
character.
\mm
, \pt
, \in
, or \cm
. Dimensions
are converted immediately to a real which gives the dimension in
points, so they can be mixed with reals, but the result is no longer
of type dimension. The keywords that require a dimension
(\shape
).
a
.
The pitch names can be redefined with the \notenames
keyword.
See Section(notelang) for pitch names in different languages. Pitches
can only be specified inside note mode which is specified with
\notes
. Therefore, keywords which require pitch arguments must
appear inside \notes
.
\notes
. See Section 3 for details. More
complicated expressions of type music are formed by surrounding a
sequence of expressions of type music with braces {
and }
or with angle brackets <
and >
. Items appearing in braces
will be treated as serial. Items in angle brackets will be
simultaneous. So for example { c e g }
represents an arpeggio
and < c e g >
represents a chord. These items can be nested any
way you like. This simple example shows how three chords can be
expressed in two different ways:
![]() |
Identifiers allow names to be assigned to constants, music, or other
Mudela structures. To assign an identifier you use
name
=value
and to refer to an identifier, you preceed its
name with a backslash: \
name
. It is legal to redefine an
identifier in terms of its old value: foo = \foo * 2.0
.
Identifier assignments must appear at the top level in the Mudela
file. Note that semicolons are forbidden after assignments appearing
at the top level but they are obligatory after assignments appearing
elsewhere. (Semicolons are also forbidden after \property
assignments.)
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 and are entirely alphanumeric. It is also impossible to refer to an identifier whose name is the same as the name of a keyword. The following words are keywords:
accepts duration midi relative textscript alternative font mm remove time bar musicalpitch repeat times cadenza header name scm translator chordmodifiers in notenames scmfile transpose chords include notes score type clef key paper script version cm keysignature partial shape consists lyrics penalty skip consistsend maininput property spanrequest context mark pt tempo
The right hand side of an identifier assignment is parsed completely
when the assignment is made. It therefore must have any context
specified in the definition. For example, you must write
foo=\notes{a8 b c}
rather than foo={a8 b c}
. Even though
the context is specified in the definition, you must refer to the
identifier inside the correct context:
foo = \paper{ linewidth = 6.0\in; } \score{ \notes{ ... } \paper{ \foo } }If
\foo
is used here without the surrounding \paper
then
an error will result. Note however that the following is acceptible
foo = \notes { ... } \score{ \foo }It is not necessary to specify
\notes
.
Identifiers can be set equal to integers, reals, strings, music,
durations (specified with \duration
), note ornaments (specified
with \script
, dynamics commands, or :
), note name tables
(specified with \notenames
, translator definitions, the
\paper
block, the \midi
block or the \score
block.
When identifiers are used for translators, the \paper
,
\midi
, and \score
blocks, they may only be referred to as
the first item in a block. So \paper{\one \two}
is illegal
because the identifier \two
is not the first thing in the block.
Unlike other identifier definitions, translator identifier definitions
can only appear within \midi
or \paper
blocks. See
Section 12.3 for more information.
To simplify different aspects of music definition (entering the notes
and manipulating them) Mudela has three different input modes which
affect how unquoted strings are interpreted.
In each mode, words are identified on the input. If "word"
is
encountered, it is treated as a string. If \word
is
encountered it is treated as a keyword or as an identifier. The
behavior of the modes differs in two ways: different modes treat
unquoted words different, and different modes have different rules for
deciding what is a word.
word
is encountered on the input it
is treated as a string.
\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. If you mistype a notename, the parser will most
likely complain that you should be in \lyrics
mode to do lyrics.
\chords
.
Very similar to Note mode.
\lyrics
. This mode is has rules that make it easy to include
punctuation and diacritical marks in words. 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 if you thought the
}
was going to terminate lyrics mode. Any _
characters
which appear in an unquoted word are converted to spaces, providing 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 specified with the above rules. Here are some examples.
Not all of these words are printable by TeX.
a&@&@&TSI|{[ % a word NOTRANS(á)foo} % a word 1THtrhortho % not a word because it starts with a digit ``Hello'' % not a word because it starts with ` Leise Fl\"u\ss{}teren meine Sapfe % 4 words _ _ _ _ % 4 words, each one a space
It is possible to create words that break the rules by prefixing them with the
dollar sign $
. Regardless of the context, a word beginning with $
extends until the next white space character. Such words can contain numbers
(even in Note mode), or other forbidden characters. The dollar sign can be
used to create and access identifiers that could not otherwise be used.
A note specification has the form
pitch
[octavespec
][!
][?
][duration
].
The pitch of the note is specified by the note's name.
LilyPond has predefined note names for various languages. 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 ocatave 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
.
Lily has predefined sets of notenames
for various languages. See Section 4.1 for details.
Rests are specified with the note name r
or R
.
There is also a note name s
which produces a nonprinting note of the
specified duration.
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.
![]() |
![]() |
![]() |
![]() |
![]() |
Whenever a C-sharp is desired, you must specify a C-sharp. LilyPond
will determine what accidentals to typeset depending on the key and
context.
A reminder accidental can be forced by
using the optional exclamation mark `!
'
on the pitch.
A cautionary accidental, i.e., an accidental within paranthesis
can be obtained using the optional question mark `?
' on the pitch.
![]() |
Durations are entered as their reciprocal values
![]() |
![]() |
If the duration is omitted then it is set equal to the previous
duration. If there is no previous duration, then a quarter note is
assumed.
The duration can be followed by a dot .
to obtain dotted note
lengths.
![]() |
Extra long notes can be obtained using the \breve
and
longa
durations:
![]() |
In order to get triplets and other tuplets, you must use the
\times
keyword which multiplies the duration by a fraction. The
syntax is \times
fraction
music
. The length of all of
the specified music will be multiplied by the fraction and the
fraction's denominator will be printed over the notes. The most
common tuplet is the triplet in which 3 notes have the length of 2, so
the notes are 2/3 their written length:
![]() |
If you try to use \times
as the first thing in your music, you
may encounter the warning ``No one to print a tuplet start bracket''.
This happens because the Tuplet-engraver is in Voice and no Voice has
been created yet. You must explicitly specify the Voice context in
this situation
![]() |
A shorthand for \times
is to write *
fraction
after a
duration. This shorthand will not label triplets correctly, but
it is convenient for long rests.
For long rests with durations equal to an integer number of whole notes,
LilyPond produces output that indicates the duration of the rest. If you use
r
then one rest symbol will be printed and several measures left blank.
If you use R
then all of the measure will be filled with whole rests.
![]() |
If you set the Score.skipBars
property, then only one measure will be
printed; with R
, a number indicating the length of the rest will be
displayed.
![]() |
Even though the \times
command is not explicit, it is still
necessary to specify a Voice
context if the music begins with
rests lengthened using *
.
Otherwise, the following will result:
![]() |
By default, Lilypond will generate beams automatically. This feature can be
disabled by setting the Voice.beamAuto
property to 0. It can be
overridden for specific cases by specifying explicit beams as
described in Section 3.3.
In order to decide how to generate beams, Lilypond uses a large number
of Voice properties, whose default values appear in
auto-beam-settings.ly. In general, beams can begin anywhere,
but their ending location is significant. Beams can end on a beat, or
at durations specified by the Voice.beamAutoEnd
property. To
end beams every quarter note, for example, you could use set
Voice.beamAutoEnd
equal to "1/4"
. To end beams every
three eighth notes you would set it to "3/8"
. The same syntax
can be used to specify beam starting points using Voice.beamAutoBegin
.
To allow different settings for different time signatures, these
property names can start with time
N
_
M
to
restrict the definition to N
/
M
time. So for example,
to specify beams ending only for 6/8 time you would use the property
Voice.time6_8beamAutoEnd
. To allow different endings for notes
of different durations, the duration can be tacked onto the end of the
property. To specify beam endings for beams that contain 32nd notes,
you would use Voice.beamAutoEnd_32
.
A beam is specified by surrounding the beamed notes with brackets
[
and ]
.
![]() |
Some more elaborate constructions:
![]() |
Another type of spanner is the 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 )
apppears to the left of the first
note in the slur. This makes it possible to put a note in slurs from
both sides:
![]() |
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
~
by analogy with TeX's tie which connects words.
Note that if you try to tie together chords which have no common
pitches, then a warning message will appear and no tie will be created.
(Note that ties between different pitches can be enabled using the
property Voice.oldTieBehavior.)
![]() |
It is possible to create beams and slurs that cross staffs by switching the context:
![]() |
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 the note by writing
`note
^\
name
', and they can be forced to appear below
by writing `note
_\
name
'. Here is a chart showing
symbols above notes, with the name of the corresponding symbol
appearing underneath.
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.
To save typing, a few common symbols can be abbreviated with single characters:
Dynamic marks are specified by using an identifier after a note without a dash:
c4 \ff
. Note that this syntax is inconsistent with the syntax for other
types of ornaments. The available dynamic marks are: \pppppp
,
\ppppp
, \pppp
, \ppp
, \pp
, \p
, \mp
,
\mf
, \f
, \ff
, \fff
, \ffff
, \fffff
,
\ffffff
, \fp
, \sf
, \sff
, \sp
, \spp
,
\sfz
and \rfz
.
A crescendo mark is started with \cr
and terminated with
\rc
. 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.
Tremolo marks can be printed by a 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 Abbrev
property if there was no last value. To place tremolo marks in
between two notes, begin with [:
length
and end with ]
.
The tremolo marks will appear instead of beams. Putting more than two
notes in such a construction will produce odd effects.
[TREMOLO BEAMS TEMPORARILY OUT OF ORDER]
The pitch names can be easily redefined using the \notenames
command.
Note name definitions have been provided in various languages.
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 sid si -d -b catalan.ly do re mi fa sol la sid si -d/-s -b
One very common error when entering music is to place notes in the wrong
octave. One way to avoid being confused by large numbers of octave changing
marks is to use
the \relative
keyword.
Music which appears within \relative
is
interpreted differently. The octave of a note is determined by making it as
close to the previous note as possible. The octave changing marks '
and
,
can then be added to raise or lower this note by octaves. You have to
specify a starting pitch because the first note of a list has no predecessor.
![]() |
When the preceeding 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 preceeding note.
![]() |
The \relative
keyword can only appear in music, so there must be a
surrounding \notes
keyword which does not appear in the fragments shown
above. Also note that if the music passed to a \relative
keyword
contains a \transpose
keyword, the tranposed music will not be
processed in relative mode. An additional \relative
must be placed
inside the \transpose
. If \relative
will be used several
times, or if it will be used in the same music with \transpose
,
then you may get bizarre effects. This can be fixed by using an
explicit Staff
context.
Another way to modify the meaning of the note names is to use the
\transpose
keyword. This keyword allows you to transpose music.
To use transposition, specify the pitch that middle C should be tranposed to.
It is important to distinguish between enharmonic pitches as they can produce
different transpositions. To transpose up half a step, for example, either
\transpose cis'
or \transpose des'
will work. But the first
version will print sharps and the second version will print flats.
In this example, a scale in the key of E is transposed to F, or to E-sharp
with odd results.
![]() |
![]() |
![]() |
If you want to use both \transpose
and \relative
, then you must use
\transpose
first. Any \relative
keywords that are outside the
\transpose
have no effect on notes that appear inside the
\transpose
. As with \relative
, using \transpose
repeatedly can cause bizarre effects. An explicit Staff
context
will eliminate the problems.
Chords can be entered either by name or by listing the notes in angle brackets.
Chords can be displayed either as notes or by name. To enter chords by name,
either place them inside the \chords
keyword.
Chord names have the form
tonic
[duration
][-
modifier
][^
subtractions
][/
inversion
]
The tonic
should be the tonic note of the chord, and the 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. A 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 (.
).
Repeating a -
character will remove a half step from the preceeding
interval.
![]() |
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.
![]() |
Chord subtractions are used to eliminate notes from a chord. The notes to be
subtracted are listed after a ^
character, separated by dots.
![]() |
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 then a warning will be printed.
![]() |
Throughout these examples, chords have been shifted around the staff
using \transpose
. The \relative
keyword has odd effects
when combined with named chords.
For displaying printed chord names, use the ChordNames
context.
The chords may be entered either using the notation described above,
or directly using angle brackets.
Lilypond examines chords specified as lists of notes to determine a name to give the chord. By default, LilyPond will not try to identify chord inversions:
![]() |
If you want inversions to be recognized, you must set the property
Score.chordInversion
:
![]() |
Lyrics 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 2.3 for a description of what is interpreted as a lyric.
In order to instruct LilyPond to write lyrics underneath the
staff, you must enter the lyrics context with \context Lyrics
.
Lyrics should be entered in lyrics mode which is entered with \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. Here is a full example:
When one word is attached to many notes, you may
want a continuous line after the lyric to show this. 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.
If you want to have hyphens centred between syllables (rather than attached
to the end of the first syllable) you can use the special --
lyric as
separate word between syllables. This will result in a hyphen whose length
varies depending on the space between syllables, and centred between the
syllables. For example:
LilyPond aligns all musical objects according to the amount of time they occupy. All musical objects have a duration. When music is written sequentially using braces the duration is the sum of the durations of the elements. When music is stacked into simultaneous music using angle brackets, the duration is the maximum of the durations of the elements.
Because LilyPond knows the durations of all musical elements, the time
signature enables LilyPond to draw bar lines automatically. The time
signature is specified with the \time
keyword: \time 3/4
.
If no time signature is given, LilyPond assumes 4/4. The automatic
generation of bar lines can toggled with the \cadenza
keyword or the
Staff.barNonAuto
property,
and an incomplete measure at the start of the music can be created
using the \partial
keyword: \partial 8*2;
creates a
starting measure lasting two eighth notes.
In order to help with error checking, you can insert bar markers in
your music by typing |
. Whenever LilyPond encounters a |
that doesn't fall at a measure boundary, she prints a warning message.
In order to specify repeats, use the \repeat
keyword. By
default, repeats are printed with repeat symbols.
![]() |
In order to specify alternate endings, use the \alternative
keyword.
![]() |
The semi
specifies that normal repeats will be printed. If
fold
is used instead then the alternatives will be stacked:
![]() |
When the repeats involve partial measures, it will be necessary to use
\partial
keywords in a somewhat unexpected way
to indicate some measure lengths.
Repeats can be unfolded by setting the property Staff.unfoldRepeats.
Note also that if your music begins with \repeat
, you must place
it in an explicit Staff
context or you will get bizarre results.
If you don't give enough alternatives for all of the repeats, then the first alternative is assumed to be repeated enough to equal to specified number of repeats.
Keywords sometimes appear alone, but usually they require arguments. A keyword may have a single argument, a sequence of arguments in braces, or a sequence of arguments separated by spaces and terminated by a semicolon. The precise syntax of each keyword is shown below. Keywords must appear in the right context. If you use a keyword in the wrong place, even if the usage is syntactically correct, you will get the message ``parse error'' from LilyPond.
\absdynamic
{
code
}
code
is unsigned and specifies the dynamic mark to print.
Normally you should use the more user friendly abbreviations defined
in the init file dynamic.ly.
FIXME: Changed to \textscript
text
style
. Defines
a text-request.
\accepts
string
;
\translator
block. It specifies what contexts are allowed with the
context that is being defined. See Section 12.3.
\alternative
{
music1
music2
... }
\repeat
keyword.
\bar
bartype
;
bartype
is a string which specifies the
kind of bar to print. Options are ":|"
, "|:"
,
":|:"
, "||"
, "|."
, ".|"
, or ".|."
.
These produce respectively a right repeat, a left repeat, a double
repeat, a double bar, a start bar, an end bar, or a thick double bar.
If bartype
is set to "empty"
then nothing is printed, but a
line break is allowed at that spot. Note that the printing of special bars
has no effect on the MIDI output.
\cadenza
togglevalue
;
togglevalue
is 0 then bar line generation is
turned off. If togglevalue
is 1 then a bar is immediately
printed and bar generation is turned on.
\clef
clefname
;
_8
or ^8
is added to the end of a clef
name then the clef lowered or raised an octave will be generated.
Here are the supported clef names with middle C shown in each clef:
The treble clef can also be obtained using the names G
or
violin
. The bass clef is also available by \clef F
.
\chord
chordlist
chordlist
in chords mode.
\chordmodifiers
modifierlist
\cm
\consists
string
;
\translator
block. It specifies that an engraver or performer named
string
should be added to the translator. See Section
12.3.
\consistsend
string
;
\context
contexttype
[=
contextname
]
music
or \context
translatortype
;
music
is processed in the new context. The second
variant appears within a \translator
block and specifies the
type of translator being created.
\duration
{
length
dotcount
}
length
is the negative logarithm (base
2) of 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
.
\font
string
\paper
to specify the font.
\header
{
key1
= val1
; key2
= val2
; ... }
\score
blocks, then a header should appear in
each score block describing its contents. 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.
\in
\include
file
file
is a string. The full filename including the
.ly extension must be given, and the filename must be quoted.
(An unquoted string will not work here.)
\key
pitch
type
;
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.
\keysignature
pitchseq
;
pitch
will
be printed in the key signature in the order that they appear on the list.
\lyrics
lyriclist
lyriclist
in lyrics mode.
\maininput
\mark
unsigned
;
or \mark
string
;
markDirection
property) the staff.
You must add Mark_engraver
to the Score context.
\midi
statementlist
\tempo
.
\mm
\musicalpitch
{
octave
note
shift
}
\name
context
;
\translator
to
specify the name of the context that the translator handles. See Section
12.3.
\notenames
assignmentlist
name
= pitch
, where pitch
is specified with the
\musicalpitch
keyword.
\notes
music
\paper
statmentlist
statmentlist
contains statements that change features of the
output. See Section 12.
\partial
duration
;
\alternative
.
\penalty
int
;
\break
and
\nobreak
in Section 11.
\property
contextname
.
propname
=
value
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.
\pt
\relative
pitch
music
music
in relative pitch
mode. In this mode, the octave of a pitch is chosen so that the
pitch is closest to the preceeding pitch.
The argument pitch
is
the starting pitch for this comparision. In the case of chords, the
first note of a chord is used as the base for the first pitches in the next
chord. See Section 4.2.
\remove
string
;
\translator
block. Specifies that a performer or engraver named
string
should be removed. See Section 12.3.
\repeat
style
count
{
music
}
count
times. Alternative endings can be specified by adding a
\alternative
keyword after the \repeat
. The style
parameter should be either semi
, for regular repeats, or
fold
for repeats displayed vertically.
\scm
scheme
;
\scmfile
filename
;
\score
statementlist
\script
alias
\script
keyword is not used
directly. Various helpful identifier definitions appear in
script.ly.
\shape
=
indent1
width1
indent2
width2
... ;
\paper
. Each pair
of indent
and width
values is a dimension specifying how far
to indent and how wide to make the line. The indentation and width of
successive lines are specified by the successive pairs of dimensions.
The last pair of dimensions will define the characeristics of all
lines beyond those explicitly specified.
\skip
duration
;
duration
. A gap will be left for the skipped time with no notes
printed. It works in Note Mode or Lyrics Mode (but generates a
mysterious error in lyrics).
\spanrequest
startstop
type
startstop
is either -1 (\start
) or 1 (\stop
). The type
parameter is a string that describes what should be started. Supported types
are "crescendo", "decrescendo", "beam", "slur". This is an internal command.
Users should use the abbreviations which are defined in the
initialization file dynamic.ly.
\tempo
duration
= perminute
;
\midi
or within music to specify the tempo. For example,
`\midi { \tempo 4 = 76;}
' requests output with 76 quarter notes
per minute. Note that if the music contains several tempo commands,
only the last one is used to set the tempo for the entire MIDI output.
\textscript
text
style
\time
numerator
/
denominator
;
\times
numerator
/
denominator
music
music
by the specified fraction.
\translator
statements
or \translator
context
= name
\paper
and specifies a translator for
converting music to notation. The translator is specified with a
single \context
statement and a series of \accepts
, and
\consists
statements. See Section 12.3.
The second variant appears in
music. It specifies that the current the contexts
contained within the specified context should be shifted to the
context with the specified name.
\transpose
pitch
music
pitch
. This is allowed in music only,
and if it appears inside \relative
, then any notes specified for
transposition should be specified inside another \relative
. See Section
4.3.
\type
string
;
\translator
to
specify the type of the translator.
\version
string
"1.0.1"
. Note that the Mudela version is different from the
LilyPond version.
Notation contexts provide information that appears in printed music
but not in the music itself. A new musical context is created using
the \context
keyword: `\context
contexttype
[=
contextname
] music
'. The following context types are
allowed.
LyricVoice
Voice
ChordNamesVoice
ChordNames
ChordNamesVoice
contexts.
Lyrics
LyricVoice
contexts.
Staff
Voice
contexts.
RhythmicStaff
Staff
but for printing
rhythms. Pitches are ignored; the notes are printed on one line.
It can contain Voice
contexts.
GrandStaff
Staff
or RhythmicStaff
contexts. It adds a brace on the left side grouping the staffs
together. The bar lines of the contained staffs are connected vertically.
It can contain Staff
contexts.
PianoStaff
GrandStaff
but with
minVerticalAlign
set equal to maxVerticalAlign
so that
interstaff beaming and slurring can be used.
StaffGroup
Staff
or RhythmicStaff
contexsts. Adds a bracket on the left side, grouping the staffs
together. The bar lines of the contained staffs are connected vertically.
It can contain Staff
, RhythmicStaff
, GrandStaff
or Lyrics
contexts.
ChoirStaff
StaffGroup
except that the
contained staffs are not connected vertically.
Score
\score
keyword rather than the \context
command. No
other context can contain a Score
context. This context handles
the administration of time signatures. It also makes sure that items
such as clefs, time signatures, and key-signatures are aligned across
staffs. It can contain Lyrics
, Staff
,
RhythmicStaff
, GrandStaff
, StaffGroup
, and
ChoirStaff
contexts.
The various contexts have properties associated with them. These
properties can be changed using the \property
command:
`\property
context
.
propname
=
value
'.
Properties can also be set within the \translator
block
corresponding to the appropriate context. In this case, they are
assigned by `propname
=
value
'. The settings made with
\property
are processed after settings made in the \translator
block, so the \property
settings will override \translator
settings.
The \property
keyword will create any property you specify.
There is no guarantee that a property will actually be used. If you
spell a property name wrong, there will be no error message. In order to find
out what properties are used, you must search the source code
for get_property
.
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.
Lyrics properties
textStyle
roman
, italic
, bold
, large
,
Large
, typewriter
, and finger
. The finger
font can only display numbers. Note also that you must be careful
when using \property
in Lyrics mode. Because of the way strings
are parsed, either put quotes around the arguments to \property
or be sure to leave a space on both sides of the dot.
Voice properties
stemLeftBeamCount
stemRightBeamCount
beamAuto
beamAutoEnd
beamAutoBegin
textEmptyDimension
noteheadStyle
cross
, diamond
, harmonic
, transparent
, and
""
. They are shown in that order below.
restStyle
restStyle=""
and mensural notation
restStyle="mensural"
are available.
"midiInstrument"
instrument
property. This must be set to one of the strings on the list of MIDI
instruments that appears in Section 12.2. If you use a
string which is not listed, LilyPond will silently substitute piano.
transposing
oldTieBehavior
verticalDirection
\down
to force them down,
\up
to force them up, or \free
to let LilyPond decide.
This can be used to distinguish between voices on the same staff. The
\stemdown
, \stemup
, and \stemboth
identifiers set
this property. See also the identifiers \voiceone
,
\voicetwo
, \voicethree
and \voicefour
.
slurVerticalDirection
\free
for free choice of slur
direction, set to \up
to force slurs up, set to \down
to
force slurs down. The shorthands \slurup
, \slurdown
, and
\slurboth
are available.
tieVerticalDirection
\free
for free choice of tie
direction, set to \up
to force ties up, set to \down
to
force ties down.
slurdash
\slurnormal
and
\slurdotted
are predefined to set the first two settings.
horizontalNoteShift
\shift
is
defined to enable this. If there are several voices, every voice must
have a distinct value of this property or no shifting will occur.
dynamicDir
\up
to print marks above the staff; set to \down
to print
marks below the staff.
dynamicStyle
textStyle
textScriptPadding
fontSize
abbrev
tupletDirection
\down
to force them below the staff,
\up
to force them above, or \free
to let LilyPond decide.
tupletVisibility
pletoff
and pleton
identifiers set the property to 0 and 3,
respectively.
markScriptPadding
markDirection
\up
to print marks above the staff;
set to \down
to print marks below the staff.
articulationScriptPadding
Staff properties
createInitdefaultClef
barNumberDirection
\up
or \down
to put
bar numbers above or below the staff.
barNumberHangOnClef
barNumberScriptPadding
barSize
markHangOnClef
marginDirection
\left
or \right
to
specify location of marginal scripts.
marginScriptPadding
forgetAccidentals
noResetKey
staffLineLeading
numberOfStaffLines
postBreakPadding
barAtLineStart
voltaVisibility
\alternative
.
voltaSpannerDuration
\alternative
. The integer specifies
the number of whole notes duration to use for the brackets. It seems
to be rounded to the nearest measure. This can be used to shrink the
length of brackets in the situation where one alternative is very
large. It may have odd effects if the specified duration is longer
than the music given in an \alternative
.
barNonAuto
\bar
keywords.
Unlike with the \cadenza
keyword, measures are still counted. Bar
generation will resume according to that count if this property is set to
zero.
defaultClef
\clef
keyword.
nuberOfStaffLines
barAlways
defaultBarType
\bar
keyword.
keyoctaviation
\keysignature bes
fis'
. The default value is 1. Can be set to zero with
\specialkey
or reset to 1 with \normalkey
.
instrument
and instr
Staff_margin_engraver
is added to the Staff translator, then the instrument
property
is used to label the first line of the staff and the instr
property is used to label subsequent lines. If the
midiInstrument
property is not set then instrument
is
used to determine the instrument for MIDI output.
createKeyOnClefChange
timeSignatureStyle
C
old
1
C2/2
, C4/4
, old2/2
, old3/2
,
old2/4
, old3/4
, old4/4
, old6/4
,
old9/4
, old4/8
, old6/8
, old6/8alt
or old9/8
clefStyle
transparent
, the clefs are not printed at all, when set to
fullSizeChanges
, clef changes in the middle of a line are
typeset with a full size clef. By default, clef changes are typeset in
smaller size.
GrandStaff properties
alignmentReference
\center
for vertical
alignment reference point to be in the center of the vertical group.
Set to \up
to put the reference point at the top of the group.
maxVerticalAlign
minVerticalAlign
Score properties
skipBars
beamquantisation
\none
for no quantization.
Set to \normal
to quantize position and slope. Set to
\traditional
to avoid wedges. These three settings are
available via \beamposfree
, \beamposnormal
, and
\beampostraditional
.
beamslopedamping
\none
for undamped beams.
Set to \normal
for damped beams. Set to \infinity
for
beams with zero slope. The identifiers \beamslopeproportional
,
\beamslopedamped
, and \beamslopezero
each set the
corresponding value.
chordInversion
Various identifiers are defined in the initialization files to provide shorthands for some settings.
\aeolian
\key
keyword to get an aeolian mode.
\break
\penalty
.
\center
\cr
\decr
\dorian
\key
keyword to get a dorian mode.
\down
\f
\ff
\fff
\ffff
\fffff
\ffffff
\fp
\free
\Gourlay
castingalgorithm
. Is equal to 1.0.
\infinity
\ionian
\key
keyword to get an ionian mode.
\left
\locrian
\key
keyword to get a locrian mode.
\lydian
\key
keyword to get a lydian mode.
\major
\key
keyword to get a major key.
\minor
\key
keyword to get a minor key.
\mixolydian
\key
keyword to get a mixolydian mode.
\mf
\mp
\nobreak
\penalty
.
\none
\normal
\normalkey
\p
\phrygian
\key
keyword to get a phrygian mode.
\pp
\ppp
\pppp
\ppppp
\pppppp
) Print pppppp symbol on preceeding note.
\rc
\rced
\rfz
\right
\sf
\sff
\sfz
\shiftoff
\shifton
\slurboth
\slurdown
\slurup
\sp
\spp
\specialkey
\stemboth
\stemdown
\stemup
\traditional
\up
\voiceone
one
and force stems down.
(See \stemdown
.)
\voicetwo
two
and force stems
up. (See \stemup
.)
\voicethree
three
and force stems
up.
\voicefour
four
, force stems down
and turn on horizontal shifting. (See \stemdown
and \shifton
.)
\Wordwrap
castingalgorithm
. Equal to 0.0.
The output produced by LilyPond is controlled by the \paper
and
\midi
keywords. These keywords appear in the \score
block
to indicate that printed or musical output should be produced. If
neither keyword appears in a \score
block, then paper output is
produced but MIDI output is not produced.
The contents of the \paper
and \midi
blocks can change the
output in various ways. These blocks can appear at the top level of a
Mudela file to set default parameters for each type of output. It is
still necessary to explicitly specify the output type in the
\score
blocks if you don't want the default behavior of
producing only paper output.
The \paper
and \midi
blocks
may begin with an optional identifier reference. No
identifier references are allowed anywhere else in the block.
The \paper
block can contain the \shape
keyword; the
\midi
block can contain the \tempo
keyword. Both of them
can contain \translator
keywords. The \paper
block can
also contain identifier assignments and parameter assignments. Unlike
at the top level, these assignments must be terminated by a semicolon.
Warning: this section is outdated and inaccurate.
There are a large number of paper variables that are used to control
details of the layout. Usually you will not want to change these
variables; they are set by default to vaules that depend on the font
size in use. The only way to find out what variables are supported is
to search the source code for get_var
. Two variables that you
may want to change are linewidth
and indent
.
In order to change the font size used for the output, many variables
need to be changed. Some identifiers and initialization files can
simplify this process. The default size is 20pt. In order to select
a different size, you must do two things. At the top level, do
\include "paper
SZ
.ly"
where SZ
is the height of
the staff in points. Values presently allowed are 11, 13, 16, 20, and
26. This loads some definitions, but does not cause them to take
effect. In order to actually change the size, you must use one of the
identifiers: \paper_eleven
, \paper_thirteen
,
\paper_sixteen
, \paper_twenty
or \paper_twentysix
inside a \paper
block.
integer
\font
keyword must appear on the right
side. This defines a music font at a particular size. See Voice
property fontSize
.
arithmetic_basicspace
and arithmetic_multiplier
arithmetic_multiplier * ( c + log2 (time) )where
time
is the amount of time a note occupies. The value
of c
is chosen such that the smallest space within a measure is
arithmetic_basicspace. The smallest space is the one following the
shortest note in the measure. Typically arithmetic_basicspace is set
to the width of a quarter note head.
beam_dir_algorithm
castingalgorithm
crescendo_shorten
forced_stem_shorten
forced_stem_shorten0
gourlay_energybound
gourlay_maxmeasures
indent
interbeam
interbeam4
interline
linewidth
notewidth
output
rulethickness
slur_clip_angle
slur_clip_height
slur_clip_ratio
slur_height_limit
slur_ratio
slur_rc_factor
slur_slope_damping
slur_thickness
1.4 *
\staffline
by default.
slur_x_gap
\interline / 5
by default.
slur_x_minimum
staffheight
4 * \interline
.
stem_length
stemthickness
tie_slope_damping
tie_x_minimum
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 this list. If
string does not exactly match one from this list then LilyPond uses
the default piano.
"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)"
The behavior of notation contexts is defined by the translators for those contexts. The translator for a context specifies what notations are handled by the context, it specifies what other contexts the context can contain, and it sets property values for the context. There are different translators for each type of output. The translators for paper output are defined in engraver.ly. The translators for MIDI output are defined in performer.ly.
The first thing that appears inside a \translator
definition is
the type of the context being created. This is specified with the
\type
keyword: \type
typename
;
. After the type
of the context is specified, property assignments, the \name
keyword and \consists
, \accepts
, and \remove
keywords can appear in any order. The \name
keyword specifies
the name of the context that is handled by the translator. If the
name is not specified, the translator won't do anything. Each
\accepts
keyword specifies what contexts can be contained inside
this one. The \consists
keywords specify which notations are
handled by the context. Each \consists
keyword specifies the
name of an engraver (for paper ouput) or performer (for MIDI output)
which handles a certain notation. The \remove
keyword can be
used to remove a performer or engraver from the translator.
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 All of the standard translators have predefined identifiers, making
it easy to redefine these contexts by adding or removing items.
The predefined identifiers are: StaffContext
,
RhythmicStaffContext
, VoiceContext
, ScoreContext
, ScoreWithNumbers
12.3.1: Paper Types and Engravers and Pre-defined Translators
Some pre-defined identifiers can simplify modification of translators. The pre-defined identifiers are:
StaffContext
RhythmicStaffContext
VoiceContext
ScoreContext
ScoreWithNumbers
BarNumberingStaffContext
HaraKiriStaffContext
OrchestralPartStaffContext
OrchestralScoreContext
\paper{ \translator{ \StaffContext \remove Some_engraver; \consists Different_engraver; }}
There are four types for paper translators:
Engraver_group_engraver
Hara_kiri_line_group_engraver
Line_group_engraver_group
Score_engraver
The engravers for paper output are:
Abbreviation_beam_engraver
Bar_engraver
Staff
and
RhythmicStaff
.
Bar_number_engraver
Score
for Score-wide numbering or to Staff
for
numbering on each staff.
Beam_engraver
Voice
translator. If omitted, then notes will be printed
with flags instead of beams.
Beam_req_swallow_translator
LyricVoice
.
Chord_name_engraver
ChordNameVoice
Clef_engraver
Staff
.
Collision_engraver
Dot_column_engraver
Voice
. If omitted, then dots appear on
top of the notes.
Dynamic_engraver
Voice
.
Font_size_engraver
Key_engraver
Staff
.
Local_key_engraver
Lyric_engraver
LyricVoice
.
Multi_measure_rest_engraver
R
. Normally in Voice
.
Piano_bar_engraver
Pitch_squash_engraver
RhythmicStaff
. Note that the notes move, but the locations of
accidentals stay the same.
Priority_horizontal_align_engraver
Repeat_engraver
Staff
and
RhythmicStaff
.
Rest_collision_engraver
Staff
.
Rest_engraver
Voice
.
Rhythmic_column_engraver
Score_priority_engraver
Script_engraver
\script
.
Normally in Voice
.
Separating_line_group_engraver
Skip_req_swallow_translator
Slur_engraver
Voice
.
Span_bar_engraver
Staffgroup
and GrandStaff
. Removing this from StaffGroup
gives the definition of ChoirStaff
.
Span_score_bar_engraver
Staff_group_bar_engraver
Staff_margin_engraver
Staff.instrument
and Staff.instr
) at the
left of the staff.
Staff_sym_engraver
Stem_engraver
Voice
.
Ties_engraver
Voice
.
Time_signature_engraver
Staff
and RhythmicStaff
.
Timing_engraver
Score
. In order to create polyrhythmic music,
this engraver should be removed from Score
and placed in Staff
.
Tuplet_engraver
Staff
.
Vertical_align_engraver
12.3.2: MIDI Types and Performers
The types available for MIDI translators are:
Performer_group_performer
Score_performer
Staff_performer
The performers for MIDI translators are:
Key_performer
Time_signature_performer
Note_performer
Lyric_performer
Swallow_performer
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.