Common octave marks can be entered just once on a reference pitch
after \fixed placed before the music. Pitches inside
\fixed only need ' or , marks
when they are above or below the octave of the reference pitch.

See also

Relative octave entry

Absolute octave entry requires specifying the octave for every
single note. Relative octave entry, in contrast, specifies each
octave in relation to the last note: changing one note’s octave
will affect all of the following notes.

Relative note mode has to be entered explicitly using the
\relative command:

\relative startpitchmusicexpr

In relative mode, each note is assumed to be as close to the
previous note as possible. This means that the octave of each
pitch inside musicexpr is calculated as follows:

If no octave changing mark is used on a pitch, its octave is
calculated so that the interval with the previous note is less
than a fifth. This interval is determined without considering
accidentals.

An octave changing mark ' or , can be
added to respectively raise or lower a pitch by an extra octave,
relative to the pitch calculated without an octave mark.

Multiple octave changing marks can be used. For example,
'' and ,, will alter the pitch by two
octaves.

The pitch of the first note is relative to
startpitch. startpitch is specified in
absolute octave mode. Which choices are meaningful?

Writing \relative gis''' { gis … } makes it easy to
determine the absolute pitch of the first note inside.

no explicit starting pitch

The form \relative { gis''' … } serves
as a compact version of the previous option: the first note
inside is written in absolute pitch itself. (This happens to be
equivalent to choosing f as the reference pitch.)

The documentation will usually employ the last option.

Here is the relative mode shown in action:

\relative {
\clef bass
c d e f
g a b c
d e f g
}

Octave changing marks are used for intervals greater than a
fourth:

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

A note sequence without a single octave mark can nevertheless span
large intervals:

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

When \relative blocks are nested, the innermost
\relative block starts with its own reference pitch
independently of the outer \relative.

\relative {
c' d e f
\relative {
c'' d e f
}
}

\relative has no effect on \chordmode blocks.

\new Staff {
\relative c''' {
\chordmode { c1 }
}
\chordmode { c1 }
}

\relative is not allowed inside of \chordmode blocks.

Music inside a \transpose block is absolute unless a
\relative is included.

\relative {
d' e
\transpose f g {
d e
\relative {
d' e
}
}
}

If the preceding item is a chord, the first note of the chord is
used as the reference point for the octave placement of a
following note or chord. Inside chords, the next note is always
relative to the preceding one. Examine the next example
carefully, paying attention to the c notes.

\relative {
c'
<c e g>
<c' e g'>
<c, e, g''>
}

As explained above, the octave of pitches is calculated only with
the note names, regardless of any alterations. Therefore, an
E-double-sharp following a B will be placed higher, while an
F-double-flat will be placed lower. In other words, a
double-augmented fourth is considered a smaller interval than a
double-diminished fifth, regardless of the number of semitones
that each interval contains.

Accidentals

Note: New users are sometimes confused about accidentals and
key signatures. In LilyPond, note names specify pitches; key
signatures and clefs determine how these pitches are displayed.
An unaltered note like c means ‘C natural’,
regardless of the key signature or clef. For more information,
see Pitches and key signatures.

A sharp pitch is made by adding is to the note
name, and a flat pitch by adding es. As you
might expect, a double sharp or double flat
is made by adding isis or eses. This syntax is
derived from Dutch note naming conventions. To use other names
for accidentals, see Note names in other languages.

\relative c'' { ais1 aes aisis aeses }

A natural pitch is entered as a simple note name; no suffix is
required. A natural sign will be printed when needed to cancel
the effect of an earlier accidental or key signature.

\relative c'' { a4 aes a2 }

Quarter tones may be added; the following is a series of Cs with
increasing pitches:

\relative c'' { ceseh1 ces ceh c cih cis cisih }

Normally accidentals are printed automatically, but you may also
print them manually. A reminder accidental can be forced by
adding an exclamation mark ! after the pitch. A
cautionary accidental (i.e., an accidental within parentheses) can
be obtained by adding the question mark ? after the
pitch.

\relative c'' { cis cis cis! cis? c c c! c? }

Accidentals on tied notes are only printed at the beginning of a
new system:

\relative c'' {
cis1~ 1~
\break
cis
}

Selected Snippets

Hiding accidentals on tied notes at the start of a new system

This shows how to hide accidentals on tied notes at the start of a new
system.

In accordance with traditional typesetting rules, a natural sign is
printed before a sharp or flat if a previous double sharp or flat on
the same note is canceled. To change this behavior to contemporary
practice, set the extraNatural property to f in the
Staff context.

Note names in other languages

There are predefined sets of note and accidental names for various
other languages. Selecting the note name language is usually done
at the beginning of the file; the following example is written
using Italian note names:

\language "italiano"
\relative {
do' re mi sib
}

The available languages and the note names they define are:

Language

Note Names

nederlands

c d e f g a bes b

catalan

do re mi fa sol la sib si

deutsch

c d e f g a b h

english

c d e f g a bf b

espanol or español

do re mi fa sol la sib si

français

do ré/re mi fa sol la sib si

italiano

do re mi fa sol la sib si

norsk

c d e f g a b h

portugues

do re mi fa sol la sib si

suomi

c d e f g a b h

svenska

c d e f g a b h

vlaams

do re mi fa sol la sib si

In addition to note names, accidental suffixes may
also vary depending on the language:

Language

sharp

flat

double sharp

double flat

nederlands

-is

-es

-isis

-eses

catalan

-d/-s

-b

-dd/-ss

-bb

deutsch

-is

-es

-isis

-eses

english

-s/--sharp

-f/--flat

-ss/-x/--sharpsharp

-ff/--flatflat

espanol or español

-s

-b

-ss/-x

-bb

français

-d

-b

-dd/-x

-bb

italiano

-d

-b

-dd

-bb

norsk

-iss/-is

-ess/-es

-ississ/-isis

-essess/-eses

portugues

-s

-b

-ss

-bb

suomi

-is

-es

-isis

-eses

svenska

-iss

-ess

-ississ

-essess

vlaams

-k

-b

-kk

-bb

In Dutch, aes is contracted to as, but both forms
are accepted in LilyPond. Similarly, both es and
ees are accepted. This also applies to
aeses / ases and
eeses / eses. Sometimes only these
contracted names are defined in the corresponding language files.

\relative c'' { a2 as e es a ases e eses }

Some music uses microtones whose alterations are fractions of a
‘normal’ sharp or flat. The following table lists note names
for quarter-tone accidentals in various languages; here the prefixes
semi- and sesqui- respectively
mean ‘half’ and ‘one and a half’. Languages that do not
appear in this table do not provide special note names yet.

Language

semi-sharp

semi-flat

sesqui-sharp

sesqui-flat

nederlands

-ih

-eh

-isih

-eseh

deutsch

-ih

-eh

-isih

-eseh

english

-qs

-qf

-tqs

-tqf

espanol or español

-cs

-cb

-tcs

-tcb

français

-sd

-sb

-dsd

-bsb

italiano

-sd

-sb

-dsd

-bsb

portugues

-sqt

-bqt

-stqt

-btqt

Most languages presented here are commonly associated with
Western classical music, also referred to as
Common Practice Period. However, alternate
pitches and tuning systems are also supported: see
Common notation for non-Western music.

Octave checks

In relative mode, it is easy to forget an octave changing mark.
Octave checks make such errors easier to find by displaying a
warning and correcting the octave if a note is found in an
unexpected octave.

To check the octave of a note, specify the absolute octave after
the = symbol. This example will generate a warning
(and change the pitch) because the second note is the absolute
octave d'' instead of d' as indicated by the octave
correction.

\relative {
c''2 d='4 d
e2 f
}

The octave of notes may also be checked with the
\octaveCheck controlpitch command.
controlpitch is specified in absolute mode. This
checks that the interval between the previous note and the
controlpitch is within a fourth (i.e., the normal
calculation of relative mode). If this check fails, a warning is
printed. While the previous note itself is not changed, future
notes are relative to the corrected value.

\relative {
c''2 d
\octaveCheck c'
e2 f
}

Compare the two bars below. The first and third \octaveCheck
checks fail, but the second one does not fail.

Transpose

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

\transpose frompitchtopitchmusicexpr

This means that musicexpr is transposed by the
interval between the pitches frompitch and
topitch: any note with pitch frompitch
is changed to topitch and any other note is
transposed by the same interval. Both pitches are entered in
absolute mode.

Note: Music inside a \transpose block is absolute
unless a \relative is included in the block.

Consider a piece written in the key of D-major. It can be
transposed up to E-major; note that the key signature is
automatically transposed as well.

\transpose d e {
\relative {
\key d \major
d'4 fis a d
}
}

If a part written in C (normal concert pitch) is to be
played on the A clarinet (for which an A is notated as a C and
thus sounds a minor third lower than notated), the appropriate
part will be produced with:

\transpose a c' {
\relative {
\key c \major
c'4 d e g
}
}

Note that we specify \key c \major explicitly. If we
do not specify a key signature, the notes will be transposed but
no key signature will be printed.

\transpose distinguishes between enharmonic pitches: both
\transpose c cis or \transpose c des will
transpose up a semitone. The first version will print sharps and
the notes will remain on the same scale step, the second version
will print flats on the scale step above.

\transpose may also be used in a different way, to input
written notes for a transposing instrument. The previous examples
show how to enter pitches in C (or concert pitch) and
typeset them for a transposing instrument, but the opposite is
also possible if you for example have a set of instrumental parts
and want to print a conductor’s score. For example, when entering
music for a B-flat trumpet that begins on a notated E (concert D),
one would write:

musicInBflat = { e4 … }
\transpose c bes, \musicInBflat

To print this music in F (e.g., rearranging to a French horn) you
could wrap the existing music with another \transpose:

See also

Known issues and warnings

The relative conversion will not affect \transpose,
\chordmode or \relative sections in its argument. To use
relative mode within transposed music, an additional \relative
must be placed inside \transpose.

Triple accidentals will not be printed if using \transpose. An
‘enharmonically equivalent’ pitch will be used instead (e.g., d-flat
rather than e-triple-flat).

Retrograde

Known issues and warnings

\retrograde is a rather simple tool. Since many events are
‘mirrored’ rather than exchanged, tweaks and directional
modifiers for opening spanners need to be added at the matching
closing spanners: ^( needs to be ended by ^), every
\< or \cresc needs to be ended by \! or
\endcr, every \> or \decr needs to be ended
by \enddecr. Property-changing commands/overrides with a
lasting effect will likely cause surprises.

Modal transformations

In a musical composition that is based on a scale, a motif is
frequently transformed in various ways. It may be
transposed to start at different places in the scale or
it may be inverted around a pivot point in the scale.
It may also be reversed to produce its retrograde, see
Retrograde.

Note: Any note that does not lie within the given scale will be
left untransformed.

Modal transposition

A motif can be transposed within a given scale with:

\modalTranspose from-pitchto-pitchscalemotif

The notes of motif are shifted within the scale by the
number of scale degrees given by the interval between to-pitch
and from-pitch:

Modal inversion

A motif can be inverted within a given scale around a given pivot
note and transposed in a single operation with:

\modalInversion around-pitchto-pitchscalemotif

The notes of motif are placed the same number of scale degrees
from the around-pitch note within the scale, but in the
opposite direction, and the result is then shifted within the
scale by the number of scale degrees given by the interval between
to-pitch and around-pitch.

So to simply invert around a note in the scale use the same value for
around-pitch and to-pitch:

To invert around a pivot between two notes in the scale, invert around
one of the notes and then transpose by one scale degree. The two notes
specified can be interpreted as bracketing the pivot point:

For mixing clefs when using cue notes, see the \cueClef and
\cueDuringWithClef commands in Formatting cue notes.

By adding _8 or ^8 to the clef name, the
clef is transposed one octave down or up respectively,
and _15 and ^15 transpose by two octaves.
Other integers can be used if required. Clef names containing
non-alphabetic characters must be enclosed in quotes

Optional octavation can be obtained by enclosing the numeric
argument in parentheses or brackets:

\clef "treble_(8)"
c'2 c'
\clef "bass^[15]"
c'2 c'

The pitches are displayed as if the numeric argument were
given without parentheses/brackets.

By default, a clef change taking place at a line break will cause
the new clef symbol to be printed at the end of the previous line,
as a warning clef, as well as the beginning of the next.
This warning clef can be suppressed.

To be more precise, it is not the \clef command itself that
prints a clef. Instead, it sets or changes a property of the
Clef_engraver, which then decides by its own whether to
display a clef or not in the current staff. The forceClef
property overrides this decision locally to re-print a clef once.

When there is a manual clef change, the glyph of the changed clef
will be smaller than normal. This behaviour can be overridden.

Selected Snippets

Tweaking clef properties

Changing the Clef glyph, its position, or the ottavation does not
change the position of subsequent notes on the staff. To get key
signatures on their correct staff lines middleCClefPosition must
also be specified, with positive or negative values moving middle
C up or down respectively, relative to the staff’s center line.

For example, \clef "treble_8" is equivalent to setting the
clefGlyph, clefPosition (the vertical position of the
clef itself on the staff), middleCPosition and
clefTransposition. Note that when any of these properties
(except middleCPosition) are changed a new clef symbol is
printed.

The following examples show the possibilities when setting these
properties manually. On the first line, the manual changes preserve the
standard relative positioning of clefs and notes, whereas on the second
line, they do not.

Key signature

Note: New users are sometimes confused about accidentals and
key signatures. In LilyPond, note names are the raw input; key
signatures and clefs determine how this raw input is displayed.
An unaltered note like c means ‘C natural’,
regardless of the key signature or clef. For more information,
see Pitches and key signatures.

The key signature indicates the tonality in which a piece is
played. It is denoted by a set of alterations (flats or sharps)
at the start of the staff. The key signature may be altered:

\key pitchmode

Here, mode should be \major or \minor
to get a key signature of pitch-major or
pitch-minor, respectively. You may also use the
standard mode names, also called church modes:
\ionian, \dorian, \phrygian, \lydian,
\mixolydian, \aeolian, and \locrian.

\relative {
\key g \major
fis''1
f
fis
}

Additional modes can be defined, by listing the alterations
for each scale step when the mode starts on C.

Accidentals in the key signature may be printed in octaves other
than their traditional positions, or in multiple octaves, by
using the flat-positions and sharp-positions
properties of KeySignature. Entries in these properties
specify the range of staff-positions where accidentals will be
printed. If a single position is specified in an entry, the
accidentals are placed within the octave ending at that staff
position.

Selected Snippets

Preventing natural signs from being printed when the key signature changes

When the key signature changes, natural signs are automatically printed
to cancel any accidentals from previous key signatures. This may be
prevented by setting to f the printKeyCancellation
property in the Staff context.

If you have more than one voice on the staff, setting octavation in one
voice will transpose the position of notes in all voices for the
duration of the ottava bracket. If the ottavation is only intended to
apply to one voice, the middleCPosition and ottava bracket may be set
explicitly. In this snippet, the bass clef usually has middleCPosition
set to 6, six positions above the center line, so in the 8va portion
middleCPosition is 7 positions (one octave) higher still.

Instrument transpositions

When typesetting scores that involve transposing instruments, some
parts can be typeset in a different pitch than the
concert pitch. In these cases, the key of the
transposing instrument should be specified; otherwise
the MIDI output and cues in other parts will produce incorrect
pitches. For more information about quotations, see
Quoting other voices.

\transposition pitch

The pitch to use for \transposition should correspond to
the real sound heard when a c' written on the staff is
played by the transposing instrument. This pitch is entered in
absolute mode, so an instrument that produces a real sound which
is one tone higher than the printed music should use
\transposition d'. \transposition should
only be used if the pitches are not being entered in
concert pitch.

Here are a few notes for violin and B-flat clarinet where the
parts have been entered using the notes and key as they appear in
each part of the conductor’s score. The two instruments are
playing in unison.

Automatic accidentals

There are many different conventions on how to typeset
accidentals. LilyPond provides a function to specify which
accidental style to use. This function is called as follows:

\new Staff <<
\accidentalStyle voice
{ … }
>>

The accidental style applies to the current Staff by
default (with the exception of the styles piano and
piano-cautionary, which are explained below). Optionally,
the function can take a second argument that determines in which
scope the style should be changed. For example, to use the same
style in all staves of the current StaffGroup, use:

\accidentalStyle StaffGroup.voice

The following accidental styles are supported. To demonstrate
each style, we use the following example:

This is the default typesetting behavior. It corresponds to
eighteenth-century common practice: accidentals are remembered to
the end of the measure in which they occur and only in their own
octave. Thus, in the example below, no natural signs are printed
before the b in the second measure or the
last c:

voice

The normal behavior is to remember the accidentals at
Staff-level. In this style, however, accidentals are
typeset individually for each voice. Apart from that, the rule is
similar to default.

As a result, accidentals from one voice do not get canceled in
other voices, which is often an unwanted result: in the following
example, it is hard to determine whether the second a
should be played natural or sharp. The voice option should
therefore be used only if the voices are to be read solely by
individual musicians. If the staff is to be used by one musician
(e.g., a conductor or in a piano score) then modern or
modern-cautionary should be used instead.

modern

This rule corresponds to the common practice in the twentieth
century. It omits some extra natural signs, which were
traditionally prefixed to a sharp following a double sharp,
or a flat following a double flat. The modern rule
prints the same accidentals as default, with
two additions that serve to avoid ambiguity: after temporary
accidentals, cancellation marks are printed also in the following
measure (for notes in the same octave) and, in the same measure,
for notes in other octaves. Hence the naturals before
the b and the c in the second measure of
the upper staff:

modern-cautionary

This rule is similar to modern, but the ‘extra’ accidentals
are printed as cautionary accidentals (with parentheses). They can also
be printed at a different size by overriding
AccidentalCautionary’s font-size property.

modern-voice

This rule is used for multivoice accidentals to be read both by
musicians playing one voice and musicians playing all voices.
Accidentals are typeset for each voice, but they are
canceled across voices in the same Staff. Hence,
the a in the last measure is canceled because the
previous cancellation was in a different voice, and
the d in the lower staff is canceled because of the
accidental in a different voice in the previous measure:

modern-voice-cautionary

This rule is the same as modern-voice, but with the extra
accidentals (the ones not typeset by voice) typeset as
cautionaries. Even though all accidentals typeset by
defaultare typeset with this rule, some of them are
typeset as cautionaries.

piano

This rule reflects twentieth-century practice for piano notation.
Its behavior is very similar to modern style, but here
accidentals also get canceled across the staves in the same
GrandStaff or PianoStaff, hence all the
cancellations of the final notes.

This accidental style applies to the current GrandStaff or
PianoStaff by default.

piano-cautionary

This is the same as piano but with the extra accidentals
typeset as cautionaries.

neo-modern

This rule reproduces a common practice in contemporary music:
accidentals are printed like with modern, but they are printed
again if the same note appears later in the same measure – except
if the note is immediately repeated.

neo-modern-cautionary

This rule is similar to neo-modern, but the ‘extra’ accidentals
are printed as cautionary accidentals (with parentheses). They can also
be printed at a different size by overriding
AccidentalCautionary’s font-size property.

neo-modern-voice

This rule is used for multivoice accidentals to be read both by
musicians playing one voice and musicians playing all voices.
Accidentals are typeset for each voice as with neo-modern,
but they are canceled across voices in the same Staff.

neo-modern-voice-cautionary

This rule is similar to neo-modern-voice, but the extra
accidentals are printed as cautionary accidentals.

dodecaphonic

This rule reflects a practice introduced by composers at
the beginning of the 20th century, in an attempt to
abolish the hierarchy between natural and non-natural notes.
With this style, every note gets an accidental sign,
including natural signs.

dodecaphonic-no-repeat

Like with the dodecaphonic accidental style every note
gets an accidental sign by default, but accidentals are
suppressed for pitches immediately repeated within the same staff.

dodecaphonic-first

Similar to the dodecaphonic accidental style every pitch
gets an accidental sign, but only the first time it is encountered
in a measure. Accidentals are only remembered for the actual octave
but throughout voices.

teaching

This rule is intended for students, and makes it easy to create
scale sheets with automatically created cautionary accidentals.
Accidentals are printed like with modern, but cautionary
accidentals are added for all sharp or flat tones specified by the
key signature, except if the note is immediately repeated.

no-reset

This is the same as default but with accidentals lasting
‘forever’ and not only within the same measure:

forget

This is the opposite of no-reset: Accidentals are not
remembered at all – and hence all accidentals are typeset
relative to the key signature, regardless of what came before in
the music.

See also

Known issues and warnings

Simultaneous notes are not considered in the automatic
determination of accidentals; only previous notes and the key
signature are considered. Forcing accidentals with !
or ? may be required when the same note name occurs
simultaneously with different alterations, as in ‘<f! fis!>’.

Cautionary cancellation of accidentals is done by looking at previous measure.
However, in the \alternative block following a \repeat volta N
section, one would expect the cancellation being calculated using the previous
played measure, not previous printed measure.
In the following example, the natural c in the second alternative does
not need a natural sign:

The following work-around can be used: define a function that locally changes
the accidental style to forget:

Ambitus

The term ambitus (pl. ambitus) denotes a range of
pitches for a given voice in a part of music. It may also denote
the pitch range that a musical instrument is capable of playing.
Ambitus are printed on vocal parts so that performers can easily
determine if it matches their capabilities.

Ambitus are denoted at the beginning of a piece near the initial
clef. The range is graphically specified by two note heads that
represent the lowest and highest pitches. Accidentals are only
printed if they are not part of the key signature.

The cross style is used to represent a variety of musical
intentions. The following generic predefined commands modify the
note head in both staff and tablature contexts and can be used to
represent any musical meaning:

\relative {
c''4 b
\xNotesOn
a b c4 b
\xNotesOff
c4 d
}

The music function form of this predefined command may be used
inside and outside chords to generate crossed note heads in both
staff and tablature contexts:

\relative {
c''4 b
\xNote { e f }
c b < g \xNote c f > b
}

As synonyms for \xNote, \xNotesOn and \xNotesOff,
\deadNote, \deadNotesOn and \deadNotesOff can
be used. The term dead note is commonly used by guitarists.

Easy notation note heads

The ‘easy play’ note head includes a note name inside the head.
It is used in music for beginners. To make the letters readable,
it should be printed in a large font size. To print with a larger
font, see Setting the staff size.

Predefined commands

\easyHeadsOn,
\easyHeadsOff.

Selected Snippets

Numbers as easy note heads

Easy notation note heads use the note-names property of the
NoteHead object to determine what appears inside the note head.
By overriding this property, it is possible to print numbers
representing the scale-degree.

A simple engraver can be created to do this for every note head object
it sees.

Shape note heads

In shape note head notation, the shape of the note head
corresponds to the harmonic function of a note in the scale. This
notation was popular in nineteenth-century American song books.
Shape note heads can be produced in Sacred Harp, Southern Harmony,
Funk (Harmonica Sacra), Walker, and Aiken (Christian Harmony) styles:

Shapes are typeset according to the step in the scale, where the base
of the scale is determined by the \key command. When writing
in a minor key, the scale step can be determined from the relative
major:

Predefined commands

Selected Snippets

Applying note head styles depending on the step of the scale

The shapeNoteStyles property can be used to define various note
head styles for each step of the scale (as set by the key signature or
the tonic property). This property requires a set of symbols,
which can be purely arbitrary (geometrical expressions such as
triangle, cross, and xcircle are allowed) or based
on old American engraving tradition (some latin note names are also
allowed).

That said, to imitate old American song books, there are several
predefined note head styles available through shortcut commands such as
\aikenHeads or \sacredHarpHeads.

This example shows different ways to obtain shape note heads, and
demonstrates the ability to transpose a melody without losing the
correspondence between harmonic functions and note head styles.

1.2.1 Writing rhythms

Durations

Durations are designated by numbers and dots. Durations are entered
as their reciprocal values. For example, a quarter note is entered
using a 4 (since it is a 1/4 note), and a half note is entered
using a 2 (since it is a 1/2 note). For notes longer than a
whole you must use the \longa (a double breve) and
\breve commands. Durations as short as 128th notes may be
specified. Shorter values are possible, but only as beamed notes.

Tuplets

Tuplets are made from a music expression with the \tuplet
command, multiplying the speed of the music expression by a fraction:

\tuplet fraction { music }

The fraction’s numerator will be printed over or under the notes,
optionally with a bracket. The most common tuplets are triplets
(3 notes sound within the duration normally allowed for 2).

\relative {
a'2 \tuplet 3/2 { b4 4 4 }
c4 c \tuplet 3/2 { b4 a g }
}

When entering long passages of tuplets, having to write a separate
\tuplet command for each group is inconvenient. It is possible
to specify the duration of one tuplet group directly before the music
in order to have the tuplets grouped automatically:

Modifying nested tuplets which begin at the same musical moment must be
done with \tweak.

To modify the duration of notes without printing a tuplet bracket, see
Scaling durations.

Predefined commands

\tupletUp,
\tupletDown,
\tupletNeutral.

Selected Snippets

Entering several tuplets using only one \tuplet command

The property tupletSpannerDuration sets how long each of the
tuplets contained within the brackets after \tuplet should
last. Many consecutive tuplets can then be placed within a single
\tuplet expression, thus saving typing.

There are several ways to set tupletSpannerDuration. The
command \tupletSpan sets it to a given duration, and clears it
when instead of a duration \default is specified. Another way
is to use an optional argument with \tuplet.

The default behavior of tuplet-bracket visibility is to print a bracket
unless there is a beam of the same length as the tuplet. To control the
visibility of tuplet brackets, set the property
'bracket-visibility to either #t (always print a
bracket), #f (never print a bracket) or #'if-no-beam
(only print a bracket if there is no beam).

Scaling durations

The duration of single notes, rests or chords may be multiplied by a
fraction N/M by appending *N/M (or *N if M
is 1) to the duration. This will not affect the appearance of the
notes or rests produced, but the altered duration will be used in
calculating the position within the measure and setting the duration
in the MIDI output. Multiplying factors may be combined like
*L*M/N. Factors are part of the duration: if a duration is
not specified for subsequent notes, the default duration taken from
the preceding note will include any scaling factor.

In the following example, the first three notes take up exactly
two beats, but no triplet bracket is printed.

The duration of spacer rests may also be modified by
a multiplier. This is useful for skipping many measures, e.g.,
s1*23.

Longer stretches of music may be compressed by a fraction in the
same way, as if every note, chord or rest had the fraction as a
multiplier. This leaves the appearance of the music unchanged but
the internal duration of the notes will be multiplied by the
fraction num/den. Here is an example showing how music
can be compressed and expanded:

See also

Known issues and warnings

The calculation of the position within a measure must take into
account all the scaling factors applied to the notes within that
measure and any fractional carry-out from earlier measures. This
calculation is carried out using rational numbers. If an intermediate
numerator or denominator in that calculation exceeds 2^30 the
execution and typesetting will stop at that point without indicating
an error.

Ties

A tie connects two adjacent note heads of the same pitch. The tie
in effect extends the duration of a note.

Note: Ties should not be confused with slurs, which
indicate articulation, or phrasing slurs, which indicate
musical phrasing. A tie is just a way of extending a note
duration, similar to the augmentation dot.

A tie is entered by appending a tilde symbol (~) to the first
of each pair of notes being tied. This indicates that the note
should be tied to the following note, which must be at the same pitch.

{ a'2~ 4~ 16 r r8 }

Ties can make use of the ‘last explicit pitch’ interpretation of
isolated durations:

{ a'2~ 4~ 16 r r8 }

Ties are used either when the note crosses a bar line, or when
dots cannot be used to denote the rhythm. Ties should also be
used when note values cross larger subdivisions of the measure:

\relative {
r8 c'~ 2 r4 |
r8^"not" c2~ 8 r4
}

If you need to tie many notes across bar lines, it may be
easier to use automatic note splitting, see Automatic note splitting. This mechanism automatically splits long notes, and
ties them across bar lines.

When a tie is applied to a chord, all note heads whose pitches
match are connected. When no note heads match, no ties will be
created. Chords may be partially tied by placing the ties inside
the chord.

Predefined commands

Selected Snippets

Using ties with arpeggios

Ties are sometimes used to write out arpeggios. In this case, two tied
notes need not be consecutive. This can be achieved by setting the
tieWaitForNote property to #t. The same feature is also
useful, for example, to tie a tremolo to a chord, but in principle, it
can also be used for ordinary consecutive notes.

Ties may be engraved manually by changing the tie-configuration
property of the TieColumn object. The first number indicates the
distance from the center of the staff in half staff-spaces, and the
second number indicates the direction (1 = up, -1 = down).

Whole measure rests, centered in the middle of the measure, must be
entered as multi-measure rests. They can be used for a single
measure as well as many measures and are discussed in
Full measure rests.

To explicitly specify a rest’s vertical position, write a note
followed by \rest. A rest of the duration of the note will
be placed at the staff position where the note would appear. This
allows for precise manual formatting of polyphonic music, since the
automatic rest collision formatter will not move these rests.

Invisible rests

An invisible rest (also called a ‘spacer rest’) can be entered
like a note with the note name s:

\relative c'' {
c4 c s c |
s2 c |
}

Spacer rests are available only in note mode and chord mode. In
other situations, for example, when entering lyrics, the
command \skip is used to skip a musical moment.
\skip requires an explicit duration, but this is ignored if
the lyrics derive their durations from the notes in an associated
melody through \addlyrics or \lyricsto.

Full measure rests

The duration of full-measure rests is identical to the duration
notation used for notes. The duration in a multi-measure rest must
always be an integral number of measure-lengths, so augmentation dots
or fractions must often be used:

A full-measure rest is printed as either a whole or breve rest,
centered in the measure, depending on the time signature.

\time 4/4
R1 |
\time 6/4
R1*3/2 |
\time 8/4
R1*2 |

By default a multi-measure rest is expanded in the printed score to
show all the rest measures explicitly. Alternatively, a multi-measure
rest can be shown as a single measure containing a multi-measure rest
symbol, with the number of measures of rest printed above the measure:

Note: Markups attached to a multi-measure rest are objects of type
MultiMeasureRestText, not TextScript. Overrides must
be directed to the correct object, or they will be ignored. See the
following example:

% This fails, as the wrong object name is specified
\override TextScript.padding = #5
R1^"wrong"
% This is the correct object name to be specified
\override MultiMeasureRestText.padding = #5
R1^"right"

When a multi-measure rest immediately follows a \partial
setting, resulting bar-check warnings may not be displayed.

Predefined commands

\textLengthOn,
\textLengthOff,
\fermataMarkup,
\compressMMRests.

Selected Snippets

Changing form of multi-measure rests

If there are ten or fewer measures of rests, a series of longa and
breve rests (called in German “Kirchenpausen” - church rests) is
printed within the staff; otherwise a simple line is shown. This
default number of ten may be changed by overriding the
expand-limit property.

Unlike ordinary rests, there is no predefined command to change the
staff position of a multi-measure rest symbol of either form by
attaching it to a note. However, in polyphonic music multi-measure
rests in odd-numbered and even-numbered voices are vertically
separated. The positioning of multi-measure rests can be controlled as
follows:

Markups attached to a multi-measure rest will be centered above or
below it. Long markups attached to multi-measure rests do not cause
the measure to expand. To expand a multi-measure rest to fit the
markup, use an empty chord with an attached markup before the
multi-measure rest.

Text attached to a spacer rest in this way is left-aligned to the
position where the note would be placed in the measure, but if the
measure length is determined by the length of the text, the text will
appear to be centered.

Time signature

Time signatures are printed at the beginning of a piece
and whenever the time signature changes. If a change takes place
at the end of a line a warning time signature sign is printed
there. This default behavior may be changed, see
Visibility of objects.

\relative c'' {
\time 2/4
c2 c
\break
c c
\break
\time 4/4
c c c c
}

The time signature symbol that is used in 2/2 and 4/4 time can be
changed to a numeric style:

In addition to setting the printed time signature, the \time
command also sets the values of the time-signature-based properties
baseMoment, beatStructure, and beamExceptions.
The predefined default values for these properties can be found in
‘scm/time-signature-settings.scm’.

The default value of beatStructure can be overridden in the
\time command itself by supplying it as the optional first
argument:

Alternatively, the default values of all these time-signature-based
variables, including baseMoment and beamExceptions,
can be set together. The values can be set independently for several
different time signatures. The new values take effect when a
subsequent \time command with the same value of the time
signature is executed:

Different values of default time signature properties can be established
for different staves by moving the Timing_translator and the
Default_bar_line_engraver from the Score context to the
Staff context.

A further method of changing these time-signature-related variables,
which avoids reprinting the time signature at the time of the change,
is shown in Setting automatic beam behavior.

Predefined commands

\numericTimeSignature,
\defaultTimeSignature.

Selected Snippets

Time signature printing only the numerator as a number (instead of the fraction)

Sometimes, a time signature should not print the whole fraction (e.g.
7/4), but only the numerator (7 in this case). This can be easily done
by using \override Staff.TimeSignature.style = #'single-digit
to change the style permanently. By using \revert
Staff.TimeSignature.style, this setting can be reversed. To apply the
single-digit style to only one time signature, use the
\override command and prefix it with a \once.

A parenthesized metronome mark with no textual indication may be
written by including an empty string in the input:

\relative {
\tempo "" 8 = 96
d''4 g e c
}

In a part for an instrument with long periods of rests,
tempo indications sometimes follow each other closely.
The command \markLengthOn provides extra horizontal space
to prevent tempo indications from overlapping, and \markLengthOff
restores the default behavior of ignoring tempo marks
for horizontal spacing.

Unmetered music

In metered music bar lines are inserted and bar numbers are calculated
automatically. In unmetered music (i.e., cadenzas), this is not
desirable and can be ‘switched off’ using the command
\cadenzaOn, then ‘switched back on’ at the appropriate place
using \cadenzaOff.

Inserting a \bar command within a cadenza does not start a new
measure, even if a bar line is printed. So any accidentals – which
are usually assumed to remain in force until the end of the measure –
will still be valid after the bar line printed by \bar. If
subsequent accidentals should be printed, forced accidentals or
reminder accidentals need to be inserted manually, see
Accidentals.

These predefined commands affect all staves in the score, even when
placed in just one Voice context. To change this, move the
Timing_translator from the Score context to the
Staff context. See Polymetric notation.

Polymetric notation

Different time signatures with equal-length measures

Set a common time signature for each staff, and set the
timeSignatureFraction to the desired fraction. Then use the
\scaleDurations function to scale the durations of the notes in
each staff to the common time signature.

In the following example, music with the time signatures of 3/4, 9/8 and
10/8 are used in parallel. In the second staff, shown durations are
multiplied by 2/3 (because 2/3 * 9/8 = 3/4) and in the third staff, the
shown durations are multiplied by 3/5 (because 3/5 * 10/8 = 3/4). It
may be necessary to insert beams manually, as the duration scaling will
affect the autobeaming rules.

Known issues and warnings

When using different time signatures in parallel, notes at the same
moment will be placed at the same horizontal location. However, the bar
lines in the different staves will cause the note spacing to be less
regular in each of the individual staves than would be normal without
the different time signatures.

Automatic note splitting

Long notes which overrun bar lines can be converted automatically to
tied notes. This is done by replacing the Note_heads_engraver
with the Completion_heads_engraver. Similarly, long rests which
overrun bar lines are split automatically by replacing the
Rest_engraver with the Completion_rest_engraver. In the
following example, notes and rests crossing the bar lines are split,
notes are also tied.

These engravers split all running notes and rests at the bar line, and
inserts ties for notes. One of its uses is to debug complex scores: if
the measures are not entirely filled, then the ties show exactly how
much each measure is off.

The property completionUnit sets a preferred duration for
the split notes.

Known issues and warnings

For consistency with previous behavior, notes and rests with
duration longer than a measure, such as c1*2, are split into
notes without any scale factor, { c1 c1 }. The property
completionFactor controls this behavior, and setting it to
#f cause split notes and rests to have the scale factor
of the input durations.

Note: If beams are used to indicate melismata in songs, then
automatic beaming should be switched off with \autoBeamOff
and the beams indicated manually. Using \partcombine with
\autoBeamOff can produce unintended results. See the
snippets for more information.

Kneed beams are inserted automatically when a large gap is detected
between the note heads. This behavior can be tuned through the
auto-knee-gap property. A kneed beam is drawn if the gap is
larger than the value of auto-knee-gap plus the width of the
beam object (which depends on the duration of the notes and the slope
of the beam). By default auto-knee-gap is set to 5.5 staff
spaces.

{
f8 f''8 f8 f''8
\override Beam.auto-knee-gap = #6
f8 f''8 f8 f''8
}

Partcombine and autoBeamOff

The function of \autoBeamOff when used with
\partcombine can be difficult to understand.

It may be preferable to use

\set Staff.autoBeaming = ##f

instead, to ensure that autobeaming will be turned off for the entire
staff.

\partcombine apparently works with 3 voices – stem up single,
stem down single, stem up combined.

An \autoBeamOff call in the first argument to partcombine will
apply to the voice that is active at the time the call is processed,
either stem up single or stem up combined. An \autoBeamOff call
in the second argument will apply to the voice that is stem down single.

In order to use \autoBeamOff to stop all autobeaming when used
with \partcombine, it will be necessary to use three calls to
\autoBeamOff.

Known issues and warnings

The properties of a beam are determined at the start of its
construction and any additional beam-property changes that occur before
the beam has been completed will not take effect until the next,
new beam starts.

Setting automatic beam behavior

When automatic beaming is enabled, the placement of automatic beams
is determined by three context properties:
baseMoment, beatStructure, and beamExceptions.
The default values of these variables may be overridden as described
below, or alternatively the default values themselves may be changed
as explained in Time signature.

If a beamExceptions rule is defined for the time signature in
force, that rule alone is used to determine the beam placement; the
values of baseMoment and beatStructure are ignored.

If no beamExceptions rule is defined for the time signature
in force, the beam placement is determined by the values of
baseMoment and beatStructure.

Beaming based on baseMoment and beatStructure

By default, beamExceptions rules are defined for most common
time signatures, so the beamExceptions rules must be disabled
if automatic beaming is to be based on baseMoment and
beatStructure. The beamExceptions rules are disabled
by

\set Timing.beamExceptions = #'()

When beamExceptions is set to #'(), either due to an
explicit setting or because no beamExceptions rules are defined
internally for the time signature in force, the ending points for
beams are on beats as specified by the context properties
baseMoment and beatStructure. beatStructure is
a scheme list that defines the length of each beat in the measure in
units of baseMoment. By default, baseMoment is one
over the denominator of the time signature. By default, each unit of
length baseMoment is a single beat.

Note that there are separate beatStructure and baseMoment
values for each time signature. Changes to these variables apply only
to the time signature that is currently in force, hence those changes
must be placed after the \time command which starts a new time
signature section, not before it. New values given to a particular
time signature are retained and reinstated whenever that time signature
is re-established.

\relative {
\time 4/4
a'8^"default" a a a a a a a
% Disable beamExceptions because they are definitely
% defined for 4/4 time
\set Timing.beamExceptions = #'()
\set Timing.baseMoment = #(ly:make-moment 1/4)
\set Timing.beatStructure = 1,1,1,1
a8^"changed" a a a a a a a
}

Beam setting changes can be limited to specific contexts. If no
setting is included in a lower-level context, the setting of the
enclosing context will apply.

baseMoment is a moment; a unit of musical duration. A
quantity of type moment is created by the scheme function
ly:make-moment. For more information about this function,
see Time administration.

By default baseMoment is set to one over the denominator of
the time signature. Any exceptions to this default can be found in
‘scm/time-signature-settings.scm’.

Beaming based on beamExceptions

Special autobeaming rules (other than ending a beam on a beat)
are defined in the beamExceptions property.

The value for beamExceptions, a somewhat complex Scheme
data structure, is easiest generated with the
\beamExceptions function. This function is given one or
more manually beamed measure-length rhythmic patterns (measures
have to be separated by a bar check | since the
function has no other way to discern the measure length). Here is
a simple example:

Note: A beamExceptions value must be complete
exceptions list. That is, every exception that should be applied
must be included in the setting. It is not possible to add, remove,
or change only one of the exceptions. While this may seem cumbersome,
it means that the current beaming settings need not be known in order
to specify a new beaming pattern.

When the time signature is changed, default values of
Timing.baseMoment, Timing.beatStructure,
and Timing.beamExceptions are set. Setting the time signature
will reset the automatic beaming settings for the Timing
context to the default behavior.

The default automatic beaming settings for a time signature
are determined in ‘scm/time-signature-settings.scm’.
Changing the default automatic beaming settings
for a time signature is described in Time signature.

Many automatic beaming settings for a time signature contain an
entry for beamExceptions. For example, 4/4 time tries to
beam the measure in two if there are only eighth notes. The
beamExceptions rule can override the beatStructure setting
if beamExceptions is not reset.

In engraving from the Romantic and Classical periods,
beams often begin midway through the measure in 3/4 time,
but modern practice is to avoid the false impression of 6/8 time
(see Gould, p. 153). Similar situations arise in 3/8 time.
This behavior is controlled by the context property beamHalfMeasure,
which has effect only in time signatures with 3 in the numerator:

How automatic beaming works

When automatic beaming is enabled, the placement of automatic beams
is determined by the context properties
baseMoment, beatStructure, and beamExceptions.

The following rules, in order of priority, apply when determining
the appearance of beams:

If a manual beam is specified with […] set the beam
as specified, otherwise

if a beam-ending rule is defined in beamExceptions
for the beam-type, use it to determine the valid places where
beams may end, otherwise

if a beam-ending rule is defined in beamExceptions
for a longer beam-type, use it to determine the valid places
where beams may end, otherwise

use the values of baseMoment and beatStructure to
determine the ends of the beats in the measure, and
end beams at the end of beats.

In the rules above, the beam-type is the duration of the
shortest note in the beamed group.

The default beaming rules can be found in
‘scm/time-signature-settings.scm’.

Selected Snippets

Subdividing beams

The beams of consecutive 16th (or shorter) notes are, by default, not
subdivided. That is, the three (or more) beams stretch unbroken over
entire groups of notes. This behavior can be modified to subdivide the
beams into sub-groups by setting the property subdivideBeams.
When set, multiple beams will be subdivided at intervals defined by the
current value of baseMoment by reducing the multiple beams to
the number of beams that indicates the metric value of the subdivision.
If the group following the division is shorter than the current metric
value (usually because the beam is incomplete) the number of beams
reflects the longest possible subdivision group. However, if there is
only one note left after the division this restriction isn’t applied.
Note that baseMoment defaults to one over the denominator of the
current time signature if not set explicitly. It must be set to a
fraction giving the duration of the beam sub-group using the
ly:make-moment function, as shown in this snippet. Also, when
baseMoment is changed, beatStructure should also be
changed to match the new baseMoment:

Beat grouping within a measure is controlled by the context property
beatStructure. Values of beatStructure are established
for many time signatures in scm/time-signature-settings.scm.
Values of beatStructure can be changed or set with \set.
Alternatively, \time can be used to both set the time signature
and establish the beat structure. For this, you specify the internal
grouping of beats in a measure as a list of numbers (in Scheme syntax)
before the time signature.

\time applies to the Timing context, so it will not
reset values of beatStructure or baseMoment that are set
in other lower-level contexts, such as Voice.

If the Measure_grouping_engraver is included in one of the
display contexts, measure grouping signs will be created. Such signs
ease reading rhythmically complex modern music. In the example, the 9/8
measure is grouped in two different patterns using the two different
methods, while the 5/8 measure is grouped according to the default
setting in scm/time-signature-settings.scm:

See also

Known issues and warnings

If a score ends while an automatic beam has not been ended and is
still accepting notes, this last beam will not be typeset at all.
The same holds for polyphonic voices, entered with
<< … \\ … >>. If a polyphonic voice ends while an
automatic beam is still accepting notes, it is not typeset.
The workaround for these problems is to manually beam the last
beam in the voice or score.

By default, the Timing translator is aliased to the
Score context. This means that setting the time signature
in one staff will affect the beaming of the other staves as well.
Thus, a time signature setting in a later staff will reset custom
beaming that was set in an earlier staff.
One way to avoid this problem is to set the time signature
in only one staff.

The default beam settings for the time signature can also be changed, so
that the desired beaming will always be used. Changes in automatic
beaming settings for a time signature are described in
Time signature.

Manual beams

In some cases it may be necessary to override the automatic
beaming algorithm. For example, the autobeamer will not put beams
over rests or bar lines, and in choral scores the beaming is
often set to follow the meter of the lyrics rather than the
notes. Such beams can be specified manually by
marking the begin and end point with [ and ].

\relative { r4 r8[ g' a r] r g[ | a] r }

Beaming direction can be set manually using direction indicators:

\relative { c''8^[ d e] c,_[ d e f g] }

Individual notes may be marked with \noBeam to prevent them
from being beamed:

Even more strict manual control with the beams can be achieved by
setting the properties stemLeftBeamCount and
stemRightBeamCount. They specify the number of beams to
draw on the left and right side, respectively, of the next note.
If either property is set, its value will be used only once, and
then it is erased. In this example, the last f is printed
with only one beam on the left side, i.e., the eighth-note beam of
the group as a whole.

For right-pointing nibs at the end of a run of beamed notes, set
stemRightBeamCount to a positive value. And for left-pointing
nibs at the start of a run of beamed notes, set
stemLeftBeamCount instead (Example 3).

Sometimes it may make sense for a lone note surrounded by rests to
carry both a left- and right-pointing flat flag. Do this with paired
[] beam indicators alone (Example 4).

(Note that \set stemLeftBeamCount is always equivalent to
\once \set. In other words, the beam count settings are not
“sticky”, so the pair of flat flags attached to the lone
16[] in the last example have nothing to do with the
\set two notes prior.)

Feathered beams

Feathered beams are used to indicate that a small group of notes
should be played at an increasing (or decreasing) tempo, without
changing the overall tempo of the piece. The extent of the
feathered beam must be indicated manually using [ and
], and the beam feathering is turned on by specifying a
direction to the Beam property grow-direction.

If the placement of the notes and the sound in the MIDI output is to
reflect the ritardando or accelerando indicated by the
feathered beam the notes must be grouped as a music expression delimited
by braces and preceded by a featherDurations command which specifies
the ratio between the durations of the first and last notes in the
group.

The square brackets show the extent of the beam and the braces show
which notes are to have their durations modified. Normally these
would delimit the same group of notes, but this is not required: the
two commands are independent.

In the following example the eight 16th notes occupy exactly the
same time as a half note, but the first note is one half as long
as the last one, with the intermediate notes gradually
lengthening. The first four 32nd notes gradually speed up, while
the last four 32nd notes are at a constant tempo.

1.2.5 Bars

Bar lines

Bar lines delimit measures, and are also used to indicate
repeats. Normally, simple bar lines are automatically inserted
into the printed output at places based on the current time
signature.

The simple bar lines inserted automatically can be changed to
other types with the \bar command. For example, a closing
double bar line is usually placed at the end of a piece:

\relative { e'4 d c2 \bar "|." }

It is not invalid if the final note in a measure does not
end on the automatically entered bar line: the note is assumed
to carry over into the next measure. But if a long sequence
of such carry-over measures appears the music can appear compressed
or even flowing off the page. This is because automatic line
breaks happen only at the end of complete measures, i.e., where
all notes end before the end of a measure.

Note: An incorrect duration can cause line breaks to be
inhibited, leading to a line of highly compressed music or
music that flows off the page.

Line breaks are also permitted at manually inserted bar lines
even within incomplete measures. To allow a line break without
printing a bar line, use the following:

\bar ""

This will insert an invisible bar line and allow (but not
force) a line break to occur at this point. The bar number
counter is not increased. To force a line break see
Line breaking.

This and other special bar lines may be inserted manually at any
point. When they coincide with the end of a measure they replace
the simple bar line which would have been inserted there
automatically. When they do not coincide with the end of a measure
the specified bar line is inserted at that point in the printed
output.

Note that manual bar lines are purely visual. They do not affect
any of the properties that a normal bar line would affect, such as
measure numbers, accidentals, line breaks, etc. They do not affect
the calculation and placement of subsequent automatic bar lines.
When a manual bar line is placed where a normal bar line already
exists, the effects of the original bar line are not altered.

Two types of simple bar lines and five types of double bar lines are
available for manual insertion:

Although the bar line types signifying repeats may be inserted
manually they do not in themselves cause LilyPond to recognize
a repeated section. Such repeated sections are better entered
using the various repeat commands (see Repeats), which
automatically print the appropriate bar lines.

In addition, you can specify ".|:-||", which is equivalent to
".|:" except at line breaks, where it gives a double bar
line at the end of the line and a start repeat at the beginning of
the next line.

The "=" bar line provides the double span bar line, used
in combination with the segno sign. Do not use it as a standalone
double thin bar line; here, \bar"||" is
preferred.

The "-" sign starts annotations to bar lines which
are useful to distinguish those with identical appearance
but different behavior at line breaks and/or different span bars.
The part following the "-" sign is not used for building up
the bar line.

If additional elements are needed, LilyPond provides a simple
way to define them. For more information on modifying or adding
bar lines, see file ‘scm/bar-line.scm’.

In scores with many staves, a \bar command in one staff is
automatically applied to all staves. The resulting bar lines are
connected between different staves of a StaffGroup,
PianoStaff, or GrandStaff.

Bar numbers

Bar numbers are typeset by default at the start of every line except
the first line. The number itself is stored in the
currentBarNumber property, which is normally updated
automatically for every measure. It may also be set manually:

Bar numbers can be typeset at regular intervals instead of just at the
beginning of every line. To do this the default behavior must be
overridden to permit bar numbers to be printed at places other than the
start of a line. This is controlled by the break-visibility
property of BarNumber. This takes three values which may be set
to #t or #f to specify whether the corresponding bar
number is visible or not. The order of the three values is
end of line visible, middle of line visible,
beginning of line visible. In the following example bar numbers
are printed at all possible places:

Selected Snippets

Printing the bar number for the first measure

By default, the first bar number in a score is suppressed if it is less
than or equal to ‘1’. By setting barNumberVisibility to
all-bar-numbers-visible, any bar number can be printed for the
first measure and all subsequent measures. Note that an empty bar line
must be inserted before the first note for this to work.

Bar numbers by default are right-aligned to their parent object. This
is usually the left edge of a line or, if numbers are printed within a
line, the left hand side of a bar line. The numbers may also be
positioned directly over the bar line or left-aligned to the bar line.

See also

Known issues and warnings

Bar numbers may collide with the top of the StaffGroup bracket,
if there is one. To solve this, the padding property of
BarNumber can be used to position the number correctly. See
StaffGroup and BarNumber for more.

Bar and bar number checks

Bar checks help detect errors in the entered durations. A bar check
may be entered using the bar symbol, |, at any place where a
bar line is expected to fall. If bar check lines are encountered at
other places, a list of warnings is printed in the log file, showing
the line numbers and lines in which the bar checks failed. In the
next example, the second bar check will signal an error.

\time 3/4 c2 e4 | g2 |

An incorrect duration can result in a completely garbled score,
especially if the score is polyphonic, so a good place to start
correcting input is by scanning for failed bar checks and
incorrect durations.

If successive bar checks are off by the same musical interval,
only the first warning message is displayed. This allows the
warning to focus on the source of the timing error.

Bar checks can also be inserted in lyrics:

\lyricmode {
\time 2/4
Twin -- kle | Twin -- kle |
}

Note that bar check marks in lyrics are evaluated at the musical
moment when the syllable following the check mark is processed.
If the lyrics are associated with the notes of a voice which has a
rest at the beginning of a bar, then no syllable can be located at the
start of that bar and a warning will be issued if a bar check mark is
placed in the lyrics at that position.

It is also possible to redefine the action taken when a bar check
or pipe symbol, |, is encountered in the input, so that
it does something other than a bar check. This is done by
assigning a music expression to "|".
In the following example | is set to insert a double bar
line wherever it appears in the input, rather than checking
for end of bar.

"|" = \bar "||"
{
c'2 c' |
c'2 c'
c'2 | c'
c'2 c'
}

When copying large pieces of music, it can be helpful to check that
the LilyPond bar number corresponds to the original that you are
entering from. This can be checked with \barNumberCheck, for
example,

\barNumberCheck #123

will print a warning if the currentBarNumber is not 123
when it is processed.

The letter ‘I’ is skipped in accordance with engraving
traditions. If you wish to include the letter ‘I’, then use one
of the following commands, depending on which style of rehearsal mark
you want (letters only, letters in a hollow box, or letters in a
hollow circle).

The style is defined by the property markFormatter. It is
a function taking the current mark (an integer) and the current
context as argument. It should return a markup object. In the
following example, markFormatter is set to a pre-defined
procedure. After a few measures, it is set to a procedure that
produces a boxed number.

The file ‘scm/translation-functions.scm’ contains the
definitions of format-mark-numbers (the default format),
format-mark-box-numbers, format-mark-letters and
format-mark-box-letters. These can be used as inspiration
for other formatting functions.

You may use format-mark-barnumbers,
format-mark-box-barnumbers, and
format-mark-circle-barnumbers to get bar numbers instead of
incremented numbers or letters.

Other styles of rehearsal mark can be specified manually:

\mark "A1"

Note that Score.markFormatter does not affect marks specified
in this manner. However, it is possible to apply a \markup to the
string.

Grace notes

Grace notes are musical ornaments, printed in a smaller font, that take
up no additional logical time in a measure.

\relative {
c''4 \grace b16 a4(
\grace { b16 c16 } a2)
}

There are three other types of grace notes possible; the
acciaccatura – an unmeasured grace note indicated by a slurred
note with a slashed stem – and the appoggiatura, which takes a
fixed fraction of the main note it is attached to and prints without the
slash. It is also possible to write a grace note with a slashed stem,
like the acciaccatura but without the slur, so as to place it
between notes that are slurred themselves, using the
\slashedGrace function.

A \grace music expression will introduce special
typesetting settings, for example, to produce smaller type, and
set directions. Hence, when introducing layout tweaks to
override the special settings, they should be placed inside
the grace expression. The overrides should also be reverted
inside the grace expression. Here, the grace note’s default stem
direction is overridden and then reverted.

The layout of grace expressions can be changed throughout the music
using the functions add-grace-property and
remove-grace-property. The following example undefines the
Stem direction for this grace, so that stems do not always point
up, and changes the default note heads to crosses.

The global defaults for grace notes are stored in the identifiers
startGraceMusic, stopGraceMusic,
startAcciaccaturaMusic, stopAcciaccaturaMusic,
startAppoggiaturaMusic and stopAppoggiaturaMusic, which
are defined in the file ly/grace-init.ly. By redefining them
other effects may be obtained.

Setting the property 'strict-grace-spacing makes the musical
columns for grace notes ’floating’, i.e., decoupled from the non-grace
notes: first the normal notes are spaced, then the (musical columns of
the) graces are put left of the musical columns for the main notes.

Known issues and warnings

A multi-note beamed acciaccatura is printed without a slash,
and looks exactly the same as a multi-note beamed
appoggiatura.

Grace note synchronization can also lead to surprises. Staff
notation, such as key signatures, bar lines, etc., are also
synchronized. Take care when you mix staves with grace notes and
staves without, for example,

Please make sure that you use the \grace command for the
spacer part, even if the visual part uses \acciaccatura or
\appoggiatura because otherwise an ugly slur fragment will
be printed, connecting the invisible grace note with the following
note.

Grace sections should only be used within sequential music expressions.
Nesting or juxtaposing grace sections is not supported, and might
produce crashes or other errors.

Each grace note in MIDI output has a length of 1/4 of its actual
duration. If the combined length of the grace notes is greater than the
length of the preceding note a “Going back in MIDI time”
error will be generated. Either make the grace notes shorter in
duration, for example:

Aligning to cadenzas

In an orchestral context, cadenzas present a special problem: when
constructing a score that includes a measured cadenza or other solo
passage, all other instruments should skip just as many notes as the
length of the cadenza, otherwise they will start too soon or too late.

One solution to this problem is to use the functions
mmrest-of-length and skip-of-length. These Scheme
functions take a defined piece of music as an argument and generate a
multi-measure rest or \skip exactly as long as the piece.

See also

Time administration

Time is administered by the Timing_translator, which by
default is to be found in the Score context. An alias,
Timing, is added to the context in which the
Timing_translator is placed. To ensure that the
Timing alias is available, you may need to explicitly
instantiate the containing context (such as Voice or
Staff).

The following properties of Timing are used
to keep track of timing within the score.

currentBarNumber

The current measure number. For an example showing the
use of this property see Bar numbers.

measureLength

The length of the measures in the current time signature. For a
4/4 time this is 1, and for 6/8 it is 3/4. Its value
determines when bar lines are inserted and how automatic beams
should be generated.

measurePosition

The point within the measure where we currently are. This
quantity is reset by subtracting measureLength whenever
measureLength is reached or exceeded. When that happens,
currentBarNumber is incremented.

timing

If set to true, the above variables are updated for every time
step. When set to false, the engraver stays in the current
measure indefinitely.

Timing can be changed by setting any of these variables
explicitly. In the next example, the default 4/4 time
signature is printed, but measureLength is set to 5/4.
At 4/8 through the third measure, the measurePosition is
advanced by 1/8 to 5/8, shortening that bar by 1/8.
The next bar line then falls at 9/8 rather than 5/4.

As the example illustrates, ly:make-moment n/m constructs a
duration of n/m of a whole note. For example,
ly:make-moment 1/8 is an eighth note duration and
ly:make-moment 7/16 is the duration of seven sixteenths
notes.

Some of these articulations have shorthands for easier entry.
Shorthands are appended to the note name, and their syntax
consists of a dash - followed by a symbol signifying the
articulation. Predefined shorthands exist for marcato,
stopped, tenuto, staccatissimo,
accent, staccato, and portato.
Their corresponding output appears as follows:

\relative {
c''4-^ c-+ c-- c-!
c4-> c-. c2-_
}

The rules for the default placement of articulations are defined
in ‘scm/script.scm’. Articulations and ornamentations
may be manually placed above or below the staff; see
Direction and placement.

Articulations are Script objects. Their properties are
described more fully in Script.

Articulations can be attached to rests as well as notes but they
cannot be attached to multi-measure rests. A special predefined
command, \fermataMarkup, is available for attaching a fermata
to a multi-measure rest (and only a multi-measure rest). This
creates a MultiMeasureRestText object.

In addition to articulations, text and markups can be attached to
notes. See Text scripts.

For more information about the ordering of Scripts and TextScripts that
are attached to the notes, see Placement of objects.

Selected Snippets

Modifying default values for articulation shorthand notation

The shorthands are defined in ‘ly/script-init.ly’, where the
variables dashHat, dashPlus, dashDash,
dashBar, dashLarger, dashDot, and
dashUnderscore are assigned default values. The default values
for the shorthands can be modified. For example, to associate the
-+ (dashPlus) shorthand with the trill symbol instead of
the default + symbol, assign the value trill to the variable
dashPlus:

\relative c'' { c1-+ }
dashPlus = "trill"
\relative c'' { c1-+ }

Controlling the vertical ordering of scripts

The vertical ordering of scripts is controlled with the
'script-priority property. The lower this number, the closer it
will be put to the note. In this example, the TextScript (the
sharp symbol) first has the lowest priority, so it is put lowest in the
first example. In the second, the prall trill (the Script) has
the lowest, so it is on the inside. When two objects have the same
priority, the order in which they are entered determines which one
comes first.

Creating a delayed turn, where the lower note of the turn uses the
accidental, requires several overrides. The
outside-staff-priority property must be set to #f, as
otherwise this would take precedence over the avoid-slur
property. Changing the fractions 2/3 and 1/3 adjusts
the horizontal position.

Dynamics

Absolute dynamic marks are specified using a command after a note,
such as c4\ff. The available dynamic marks are
\ppppp, \pppp, \ppp, \pp, \p,
\mp, \mf, \f, \ff, \fff,
\ffff, \fffff, \fp, \sf, \sff,
\sp, \spp, \sfz, and \rfz. Dynamic
marks may be manually placed above or below the staff; see
Direction and placement.

\relative c'' {
c2\ppp c\mp
c2\rfz c^\mf
c2_\spp c^\ff
}

A crescendo mark is started with \< and
terminated with \!, an absolute dynamic, or an additional
crescendo or decrescendo mark. A decrescendo mark is
started with \> and is also terminated with \!, an
absolute dynamic, or another crescendo or decrescendo mark.
\cr and \decr may be used instead of \< and
\>. Hairpins are engraved by default using this
notation.

A hairpin that is terminated with \! will end at the
right edge of the note that has the \! assigned to it. In the
case where it is terminated with the start of another crescendo
or decrescendo mark, it will end at the centre of the note
that has the next \< or \> assigned to it. The next
hairpin will then start at the right edge of the same note
instead of the usual left edge had it been terminated with \!
before. A hairpin ending on a downbeat will stop at the preceding bar line.

\relative {
c''1\< | c4 a c\< a | c4 a c\! a\< | c4 a c a\!
}

Hairpins that are terminated with absolute dynamic marks instead of
\! will also be engraved in a similar way. However, the length
of the absolute dynamic itself can alter where the preceding hairpin
ends.

\relative {
c''1\< | c4 a c\mf a | c1\< | c4 a c\ffff a
}

Spacer rests are needed to engrave multiple marks on one note.
This is particularly useful when adding a crescendo and
decrescendo to the same note:

\relative {
c''4\< c\! d\> e\!
<< f1 { s4 s4\< s4\> s4\! } >>
}

The \espressivo command can be used to indicate a crescendo
and decrescendo on the same note. However, be warned that this is
implemented as an articulation, not a dynamic.

A Dynamics context is available to engrave dynamics on
their own horizontal line. Use spacer rests to indicate timing.
(Notes in a Dynamics context will also take up
musical time, but will not be engraved.)
The Dynamics context can usefully contain some other
items such as text scripts, text spanners, and piano pedal marks.

\relative c'' {
\override Hairpin.stencil = #flared-hairpin
a4\< a a a\f
a4\p\< a a a\ff
a4\sfz\< a a a\!
\override Hairpin.stencil = #constante-hairpin
a4\< a a a\f
a4\p\< a a a\ff
a4\sfz\< a a a\!
\override Hairpin.stencil = #flared-hairpin
a4\> a a a\f
a4\p\> a a a\ff
a4\sfz\> a a a\!
\override Hairpin.stencil = #constante-hairpin
a4\> a a a\f
a4\p\> a a a\ff
a4\sfz\> a a a\!
}

Vertically aligned dynamics and textscripts

All DynamicLineSpanner objects (hairpins and dynamic texts) are
placed with their reference line at least 'staff-padding from
the staff, unless other notation forces them to be farther. Setting
'staff-padding to a sufficiently large value aligns the dynamics.

The same idea, together with \textLengthOn, is used to align
the text scripts along their baseline.

Simple, centered dynamic marks are easily created with the
make-dynamic-script function.

sfzp = #(make-dynamic-script "sfzp")
\relative {
c'4 c c\sfzp c
}

In general, make-dynamic-script takes any markup object as its
argument. The dynamic font only contains the characters
f,m,p,r,s and z, so if a dynamic mark that includes
plain text or punctuation symbols is desired, markup commands that
reverts font family and font encoding to normal text should be used,
for example \normal-text. The interest of using
make-dynamic-script instead of an ordinary markup is ensuring
the vertical alignment of markup objects and hairpins that are
attached to the same note head.

Simultaneous or overlapping slurs require special attention. Most
occurences of outer slurs actually indicate phrasing, and phrasing
slurs may overlap a regular slur, see Phrasing slurs. When
multiple regular slurs are needed in a single Voice,
matching slur starts and ends need to be labelled by preceding
them with \= followed by an identifying key (a symbol or
non-negative integer).

\fixed c' {
<c~ f\=1( g\=2( >2 <c e\=1) a\=2) >
}

Slurs can be solid, dotted, or dashed. Solid is the default slur
style:

Slurs can be made with complex dash patterns by defining the
dash-definition property. dash-definition is a list of
dash-elements. A dash-element is a list of parameters
defining the dash behavior for a segment of the slur.

The slur is defined in terms of the bezier parameter t which ranges
from 0 at the left end of the slur to 1 at the right end of the slur.
dash-element is a list (start-t stop-t dash-fraction
dash-period). The region of the slur from start-t to
stop-t will have a fraction dash-fraction of each
dash-period black. dash-period is defined in terms of
staff spaces. dash-fraction is set to 1 for a solid slur.

Phrasing slurs

Phrasing slurs (or phrasing marks) that indicate a
musical sentence are written using the commands \( and
\) respectively:

\relative {
c''4\( d( e) f(
e2) d\)
}

Typographically, a phrasing slur behaves almost exactly like a
normal slur. However, they are treated as different objects; a
\slurUp will have no effect on a phrasing slur. Phrasing
may be manually placed above or below the staff; see
Direction and placement.

Simultaneous or overlapping phrasing slurs are entered using
\= as with regular slurs, see Slurs.

Phrasing slurs can be solid, dotted, or dashed. Solid is the default
style for phrasing slurs:

Breath marks

Breath marks are entered using \breathe:

{ c''2. \breathe d''4 }

Unlike other expressive marks, a breath mark is not associated with
the preceding note but is a separate music event. So all the
expressive marks which are attached to the preceding note, any square
brackets indicating manual beams, and any brackets indicating slurs
and phrasing slurs must be placed before \breathe.

A breath mark will end an automatic beam; to override this behavior, see
Manual beams.

\relative { c''8 \breathe d e f g2 }

Musical indicators for breath marks in ancient notation,
divisiones, are supported. For details, see Divisiones.

Selected Snippets

Changing the breath mark symbol

The glyph of the breath mark can be tuned by overriding the text
property of the BreathingSign layout object with any markup
text.

Vocal and wind music frequently uses a tick mark as a breathing sign.
This indicates a breath that subtracts a little time from the previous
note rather than causing a short pause, which is indicated by the comma
breath mark. The mark can be moved up a little to take it away from
the stave.

Falls and doits

Falls and doits can be added to notes using
the \bendAfter command. The direction of the fall or doit
is indicated with a plus or minus (up or down). The number
indicates the pitch interval that the fall or doit will extend
beyond the main note.

A glissando can connect notes in chords. If anything other than a
direct one-to-one pairing of the notes in the two chords is required
the connections between the notes are defined by setting
\glissandoMap, where the notes of a chord are assumed to be
numbered from zero in the order in which they appear in the input
‘.ly’ file.

A glissando which extends into several \alternative blocks can
be simulated by adding a hidden grace note with a glissando at the
start of each \alternative block. The grace note should be at
the same pitch as the note which starts the initial glissando. This is
implemented here with a music function which takes the pitch of the
grace note as its argument.

Note that in polyphonic music the grace note must be matched with
corresponding grace notes in all other voices.

Trills that require an auxiliary note with an explicit pitch can
be typeset with the \pitchedTrill command. The first
argument is the main note, and the second is the trilled
note, printed as a stemless note head in parentheses.

1.4 Repeats

Repetition is a central concept in music, and multiple notations
exist for repetitions. LilyPond supports the following kinds of
repeats:

volta

The repeated music is not written out but enclosed between repeat bar
lines. If the repeat is at the beginning of a piece, a repeat bar
line is only printed at the end of the repeat. Alternative endings
(volte) are printed left to right with brackets. This is the standard
notation for repeats with alternatives.

unfold

The repeated music is fully written out, as many times as
specified by repeatcount. This is useful when
entering repetitious music.

percent

These are beat or measure repeats. They look like single slashes or
percent signs.

1.4.1 Long repeats

This section discusses how to input long (usually multi-measure)
repeats. The repeats can take two forms: repeats enclosed between
repeat signs; or written-out repeats, used to input repetitious music.
Repeat signs can also be controlled manually.

Note: If there are two or more alternatives, nothing should appear
between the closing brace of one and the opening brace of the next
in an \alternative block, otherwise you will not get the
expected number of endings.

Note: If you include \relative inside a
\repeat without explicitly instantiating the
Voice context, extra (unwanted) staves will appear. See
An extra staff appears.

If a repeat that has no alternate endings starts in the middle of a
measure, it will usually end at a corresponding place in the middle of a
later measure (so that the two ends add up to one complete measure). In
this case the repeat signs are not ‘true’ bar lines so neither bar
checks nor \partial commands should be placed there:

c'4 e g
\repeat volta 4 {
e4 |
c2 e |
g4 g g
}
g4 |
a2 a |
g1 |

If a repeat that has no alternate endings starts with a partial measure,
then the same principles apply, except that a \partial command is
required at the start of the measure:

The \inStaffSegno command can be used to generate a composite
bar line incorporating the segno symbol with the appropriate repeat
bar line when used with the \repeat volta command. The
correct type of repeat bar line, viz. start repeat, end repeat or
double repeat, is selected automatically. Note that the
corresponding “D.S.” mark must be added manually.

Alternative bar line symbols can be obtained by setting (in the Score
context) the properties segnoType, startRepeatSegnoType,
endRepeatSegnoType or doubleRepeatSegnoType to the
required bar line type. The alternative bar line types must be
selected from the pre-defined types or types previously defined
with the \defineBarLine command (see Bar lines).

Selected Snippets

Shortening volta brackets

By default, the volta brackets will be drawn over all of the
alternative music, but it is possible to shorten them by setting
voltaSpannerDuration. In the next example, the bracket only
lasts one measure, which is a duration of 3/4.

The Volta_engraver by default resides in the Score
context, and brackets for the repeat are thus normally only printed
over the topmost staff. This can be adjusted by adding the
Volta_engraver to the Staff context where the brackets
should appear; see also the “Volta multi staff” snippet.

Known issues and warnings

Slurs that span from a \repeat block into an
\alternative block will only work for the first alternative
ending. The visual appearance of a continuing slur in other
alternative blocks may be simulated with \repeatTie if the
slur extends into only one note in the alternative block, although
this method does not work in TabStaff. Other methods which
may be tailored to indicate continuing slurs over several notes in
alternative blocks, and which also work in TabStaff contexts,
are shown in Modifying ties and slurs.

Also, slurs cannot wrap around from the end of one
alternative back to the beginning of the repeat.

Glissandi that span from a \repeat block into an
\alternative block will only work for the first alternative
ending. The visual appearance of a continuing glissando in other
alternative blocks may be indicated by coding a glissando starting
on a hidden grace note. For an example, see
“Extending glissandi across repeats” under Selected Snippets
in Glissando.

If a repeat that begins with an incomplete measure has an
\alternative block that contains modifications to the
measureLength property, using \unfoldRepeats will
result in wrongly-placed bar lines and bar check warnings.

A nested repeat like

\repeat …
\repeat …
\alternative

is ambiguous, since it is not clear to which \repeat the
\alternative belongs. This ambiguity is resolved by always
having the \alternative belong to the inner \repeat.
For clarity, it is advisable to use braces in such situations.

Manual repeat marks

Note: These methods are only used for displaying unusual repeat
constructs, and may produce unexpected behavior. In most cases,
repeats should be created using the standard \repeat command
or by printing the relevant bar lines. For more information, see
Bar lines.

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

Text can be included with the volta bracket. The text can be a
number or numbers or markup text, see Formatting text. The
simplest way to use markup text is to define the markup first,
then include the markup in a Scheme list.

1.4.2 Short repeats

This section discusses how to input short repeats. Short repeats can
take two forms: slashes or percent signs to represent repeats of a
single note, a single measure or two measures, and tremolos otherwise.

Tremolo repeats

Tremolos can take two forms: alternation between two chords or two
notes, and rapid repetition of a single note or chord. Tremolos
consisting of an alternation are indicated by adding beams between the
notes or chords being alternated, while tremolos consisting of the
rapid repetition of a single note are indicated by adding beams or
slashes to a single note.

The \repeat tremolo syntax expects exactly two notes within
the braces, and the number of repetitions must correspond to a
note value that can be expressed with plain or dotted notes. Thus,
\repeat tremolo 7 is valid and produces a double dotted
note, but \repeat tremolo 9 is not.

The duration of the tremolo equals the duration of the
braced expression multiplied by the number of repeats:
\repeat tremolo 8 { c16 d16 } gives a whole note tremolo,
notated as two whole notes joined by tremolo beams.

There are two ways to put tremolo marks on a single note. The
\repeat tremolo syntax is also used here, in which case
the note should not be surrounded by braces:

\repeat tremolo 4 c'16

The same output can be obtained by adding :N after
the note, where N indicates the duration of the
subdivision (it must be at least 8). If N is 8, one
beam is added to the note’s stem. If N is omitted,
the last value is used:

\relative {
c''2:8 c:32
c: c:
}

Selected Snippets

Cross-staff tremolos

Since \repeat tremolo expects exactly two musical arguments for
chord tremolos, the note or chord which changes staff within a
cross-staff tremolo should be placed inside curly braces together with
its \change Staff command.

However some notation, such as dynamics and hairpins must be
attached to the chord rather than to notes within the chord,
otherwise they will not print. Other notation like fingerings and
slurs will get placed markedly different when attached to notes
within a chord rather than to whole chords or single notes.

A chord acts merely as a container for its notes, its articulations and
other attached elements. Consequently, a chord without notes inside
does not actually have a duration. Any attached articulations will
happen at the same musical time as the next following note or chord and
be combined with them (for more complex possibilities of combining such
elements, see Simultaneous expressions):

Relative mode can be used for pitches in chords. The first note of
each chord is always relative to the first note of the chord that
came before it, or in the case where no preceding chord exists, the
pitch of the last note that came before the chord. All remaining notes
in the chord are relative to the note that came before it
within the same chord.

The chord repetition symbol always remembers the last instance of
a chord so it is possible to repeat the most recent chord even if
other non-chorded notes or rests have been added since.

\relative {
<a' c e>1 c'4 q2 r8 q8 |
q2 c, |
}

However, the chord repetition symbol does not retain any dynamics,
articulation or ornamentation within, or attached to, the previous
chord.

\relative {
<a'-. c\prall e>1\sfz c'4 q2 r8 q8 |
q2 c, |
}

To have some of them retained, the \chordRepeats function can be
be called explicitly with an extra argument specifying a list of
event types to keep unless events of that type are already
present on the q chord itself.

Here using \chordRepeats inside of a \relative construction
produces unexpected results: once chord events have been expanded, they
are indistinguishable from having been entered as regular chords, making
\relative assign an octave based on their current context.

Since nested instances of \relative don’t affect one another,
another \relative inside of \chordRepeats can be used for
establishing the octave relations before expanding the repeat chords.
In that case, the whole content of the inner \relative does not
affect the outer one; hence the different octave entry of the final note
in this example.

Interactions with \relative occur only with explicit calls of
\chordRepeats: the implicit expansion at the start of typesetting
is done at a time where all instances of \relative have already
been processed.

Simultaneous expressions

One or more music expressions enclosed in double angle brackets are
taken to be simultaneous. If the first expression begins with a
single note or if the whole simultaneous expression appears
explicitly within a single voice, the whole expression is placed on
a single staff; otherwise the elements of the simultaneous
expression are placed on separate staves.

This can be useful if the simultaneous sections have identical
rhythms, but attempts to attach notes with different durations to
the same stem will cause errors. Notes, articulations, and property
changes in a single ‘Voice’ are collected and engraved in
musical order:

\relative {
<a' c>4-. <>-. << c a >> << { c-. <c a> } { a s-. } >>
}

Multiple stems or beams or different note durations or properties at
the same musical time require the use of multiple voices.

The following example shows how simultaneous expressions can
generate multiple staves implicitly:

Clusters

A cluster indicates a continuous range of pitches to be played.
They can be denoted as the envelope of a set of notes. They are
entered by applying the function \makeClusters to a sequence
of chords, e.g.,

\relative \makeClusters { <g' b>2 <c g'> }

Ordinary notes and clusters can be put together in the same staff,
even simultaneously. In such a case no attempt is made to
automatically avoid collisions between ordinary notes and clusters.

See also

Known issues and warnings

Clusters look good only if they span at least two chords; otherwise
they appear too narrow.

Clusters do not have a stem and cannot indicate durations by
themselves, but the length of the printed cluster is determined by
the durations of the defining chords. Separate clusters need a
separating rest between them.

Here, voices are instantiated explicitly and are given names. The
\voiceOne … \voiceFour commands set up the voices
so that first and third voices get stems up, second and fourth
voices get stems down, third and fourth voice note heads are
horizontally shifted, and rests in the respective voices are
automatically moved to avoid collisions. The \oneVoice
command returns all the voice settings to the neutral default
directions.

Temporary polyphonic passages

A temporary polyphonic passage can be created with the following
construct:

<< { \voiceOne … }
\new Voice { \voiceTwo … }
>> \oneVoice

Here, the first expression within a temporary polyphonic passage is
placed into the Voice context which was in use immediately
before the polyphonic passage, and that same Voice context
continues after the temporary section. Other expressions within
the angle brackets are assigned to distinct temporary voices.
This allows lyrics to be assigned to one continuing voice before,
during and after a polyphonic section:

Here, the \voiceOne and \voiceTwo commands are
required to define the settings of each voice.

The double backslash construct

The << {…} \\ {…} >> construct, where the two (or
more) expressions are separated by double backslashes, behaves
differently to the similar construct without the double backslashes:
all the expressions within this construct are assigned
to new Voice contexts. These new Voice contexts
are created implicitly and are given the fixed names "1",
"2", etc.

This syntax can be used where it does not matter that temporary
voices are created and then discarded. These implicitly created
voices are given the settings equivalent to the effect of the
\voiceOne … \voiceFour commands, in the order in
which they appear in the code.

In the following example, the intermediate voice has stems up,
therefore we enter it in the third place, so it becomes voice
three, which has the stems up as desired. Spacer rests are
used to avoid printing doubled rests.

Identical rhythms

In the special case that we want to typeset parallel pieces of music
that have the same rhythm, we can combine them into a single
Voice context, thus forming chords. To achieve this, enclose
them in a simple simultaneous music construct within an explicit voice:

Collision resolution

The note heads of notes in different voices with the same pitch,
same note head and opposite stem direction are automatically
merged, but notes with different note heads or the same stem
direction are not. Rests opposite a stem in a different voice
are shifted vertically. The following example shows three
different circumstances, on beats 1 and 3 in bar 1 and beat 1
in bar 2, where the automatic merging fails.

The half note and eighth note at the start of the second measure
are incorrectly merged because the automatic merge cannot
successfully complete the merge when three or more notes line up in
the same note column, and in this case the merged note head is
incorrect. To allow the merge to select the correct note head
a \shift must be applied to the note that should not be
merged. Here, \shiftOn is applied to move the top
g out of the column, and \mergeDifferentlyHeadedOn
then works properly.

The \shiftOn command allows (but does not force) the notes
in a voice to be shifted. When \shiftOn is applied to a
voice, a note or chord in that voice is shifted only if its stem
would otherwise collide with a stem from another voice, and only
if the colliding stems point in the same direction. The
\shiftOff command prevents this type of shifting from
occurring.

By default, the outer voices (normally voices one and two) have
\shiftOff specified, while the inner voices (three and
above) have \shiftOn specified. When a shift is applied,
voices with upstems (odd-numbered voices) are shifted to the
right, and voices with downstems (even-numbered voices) are
shifted to the left.

Here is an example to help you visualize how an abbreviated
polyphonic expression would be expanded internally.

Note: Note that with three or more voices, the vertical order
of voices in your input file should not be the same as the
vertical order of voices on the staff!

Predefined commands

Selected Snippets

Additional voices to avoid collisions

In some instances of complex polyphonic music, additional voices are
necessary to prevent collisions between notes. If more than four
parallel voices are needed, additional voices can be added by defining
a variable using the Scheme function context-spec-music.

Automatic part combining

Automatic part combining is used to merge two separate parts of music
onto a single staff. This can be especially helpful when typesetting
orchestral scores. A single Voice is printed while the two parts
of music are the same, but in places where they differ, a second
Voice is printed. Stem directions are set up & down accordingly
while Solo and a due parts are also identified and marked
appropriately.

The syntax for automatic part combining is:

\partcombine musicexpr1musicexpr2

The following example demonstrates the basic functionality, putting
parts on a single staff as polyphony and setting stem directions
accordingly. The same variables are used for the independent parts and
the combined staff.

Both parts have identical notes in the third measure, so only one
instance of the notes is printed. Stem, slur, and tie directions are
set automatically, depending on whether the parts are playing solo or in
unison. When needed in polyphony situations, the first part (with
context called one) gets “up” stems, while the second (called
two) always gets “down” stems. In solo situations, the first
and second parts get marked with “Solo” and “Solo II”,
respectively. The unison (a due) parts are marked with the
text “a2”.

By default, the partcombiner merges two notes of the same pitch as an
a due note, combines notes with the same
rhythm less than a ninth apart as chords and separates notes more than
a ninth apart (or when the voices cross) into
separate voices. This can be overridden with an optional argument of a pair
of numbers after the \partcombine command: the first specifies
the interval where notes start to be combined (the default is zero) and the
second where the notes are split into separate voices. Setting the second
argument to zero means that the partcombiner splits notes with an interval of
a second or more, setting it to one splits notes of a third or more, and so on.

Both arguments to \partcombine will be interpreted as separate
Voice contexts, so if the music is being specified in relative
mode then both parts must contain a \relative function,
i.e.,

\partcombine
\relative … musicexpr1
\relative … musicexpr2

A \relative section that encloses a \partcombine has no
effect on the pitches of musicexpr1 or
musicexpr2.

In professional scores, voices are often kept apart from each other for
long passages of music even if some of the notes are the same in both
voices, and could just as easily be printed as unison. Combining notes
into a chord, or showing one voice as solo is, therefore, not ideal as
the \partcombine function considers each note separately. In this
case the \partcombine function can be overridden with one of the
following commands. All of the commands may be preceded with
\once in order to have them only apply to the next note in
the music expression.

\partcombineApart keeps the
notes as two separate voices, even if they can be combined into a chord
or unison.

\partcombineChords combines the
notes into a chord.

\partcombineUnisono combines
both voices as “unison”.

\partcombineSoloI prints only
voice one, and marks it as a “Solo”.

\partcombineSoloII prints only
voice two and marks it as a “Solo”.

\partcombineAutomatic ends
the functions of the commands above, and reverts back to the standard
\partcombine functionality.

Using \partcombine with lyrics

The \partcombine command is not designed to work with
lyrics; if one of the voices is explicitly named in order to
attach lyrics to it, the partcombiner will stop working. However,
this effect can be achieved using a NullVoice context. See
Polyphony with shared lyrics.

Selected Snippets

Combining two parts on the same staff

The part combiner tool ( \partcombine command ) allows the
combination of several different parts on the same staff. Text
directions such as “solo” or “a2” are added by default; to remove
them, simply set the property printPartCombineTexts to f.
For vocal scores (hymns), there is no need to add “solo/a2” texts,
so they should be switched off. However, it might be better not to use
it if there are any solos, as they won’t be indicated. In such cases,
standard polyphonic notation may be preferable.

This snippet presents the three ways two parts can be printed on a same
staff: standard polyphony, \partcombine without texts, and
\partcombine with texts.

Known issues and warnings

If printPartCombineTexts is set and the two voices play the same
notes “on and off”, in the same measure, the part combiner may
typeset a2 more than once in that measure.

\partcombine only knows when a note starts in a Voice; it
cannot, for example, remember if a note in one Voice has already
started when combining notes that have just started in the other
Voice. This can lead to a number of unexpected issues including
“Solo” or “Unison” marks being printed incorrectly.

\partcombine keeps all spanners (slurs, ties, hairpins, etc.) in
the same Voice so that if any such spanners start or end in a
different Voice, they may not be printed properly or at all.

If the \partcombine function cannot combine both music
expressions (i.e., when both voices have different durations), it will
give the voices, internally, its own custom names: one and
two respectively. This means if there is any “switch” to a
differently named Voice context, the events in that differently
named Voice will be ignored.

Writing music in parallel

Music for multiple parts can be interleaved in input code. The
function \parallelMusic accepts a list with the names of a
number of variables to be created, and a musical expression. The
content of alternate measures from the expression become the value
of the respective variables, so you can use them afterwards to
print the music.

Note: Bar checks | must be used, and the measures must
be of the same length.

Relative mode may be used. Note that the \relative command
is not used inside \parallelMusic itself. The notes are
relative to the preceding note in the voice, not to the previous
note in the input – in other words, relative notes for
voiceA ignore the notes in voiceB.

Instantiating new staves

The DrumStaff context creates a five-line staff set up for
a typical drum set. Each instrument is shown with a different
symbol. The instruments are entered in drum mode following a
\drummode command, with each instrument specified by name.
For details, see Percussion staves.

\new DrumStaff {
\drummode { cymc hh ss tomh }
}

RhythmicStaff creates a single-line staff that only
displays the rhythmic values of the input. Real durations are
preserved. For details, see Showing melody rhythms.

\new RhythmicStaff { c4 d e f }

TabStaff creates a tablature with six strings in standard
guitar tuning. For details, see Default tablatures.

\new TabStaff \relative { c''4 d e f }

There are two staff contexts specific for the notation of ancient
music: MensuralStaff and VaticanaStaff. They are
described in Pre-defined contexts.

The GregorianTranscriptionStaff context creates a staff to
notate modern Gregorian chant. It does not show bar lines.

Each staff group context sets the property
systemStartDelimiter to one of the following values:
SystemStartBar, SystemStartBrace, or
SystemStartBracket. A fourth delimiter,
SystemStartSquare, is also available, but it must be
explicitly specified.

If there is only one staff in one of the staff types ChoirStaff
or StaffGroup, by default the bracket and the starting bar line
will not be displayed. This can be changed by overriding
collapse-height to set its value to be less than the number of
staff lines in the staff.

Note that in contexts such as PianoStaff and GrandStaff
where the systems begin with a brace instead of a bracket, another
property has to be set, as shown on the second system in the example.

Selected Snippets

Nesting staves

The property systemStartDelimiterHierarchy can be used to make
more complex nested staff groups. The command \set
StaffGroup.systemStartDelimiterHierarchy takes an alphabetical list of
the number of staves produced. Before each staff a system start
delimiter can be given. It has to be enclosed in brackets and takes as
much staves as the brackets enclose. Elements in the list can be
omitted, but the first bracket takes always the complete number of
staves. The possibilities are SystemStartBar,
SystemStartBracket, SystemStartBrace, and
SystemStartSquare.

Separating systems

If the number of systems per page changes from page to page it is
customary to separate the systems by placing a system separator mark
between them. By default the system separator is blank, but can be
turned on with a \paper option.

See also

1.6.2 Modifying single staves

This section explains how to change specific attributes of one
staff: for example, modifying the number of staff lines or the
staff size. Methods to start and stop staves and set ossia
sections are also described.

The position of each staff line can also be altered. A list of
numbers sets each line’s position. 0 corresponds to the normal
center line, and the normal line positions are
(-4 -2 0 2 4). A single staff line is
printed for every value entered so that the number of staff lines, as
well as their position, can be changed with a single override.

To preserve typical stem directions (in the bottom half of the staff
stems point up, in the top half they point down), align the center
line (or space) of the customized staff with the position of the
normal center line (0). The clef position and the position of
middle C may need to be adjusted accordingly to fit the new
lines. See Clef.

Staff line thickness can be altered. Ledger lines and note stems, by
default, are also affected.

Ledger lines can also be made to appear inside the staff where custom
staff lines are required. The example shows the default position of
ledger lines when the explicit ledger-position is and is not set.
The \stopStaff is needed in the example to revert the
\override for the whole StaffSymbol.

Selected Snippets

Making some staff lines thicker than the others

For educational purposes, a staff line can be thickened (e.g., the
middle line, or to emphasize the line of the G clef). This can be
achieved by adding extra lines very close to the line that should be
emphasized, using the line-positions property of the
StaffSymbol object.

Ossia staves

However, the above example is not what is usually desired. To
create ossia staves that are above the original staff, have no
time signature or clef, and have a smaller font size, tweaks must
be used. The Learning Manual describes a specific technique to
achieve this goal, beginning with
Nesting music expressions.

The following example uses the alignAboveContext property
to align the ossia staff. This method is most appropriate when
only a few ossia staves are needed.

If many isolated ossia staves are needed, creating an empty
Staff context with a specific context id may be more
appropriate; the ossia staves may then be created by
calling this context and using \startStaff and
\stopStaff at the desired locations. The benefits of this
method are more apparent if the piece is longer than the following
example.

Using the \RemoveAllEmptyStaves command to create ossia
staves may be used as an alternative. This method is most
convenient when ossia staves occur immediately following a line
break. For more information about
\RemoveAllEmptyStaves, see Hiding staves.

Empty staves can be hidden (for a so-called ‘Frenched Score’)
by applying the \RemoveEmptyStaves command on a context, which
can be done globally (in a \layout block) as well as for
specific staves only (in a \with block). This command removes
all empty staves in a score except for those in the first system. If
you want those in the first system to be hidden also, use
\RemoveAllEmptyStaves. Supported contexts are Staff,
RhythmicStaff and VaticanaStaff.

Note: A staff is considered empty when it contains only
multi-measure rests, rests, skips, spacer rests, or a combination of these
elements.

Instrument names

Instrument names can be printed on the left side of staves in the
Staff, PianoStaff, StaffGroup, GrandStaff
and ChoirStaff contexts. The value of
instrumentName is used for the first staff, and the value
of shortInstrumentName is used for all succeeding staves.

However, if the instrument names are longer, the instrument names in a
staff group may not be centered unless the indent and
short-indent settings are increased. For details about these
settings, see \paper variables for shifts and indents.

To add instrument names to other contexts (such as ChordNames or
FiguredBass), Instrument_name_engraver must be added to
that context. For details, see Modifying context plug-ins.

The shortInstrumentName may be changed in the middle of a piece,
along with other settings as needed for the new instrument.
However, only the first instance of instrumentName will be
printed and subsequent changes will be ignored:

Quoting other voices

It is very common for one voice to use the same notes as those from
another voice. For example, first and second violins playing the same
phrase during a particular passage of the music. This is done by
letting one voice quote the other, without having to re-enter the
music all over again for the second voice.

The \addQuote command, used in the top level scope, defines a
stream of music from which fragments can be quoted.

The \quoteDuring command is used to indicate the point where the
quotation begins. It is followed by two arguments: the name of the
quoted voice, as defined with \addQuote, and a music expression
for the duration of the quote.

By default quoted music will include all articulations, dynamics,
markups, etc., in the quoted expression. It is possible to choose which
of these objects from the quoted music are displayed by using the
quotedEventTypes context property.

See also

Known issues and warnings

Only the contents of the first Voice occurring in an
\addQuote command will be considered for quotation, so if the music
expression contains \new or \context Voice
statements, their contents will not be quoted. Quoting grace notes
is unsupported and may cause LilyPond to crash whereas quoting nested
triplets may result in poor notation.

Formatting cue notes

The \cueClef command can also be used with an explict
CueVoice context if a change of clef is required and will print
an appropriately sized clef for the cue notes. The \cueClefUnset
command can then be used to switch back to the original clef, again with
an appropriately sized clef.

For more complex cue note placement, e.g including transposition, or
inserting cue notes from multiple music sources the \cueDuring or
\cueDuringWithClef commands can be used. These are more
specialized form of \quoteDuring, see Quoting other voices
in the previous section.

The syntax is:

\cueDuring #quotename #direction #music

and

\cueDuringWithClef #quotename #direction #clef #music

The music from the corresponding measures of the quote name
is added as a CueVoice context and occurs simultaneously with the
music, which then creates a polyphonic situation. The
direction takes the argument UP or DOWN, and
corresponds to the first and second voices respectively, determining how
the cue notes are printed in relation to the other voice.

It is possible to adjust which aspects of the music are quoted with
\cueDuring by setting the quotedCueEventTypes
property. Its default value is '(note-event rest-event
tie-event beam-event tuplet-span-event), which means that only
notes, rests, ties, beams and tuplets are quoted, but not
articulations, dynamic marks, markup, etc.

Note: When a Voice starts with cueDuring, as in the
following example, the Voice context must be explicitly declared,
or else the entire music expression would belong to the CueVoice
context.

Markup can be used to show the name of the quoted instrument.
If the cue notes require a change in clef,
this can be done manually but the original clef should also be
restored manually at the end of the cue notes.

Alternatively, the \cueDuringWithClef function can be used
instead. This command takes an extra argument to specify the change of
clef that needs to be printed for the cue notes but will automatically
print the original clef once the cue notes have finished.

Like \quoteDuring, \cueDuring takes instrument
transpositions into account. Cue notes are produced at the
pitches that would be written for the instrument receiving the cue
to produce the sounding pitches of the source instrument.

To transpose cue notes differently, use
\transposedCueDuring. This command takes an extra argument
to specify (in absolute mode) the printed pitch that you want to
represent the sound of a concert middle C. This is useful for
taking cues from an instrument in a completely different register.

The \killCues command removes cue notes from a music
expression, so the same music expression can be used to produce
the instrument part with cues and the score. The \killCues
command removes only the notes and events that were quoted by
\cueDuring. Other markup associated with cues, such as clef
changes and a label identifying the source instrument, can be
tagged for selective inclusion in the score; see Using tags.

See also

Known issues and warnings

Collisions can occur with rests, when using \cueDuring,
between Voice and CueVoice contexts. When using
\cueDuringWithClef or \transposedCueDuring the extra
argument required for each case must come after the quote and the
direction.

The \magnifyMusic command is not intended for cue notes,
grace notes, or ossia staves—there are more appropriate methods
of entering each of those constructs. Instead, it is useful when
the notation size changes in a single instrumental part on one
staff, and where grace notes are not appropriate, such as in
cadenza-like passages or in cases such as the above examples.
Setting the \magnifyMusic value to 0.63 duplicates the
dimensions of the CueVoice context.

The default font-size value for each layout object is
listed in the Internals Reference. The font-size property
can only be set for layout objects that support the
font-interface layout interface. If font-size is
not specified in the object’s ‘Standard settings’ list, its
value is 0. See All layout objects.

Understanding the fontSize property

The fontSize context property adjusts the relative size of
all glyph-based notational elements in a context:

The fontSize value is a number indicating the size relative
to the standard size for the current staff height. The default
fontSize is 0; adding 6 to any fontSize value
doubles the printed size of the glyphs, and subtracting 6 halves
the size. Each step increases the size by approximately 12%.

The scheme function magnification->font-size is provided
for convenience since the logarithmic units of the
font-size property are not entirely intuitive. For
example, to adjust the musical notation to 75% of the default
size, use:

\set fontSize = #(magnification->font-size 0.75)

The scheme function magstep does the opposite: it converts
a font-size value into a magnification factor.

The fontSize property will only affect notational elements
that are drawn with glyphs, such as noteheads, accidentals,
scripts, etc. It will not affect the size of the staff itself,
nor will it scale stems, beams, or horizontal spacing. To scale
stems, beams, and horizontal spacing along with the notation size
(without changing the staff size), use the \magnifyMusic
command discussed above. To scale everything, including the staff
size, see Setting the staff size.

Whenever the fontSizecontext property is set, its
value is added to the value of the font-sizegrob
property for individual layout objects, before any glyphs are
printed. This can cause confusion when setting individual
font-size properties while fontSize is already set:

% the default font-size for NoteHead is 0
% the default font-size for Fingering is -5
c''4-3
\set fontSize = -3
% the effective font size for NoteHead is now -3
% the effective font size for Fingering is now -8
c''4-3
\override Fingering.font-size = 0
% the effective font size for Fingering is now -3
c''4-3

Font size changes are achieved by scaling the design size that is
closest to the desired size. The standard font size (for
font-size = 0) depends on the standard staff height.
For a 20pt staff, an 11pt font is selected.

Known issues and warnings

There are currently two bugs that are preventing proper horizontal
spacing when using \magnifyMusic. There is only one
available workaround, and it is not guaranteed to work in every
case. In the example below, replace the mag variable with
your own value. You may also try removing one or both of the
\newSpacingSection commands, and/or the \override
and \revert commands:

Fingerings and string numbers applied to individual notes will
automatically avoid beams and stems, but this is not true by default
for fingerings and string numbers applied to the individual notes of
chords. The following example shows how this default behavior can be
overridden.

The full range of colors defined for X11 can be accessed by using
the Scheme function x11-color. The function takes one
argument; this can be a symbol in the form 'FooBar or
a string in the form "FooBar". The first form is
quicker to write and is more efficient. However, using the second
form it is possible to access X11 colors by the multi-word form of
its name.

If x11-color cannot make sense of the parameter then the
color returned defaults to black.

See also

Known issues and warnings

An X11 color is not necessarily exactly the same shade as a
similarly named normal color.

Not all X11 colors are distinguishable in a web browser, i.e.,
a web browser might not display a difference between LimeGreen
and ForestGreen. For web use normal colors are recommended
(i.e., blue, green, red).

Notes in a chord cannot be separately colored with
\override; use \tweak or the equivalent
\single\override before the respective note instead, see
The \tweak command.

There are two music functions, balloonGrobText and
balloonText; the former is used like
\once \override to attach text to any grob, and the
latter is used like \tweak, typically within chords, to
attach text to an individual note.

Balloon text does not influence note spacing, but this can be altered:

Grid lines

Vertical lines can be drawn between staves synchronized with the
notes.

The Grid_point_engraver must be used to create the end
points of the lines, while the Grid_line_span_engraver must
be used to actually draw the lines. By default this centers grid
lines horizontally below and to the left side of each note head.
Grid lines extend from the middle lines of each staff. The
gridInterval must specify the duration between the grid
lines.

1.8.1 Writing text

This section introduces different ways of adding text to a score.

Note: To write accented and special text (such as characters
from other languages), simply insert the characters directly into
the LilyPond file. The file must be saved as UTF-8. For more
information, see Text encoding.

Text scripts

Simple “quoted text” indications may be added to a score, as
demonstrated in the following example. Such indications may be
manually placed above or below the staff, using the syntax described
in Direction and placement.

\relative { a'8^"pizz." g f e a4-"scherz." f }

This syntax is actually a shorthand; more complex text formatting may be
added to a note by explicitly using a \markup block, as described
in Formatting text.

By default, text indications do not influence the note spacing. However,
their widths can be taken into account: in the following example, the
first text string does not affect spacing, whereas the second one does.

Text spanners

Some performance indications, e.g., rallentando or
accelerando, are written as text and are extended over
multiple notes with dotted lines. Such objects, called
“spanners”, may be created from one note to another using the
following syntax:

The string to be printed is set through object properties. By default
it is printed in italic characters, but different formatting can be
obtained using \markup blocks, as described in
Formatting text.

Postfix functions for custom crescendo text spanners. The spanners
should start on the first note of the measure. One has to use
-\mycresc, otherwise the spanner start will rather be assigned to the
next note.

Such objects are only typeset above the top staff of the score;
depending on whether they are specified at the end or the middle of a
bar, they can be placed above the bar line or between notes. When
specified at a line break, the mark will be printed at the beginning of
the next line.

\relative c'' {
\mark "Allegro"
c1 c
\mark "assai" \break
c c
}

Predefined commands

\markLengthOn,
\markLengthOff.

Selected Snippets

Printing marks at the end of a line

Marks can be printed at the end of the current line, instead of the
beginning of the following line. In such cases, it might be preferable
to align the right end of the mark with the bar line.

Separate text blocks can be spread over multiple pages,
making it possible to print text documents or books entirely
within LilyPond. This feature, and the specific syntax it
requires, are described in Multi-page markup.

Predefined commands

\markup,
\markuplist.

Selected Snippets

Stand-alone two-column markup

Stand-alone text may be arranged in several columns using
\markup commands:

Text markup introduction

A \markup block is used to typeset text with an extensible
syntax called “markup mode”.

The markup syntax is similar to LilyPond’s usual syntax: a
\markup expression is enclosed in curly braces
{… }. A single word is regarded as a minimal expression,
and therefore does not need to be enclosed with braces.

Unlike simple “quoted text” indications, \markup blocks may
contain nested expressions or markup commands, entered using the
backslash \ character. Such commands only affect the first
following expression.

A \markup block may also contain quoted text strings. Such
strings are treated as minimal text expressions, and therefore any
markup command or special character (such as \ and #)
will be printed verbatim without affecting the formatting of the text.
Double quotation marks themselves may be printed by preceding them
with backslashes.

To be treated as a distinct expression, a list of words needs to be
enclosed with double quotes or preceded by a command. The way markup
expressions are defined affects how these expressions will be stacked,
centered and aligned; in the following example, the second
\markup expression is treated the same as the first one:

The markup mode provides an easy way to select alternate font
families. The default serif font, of roman type, is automatically
selected unless specified otherwise; on the last line of the following
example, there is no difference between the first and the second word.

Some objects may have alignment procedures of their own, and therefore
are not affected by these commands. It is possible to move such
markup objects as a whole, as shown for instance in
Text marks.

Vertical alignment is a bit more complex. As stated above, markup
objects can be moved as a whole; however, it is also possible to move
specific elements inside a markup block. In this case, the element to
be moved needs to be preceded with an anchor point, that can be
another markup element or an invisible object. The following example
demonstrates these two possibilities; the last markup in this example
has no anchor point, and therefore is not moved.

Similarly, a list of elements or expressions may be spread to fill the
entire horizontal line width (if there is only one element, it will be
centered on the page). These expressions can, in turn, include
multi-line text or any other markup expression:

Advanced graphic features include the ability to include external
image files converted to the Encapsulated PostScript format
(eps), or to directly embed graphics into the input file, using
native PostScript code. In such a case, it may be useful to
explicitly specify the size of the drawing, as demonstrated below:

However, all these glyphs except the braces of various sizes contained
in fetaBraces are available using the simpler syntax described
in Music notation inside markup.

When using the glyphs contained in fetaBraces, the size of the
brace is specified by the numerical part of the glyph name, in
arbitrary units. Any integer from 0 to 575 inclusive
may be specified, 0 giving the smallest brace. The optimum
value must be determined by trial and error. These glyphs are all
left braces; right braces may be obtained by rotation, see
Rotating objects.

Each family may include different shapes and series. The following
example demonstrates the ability to select alternate families, shapes,
series and sizes. The value supplied to font-size is the
required change from the default size.

font-name can be described using a comma-separated list of ‘fonts’
and a white-space separated list of ‘styles’.
As long as the ‘font’ in the list is installed
and contains requested glyph, it will be used,
otherwise the next font in the list will be used instead.

Running lilypond with the following option displays a list of all
available fonts on the operating system:

Entire document fonts

It is possible to change the fonts to be used as the default fonts in
the roman, sans and typewriter font families by
specifying them, in that order, as shown in the example below, which
automatically scales the fonts with the value set for the global staff
size. Similar to Single entry fonts, it can be described using a
comma-separated list of ‘fonts’. However, font ‘styles’ can not be
described. For an explanation of fonts, see Fonts explained.

Entering lyrics

Lyrics are entered in a special input mode, which can be introduced
by the keyword \lyricmode, or by using \addlyrics or
\lyricsto. In this special input mode, the input d
is not parsed as the pitch D, but rather as a one-letter
syllable of text. In other words, syllables are entered like notes
but with pitches replaced by text.

For example:

\lyricmode { Three4 blind mice,2 three4 blind mice2 }

There are two main methods for specifying the horizontal placement
of the syllables, either by specifying the duration of each syllable
explicitly, as in the example above, or by leaving the lyrics to be
aligned automatically to a melody or other voice of music, using
\addlyrics or \lyricsto. The former method is
described below in Manual syllable durations. The latter
method is described in Automatic syllable durations.

A word or syllable of lyrics begins with an alphabetic character
(plus some other characters, see below) and is terminated by any
white space or a digit. Later characters in the syllable can be any
character that is not a digit or white space.

Because any character that is not a digit or white space is regarded
as part of the syllable, a word is valid even if it ends with
}, which often leads to the following mistake:

\lyricmode { lah lah lah}

In this example, the } is included in the final syllable, so the
opening brace is not balanced and the input file will probably not
compile. Instead, braces should always be surrounded with white space:

\lyricmode { lah lah lah }

Punctuation, lyrics with accented characters, characters from
non-English languages, or special characters (such as the heart
symbol or slanted quotes), may simply be inserted directly
into the input file, providing it is saved with UTF-8 encoding.
For more information, see Special characters.

The full definition of a word start in lyrics mode is somewhat more
complex. A word in lyrics mode is one that begins with an
alphabetic character, _, ?, !, :,
', the control characters ^A through ^F,
^Q through ^W, ^Y, ^^, any 8-bit
character with an ASCII code over 127, or a two-character
combination of a backslash followed by one of `, ',
", or ^.

Great control over the appearance of lyrics comes from using
\markup inside the lyrics themselves. For explanation of many
options, see Formatting text.

Aligning lyrics to a melody

Lyrics are interpreted in \lyricmode and printed in a
Lyrics context, see Contexts explained.

\new Lyrics \lyricmode { … }

Two variants of \lyricmode additionally set an associated
context used to synchronise the lyric syllables to music. The more
convenient \addlyrics immediately follows the musical content
of the Voice context with which it should be synchronised, implicitly
creating a Lyrics context of its own. The more versatile
\lyricsto requires both specifying the associated Voice context
by name and explicitly creating a containing Lyrics context. For
details see Automatic syllable durations.

Lyrics can be aligned with melodies in two main ways:

Lyrics can be aligned automatically, with the durations of the
syllables being taken from another voice of music or (in special
circumstances) an associated melody, using \addlyrics,
\lyricsto, or by setting the associatedVoice property.
For more details, see Automatic syllable durations.

The second stanza shows how the voice from which the lyric
durations are taken can be changed. This is useful if the words to
different stanzas fit the notes in different ways and all the
durations are available in Voice contexts. For more details, see
Stanzas.

Lyrics can be aligned independently of the duration of any notes
if the durations of the syllables are specified explicitly,
and entered with \lyricmode.

The first stanza is not aligned with the notes because the durations
were not specified, and the previous value of 2 is used for each
word.

The second stanza shows how the words can be aligned quite
independently from the notes. This is useful if the words to
different stanzas fit the notes in different ways and the required
durations are not available in a music context. For more details
see Manual syllable durations. This technique is also useful
when setting dialogue over music; for examples showing this, see
Dialogue over music.

Automatic syllable durations

Lyrics can be automatically aligned to the notes of a melody in
three ways:

by specifying the named Voice context containing the melody with
\lyricsto,

by introducing the lyrics with \addlyrics and placing them
immediately after the Voice context containing the melody,

by setting the associatedVoice property, the alignment of
the lyrics may be switched to a different named Voice context at
any musical moment.

In all three methods hyphens can be drawn between the syllables of
a word and extender lines can be drawn beyond the end of a word. For
details, see Extenders and hyphens.

The Voice context containing the melody to which the lyrics
are being aligned must not have “died”, or the lyrics after that
point will be lost. This can happen if there are periods when that
voice has nothing to do. For methods of keeping contexts alive, see
Keeping contexts alive.

Using \lyricsto

Lyrics can be aligned under a melody automatically by specifying
the named Voice context containing the melody with
\lyricsto:

This aligns the lyrics to the notes of the named Voice
context, which must already exist. Therefore normally the
Voice context is specified first, followed by the
Lyrics context. The lyrics themselves follow the
\lyricsto command. The \lyricsto command
invokes lyric mode automatically. By default, the lyrics are placed
underneath the notes. For other placements, see
Placing lyrics vertically.

Using \addlyrics

The \addlyrics command is just a convenient shortcut that
can sometimes be used instead of having to set up the lyrics
through a more complicated LilyPond structure.

The command \addlyrics cannot handle polyphonic settings.
Also, it cannot be used to associate lyrics to a TabVoice.
For these cases one should use \lyricsto.

Using associatedVoice

The melody to which the lyrics are being aligned can be changed by
setting the associatedVoice property,

\set associatedVoice = #"lala"

The value of the property (here: "lala") should be the name
of a Voice context. For technical reasons, the \set
command must be placed one syllable before the one to which the
change in voice is to apply.

Manual syllable durations

In some complex vocal music, it may be desirable to place lyrics
completely independently of notes. In this case do not use
\lyricsto or \addlyrics and do not set
associatedVoice. Syllables are entered like notes –
but with pitches replaced by text – and the duration of each
syllable is entered explicitly after the syllable.

Hyphenated lines may be drawn between syllables
as usual, but extender lines cannot be drawn when there is no
associated voice.

Multiple syllables to one note

In order to assign more than one syllable to a single note with
spaces between the syllables, you can surround the phrase with
quotes or use a _ character. Alternatively, you can use
the tilde symbol (~) to get a lyric tie.

Multiple notes to one syllable

Sometimes, particularly in Medieval and baroque music, several notes are
sung on one syllable; this is called melisma, see
melisma. The syllable to a melisma is usually
left-aligned with the first note of the melisma.

When a melisma occurs on a syllable other than the last one in a
word, that syllable is usually joined to the following one with a
hyphenated line. This is indicated by placing a double hyphen,
--, immediately after the syllable.

Alternatively, when a melisma occurs on the last or only syllable in
a word an extender line is usually drawn from the end of the syllable
to the last note of the melisma. This is indicated by placing a
double underscore, __, immediately after the word.

There are five ways in which melismata can be indicated:

Melismata are created automatically over notes which are tied
together:

Other settings for melismaBusyProperties can be used to
selectively include or exclude ties, slurs, and beams from the
automatic detection of melismata; see melismaBusyProperties
in Tunable context properties.

If a melisma is required during a passage in which
melismaBusyProperties is active, it may be indicated by
placing a single underscore in the lyrics for each note which
should be included in the melisma:

Extenders and hyphens

In the last syllable of a word, melismata are sometimes indicated with
a long horizontal line starting in the melisma syllable, and ending in
the next one. Such a line is called an extender line, and it is
entered as ‘ __ ’ (note the spaces before and after the two
underscore characters).

Note: Melismata are indicated in the score with extender lines,
which are entered as one double underscore; but short melismata can
also be entered by skipping individual notes, which are entered as
single underscore characters; these do not make an extender line to be
typeset by default.

Centered hyphens are entered as ‘ -- ’ between syllables of a
same word (note the spaces before and after the two hyphen
characters). The hyphen will be centered between the syllables, and
its length will be adjusted depending on the space between the
syllables.

In tightly engraved music, hyphens can be removed. Whether this
happens can be controlled with the minimum-distance (minimum
distance between two syllables) and the minimum-length
(threshold below which hyphens are removed) properties of
LyricHyphen.

Durations do not need to be added if the variable is to be invoked
with \addlyrics or \lyricsto.

For different or more complex orderings, the best way is to define
the music and lyric variables first, then set up the hierarchy of
staves and lyrics, omitting the lyrics themselves, and then add the
lyrics using \context underneath. This ensures that the
voices referenced by \lyricsto have always been defined
earlier. For example:

Placing lyrics vertically

Depending on the type of music, lyrics may be positioned
above the staff, below the staff, or between staves. Placing
lyrics below the associated staff is the easiest, and can be
achieved by simply defining the Lyrics context below the Staff
context:

Alternatively, a two-step process may be used. First the Lyrics
context is declared (without any content) before the Staff and
Voice contexts, then the \lyricsto command is placed after
the Voice declaration it references by using \context, as
follows:

Selected Snippets

Lyrics alignment

Horizontal alignment for lyrics can be set by overriding the
self-alignment-X property of the LyricText object.
#-1 is left, #0 is center and #1 is right;
however, you can use #LEFT, #CENTER and #RIGHT as
well.

Repeats with alternative endings

If the words of the repeated section are the same, and none of the
\alternative blocks start with a rest, exactly the same
structure can be used for both the lyrics and music. This has the
advantage that \unfoldRepeats will expand both music and
lyrics correctly.

But when the repeated section has different words, or when one
of the \alternative blocks starts with a rest, a repeat
construct cannot be used around the words and \skip commands
have to be inserted manually to skip over the notes in the
alternative sections which do not apply.

Note: do not use an underscore, _, to skip notes – an
underscore indicates a melisma, causing the preceding syllable
to be left-aligned.

Note: The \skip command must be followed by a number,
but this number is ignored in lyrics which derive their durations
from the notes in an associated melody through addlyrics or
lyricsto. Each \skip skips a single note of any
value, irrespective of the value of the following number.

When a note is tied over into two or more alternative endings a
tie is used to carry the note into the first alternative ending and
a \repeatTie is used in the second and subsequent endings.
This structure causes difficult alignment problems when lyrics are
involved and increasing the length of the alternative sections so
the tied notes are contained wholly within them may give a more
acceptable result.

The tie creates a melisma into the first alternative, but not into
the second and subsequent alternatives, so to align the lyrics
correctly it is necessary to disable the automatic creation of
melismata over the volta section and insert manual skips.

Divisi lyrics

When just the words and rhythms of the two parts differ with the
pitches remaining the same, temporarily turning off the automatic
detection of melismata and indicating the melisma in the lyrics
may be the appropriate method to use:

It is common in choral music to have a voice part split for
several measures. The << {…} \\ {…} >>
construct, where the two (or more) musical expressions are
separated by double backslashes, might seem the proper way to
set the split voices. This construct, however, will assign
all the expressions within it to NEW Voice
contexts which will result in no lyrics being set for
them since the lyrics will be set to the original voice context
– not, typically, what one wants. The temporary polyphonic
passage is the proper construct to use, see section
Temporary polyphonic passages in Single-staff polyphony.

Polyphony with shared lyrics

When two voices with different rhythms share the same lyrics,
aligning the lyrics to one of the voices may lead to problems in
the other voice. For example, the second lyric extender below is
too short, since the lyrics are aligned only to the top voice:

To get the desired result, align the lyrics to a new
NullVoice context containing a suitable combination of the
two voices. The notes of the NullVoice context do not
appear on the printed page, but can be used to align the lyrics
appropriately:

Adding dynamics marks to stanzas

Stanzas differing in loudness may be indicated by putting a
dynamics mark before each stanza. In LilyPond, everything coming in
front of a stanza goes into the StanzaNumber object; dynamics
marks are no different. For technical reasons, you have to set the
stanza outside \lyricmode:

Stanzas with different rhythms

Often, different stanzas of one song are put to one melody in slightly
differing ways. Such variations can still be captured with
\lyricsto.

Ignoring melismata

One possibility is that the text has a melisma in one stanza, but
multiple syllables in another. One solution is to make the faster
voice ignore the melisma. This is done by setting
ignoreMelismata in the Lyrics context.

Known issues and warnings

Like associatedVoice, includeGraceNotes needs to be
set at latest one syllable before the one which is to be put under a
grace note. For the case of a grace note at the very beginning of a
piece of music, consider using a \with or \context
block:

The text for the first stanza is set to the melody called
‘lahlah’ in the usual way, but the second stanza is set initally
to the lahlah context and is then switched to the
alternative melody for the syllables ‘ran’ to ‘sau’ by
the lines:

Here, alternative is the name of the Voice context
containing the triplet.

Note the placement of the \set associatedVoice command –
it appears to be one syllable too early, but this is correct.

Note: The set associatedVoice command must be placed
one syllable before the one at which the switch to the new
voice is to occur. In other words, changing the associated Voice
happens one syllable later than expected. This is for technical
reasons, and it is not a bug.

Printing stanzas at the end

Sometimes it is appropriate to have one stanza set
to the music, and the rest added in verse form at
the end of the piece. This can be accomplished by adding
the extra verses into a \markup section outside
of the main score block. Notice that there are two
different ways to force linebreaks when using
\markup.

Printing stanzas at the end in multiple columns

When a piece of music has many verses, they are often printed in
multiple columns across the page. An outdented verse number often
introduces each verse. The following example shows how to produce such
output in LilyPond.

2.1.4 Songs

References for songs

Songs are usually written on three staves with the melody for the
singer on the top staff and two staves of piano accompaniment at
the bottom. The lyrics of the first stanza are printed immediately
underneath the top staff. If there are just a small number of
further stanzas these can be printed immediately under the first
one, but if there are more stanzas than can be easily accommodated
there the second and subsequent stanzas are printed after the music
as stand-alone text.

All the notational elements needed to write songs are fully described
elsewhere:

References for choral

Choral music is usually notated on two, three or four staves within
a ChoirStaff group. Accompaniment, if required, is placed
beneath in a PianoStaff group, which is usually reduced in
size for rehearsal of a cappella choral works. The notes for
each vocal part are placed in a Voice context, with each staff
being given either a single vocal part (i.e., one Voice) or
a pair of vocal parts (i.e., two Voices).

Words are placed in Lyrics contexts, either underneath each
corresponding music staff, or one above and one below the music
staff if this contains the music for two parts.

Several common topics in choral music are described fully elsewhere:

An introduction to creating an SATB vocal score can be found in
the Learning Manual, see Four-part SATB vocal score.
There is also a built-in template which simplifies the entry of
SATB vocal music, see Built-in templates.

Several templates suitable for various styles of choral music can
also be found in the Learning Manual, see
Vocal ensembles templates.

Shape note heads, as used in Sacred Harp and similar notation, are
described in Shape note heads.

When two vocal parts share a staff the stems, ties, slurs, etc., of
the higher part will be directed up and those of the lower part
down. To do this, use \voiceOne and \voiceTwo. See
Single-staff polyphony.

When a vocal part temporarily splits, you should use
Temporary polyphonic passages
(see Single-staff polyphony).

Score layouts for choral

Choral music containing four staves, with or without piano
accompaniment, is usually laid out with two systems per page.
Depending on the page size, achieving this may require changes
to several default settings. The following settings should be
considered:

The global staff size can be modified to change the overall size
of the elements of the score. See Setting the staff size.

The distances between the systems, the staves and the lyrics can
all be adjusted independently. See Vertical spacing.

The dimensions of the vertical layout variables can be displayed as
an aid to adjusting the vertical spacing. This and other
possibilities for fitting the music onto fewer pages are described
in Fitting music onto fewer pages.

If the number of systems per page changes from one to two it is
customary to indicate this with a system separator mark between
the two systems. See Separating systems.

Dynamic markings by default are placed below the staff, but in
choral music they are usually placed above the staff in order to
avoid the lyrics. The predefined command \dynamicUp does
this for the dynamic markings in a single Voice context.
If there are many Voice contexts this predefined command
would have to be placed in every one. Alternatively its expanded
form can be used to place all dynamic markings in the entire score
above their respective staves, as shown here:

2.1.6 Opera and stage musicals

The music, lyrics and dialogue to opera and stage musicals are
usually set out in one or more of the following forms:

A Conductors’ Score containing the full orchestral and vocal
parts, together with libretto cues if there are spoken passages.

Orchestral Parts containing the music for the individual
instruments of the orchestra or band.

A Vocal Score containing all vocal parts with piano
accompaniment. The accompaniment is usually an orchestral
reduction, and if so the name of the original orchestral instrument
is often indicated. Vocal scores sometimes includes stage
directions and libretto cues.

A Vocal Book containing just the vocal parts
(no accompaniment), sometimes combined with the libretto.

A Libretto containing the extended passages of spoken
dialogue usually found in musicals, together with the words to the
sung parts. Stage directions are usually included. LilyPond can
be used to typeset libretti but as they contain no music
alternative methods may be preferable.

The sections in the LilyPond documentation which cover the topics
needed to create scores in the styles commonly found in opera and
musicals are indicated in the References below. This is followed
by sections covering those techniques which are peculiar to
typesetting opera and musical scores.

References for opera and stage musicals

The printing of empty staves in conductors’ scores and vocal scores
is often suppressed. To create such a “Frenched score” see
Hiding staves.

Writing orchestral parts is covered in Writing parts.
Other sections in the Specialist notation chapter may be relevant,
depending on the orchestration used. Many instruments are
transposing instruments, see Instrument transpositions.

If the number of systems per page changes from page to page it is
customary to separate the systems with a system separator mark.
See Separating systems.

Dialogue cues, stage directions and footnotes can be inserted, see
Creating footnotes and Text. Extensive stage directions
can also be added with a section of stand-alone markups between two
\score blocks, see Separate text.

When two or more characters share a staff the character’s name is
usually printed above the staff at the start of every section
applying to that character. This can be done with markup. Often a
specific font is used for this purpose.

Alternatively, if there are many character changes, it may be easier
to set up variables to hold the definitions for each character so
that the switch of characters can be indicated easily and concisely.

Musical cues

Musical cues can be inserted in Vocal Scores, Vocal Books and
Orchestral Parts to indicate what music in another part
immediately precedes an entry. Also, cues are often inserted in the
piano reduction in Vocal Scores to indicate what each orchestral
instrument is playing. This aids the conductor when a full
Conductors’ Score is not available.

The basic mechanism for inserting cues is fully explained in the
main text, see Quoting other voices and
Formatting cue notes. But when many cues have to be
inserted, for example, as an aid to a conductor in a vocal score,
the instrument name must be positioned carefully just before and
close to the start of the cue notes. The following example shows
how this is done.

If a transposing instrument is being quoted the instrument part should
specify its key so the conversion of its cue notes will be done
automatically. The example below shows this transposition for a
B-flat clarinet. The notes in this example are low on the staff so
DOWN is specified in \cueDuring (so the stems are
down) and the instrument name is positioned below the staff.

From these two examples it is clear that inserting many cues in a
Vocal Score would be tedious, and the notes of the piano part would
become obscured. However, as the following snippet shows, it is
possible to define a music function to reduce the amount of typing
and to make the piano notes clearer.

Selected Snippets

Adding orchestral cues to a vocal score

This shows one approach to simplify adding many orchestral cues to the
piano reduction in a vocal score. The music function \cueWhile
takes four arguments: the music from which the cue is to be taken, as
defined by \addQuote, the name to be inserted before the cue
notes, then either #UP or #DOWN to specify either
\voiceOne with the name above the staff or \voiceTwo
with the name below the staff, and finally the piano music in parallel
with which the cue notes are to appear. The name of the cued
instrument is positioned to the left of the cued notes. Many passages
can be cued, but they cannot overlap each other in time.

Known issues and warnings

\cueDuring automatically inserts a CueVoice context
and all cue notes are placed in that context. This means it is not
possible to have two overlapping sequences of cue notes by this
technique. Overlapping sequences could be entered by explicitly
declaring separate CueVoice contexts and using
\quoteDuring to extract and insert the cue notes.

For longer phrases it may be necessary to expand the music to make
the words fit neatly. There is no provision in LilyPond to do this
fully automatically, and some manual intervention to layout the
page will be necessary.

For long phrases or for passages with a lot of closely packed
dialogue, using a Lyrics context will give better results. The
Lyrics context should not be associated with a music Voice; instead
each section of dialogue should be given an explicit duration. If
there is a gap in the dialogue, the final word should be separated
from the rest and the duration split between them so that the
underlying music spaces out smoothly.

If the dialogue extends for more than one line it will be necessary
to manually insert \breaks and adjust the placing of the
dialogue to avoid running into the right margin. The final word of
the last measure on a line should also be separated out, as above.

2.1.7 Chants psalms and hymns

The music and words for chants, psalms and hymns usually follow a
well-established format in any particular church. Although the
formats may differ from church to church the type-setting problems
which arise are broadly similar, and are covered in this section.

Chants for psalms in the Anglican tradition are usually either
single, with 7 bars of music, or double, with two lots
of 7 bars. Each group of 7 bars is divided into two halves,
corresponding to the two halves of each verse, usually separated by
a double bar line. Only whole and half notes are used. The 1st bar
in each half always contains a single chord of whole notes. This is
the “reciting note”. Chants are usually centered on the page.

Canticles and other liturgical texts may be set more freely, and
may use notational elements from ancient music. Often the words
are shown underneath and aligned with the notes. If so, the notes
are spaced in accordance with the syllables rather than the notes’
durations.

Ancient notation template – modern transcription of gregorian music

This example demonstrates how to do modern transcription of Gregorian
music. Gregorian music has no measure, no stems; it uses only half and
quarter note heads, and special marks, indicating rests of different
length.

Pointing a psalm

The words to an Anglican psalm are usually printed in separate
verses centered underneath the chant.

Single chants (with 7 bars) are repeated for every verse. Double
chants (with 14 bars) are repeated for every pair of verses. Marks
are inserted in the words to show how they should be fitted to the
chant. Each verse is divided into two halves. A colon is usually
used to indicate this division. This corresponds to the double bar
line in the music. The words before the colon are sung to the first
three bars of music; the words after the colon are sung to the last
four bars.

Single bar lines (or in some psalters an inverted comma or similar
symbol) are inserted between words to indicate where the bar lines
in the music fall. In markup mode a single bar line can be entered
with the bar check symbol, |.

Where there is one whole note in a bar all the words corresponding
to that bar are recited on that one note in speech rhythm. Where
there are two notes in a bar there will usually be only one or two
corresponding syllables. If there are more that two syllables a
dot is usually inserted to indicate where the change in note occurs.

Partial measures in hymn tunes

Hymn tunes frequently start and end every line of music with
partial measures so that each line of music corresponds exactly
with a line of text. This requires a \partial command at
the start of the music and \bar "|" or \bar "||"
commands at the end of each line.

Hymn template

This code shows one way of setting out a hymn tune when each line
starts and ends with a partial measure. It also shows how to add the
verses as stand-alone text under the music.

2.2 Keyboard and other multi-staff instruments

This section discusses several aspects of music notation that are
unique to keyboard instruments and other instruments notated on
many staves, such as harps and vibraphones. For the purposes of
this section this entire group of multi-staff instruments is called
“keyboards” for short, even though some of them do not have a
keyboard.

References for keyboards

Keyboard instruments are usually notated with Piano staves. These
are two or more normal staves coupled with a brace. The same
notation is also used for other keyed instruments.
Organ music is normally written with two staves inside a
PianoStaff group and third, normal staff for the pedals.

The staves in keyboard music are largely independent, but
sometimes voices can cross between the two staves. This
section discusses notation techniques particular to keyboard
music.

Several common issues in keyboard music are covered elsewhere:

Keyboard music usually contains multiple voices and the
number of voices may change regularly; this is described in
Collision resolution.

If the beaming needs to be tweaked, make any changes to the stem
directions first. The beam positions are then measured from the
center of the staff that is closest to the beam. For a simple
example of beam tweaking, see
notation
Fixing overlapping notation.

The stem and slur overlap the intervening line of dynamics
because automatic collision resolution is suspended for beams, slurs
and other spanners that connect notes on different staves,
as well as for stems and articulations if their placement is
affected by a cross-staff spanner.
The resulting collisions must be resolved manually, where necessary,
using the methods in Fixing overlapping notation.

Changing staff automatically

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

\autochange …music…

This will create two staves inside the current staff group
(usually a PianoStaff), called "up" and
"down". The lower staff will be in the bass clef by default.
The autochanger switches on the basis of the pitch (middle C is the
turning point), and it looks ahead skipping over rests to switch
in advance.

\new PianoStaff {
\autochange {
g4 a b c'
d'4 r a g
}
}

It is possible to specify other pitches for the turning point.
If the staves are not instantiated explicitly, other clefs may be used.

For the time being, this engraver can not be specified by its name in
double quotes, but rather prefixing its name with a hash symbol
#, due to the way it is implemented.

Selected Snippets

Indicating cross-staff chords with arpeggio bracket

An arpeggio bracket can indicate that notes on two different staves are
to be played with the same hand. In order to do this, the
PianoStaff must be set to accept cross-staff arpeggios and the
arpeggios must be set to the bracket shape in the PianoStaff
context.

Discant symbols

Accordions are often built with more than one set of reeds that may be
in unison with, an octave above, or an octave below the written pitch.
Each accordion maker has different names for the shifts that
select the various reed combinations, such as oboe,
musette, or bandonium, so a system of symbols has
come into use to simplify the performance instructions.

Selected Snippets

Accordion register symbols

Accordion register symbols are available as \markup as well as
as standalone music events (as register changes tend to occur between
actual music events. Bass registers are not overly standardized. The
available commands can be found in ’Accordion Registers’ in the
Notation Reference.