# LilyPond — Notation Reference

 This manual provides a reference for all notation that can be produced with LilyPond version 2.16.2. It assumes that the reader is familiar with the material in the Learning Manual.
 For more information about how this manual fits with the other documentation, or to read this manual in other formats, see Manuals. If you are missing any manuals, the complete documentation can be found at http://www.lilypond.org/.

# 1. Musical notation

This chapter explains how to create musical notation.

## 1.1 Pitches

This section discusses how to specify the pitch of notes. There are three steps to this process: input, modification, and output.

### 1.1.1 Writing pitches

This section discusses how to input pitches. There are two different ways to place notes in octaves: absolute and relative mode. In most cases, relative mode will be more convenient.

#### Absolute octave entry

A pitch name is specified using lowercase letters a through g. The note names c to b are engraved in the octave below middle C.

{
\clef bass
c4 d e f
g4 a b c
d4 e f g
}


Other octaves may be specified with a single quote (') or comma (,) character. Each ' raises the pitch by one octave; each , lowers the pitch by an octave.

{
\clef treble
c'4 c'' e' g
d''4 d' d c
\clef bass
c,4 c,, e, g
d,,4 d, d c
}


Music Glossary: Pitch names.

Snippets: Pitches.

#### Relative octave entry

When octaves are specified in absolute mode it is easy to accidentally put a pitch in the wrong octave. Relative octave mode reduces these errors since most of the time it is not necessary to indicate any octaves at all. Furthermore, in absolute mode a single mistake may be difficult to spot, while in relative mode a single error puts the rest of the piece off by one octave.

\relative startpitch musicexpr


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, and it is recommended that it be a octave of c.

Here is the relative mode shown in action:

\relative c {
\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'' {
c g c f,
c' a, e'' c
}


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

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


When \relative blocks are nested, the innermost \relative block applies.

\relative c' {
c d e f
\relative c'' {
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 c' {
d e
\transpose f g {
d e
\relative c' {
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
<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.

\relative c'' {
c2 fis
c2 ges
b2 eisis
b2 feses
}


One consequence of these rules is that the first note inside \relative f music is interpreted just the same as if it was written in absolute pitch mode.

Music Glossary: fifth, interval, Pitch names.

Notation Reference: Octave checks.

Snippets: Pitches.

Internals Reference: RelativeOctaveMusic.

If no startpitch is specified for \relative, then c' is assumed. However, this is a deprecated option and may disappear in future versions, so its use is discouraged.

#### Accidentals

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

ais1 aes aisis aeses


A natural will cancel the effect of an accidental or key signature. However, naturals are not encoded into the note name syntax with a suffix; a natural pitch is shown as a simple note name:

a4 aes a2


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

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. These extra accidentals can also be used to produce natural signs.

cis cis cis! cis? c c c! c?


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

cis1~ cis~
\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.

\relative c'' {
\override Accidental #'hide-tied-accidental-after-break = ##t
cis1~ cis~
\break
cis
}


Preventing extra naturals from being automatically added

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

\relative c'' {
aeses4 aes ais a
\set Staff.extraNatural = ##f
aeses4 aes ais a
}


Music Glossary: sharp, flat, double sharp, double flat, Pitch names, quarter tone.

Learning Manual: Accidentals and key signatures.

Snippets: Pitches.

Internals Reference: Accidental_engraver, Accidental, AccidentalCautionary, accidental-interface.

#### Known issues and warnings

There are no generally accepted standards for denoting quarter-tone accidentals, so LilyPond’s symbol does not conform to any standard.

#### 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' {
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

do 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

-s

-b

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

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

-cs

-cb

-tcs

-tcb

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.

Music Glossary: Pitch names, Common Practice Period.

Notation Reference: Common notation for non-Western music.

Installed Files: ‘scm/define-note-names.scm’.

Snippets: Pitches.

### 1.1.2 Changing multiple pitches

This section discusses how to modify pitches.

#### 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'' {
c2 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, but the previous note is not changed. Future notes are relative to the controlpitch.

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


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

\relative c'' {
c4 f g f

c4
\octaveCheck c'
f
\octaveCheck c'
g
\octaveCheck c'
f
}


Snippets: Pitches.

Internals Reference: RelativeOctaveCheck.

#### Transpose

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

\transpose frompitch topitch musicexpr


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 c' {
\key d \major
d4 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 c' {
\key c \major
c4 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.

music = \relative c' { c d e f }
\new Staff {
\transpose c cis { \music }
\transpose c des { \music }
}


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

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


#### Selected Snippets

Transposing pitches with minimum accidentals ("Smart" transpose)

This example uses some Scheme code to enforce enharmonic modifications for notes in order to have the minimum number of accidentals. In this case, the following rules apply:

Double accidentals should be removed

B sharp -> C

E sharp -> F

C flat -> B

F flat -> E

In this manner, the most natural enharmonic notes are chosen.

#(define (naturalize-pitch p)
(let ((o (ly:pitch-octave p))
(a (* 4 (ly:pitch-alteration p)))
;; alteration, a, in quarter tone steps,
;; for historical reasons
(n (ly:pitch-notename p)))
(cond
((and (> a 1) (or (eq? n 6) (eq? n 2)))
(set! a (- a 2))
(set! n (+ n 1)))
((and (< a -1) (or (eq? n 0) (eq? n 3)))
(set! a (+ a 2))
(set! n (- n 1))))
(cond
((> a 2) (set! a (- a 4)) (set! n (+ n 1)))
((< a -2) (set! a (+ a 4)) (set! n (- n 1))))
(if (< n 0) (begin (set! o (- o 1)) (set! n (+ n 7))))
(if (> n 6) (begin (set! o (+ o 1)) (set! n (- n 7))))
(ly:make-pitch o n (/ a 4))))

#(define (naturalize music)
(let ((es (ly:music-property music 'elements))
(e (ly:music-property music 'element))
(p (ly:music-property music 'pitch)))
(if (pair? es)
(ly:music-set-property!
music 'elements
(map (lambda (x) (naturalize x)) es)))
(if (ly:music? e)
(ly:music-set-property!
music 'element
(naturalize e)))
(if (ly:pitch? p)
(begin
(set! p (naturalize-pitch p))
(ly:music-set-property! music 'pitch p)))
music))

naturalizeMusic =
#(define-music-function (parser location m)
(ly:music?)
(naturalize m))

music = \relative c' { c4 d e g }

\score {
\new Staff {
\transpose c ais { \music }
\naturalizeMusic \transpose c ais { \music }
\transpose c deses { \music }
\naturalizeMusic \transpose c deses { \music }
}
\layout { }
}


Notation Reference: Instrument transpositions, Inversion, Modal transformations, Relative octave entry, Retrograde.

Snippets: Pitches.

Internals Reference: TransposedMusic.

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

#### Inversion

A music expression can be inverted and transposed in a single operation with:

\inversion around-pitch to-pitch musicexpr


The musicexpr is inverted interval-by-interval around around-pitch, and then transposed so that around-pitch is mapped to to-pitch.

music = \relative c' { c d e f }
\new Staff {
\music
\inversion d' d' \music
\inversion d' ees' \music
}


Note: Motifs to be inverted should be expressed in absolute form or be first converted to absolute form by enclosing them in a relative block.

Notation Reference: Modal transformations, Retrograde, Transpose.

A music expression can be reversed to produce its retrograde:

music = \relative c' { c8. ees16( fis8. a16 b8.) gis16 f8. d16 }

\new Staff {
\music
}


#### Known issues and warnings

Manual ties inside \retrograde will be broken and generate warnings. Some ties can be generated automatically by enabling Automatic note splitting.

Notation Reference: Inversion, Modal transformations, Transpose.

#### 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-pitch to-pitch scale motif


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:

diatonicScale = \relative c' { c d e f g a b }
motif = \relative c' { c8 d e f g a b c }

\new Staff {
\motif
\modalTranspose c f \diatonicScale \motif
\modalTranspose c b, \diatonicScale \motif
}


An ascending scale of any length and with any intervals may be specified:

pentatonicScale = \relative c' { ges aes bes des ees }
motif = \relative c' { ees8 des ges,4 <ges' bes,> <ges bes,> }

\new Staff {
\motif
\modalTranspose ges ees' \pentatonicScale \motif
}


When used with a chromatic scale \modalTranspose has a similar effect to \transpose, but with the ability to specify the names of the notes to be used:

chromaticScale = \relative c' { c cis d dis e f fis g gis a ais b }
motif = \relative c' { c8 d e f g a b c }

\new Staff {
\motif
\transpose c f \motif
\modalTranspose c f \chromaticScale \motif
}


#### 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-pitch to-pitch scale motif


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:

octatonicScale = \relative c' { ees f fis gis a b c d }
motif = \relative c' { c8. ees16 fis8. a16 b8. gis16 f8. d16 }

\new Staff {
\motif
\modalInversion fis' fis' \octatonicScale \motif
}


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:

scale = \relative c' { c g' }
motive = \relative c' { c c g' c, }

\new Staff {
\motive
\modalInversion c' g' \scale \motive
}


octatonicScale = \relative c' { ees f fis gis a b c d }
motif = \relative c' { c8. ees16 fis8. a16 b8. gis16 f8. d16 }

\new Staff {
\motif
\retrograde \modalInversion c' c' \octatonicScale \motif
}


### 1.1.3 Displaying pitches

This section discusses how to alter the output of pitches.

#### Clef

The clef may be altered. Middle C is shown in every example. The following clef names can (but do not need to) be enclosed in quotes.

\clef treble
c2 c
\clef alto
c2 c
\clef tenor
c2 c
\clef bass
c2 c


Other clefs include:

\clef french
c2 c
\clef soprano
c2 c
\clef mezzosoprano
c2 c
\clef baritone
c2 c

\break

\clef varbaritone
c2 c
\clef subbass
c2 c
\clef percussion
c2 c

\break

\clef G   % synonym for treble
c2 c
\clef F   % synonym for bass
c2 c
\clef C   % synonym for alto
c2 c


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

\clef treble
c2 c
\clef "treble_8"
c2 c
\clef "bass^15"
c2 c
\clef "alto_2"
c2 c
\clef "G_8"
c2 c
\clef "F^5"
c2 c


Some special purpose clefs are described in Mensural clefs, Gregorian clefs, Default tablatures, and Custom tablatures. For mixing different clefs when using cue notes within a score, see the \cueClef and \cueDuringWithClef functions in Formatting cue notes.

#### Selected Snippets

Tweaking clef properties

The command \clef "treble_8" is equivalent to setting clefGlyph, clefPosition (which controls the vertical position of the clef), middleCPosition and clefOctavation. A clef is printed when any of the properties except middleCPosition are changed.

Note that changing the glyph, the position of the clef, or the octavation does not in itself change the position of subsequent notes on the staff: the position of middle C must also be specified to do this. The positional parameters are relative to the staff center line, positive numbers displacing upwards, counting one for each line and space. The clefOctavation value would normally be set to 7, -7, 15 or -15, but other values are valid.

When a clef change takes place at a line break the new clef symbol is printed at both the end of the previous line and the beginning of the new line by default. If the warning clef at the end of the previous line is not required it can be suppressed by setting the Staff property explicitClefVisibility to the value end-of-line-invisible. The default behavior can be recovered with \unset Staff.explicitClefVisibility.

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.

\layout { ragged-right = ##t }

{
% The default treble clef
c'1
% The standard bass clef
\set Staff.clefGlyph = #"clefs.F"
\set Staff.clefPosition = #2
\set Staff.middleCPosition = #6
c'1
% The baritone clef
\set Staff.clefGlyph = #"clefs.C"
\set Staff.clefPosition = #4
\set Staff.middleCPosition = #4
c'1
% The standard choral tenor clef
\set Staff.clefGlyph = #"clefs.G"
\set Staff.clefPosition = #-2
\set Staff.clefOctavation = #-7
\set Staff.middleCPosition = #1
c'1
% A non-standard clef
\set Staff.clefPosition = #0
\set Staff.clefOctavation = #0
\set Staff.middleCPosition = #-4
c'1 \break

% The following clef changes do not preserve
% the normal relationship between notes and clefs:

\set Staff.clefGlyph = #"clefs.F"
\set Staff.clefPosition = #2
c'1
\set Staff.clefGlyph = #"clefs.G"
c'1
\set Staff.clefGlyph = #"clefs.C"
c'1
\set Staff.clefOctavation = #7
c'1
\set Staff.clefOctavation = #0
\set Staff.clefPosition = #0
c'1

\set Staff.middleCPosition = #0
c'1
}


Notation Reference: Mensural clefs, Gregorian clefs, Default tablatures, Custom tablatures, Formatting cue notes.

Snippets: Pitches.

Internals Reference: Clef_engraver, Clef, OctavateEight, clef-interface.

#### 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 Accidentals 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 pitch mode


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.

\key g \major
fis1
f
fis


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

\relative c' {
\key d \major
a4 b cis d
\key g \minor
a4 bes c d
\set Staff.printKeyCancellation = ##f
\key d \major
a4 b cis d
\key g \minor
a4 bes c d
}


The commonly used \key command sets the keySignature property, in the Staff context.

To create non-standard key signatures, set this property directly. The format of this command is a list:

 \set Staff.keySignature = #(((octave . step) . alter) ((octave . step) . alter) ...)  where, for each element in the list, octave specifies the octave (0 being the octave from middle C to the B above), step specifies the note within the octave (0 means C and 6 means B), and alter is ,SHARP ,FLAT ,DOUBLE-SHARP etc. (Note the leading comma.) The accidentals in the key signature will appear in the reverse order to that in which they are specified.

Alternatively, for each item in the list, using the more concise format (step . alter) specifies that the same alteration should hold in all octaves.

For microtonal scales where a “sharp” is not 100 cents, alter refers to the alteration as a proportion of a 200-cent whole tone.

Here is an example of a possible key signature for generating a whole-tone scale:

\relative c' {
\set Staff.keySignature = #(((0 . 6) . ,FLAT)
((0 . 5) . ,FLAT)
((0 . 3) . ,SHARP))
c4 d e fis
aes4 bes c2
}


Music Glossary: church mode, scordatura.

Learning Manual: Accidentals and key signatures.

Snippets: Pitches.

#### Ottava brackets

Ottava brackets introduce an extra transposition of an octave for the staff:

a2 b
\ottava #-2
a2 b
\ottava #-1
a2 b
\ottava #0
a2 b
\ottava #1
a2 b
\ottava #2
a2 b


#### Selected Snippets

Ottava text

Internally, \ottava sets the properties ottavation (for example, to 8va or 8vb) and middleCPosition. To override the text of the bracket, set ottavation after invoking \ottava.

{
\ottava #1
\set Staff.ottavation = #"8"
c''1
\ottava #0
c'1
\ottava #1
\set Staff.ottavation = #"Text"
c''1
}


Music Glossary: octavation.

Snippets: Pitches.

Internals Reference: Ottava_spanner_engraver, OttavaBracket, ottava-bracket-interface.

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

\new GrandStaff <<
\new Staff = "violin" {
\relative c'' {
\set Staff.instrumentName = #"Vln"
\set Staff.midiInstrument = #"violin"
% not strictly necessary, but a good reminder
\transposition c'

\key c \major
g4( c8) r c r c4
}
}
\new Staff = "clarinet" {
\relative c'' {
\set Staff.instrumentName = \markup { Cl (B\flat) }
\set Staff.midiInstrument = #"clarinet"
\transposition bes

\key d \major
a4( d8) r d r d4
}
}
>>


The \transposition may be changed during a piece. For example, a clarinetist may switch from an A clarinet to a B-flat clarinet.

\set Staff.instrumentName = #"Cl (A)"
\key a \major
\transposition a
c d e f
\textLengthOn
<>^\markup { Switch to B\flat clarinet }
R1

\key bes \major
\transposition bes
c2 g


Music Glossary: concert pitch, transposing instrument.

Notation Reference: Quoting other voices, Transpose.

Snippets: Pitches.

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

musicA = {
<<
\relative c' {
cis'8 fis, bes4 <a cis>8 f bis4 |
cis2. <c, g'>4 |
}
\\
\relative c' {
ais'2 cis, |
fis8 b a4 cis2 |
}
>>
}

musicB = {
\clef bass
\new Voice {
\voiceTwo \relative c' {
<fis, a cis>8[ <fis a cis>
\change Staff = up
cis' cis
\change Staff = down
<fis, a> <fis a>]
\showStaffSwitch
\change Staff = up
dis'4 |
\change Staff = down
<fis, a cis>4 gis <f a d>2 |
}
}
}

\new PianoStaff {
<<
\context Staff = "up" {
\accidentalStyle "default"
\musicA
}
\context Staff = "down" {
\accidentalStyle "default"
\musicB
}
>>
}


Note that the last lines of this example can be replaced by the following, as long as the same accidental style should be used in both staves.

\new PianoStaff {
<<
\context Staff = "up" {
%%% change the next line as desired:
\accidentalStyle #'Score "default"
\musicA
}
\context Staff = "down" {
\musicB
}
>>
}

default

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 (the ones not typeset by default) are typeset as cautionary accidentals. They are by default printed with parentheses, but they can also be printed in reduced size by defining the cautionary-style property of AccidentalSuggestion.

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

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.

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.

Snippets: Pitches.

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

forget = #(define-music-function (parser location music) (ly:music?) #{
\accidentalStyle "forget"
#music
\accidentalStyle "modern"
#})
{
\accidentalStyle "modern"
\time 2/4
\repeat volta 2 {
c'2
}
\alternative {
cis'
\forget c'
}
}


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

\layout {
\context {
\Voice
\consists "Ambitus_engraver"
}
}

\relative c'' {
aes c e2
cis,1
}


#### Selected Snippets

Ambitus can be added per voice. In this case, the ambitus must be moved manually to prevent collisions.

\new Staff <<
\new Voice \with {
\consists "Ambitus_engraver"
} \relative c'' {
\override Ambitus #'X-offset = #2.0
\voiceOne
c4 a d e
f1
}
\new Voice \with {
\consists "Ambitus_engraver"
} \relative c' {
\voiceTwo
es4 f g as
b1
}
>>


Ambitus with multiple voices

Adding the Ambitus_engraver to the Staff context creates a single ambitus per staff, even in the case of staves with multiple voices.

\new Staff \with {
\consists "Ambitus_engraver"
}
<<
\new Voice \relative c'' {
\voiceOne
c4 a d e
f1
}
\new Voice \relative c' {
\voiceTwo
es4 f g as
b1
}
>>


Changing the ambitus gap

It is possible to change the default gap setting for ambitus.

\layout {
\context {
\Voice
\consists "Ambitus_engraver"
}
}

\new Staff {
\time 2/4
% Default setting
c'4 g''
}

\new Staff {
\time 2/4
\override AmbitusLine #'gap = #0
c'4 g''
}

\new Staff {
\time 2/4
\override AmbitusLine #'gap = #1
c'4 g''
}

\new Staff {
\time 2/4
\override AmbitusLine #'gap = #1.5
c'4 g''
}


Music Glossary: ambitus.

Snippets: Pitches.

Internals Reference: Ambitus_engraver, Voice, Staff, Ambitus, AmbitusAccidental, AmbitusLine, AmbitusNoteHead, ambitus-interface.

#### Known issues and warnings

There is no collision handling in the case of multiple per-voice ambitus.

This section suggests ways of altering note heads.

The appearance of note heads may be altered:

c4 b
c4 b
a b
a b
c4 d e f


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:

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

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

There is also a shorthand for diamond shapes which can be used only inside chords:

<c f\harmonic>2 <d a'\harmonic>4 <c g'\harmonic>


#### Predefined commands

\harmonic, \xNotesOn, \xNotesOff, \xNote.

Snippets: Pitches.

Notation Reference: Note head styles, Chorded notes, Indicating harmonics and dampened notes.

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.

#(set-global-staff-size 26)
\relative c' {
c2 e4 f
g1
c,1
}


#### Predefined commands

\easyHeadsOn, \easyHeadsOff.

#### Selected Snippets

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.

#(define Ez_numbers_engraver
(make-engraver
(acknowledgers
(let* ((context (ly:translator-context engraver))
(tonic-pitch (ly:context-property context 'tonic))
(tonic-name (ly:pitch-notename tonic-pitch))
(grob-pitch
(ly:event-property (event-cause grob) 'pitch))
(grob-name (ly:pitch-notename grob-pitch))
(delta (modulo (- grob-name tonic-name) 7))
(note-names
(make-vector 7 (number->string (1+ delta)))))
(ly:grob-set-property! grob 'note-names note-names))))))

#(set-global-staff-size 26)

\layout {
ragged-right = ##t
\context {
\Voice
\consists \Ez_numbers_engraver
}
}

\relative c' {
c4 d e f
g4 a b c \break

\key a \major
a,4 b cis d
e4 fis gis a \break

\key d \dorian
d,4 e f g
a4 b c d
}


Notation Reference: Setting the staff size.

Snippets: Pitches.

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:

\aikenHeads
c, d e f g2 a b1 c \break
c,4 d e f g2 a b1 c \break
c,4 d e f g2 a b1 c \break
c,4 d e f g2 a b1 c \break
c,4 d e f g2 a b1 c \break


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:

\key a \minor
a b c d e2 f g1 a \break
a,4 b c d e2 f g1 a \break
a,2 b c d \break
a2 b c d \break
a2 b c d \break
a2 b c d \break



#### Predefined commands

\aikenHeads, \aikenHeadsMinor, \funkHeads, \funkHeadsMinor, \sacredHarpHeads, \sacredHarpHeadsMinor, \southernHarmonyHeads, \southernHarmonyHeadsMinor, \walkerHeads, \walkerHeadsMinor.

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

fragment = {
\key c \major
c2 d
e2 f
g2 a
b2 c
}

\new Staff {
\transpose c d
\relative c' {
\set shapeNoteStyles = #'#(do re mi fa
#f la ti)
\fragment
}

\break

\relative c' {
\set shapeNoteStyles = #'#(cross triangle fa #f
mensural xcircle diamond)
\fragment
}
}


Snippets: Pitches.

#### Improvisation

Improvisation is sometimes denoted with slashed note heads, where the performer may choose any pitch but should play the specified rhythm. Such note heads can be created:

\new Voice \with {
\consists "Pitch_squash_engraver"
} {
e8 e g a a16( bes) a8 g
\improvisationOn
e8 ~
e2 ~ e8 f4 f8 ~
f2
\improvisationOff
a16( bes) a8 g e
}


#### Predefined commands

\improvisationOn, \improvisationOff.

Snippets: Pitches.

Internals Reference: Pitch_squash_engraver, Voice, RhythmicStaff.

## 1.2 Rhythms

This section discusses rhythms, rests, durations, beaming and bars.

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

\time 8/1
c\longa c\breve c1 c2
c4 c8 c16 c32 c64 c128 c128


Here are the same durations with automatic beaming turned off.

\time 8/1
\autoBeamOff
c\longa c\breve c1 c2
c4 c8 c16 c32 c64 c128 c128


A note with the duration of a quadruple breve may be entered with \maxima, but this is supported only within ancient music notation. For details, see Ancient notation.

If the duration is omitted, it is set to the previously entered duration. The default for the first note is a quarter note.

a a a2 a a4 a a1 a


To obtain dotted note lengths, place a dot (.) after the duration. Double-dotted notes are specified by appending two dots, and so on.

a4 b c4. b8 a4. b4.. c8.


Some durations cannot be represented with just binary durations and dots; they can be represented only by tying two or more notes together. For details, see Ties.

For ways of specifying durations for the syllables of lyrics and ways of aligning lyrics to notes, see Vocal music.

Optionally, notes can be spaced strictly proportionately to their duration. For details of this and other settings which control proportional notation, see Proportional notation.

Dots are normally moved up to avoid staff lines, except in polyphonic situations. Dots may be manually placed above or below the staff; see Direction and placement.

#### Predefined commands

\autoBeamOn, \autoBeamOff, \dotsUp, \dotsDown, \dotsNeutral.

#### Selected Snippets

Alternative breve note

This code demonstrates how to use the alternative breve note with two vertical lines on each side of the notehead instead of one line.

\relative c'' {
\time 4/2
c\breve |
b\breve
a\breve
}


Changing the number of augmentation dots per note

This code demonstrates how to change the number of augmentation dots on a single note.

\relative c' {
c4.. a16 r2 |
\override Dots #'dot-count = #4
c4.. a16 r2 |
\override Dots #'dot-count = #0
c4.. a16 r2 |
\revert Dots #'dot-count
c4.. a16 r2 |
}


Music Glossary: breve, longa, maxima, note value, Duration names notes and rests.

Notation Reference: Automatic beams, Ties, Stems, Writing rhythms, Writing rests, Vocal music, Ancient notation, Proportional notation.

Snippets: Rhythms.

Internals Reference: Dots, DotColumn.

#### Known issues and warnings

There is no fundamental limit to rest durations (both in terms of longest and shortest), but the number of glyphs is limited: rests from 128th to maxima (8 x whole) may be printed.

#### Tuplets

Tuplets are made from a music expression by multiplying all the durations with a fraction:

\times fraction { music }


The duration of music will be multiplied by the fraction. The fraction’s denominator will be printed over or under the notes, optionally with a bracket. The most common tuplet is the triplet in which 3 notes have the duration of 2, so the notes are 2/3 of their written length.

a2 \times 2/3 { b4 b b }
c4 c \times 2/3 { b4 a g }


Tuplet brackets may be manually placed above or below the staff; see Direction and placement.

Tuplets may be nested:

\autoBeamOff
c4 \times 4/5 { f8 e f \times 2/3 { e[ f g] } } f4


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 \times command

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

In the example, two triplets are shown, while \times was entered only once.

Read the relevant sections of the Notation Reference for more information about ly:make-moment.

\relative c' {
\time 2/4
\set tupletSpannerDuration = #(ly:make-moment 1 4)
\times 2/3 { c8 c c c c c }
}


Changing the tuplet number

By default, only the numerator of the tuplet number is printed over the tuplet bracket, i.e., the denominator of the argument to the \times command. Alternatively, num:den of the tuplet number may be printed, or the tuplet number may be suppressed altogether.

\relative c'' {
\times 2/3 { c8 c c }
\times 2/3 { c8 c c }
\override TupletNumber #'text = #tuplet-number::calc-fraction-text
\times 2/3 { c8 c c }
\override TupletNumber #'stencil = ##f
\times 2/3 { c8 c c }
}


Non-default tuplet numbers

LilyPond also provides formatting functions to print tuplet numbers different than the actual fraction, as well as to append a note value to the tuplet number or tuplet fraction.

\relative c'' {
\once \override TupletNumber #'text =
#(tuplet-number::non-default-tuplet-denominator-text 7)
\times 2/3  { c4. c4. c4. c4. }
\once \override TupletNumber #'text =
#(tuplet-number::non-default-tuplet-fraction-text 12 7)
\times 2/3  { c4. c4. c4. c4. }
\once \override TupletNumber #'text =
#(tuplet-number::append-note-wrapper
(tuplet-number::non-default-tuplet-fraction-text 12 7) "8")
\times 2/3  { c4. c4. c4. c4. }

\once \override TupletNumber #'text =
#(tuplet-number::append-note-wrapper
tuplet-number::calc-denominator-text "4")
\times 2/3  { c8 c8 c8 c8 c8 c8 }
\once \override TupletNumber #'text =
#(tuplet-number::append-note-wrapper
tuplet-number::calc-fraction-text "4")
\times 2/3  { c8 c8 c8 c8 c8 c8 }

\once \override TupletNumber #'text =
#(tuplet-number::fraction-with-notes "4." "8")
\times 2/3  { c4. c4. c4. c4. }
\once \override TupletNumber #'text =
#(tuplet-number::non-default-fraction-with-notes 12 "8" 4 "4")
\times 2/3  { c4. c4. c4. c4. }
}


Controlling tuplet bracket visibility

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

music = \relative c'' {
\times 2/3 { c16[ d e } f8]
\times 2/3 { c8 d e }
\times 2/3 { c4 d e }
}

\new Voice {
\relative c' {
<< \music s4^"default" >>
\override TupletBracket #'bracket-visibility = #'if-no-beam
<< \music s4^"'if-no-beam" >>
\override TupletBracket #'bracket-visibility = ##t
<< \music s4^"#t" >>
\override TupletBracket #'bracket-visibility = ##f
<< \music s4^"#f" >>
}
}


Permitting line breaks within beamed tuplets

This artificial example shows how both manual and automatic line breaks may be permitted to within a beamed tuplet. Note that such off-beat tuplets have to be beamed manually.

\layout {
\context {
\Voice
% Permit line breaks within tuplets
\remove "Forbid_line_break_engraver"
% Allow beams to be broken at line breaks
\override Beam #'breakable = ##t
}
}
\relative c'' {
a8
\repeat unfold 5 { \times 2/3 { c[ b a] } }
% Insert a manual line break within a tuplet
\times 2/3 { c[ b \bar "" \break a] }
\repeat unfold 5 { \times 2/3 { c[ b a] } }
c8
}


Music Glossary: triplet, tuplet, polymetric.

Learning Manual: Tweaking methods.

Notation Reference: Time administration, Scaling durations, The \tweak command, Polymetric notation.

Snippets: Rhythms.

Internals Reference: TupletBracket, TupletNumber, TimeScaledMusic.

#### Known issues and warnings

Grace notes may be placed within tuplet brackets, except when a staff begins with a grace note followed by a tuplet. In this particular case, the grace note must be placed before the \times command to avoid errors.

When using a tuplet at the beginning of a piece with a \tempo mark, the music must be explicitly entered in a \new Voice block, as discussed in Voices contain music.

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

\time 2/4
% Alter durations to triplets
a4*2/3 gis a
% Normal durations
a4 a
% Double the duration of chord
<a d>4*2
% Duration of quarter, appears like sixteenth
b16*4 c4


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:

\time 2/4
% Normal durations
<c a>4 c8 a
% Scale music by *2/3
\scaleDurations 2/3 {
<c a f>4. c8 a f
}
% Scale music by *2
\scaleDurations 2/1 {
<c' a>4 c8 b
}


One application of this command is in polymetric notation, see Polymetric notation.

Notation Reference: Tuplets, Invisible rests, Polymetric notation.

Snippets: Rhythms.

#### 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 using the tilde symbol (~).

a2 ~ a


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 c' {
r8 c8 ~ c2 r4 |
r8^"not" c2 ~ c8 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 tie inside the chord.

<c e g> ~ <c e g>
<c~ e g~ b> <c e g b>


When a second alternative of a repeat starts with a tied note, you have to specify the repeated tie as follows:

\repeat volta 2 { c g <c e>2 ~ }
\alternative {
% First alternative: following note is tied normally
{ <c e>2. r4 }
% Second alternative: following note has a repeated tie
{ <c e>2\repeatTie d4 c } }


L.v. ties (laissez vibrer) indicate that notes must not be damped at the end. It is used in notation for piano, harp and other string and percussion instruments. They can be entered as follows:

<c f g>1\laissezVibrer


Ties may be manually placed above or below the staff; see Direction and placement.

Ties may be made dashed, dotted, or a combination of solid and dashed.

\tieDotted
c2 ~ c
\tieDashed
c2 ~ c
\tieHalfDashed
c2 ~ c
\tieHalfSolid
c2 ~ c
\tieSolid
c2 ~ c


Custom dash patterns can be specified:

\tieDashPattern #0.3 #0.75
c2 ~ c
\tieDashPattern #0.7 #1.5
c2 ~ c
\tieSolid
c2 ~ c


Dash pattern definitions for ties have the same structure as dash pattern definitions for slurs. For more information about complex dash patterns, see Slurs.

Override whiteout and layer layout properties for ties that collide with other objects in a staff.

\override Tie #'layer = #-2
\override Staff.TimeSignature #'layer = #-1
\override Staff.KeySignature #'layer = #-1
\override Staff.TimeSignature #'whiteout = ##t
\override Staff.KeySignature #'whiteout = ##t
b2 b~
\time 3/4
\key a \major
b r4


#### Predefined commands

\tieUp, \tieDown, \tieNeutral, \tieDotted, \tieDashed, \tieDashPattern, \tieHalfDashed, \tieHalfSolid, \tieSolid.

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

\relative c' {
\set tieWaitForNote = ##t
\grace { c16[ ~ e ~ g] ~ } <c, e g>2
\repeat tremolo 8 { c32 ~ c' ~ } <c c,>1
e8 ~ c ~ a ~ f ~ <e' c a f>2
\tieUp
c8 ~ a
\tieDown
\tieDotted
g8 ~ c g2
}


Engraving ties manually

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

\relative c' {
<c e g>2~ <c e g>
\override TieColumn #'tie-configuration =
#'((0.0 . 1) (-2.0 . 1) (-4.0 . 1))
<c e g>2~ <c e g>
}


Music Glossary: tie, laissez vibrer.

Notation Reference: Slurs, Automatic note splitting.

Snippets: Expressive marks, Rhythms.

Internals Reference: LaissezVibrerTie, LaissezVibrerTieColumn, TieColumn, Tie.

#### Known issues and warnings

Switching staves when a tie is active will not produce a slanted tie.

Changing clefs or ottavations during a tie is not really well-defined. In these cases, a slur may be preferable.

### 1.2.2 Writing rests

Rests are entered as part of the music in music expressions.

#### Rests

Rests are entered like notes with the note name r. Durations longer than a whole rest use the following predefined commands:

\new Staff {
% These two lines are just to prettify this example
\time 16/1
\override Staff.TimeSignature #'stencil = ##f
% Print a maxima rest, equal to four breves
r\maxima
% Print a longa rest, equal to two breves
r\longa
% Print a breve rest
r\breve
r1 r2 r4 r8 r16 r32 r64 r128
}


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.

a4\rest d4\rest


#### Selected Snippets

Rest styles

Rests may be used in various styles.

\layout {
indent = 0
\context {
\Staff
\remove "Time_signature_engraver"
}
}

\new Staff \relative c {
\override Staff.Rest #'style = #'mensural
r\maxima^\markup \typewriter { mensural }
r\longa r\breve r1 r2 r4 r8 r16 s32 s64 s128 s128
\bar ""

\override Staff.Rest #'style = #'neomensural
r\maxima^\markup \typewriter { neomensural }
r\longa r\breve r1 r2 r4 r8 r16 s32 s64 s128 s128
\bar ""

\override Staff.Rest #'style = #'classical
r\maxima^\markup \typewriter { classical }
r\longa r\breve r1 r2 r4 r8 r16 r32 r64 r128 s128
\bar ""

\override Staff.Rest  #'style = #'default
r\maxima^\markup \typewriter { default }
r\longa r\breve r1 r2 r4 r8 r16 r32 r64 r128 s128
}


Music Glossary: breve, longa, maxima.

Notation Reference: Full measure rests.

Snippets: Rhythms.

Internals Reference: Rest.

#### Known issues and warnings

There is no fundamental limit to rest durations (both in terms of longest and shortest), but the number of glyphs is limited: there are rests from 128th to maxima (8 x whole).

#### Invisible rests

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

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.

<<
{
a2 \skip2 a2 a2
}
\new Lyrics {
\lyricmode {
foo2 \skip 1 bla2
}
}
>>


Because \skip is a command, it does not affect the default durations of following notes, unlike s.

<<
{
\repeat unfold 8 { a4 }
}
{
a4 \skip 2 a |
s2 a
}
>>


A spacer rest implicitly causes Staff and Voice contexts to be created if none exist, just like notes and rests do:

s1 s s


\skip simply skips musical time; it creates no output of any kind.

% This is valid input, but does nothing
\skip 1 \skip1 \skip 1


Learning Manual: Visibility and color of objects.

Notation Reference: Hidden notes, Visibility of objects.

Snippets: Rhythms.

Internals Reference: SkipMusic.

#### Full measure rests

Rests for one or more full measures are entered like notes with the note name uppercase R:

% Rest measures contracted to single measure
\compressFullBarRests
R1*4
R1*24
R1*4
b2^"Tutti" b4 a4


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:

\compressFullBarRests
\time 2/4
R1 | R2 |
\time 3/4
R2. | R2.*2 |
\time 13/8
R1*13/8 | R1*13/8*12 |
\time 10/8
R4*5*4 |


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:

% Default behavior
\time 3/4 r2. | R2.*2 |
\time 2/4 R2 |
\time 4/4
% Rest measures contracted to single measure
\compressFullBarRests
r1 | R1*17 | R1*4 |
% Rest measures expanded
\expandFullBarRests
\time 3/4
R2.*2 |


Markups can be added to multi-measure rests. The predefined command \fermataMarkup is provided for adding fermatas.

\compressFullBarRests
\time 3/4
R2.*10^\markup { \italic "ad lib." }
R2.^\fermataMarkup


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
R1^"wrong"
% This is the correct object name to be specified
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, \compressFullBarRests, \expandFullBarRests.

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

\relative c'' {
\compressFullBarRests
R1*2 | R1*5 | R1*9
\override MultiMeasureRest #'expand-limit = #3
R1*2 | R1*5 | R1*9
}


Positioning multi-measure rests

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:

\relative c'' {
% Multi-measure rests by default are set under the fourth line
R1
% They can be moved using an override
\override MultiMeasureRest #'staff-position = #-2
R1
\override MultiMeasureRest #'staff-position = #0
R1
\override MultiMeasureRest #'staff-position = #2
R1
\override MultiMeasureRest #'staff-position = #3
R1
\override MultiMeasureRest #'staff-position = #6
R1
\revert MultiMeasureRest #'staff-position
\break

% In two Voices, odd-numbered voices are under the top line
<< { R1 } \\ { a1 } >>
% Even-numbered voices are under the bottom line
<< { a1 } \\ { R1 } >>
% Multi-measure rests in both voices remain separate
<< { R1 } \\ { R1 } >>

% Separating multi-measure rests in more than two voices
% requires an override
<< { R1 } \\ { R1 } \\
\once \override MultiMeasureRest #'staff-position = #0
{ R1 }
>>

% Using compressed bars in multiple voices requires another override
% in all voices to avoid multiple instances being printed
\compressFullBarRests
<<
\revert MultiMeasureRest #'staff-position
{ R1*3 }
\\
\revert MultiMeasureRest #'staff-position
{ R1*3 }
>>
}


Multi-measure rest markup

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 a spacer rest with an attached markup before the multi-measure rest.

Note that the spacer rest causes a bar line to be inserted. 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.

\relative c' {
\compressFullBarRests
\textLengthOn
s1*0^\markup { [MAJOR GENERAL] }
R1*19
s1*0_\markup { \italic { Cue: ... it is yours } }
s1*0^\markup { A }
R1*30^\markup { [MABEL] }
\textLengthOff
c4^\markup { CHORUS } d f c
}


Music Glossary: multi-measure rest.

Notation Reference: Durations, Text, Formatting text, Text scripts.

Snippets: Rhythms.

Internals Reference: MultiMeasureRest, MultiMeasureRestNumber, MultiMeasureRestText.

#### Known issues and warnings

Fingerings over multi-measure rests (e.g. R1*10-4) may result in the fingering numeral colliding with the bar counter numeral.

There is no way to automatically condense multiple ordinary rests into a single multi-measure rest.

Multi-measure rests do not take part in rest collisions.

### 1.2.3 Displaying rhythms

#### Time signature

The time signature is set as follows:

\time 2/4 c2
\time 3/4 c2.


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.

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

% Default style
\time 4/4 c1
\time 2/2 c1
% Change to numeric style
\numericTimeSignature
\time 4/4 c1
\time 2/2 c1
% Revert to default style
\defaultTimeSignature
\time 4/4 c1
\time 2/2 c1


Mensural time signatures are covered in Mensural time signatures.

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:

\score {
\new Staff {
\relative c' {
\time #'(2 2 3) 7/8
\repeat unfold 7 { c8 } |
\time #'(3 2 2) 7/8
\repeat unfold 7 { c8 } |
}
}
}


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:

\score {
\new Staff {
\relative c' {
\overrideTimeSignatureSettings
4/4        % timeSignatureFraction
1/4        % baseMomentFraction
#'(3 1)    % beatStructure
#'()       % beamExceptions
\time 4/4
\repeat unfold 8 { c8 } |
}
}
}


\overrideTimeSignatureSettings takes four arguments:

1. timeSignatureFraction, a fraction describing the time signature to which these values apply.
2. baseMomentFraction, a fraction containing the numerator and denominator of the basic timing unit for the time signature.
3. beatStructure, a Scheme list indicating the structure of the beats in the measure, in units of the base moment.
4. beamExceptions, an alist containing any beaming rules for the time signature that go beyond ending at every beat, as described in Setting automatic beam behavior.

The context containing \overrideTimeSignatureSettings must be instantiated before the \overrideTimeSignatureSettings call is executed. That means it must either be explicitly instantiated or there must be music in the context before the \overrideTimeSignatureSettings call:

\score {
\relative c' {
% This call will fail because the context isn't yet instantiated
\overrideTimeSignatureSettings
4/4        % timeSignatureFraction
1/4        % baseMomentFraction
#'(3 1)    % beatStructure
#'()       % beamExceptions
\time 4/4
c8^\markup {"Beamed (2 2)"}
\repeat unfold 7 { c8 } |
% This call will succeed
\overrideTimeSignatureSettings
4/4        % timeSignatureFraction
1/4        % baseMomentFraction
#'(3 1)    % beatStructure
#'()       % beamExceptions
\time 4/4
c8^\markup {"Beamed (3 1)"}
\repeat unfold 7 { c8 } |
}
}


Changed values of default time signature properties can be restored to the original values:

\score{
\relative c' {
\repeat unfold 8 { c8 } |
\overrideTimeSignatureSettings
4/4        % timeSignatureFraction
1/4        % baseMomentFraction
#'(3 1)    % beatStructure
#'()       % beamExceptions
\time 4/4
\repeat unfold 8 { c8 } |
\revertTimeSignatureSettings 4/4
\time 4/4
\repeat unfold 8 { c8 } |
}
}


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.

\score {
\new StaffGroup <<
\new Staff {
\overrideTimeSignatureSettings
4/4        % timeSignatureFraction
1/4        % baseMomentFraction
#'(3 1)    % beatStructure
#'()       % beamExceptions
\time 4/4
\repeat unfold 8 {c''8}
}
\new Staff {
\overrideTimeSignatureSettings
4/4        % timeSignatureFraction
1/4        % baseMomentFraction
#'(1 3)    % beatStructure
#'()       % beamExceptions
\time 4/4
\repeat unfold 8 {c''8}
}
>>
\layout {
\context {
\Score
\remove "Timing_translator"
\remove "Default_bar_line_engraver"
}
\context {
\Staff
\consists "Timing_translator"
\consists "Default_bar_line_engraver"
}
}
}


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.

\relative c'' {
\time 3/4
c4 c c
% Change the style permanently
\override Staff.TimeSignature #'style = #'single-digit
\time 2/4
c4 c
\time 3/4
c4 c c
% Revert to default style:
\revert Staff.TimeSignature #'style
\time 2/4
c4 c
% single-digit style only for the next time signature
\once \override Staff.TimeSignature #'style = #'single-digit
\time 5/4
c4 c c c c
\time 2/4
c4 c
}


Music Glossary: time signature

Notation Reference: Mensural time signatures, Setting automatic beam behavior, Time administration.

Installed Files: ‘scm/time-signature-settings.scm’.

Snippets: Rhythms.

Internals Reference: TimeSignature, Timing_translator.

#### Metronome marks

A basic metronome mark is simple to write:

\tempo 4 = 120
c2 d
e4. d8 c2


Metronome marks may also be printed as a range of two numbers:

\tempo 4 = 40 ~ 46
c4. e8 a4 g
b,2 d4 r


Tempo indications with text can be used instead:

\tempo "Allegretto"
c4 e d c
b4. a16 b c4 r4


Combining a metronome mark and text will automatically place the metronome mark within parentheses:

\tempo "Allegro" 4 = 160
g4 c d e
d4 b g2


In general, the text can be any markup object:

\tempo \markup { \italic Faster } 4 = 132
a8-. r8 b-. r gis-. r a-. r


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

\tempo "" 8 = 96
d4 g e c


#### Selected Snippets

Printing metronome and rehearsal marks below the staff

By default, metronome and rehearsal marks are printed above the staff. To place them below the staff simply set the direction property of MetronomeMark or RehearsalMark appropriately.

\layout { ragged-right = ##f }

{
% Metronome marks below the staff
\override Score.MetronomeMark #'direction = #DOWN
\tempo 8. = 120
c''1

% Rehearsal marks below the staff
\override Score.RehearsalMark #'direction = #DOWN
\mark \default
c''1
}


Changing the tempo without a metronome mark

To change the tempo in MIDI output without printing anything, make the metronome mark invisible.

\score {
\new Staff \relative c' {
\tempo 4 = 160
c4 e g b
c4 b d c
\set Score.tempoHideNote = ##t
\tempo 4 = 96
d,4 fis a cis
d4 cis e d
}
\layout { }
\midi { }
}


Creating metronome marks in markup mode

New metronome marks can be created in markup mode, but they will not change the tempo in MIDI output.

\relative c' {
\tempo \markup {
\concat {
(
\smaller \general-align #Y #DOWN \note #"16." #1
" = "
\smaller \general-align #Y #DOWN \note #"8" #1
)
}
}
c1
c4 c' c,2
}


For more details, see Formatting text.

Music Glossary: metronome, metronomic indication, tempo indication, metronome mark.

Notation Reference: Formatting text, MIDI output.

Snippets: Staff notation.

Internals Reference: MetronomeMark.

#### Upbeats

Partial or pick-up measures, such as an anacrusis or an upbeat, are entered using the \partial command,

\partial duration


where duration is the remaining length of the partial measure before the start of the next full measure.

\time 3/4
\partial 8
e8 | a4 c8 b c4 |


The duration can be any value less than a full measure:

\time 3/4
\partial 4.
r4 e8 | a4 c8 b c4 |


The \partial duration can also be written as;

\set Timing.measurePosition -duration


So \partial 8 becomes:

\time 3/4
\set Timing.measurePosition = #(ly:make-moment -1 8)
e8 | a4 c8 b c4 |


The property measurePosition contains a rational number indicating how much of the measure has passed at this point. Note that this is set to a negative number by the \partial command: i.e., \partial 4 is internally translated to -4, meaning “there is a quarter note left in the measure.”

Music Glossary: anacrusis.

Notation Reference: Grace notes.

Snippets: Rhythms.

Internal Reference: Timing_translator.

#### Known issues and warnings

The \partial command should be used only at the beginning of a piece. If you use it after the beginning, warnings or problems may occur, so use \set Timing.measurePosition instead.

\time 6/8
\partial 8
e8 | a4 c8 b[ c b] |
\set Timing.measurePosition = #(ly:make-moment -1 4)
r8 e,8 | a4 c8 b[ c b] |


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

c4 d e d
c4 c d8[ d d] f4 g4.
\bar "|"
d4 e d c


Bar numbering is resumed at the end of the cadenza.

% Show all bar numbers
\override Score.BarNumber #'break-visibility = #all-visible
c4 d e d
c4 c d8[ d d] f4 g4.
\bar "|"
d4 e d c


A new bar is never started within a cadenza, even if one or more \bar commands are inserted within it. Therefore, reminder accidentals will need to be added manually. See Accidentals.

c4 d e d
cis4 d cis d
\bar "|"
cis4 d cis! d
\bar "|"


Automatic beaming is disabled by \cadenzaOn. Therefore, all beaming in cadenzas must be entered manually. See Manual beams.

\repeat unfold 8 { c8 }
cis8 c c c c
\bar"|"
c8 c c
\repeat unfold 8 { c8 }


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.

#### Predefined commands

\cadenzaOn, \cadenzaOff.

Notation Reference: Visibility of objects, Polymetric notation, Manual beams, Accidentals.

Snippets: Rhythms.

#### Known issues and warnings

Automatic line and page breaks are inserted only at bar lines, so ‘invisible’ bar lines will need to be inserted manually in long stretches of unmetered music to permit breaking:

\bar ""


Explicitly create a Voice context when starting a piece with \cadenzaOn, else unexpected errors may occur.

\new Voice {
\relative c' {
c16[^"Solo Free Time" d e f] g2.
\bar "||"
}
}


#### Polymetric notation

Polymetric notation is supported explicitly or by manually modifying the visible time signature symbol and/or scaling note durations.

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

\relative c' <<
\new Staff {
\time 3/4
c4 c c |
c4 c c |
}
\new Staff {
\time 3/4
\set Staff.timeSignatureFraction = 9/8
\scaleDurations 2/3
\repeat unfold 6 { c8[ c c] }
}
\new Staff {
\time 3/4
\set Staff.timeSignatureFraction = 10/8
\scaleDurations 3/5 {
\repeat unfold 2 { c8[ c c] }
\repeat unfold 2 { c8[ c] } |
c4. c \times 2/3 { c8[ c c] } c4
}
}
>>


#### Different time signatures with unequal-length measures

Each staff can be given its own independent time signature by moving the Timing_translator and the Default_bar_line_engraver to the Staff context.

\layout {
\context {
\Score
\remove "Timing_translator"
\remove "Default_bar_line_engraver"
}
\context {
\Staff
\consists "Timing_translator"
\consists "Default_bar_line_engraver"
}
}

% Now each staff has its own time signature.

\relative c' <<
\new Staff {
\time 3/4
c4 c c |
c4 c c |
}
\new Staff {
\time 2/4
c4 c |
c4 c |
c4 c |
}
\new Staff {
\time 3/8
c4. |
c8 c c |
c4. |
c8 c c |
}
>>


#### Compound time signatures

These are created using the \compoundMeter function. The syntax for this is:

\compoundMeter #'(list of lists)


The simplest construction is a single list, where the last number indicates the bottom number of the time signature and those that come before it, the top numbers.

\relative c' {
\compoundMeter #'((2 2 2 8))
\repeat unfold 6 c8 \repeat unfold 12 c16
}


More complex meters can be constructed using additional lists. Also, automatic beaming settings will be adjusted depending on the values.

\relative c' {
\compoundMeter #'((1 4) (3 8))
\repeat unfold 5 c8 \repeat unfold 10 c16
}

\relative c' {
\compoundMeter #'((1 2 3 8) (3 4))
\repeat unfold 12 c8
}


Music Glossary: polymetric, polymetric time signature, meter.

Notation Reference: Automatic beams, Manual beams, Time signature, Scaling durations.

Snippets: Rhythms.

Internals Reference: TimeSignature, Timing_translator, Default_bar_line_engraver, Staff.

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

\new Voice \with {
\remove "Rest_engraver"
\consists "Completion_rest_engraver"
}

{ c2. c8 d4 e f g a b c8 c2 b4 a g16 f4 e d c8. c2 r1*2 }


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.

Music Glossary: tie

Learning Manual: Engravers explained, Adding and removing engravers.

Snippets: Rhythms.

#### Known issues and warnings

Not all durations (especially those containing tuplets) can be represented exactly with normal notes and dots, but the Completion_heads_engraver will not insert tuplets.

The Completion_heads_engraver only affects notes; it does not split rests.

#### Showing melody rhythms

Sometimes you might want to show only the rhythm of a melody. This can be done with the rhythmic staff. All pitches of notes on such a staff are squashed, and the staff itself has a single line

<<
\new RhythmicStaff {
\new Voice = "myRhythm" {
\time 4/4
c4 e8 f g2
r4 g g f
g1
}
}
\new Lyrics {
\lyricsto "myRhythm" {
This is my song
I like to sing
}
}
>>


Guitar chord charts often show the strumming rhythms. This can be done with the Pitch_squash_engraver and \improvisationOn.

<<
\new ChordNames {
\chordmode {
c1 f g c
}
}
\new Voice \with {
\consists "Pitch_squash_engraver"
} \relative c'' {
\improvisationOn
c4 c8 c c4 c8 c
f4 f8 f f4 f8 f
g4 g8 g g4 g8 g
c4 c8 c c4 c8 c
}
>>


#### Predefined commands

\improvisationOn, \improvisationOff.

#### Selected Snippets

Guitar strum rhythms

For guitar music, it is possible to show strum rhythms, along with melody notes, chord names and fret diagrams.

\include "predefined-guitar-fretboards.ly"
<<
\new ChordNames {
\chordmode {
c1 | f | g | c
}
}
\new FretBoards {
\chordmode {
c1 | f | g | c
}
}
\new Voice \with {
\consists "Pitch_squash_engraver"
} {
\relative c'' {
\improvisationOn
c4 c8 c c4 c8 c
f4 f8 f f4 f8 f
g4 g8 g g4 g8 g
c4 c8 c c4 c8 c
}
}
\new Voice = "melody" {
\relative c'' {
c2 e4 e4
f2. r4
g2. a4
e4 c2.
}
}
\new Lyrics {
\lyricsto "melody" {
This is my song.
I like to sing.
}
}
>>


Snippets: Rhythms.

Internals Reference: RhythmicStaff, Pitch_squash_engraver.

### 1.2.4 Beams

#### Automatic beams

By default, beams are inserted automatically:

\time 2/4 c8 c c c
\time 6/8 c8 c c c8. c16 c8


If these automatic decisions are not satisfactory, beaming can be entered explicitly; see Manual beams. Beams must be entered manually if beams are to be extended over rests.

If automatic beaming is not required, it may be turned off with \autoBeamOff and on with \autoBeamOn:

c4 c8 c8. c16 c8. c16 c8
\autoBeamOff
c4 c8 c8. c16 c8.
\autoBeamOn
c16 c8


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.

Beaming patterns that differ from the automatic defaults can be created; see Setting automatic beam behavior.

#### Predefined commands

\autoBeamOff, \autoBeamOn.

#### Selected Snippets

Beams across line breaks

Line breaks are normally forbidden when beams cross bar lines. This behavior can be changed as shown:

\relative c'' {
\override Beam #'breakable = ##t
c8 c[ c] c[ c] c[ c] c[ \break
c8] c[ c] c[ c] c[ c] c
}


Changing beam knee gap

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.

{
%\set Staff.autoBeaming = ##f % turns off all autobeaming
\partcombine
{
\autoBeamOff % applies to split up stems
\repeat unfold 4 a'16
%\autoBeamOff % applies to combined up stems
\repeat unfold 4 a'8
\repeat unfold 4 a'16
}
{
\autoBeamOff % applies to down stems
\repeat unfold 4 f'8
\repeat unfold 8 f'16 |
}
}


Notation Reference: Manual beams, Setting automatic beam behavior.

Installed Files: ‘scm/auto-beam.scm’.

Snippets: Rhythms.

Internals Reference: Auto_beam_engraver, Beam_engraver, Beam, BeamEvent, BeamForbidEvent, beam-interface, unbreakable-spanner-interface.

#### 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 is used to determine the beam placement. If no beamExceptions rule is defined for the time signature in force, the beam placement is determined by the settings of baseMoment and beatStructure.

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

\set Timing.beamExceptions = #'()


#### Beaming based on baseMoment and beatStructure

In most instances, automatic beams will end at the end of a beat. The ending points for beats are determined 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.

\time 5/16
c16^"default" c c c c |
\set Timing.beatStructure = #'(2 3)
c16^"(2+3)" c c c c |
\set Timing.beatStructure = #'(3 2)
c16^"(3+2)" c c c c |


If a common time signature is being used, beamExceptions must be disabled to enable beatStructure to work. The \set Timing.beamExceptions = #'() command can always be included if beaming is being determined by beatStructure.

\time 4/4
a8^"default" a a a a a a a

\set Timing.baseMoment = #(ly:make-moment 1 4)
\set Timing.beatStructure = #'(1 1 1 1)
a8^"no change" a a a a a a a

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

\new Staff {
\time 7/8
\set Staff.beatStructure = #'(2 3 2)
<<
\new Voice = one {
\relative c'' {
a8 a a a a a a
}
}
\new Voice = two {
\relative c' {
\voiceTwo
\set Voice.beatStructure = #'(1 3 3)
f8 f f f f f f
}
}
>>
}


When multiple voices are used the Staff context must be specified if the beaming is to be applied to all voices in the staff:

\time 7/8
% rhythm 3-1-1-2
% Change applied to Voice by default --  does not work correctly
% Because of autogenerated voices, all beating will
% be at baseMoment (1 . 8)
\set beatStructure = #'(3 1 1 2)
<< {a8 a a a16 a a a a8 a} \\ {f4. f8 f f f} >>

% Works correctly with context Staff specified
\set Staff.beatStructure = #'(3 1 1 2)
<< {a8 a a a16 a a a a8 a} \\ {f4. f8 f f f} >>


The value of baseMoment can be adjusted to change the beaming behavior, if desired. When this is done, the value of beatStructure must be set to be compatible with the new value of baseMoment.

\time 5/8
\set Timing.baseMoment = #(ly:make-moment 1 16)
\set Timing.beatStructure = #'(7 3)
\repeat unfold 10 { a16 }


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.

\time 3/16
\set Timing.beatStructure = #'(2 1)
\set Timing.beamExceptions =
#'(                         ;start of alist
(end .                   ;entry for end of beams
(                       ;start of alist of end points
((1 . 32) . (2 2 2))   ;rule for 1/32 beams -- end each 1/16
)))                     %close all entries
c16 c c |
\repeat unfold 6 { c32 } |


beamExceptions is an alist with a key of rule-type and a value of beaming-rules.

At this time the only available value of rule-type is 'end for beam ending.

Beaming-rules is a scheme alist (or list of pairs) that indicates the beam type and the grouping to be applied to beams containing notes with a shortest duration of that beam type.

#'((beam-type1 . grouping-1)
(beam-type2 . grouping-2)
(beam-type3 . grouping-3))


Beam type is a scheme pair indicating the duration of the beam, e.g., (1 . 16).

Grouping is a scheme list indicating the grouping to be applied to the beam. The grouping is in units of the beam type.

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.

\time 6/8
\repeat unfold 6 { a8 }
% group (4 + 2)
\set Timing.beatStructure = #'(4 2)
\repeat unfold 6 { a8 }
% go back to default behavior
\time 6/8
\repeat unfold 6 { a8 }


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.

\time 4/4
\set Timing.baseMoment = #(ly:make-moment 1 8)
\set Timing.beatStructure = #'(3 3 2)
% This won't beam (3 3 2) because of beamExceptions
\repeat unfold 8 {c8} |
% This will beam (3 3 2) because we clear beamExceptions
\set Timing.beamExceptions = #'()
\repeat unfold 8 {c8}


In a similar fashion, eighth notes in 3/4 time are beamed as a full measure by default. To beam eighth notes in 3/4 time on the beat, reset beamExceptions.

\time 3/4
% by default we beam in (6) due to beamExceptions
\repeat unfold 6 {a8} |
% This will beam (1 1 1) due to beatLength
\set Timing.beamExceptions = #'()
\repeat unfold 6 {a8}


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:

\time 3/4
r4. a8 a a |
\set Timing.beamHalfMeasure = ##f
r4. a8 a a |


#### 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 determined 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 just one beam between the sub-groups. 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:

\relative c'' {
c32[ c c c c c c c]
\set subdivideBeams = ##t
c32[ c c c c c c c]

% Set beam sub-group length to an eighth note
\set baseMoment = #(ly:make-moment 1 8)
\set beatStructure = #'(2 2 2 2)
c32[ c c c c c c c]

% Set beam sub-group length to a sixteenth note
\set baseMoment = #(ly:make-moment 1 16)
\set beatStructure = #'(4 4 4 4)
c32[ c c c c c c c]
}


Strict beat beaming

Beamlets can be set to point in the direction of the beat to which they belong. The first beam avoids sticking out flags (the default); the second beam strictly follows the beat.

\relative c'' {
\time 6/8
a8. a16 a a
\set strictBeatBeaming = ##t
a8. a16 a a
}


Conducting signs measure grouping signs

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

\score {
\new Voice \relative c'' {
\time 9/8
g8 g d d g g a( bes g) |
\set Timing.beatStructure = #'(2 2 2 3)
g8 g d d g g a( bes g) |
\time #'(4 5) 9/8
g8 g d d g g a( bes g) |
\time 5/8
a4. g4 |
}
\layout {
\context {
\Staff
\consists "Measure_grouping_engraver"
}
}
}


Beam endings in Score context

Beam-ending rules specified in the Score context apply to all staves, but can be modified at both Staff and Voice levels:

\relative c'' {
\time 5/4
% Set default beaming for all staves
\set Score.baseMoment = #(ly:make-moment 1 8)
\set Score.beatStructure = #'(3 4 3)
<<
\new Staff {
c8 c c c c c c c c c
}
\new Staff {
% Modify beaming for just this staff
\set Staff.beatStructure = #'(6 4)
c8 c c c c c c c c c
}
\new Staff {
% Inherit beaming from Score context
<<
{
\voiceOne
c8 c c c c c c c c c
}
% Modify beaming for this voice only
\new Voice {
\voiceTwo
\set Voice.beatStructure = #'(6 4)
a8 a a a a a a a a a
}
>>
}
>>
}


Notation Reference: Time signature.

Installed Files: ‘scm/time-signature-settings.scm’.

Snippets: Rhythms.

Internals Reference: Auto_beam_engraver, Beam, BeamForbidEvent, beam-interface.

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

<<
\new Staff {
\time 3/4
\set Timing.baseMoment = #(ly:make-moment 1 8)
\set Timing.beatStructure = #'(1 5)
\repeat unfold 6 { a8 }
}
\new Staff {
\repeat unfold 6 { a8 }
}
>>


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.

<<
\new Staff {
\overrideTimeSignatureSettings
3/4               % timeSignatureFraction
1/8               % baseMomentFraction
#'(1 5)           % beatStructure
#'()		% beamExceptions
\time 3/4
\repeat unfold 6 { a8 }
}
\new Staff {
\time 3/4
\repeat unfold 6 { a8 }
}
>>


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

r4 r8[ g' a r] r g[ | a] r


Beaming direction can be set manually using direction indicators:

c8^[ d e] c,_[ d e f g]


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

\time 2/4
c8 c\noBeam c c


Grace note beams and normal note beams can occur simultaneously. Unbeamed grace notes are not put into normal note beams.

c4 d8[
\grace { e32[ d c d] }
e8] e[ e
\grace { f16 }
e8 e]


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.

a8[ r16 f g a]
a8[ r16
\set stemLeftBeamCount = #2
\set stemRightBeamCount = #1
f16
\set stemLeftBeamCount = #1
g16 a]


#### Predefined commands

\noBeam.

#### Selected Snippets

Flat flags and beam nibs

Flat flags on lone notes and beam nibs at the ends of beamed figures are both possible with a combination of stemLeftBeamCount, stemRightBeamCount and paired [] beam indicators.

For right-pointing flat flags on lone notes, use paired [] beam indicators and set stemLeftBeamCount to zero (see Example 1).

For left-pointing flat flags, set stemRightBeamCount instead (Example 2).

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 c'16[] in the last example have nothing to do with the \set two notes prior.)

\score {
<<
% Example 1
\new RhythmicStaff {
\set stemLeftBeamCount = #0
c16[]
r8.
}
% Example 2
\new RhythmicStaff {
r8.
\set stemRightBeamCount = #0
c16[]
}
% Example 3
\new RhythmicStaff {
c16 c
\set stemRightBeamCount = #2
c16 r r
\set stemLeftBeamCount = #2
c16 c c
}
% Example 4
\new RhythmicStaff {
c16 c
\set stemRightBeamCount = #2
c16 r
c16[]
r16
\set stemLeftBeamCount = #2
c16 c
}
>>
}


Notation Reference: Direction and placement, Grace notes.

Snippets: Rhythms.

Internals Reference: Beam, BeamEvent, Beam_engraver, beam-interface, Stem_engraver.

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

\override Beam #'grow-direction = #LEFT
\featherDurations #(ly:make-moment 2 1)
{ c16[ c c c c c c c] }
\override Beam #'grow-direction = #RIGHT
\featherDurations #(ly:make-moment 2 3)
{ c32[ d e f] }
% revert to non-feathered beams
\override Beam #'grow-direction = #'()
{ g32[ a b c] }


The spacing in the printed output represents the note durations only approximately, but the MIDI output is exact.

#### Predefined commands

\featherDurations.

Snippets: Rhythms.

#### Known issues and warnings

The \featherDurations command only works with very short music snippets, and when numbers in the fraction are small.

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

e4 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 which 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:

f1 \bar "|"
f1 \bar "."
g1 \bar "||"
a1 \bar ".|"
b1 \bar ".|."
c1 \bar "|.|"
d1 \bar "|."
e1


together with dotted and dashed bar lines:

f1 \bar ":"
g1 \bar "dashed"
a1


and five types of repeat bar line:

f1 \bar "|:"
g1 \bar ":|:"
a1 \bar ":|.|:"
b1 \bar ":|.:"
c1 \bar ":|"
e1


Additionally, a bar line can be printed as a simple tick:

f1 \bar "'"


However, as such ticks are typically used in Gregorian chant, it is preferable to use \divisioMinima there instead, described in the section Divisiones in Gregorian chant.

For in-line segno signs, there are three types of bar lines which differ in their behavior at line breaks:

c4 c c c
\bar "S"
c4 c c c \break
\bar "S"
c4 c c c
\bar "|S"
c4 c c c \break
\bar "|S"
c4 c c c
\bar "S|"
c4 c c c \break
\bar "S|"
c1


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.

c4 c c c
\bar "||:"
c4 c c c \break
\bar "||:"
c4 c c c


For combinations of repeats with the segno sign, there are six different variations:

c4 c c c
\bar ":|S"
c4 c c c \break
\bar ":|S"
c4 c c c
\bar ":|S."
c4 c c c \break
\bar ":|S."
c4 c c c
\bar "S|:"
c4 c c c \break
\bar "S|:"
c4 c c c
\bar ".S|:"
c4 c c c \break
\bar ".S|:"
c4 c c c
\bar ":|S|:"
c4 c c c \break
\bar ":|S|:"
c4 c c c
\bar ":|S.|:"
c4 c c c \break
\bar ":|S.|:"
c1


Additionally there is an \inStaffSegno command which creates a segno bar, placed in cooperation with the \repeat volta command.

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.

<<
\new StaffGroup <<
\new Staff {
e4 d
\bar "||"
f4 e
}
\new Staff { \clef bass c4 g e g }
>>
\new Staff { \clef bass c2 c2 }
>>


#### Selected Snippets

The command ‘\bar bartype’ is a shortcut for ‘\set Timing.whichBar = bartype’. A bar line is created whenever the whichBar property is set.

The default bar type used for automatically inserted bar lines is "|". This may be changed at any time with ‘\set Timing.defaultBarType = bartype’.

Notation Reference: Line breaking, Repeats, Grouping staves.

Snippets: Rhythms.

Internals Reference: BarLine (created at Staff level), SpanBar (across staves), Timing_translator (for Timing properties).

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

c1 c c c
\break
\set Score.currentBarNumber = #50
c1 c c c


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:

\override Score.BarNumber #'break-visibility = #'#(#t #t #t)
\set Score.currentBarNumber = #11
% Permit first bar number to be printed
\bar ""
c1 | c | c | c
\break
c1 | c | c | c


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

\relative c' {
\set Score.barNumberVisibility = #all-bar-numbers-visible
\bar ""
c1 | d | e | f \break
g1 | e | d | c
}


Printing bar numbers at regular intervals

Bar numbers can be printed at regular intervals by setting the property barNumberVisibility. Here the bar numbers are printed every two measures except at the end of the line.

\relative c' {
\override Score.BarNumber #'break-visibility = #end-of-line-invisible
\set Score.currentBarNumber = #11
% Permit first bar number to be printed
\bar ""
% Print a bar number every second measure
\set Score.barNumberVisibility = #(every-nth-bar-number-visible 2)
c1 | c | c | c | c
\break
c1 | c | c | c | c
}


Printing bar numbers inside boxes or circles

Bar numbers can also be printed inside boxes or circles.

\relative c' {
% Prevent bar numbers at the end of a line and permit them elsewhere
\override Score.BarNumber #'break-visibility = #end-of-line-invisible
\set Score.barNumberVisibility = #(every-nth-bar-number-visible 4)

% Increase the size of the bar number by 2
\override Score.BarNumber #'font-size = #2

% Draw a box round the following bar number(s)
\override Score.BarNumber #'stencil
= #(make-stencil-boxer 0.1 0.25 ly:text-interface::print)
\repeat unfold 5 { c1 }

% Draw a circle round the following bar number(s)
\override Score.BarNumber #'stencil
= #(make-stencil-circler 0.1 0.25 ly:text-interface::print)
\repeat unfold 4 { c1 } \bar "|."
}


Alternative bar numbering

Two alternative methods for bar numbering can be set, especially for when using repeated music.

\relative c'{
\set Score.alternativeNumberingStyle = #'numbers
\repeat volta 3 { c4 d e f | }
\alternative {
{ c4 d e f | c2 d \break }
{ f4 g a b | f4 g a b | f2 a | \break }
{ c4 d e f | c2 d }
}
c1 \break
\set Score.alternativeNumberingStyle = #'numbers-with-letters
\repeat volta 3 { c,4 d e f | }
\alternative {
{ c4 d e f | c2 d \break }
{ f4 g a b | f4 g a b | f2 a | \break }
{ c4 d e f | c2 d }
}
c1
}


Aligning bar numbers

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.

\relative c' {
\set Score.currentBarNumber = #111
\override Score.BarNumber #'break-visibility = #all-visible
% Increase the size of the bar number by 2
\override Score.BarNumber #'font-size = #2
% Print a bar number every second measure
\set Score.barNumberVisibility = #(every-nth-bar-number-visible 2)
c1 | c1
% Center-align bar numbers
\override Score.BarNumber #'self-alignment-X = #CENTER
c1 | c1
% Left-align bar numbers
\override Score.BarNumber #'self-alignment-X = #LEFT
c1 | c1
}


Removing bar numbers from a score

Bar numbers can be removed entirely by removing the Bar_number_engraver from the Score context.

\layout {
\context {
\Score
\remove "Bar_number_engraver"
}
}

\relative c'' {
c4 c c c \break
c4 c c c
}


Snippets: Rhythms.

Internals Reference: BarNumber, Bar_number_engraver.

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


Bar checks can also be used in lyrics:

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


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.

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

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

Snippets: Rhythms.

#### Rehearsal marks

To print a rehearsal mark, use the \mark command.

c1 \mark \default
c1 \mark \default
c1 \mark \default
c1 \mark \default


The mark is incremented automatically if you use \mark \default, but you can also use an integer argument to set the mark manually. The value to use is stored in the property rehearsalMark.

c1 \mark \default
c1 \mark \default
c1 \mark #8
c1 \mark \default
c1 \mark \default


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

\set Score.markFormatter = #format-mark-alphabet
\set Score.markFormatter = #format-mark-box-alphabet
\set Score.markFormatter = #format-mark-circle-alphabet

\set Score.markFormatter = #format-mark-box-alphabet
c1 \mark \default
c1 \mark \default
c1 \mark #8
c1 \mark \default
c1 \mark \default


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.

\set Score.markFormatter = #format-mark-numbers
c1 \mark \default
c1 \mark \default
\set Score.markFormatter = #format-mark-box-numbers
c1 \mark \default
\set Score.markFormatter = #format-mark-circle-numbers
c1 \mark \default
\set Score.markFormatter = #format-mark-circle-letters
c1


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.

\mark \markup{ \box A1 }


Music glyphs (such as the segno sign) may be printed inside a \mark

c1 \mark \markup { \musicglyph #"scripts.segno" }
c1 \mark \markup { \musicglyph #"scripts.coda" }
c1 \mark \markup { \musicglyph #"scripts.ufermata" }
c1


See The Feta font, for a list of symbols which may be printed with \musicglyph.

For common tweaks to the positioning of rehearsal marks, see Formatting text. For more precise control, see break-alignable-interface in Aligning objects.

The file ‘scm/translation-functions.scm’ contains the definitions of format-mark-numbers and format-mark-letters. They can be used as inspiration for other formatting functions.

Notation Reference: The Feta font, Formatting text, Aligning objects.

Installed Files: ‘scm/translation-functions.scm’.

Snippets: Rhythms.

Internals Reference: MarkEvent, Mark_engraver, RehearsalMark.

### 1.2.6 Special rhythmic concerns

#### Grace notes

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

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

\acciaccatura d8 c4
\appoggiatura e8 d4
\acciaccatura { g16[ f] } e2
\slashedGrace a,8 g4
\slashedGrace b16 a4(
\slashedGrace b8 a2)


The placement of grace notes is synchronized between different staves. In the following example, there are two sixteenth grace notes for every eighth grace note

<<
\new Staff { e2 \grace { c16[ d e f] } e2 }
\new Staff { c2 \grace { g8[ b] } c2 }
>>


If you want to end a note with a grace, use the \afterGrace command. It takes two arguments: the main note, and the grace notes following the main note.

c1 \afterGrace d1 { c16[ d] } c1


This will put the grace notes after a space lasting 3/4 of the length of the main note. The default fraction 3/4 can be changed by setting afterGraceFraction. The following example shows the results from setting the space at the default, at 15/16, and finally at 1/2 of the main note.

<<
\new Staff {
c1 \afterGrace d1 { c16[ d] } c1
}
\new Staff {
#(define afterGraceFraction (cons 15 16))
c1 \afterGrace d1 { c16[ d] } c1
}
\new Staff {
#(define afterGraceFraction (cons 1 2))
c1 \afterGrace d1 { c16[ d] } c1
}
>>


The space between the main note and the grace note may also be specified using spacers. The following example places the grace note after a space lasting 7/8 of the main note.

\new Voice {
<<
{ d1^\trill_( }
{ s2 s4. \grace { c16[ d] } }
>>
c1)
}


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.

\new Voice {
\acciaccatura {
\stemDown
f16->
\stemNeutral
}
g4 e c2
}


#### Selected Snippets

Using grace note slashes with normal heads

The slash through the stem found in acciaccaturas can be applied in other situations.

\relative c'' {
\override Flag #'stroke-style = #"grace"
c8( d2) e8( f4)
}


Tweaking grace layout within music

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.

\relative c'' {
\new Staff {
$(remove-grace-property 'Voice 'Stem 'direction)$(add-grace-property 'Voice 'NoteHead 'style 'cross)
\new Voice {
\acciaccatura { f16 } g4
\grace { d16[ e] } f4
\appoggiatura { f,32[ g a] } e2
}
}
}


Redefining grace note global defaults

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.

startAcciaccaturaMusic = {
<>(
\override Flag #'stroke-style = #"grace"
\slurDashed
}

stopAcciaccaturaMusic = {
\revert Flag #'stroke-style
\slurSolid
<>)
}

\relative c'' {
\acciaccatura d8 c1
}


Positioning grace notes with floating space

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.

\relative c'' {
<<
\override Score.SpacingSpanner #'strict-grace-spacing = ##t
\new Staff \new Voice {
\afterGrace c4 { c16[ c8 c16] }
c8[ \grace { b16[ d] } c8]
c4 r
}
\new Staff {
c16 c c c c c c c c4 r
}
>>
}


Music Glossary: grace notes, acciaccatura, appoggiatura.

Notation Reference: Scaling durations, Manual beams.

Installed Files: ‘ly/grace-init.ly’.

Snippets: Rhythms.

Internals Reference: GraceMusic, Grace_beam_engraver, Grace_engraver, Grace_spacing_engraver.

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

<<
\new Staff { e4 \bar "|:" \grace c16 d2. }
\new Staff { c4 \bar "|:" d2. }
>>


This can be remedied by inserting grace skips of the corresponding durations in the other staves. For the above example

<<
\new Staff { e4 \bar "|:" \grace c16 d2. }
\new Staff { c4 \bar "|:" \grace s16 d2. }
>>


The use of grace notes within voice contexts confuses the way the voice is typeset. This can be overcome by inserting a rest or note between the voice command and the grace note.

accMusic = {
\acciaccatura { f8 } e8 r8 \acciaccatura { f8 } e8 r4
}

\new Staff {
<<
\new Voice {
\relative c'' {
r8 r8 \voiceOne \accMusic \oneVoice r8 |
r8 \voiceOne r8 \accMusic \oneVoice r8 |
}
}
\new Voice {
\relative c' {
s8 s8 \voiceTwo \accMusic \oneVoice s8 |
s8 \voiceTwo r8 \accMusic \oneVoice s8 |
}
}
>>
}


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:

\acciaccatura { c'8[ d' e' f' g'] }


becomes:

\acciaccatura { c'16[ d' e' f' g'] }


Or explicitly change the musical duration:

\acciaccatura { \scaleDurations 1/2 { c'8[ d' e' f' g'] } }


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.

MyCadenza = \relative c' {
c4 d8 e f g g4
f2 g4 g
}

\new GrandStaff <<
\new Staff {
}
\new Staff {
c'1
c'1
}
>>


Snippets: Rhythms.

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.

\new Voice \relative c' {
\set Timing.measureLength = #(ly:make-moment 5 4)
c1 c4 |
c1 c4 |
c4 c
\set Timing.measurePosition = #(ly:make-moment 5 8)
b4 b b8 |
c4 c1 |
}


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.

Notation Reference: Bar numbers, Unmetered music.

Snippets: Rhythms.

Internals Reference: Timing_translator, Score.

## 1.3 Expressive marks

This section lists various expressive marks that can be created in a score.

### 1.3.1 Expressive marks attached to notes

This section explains how to create expressive marks that are attached to notes: articulations, ornamentations, and dynamics. Methods to create new dynamic markings are also discussed.

#### Articulations and ornamentations

A variety of symbols that denote articulations, ornamentations, and other performance indications can be attached to a note using this syntax:

note\name


The possible values for name are listed in List of articulations. For example:

c4\staccato c\mordent b2\turn
c1\fermata


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:

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

\override Script #'color = #red
\override MultiMeasureRestText #'color = #blue
a2\fermata r\fermata
R1\fermataMarkup


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.

\relative c''' {
\once \override TextScript #'script-priority = #-100
a2^\prall^\markup { \sharp }

\once \override Script #'script-priority = #-100
a2^\prall^\markup { \sharp }
}


Creating a delayed turn

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. The value of halign is used to position the turn horizontally.

\relative c'' {
\once \override TextScript #'avoid-slur = #'inside
\once \override TextScript #'outside-staff-priority = ##f
c2(^\markup \tiny \override #'(baseline-skip . 1) {
\halign #-4
\center-column {
\sharp
\musicglyph #"scripts.turn"
}
}
d4.) c8
}


Music Glossary: tenuto, accent, staccato, portato.

Learning Manual: Placement of objects.

Notation Reference: Text scripts, Direction and placement, List of articulations, Trills.

Installed Files: ‘scm/script.scm’.

Snippets: Expressive marks.

Internals Reference: Script, TextScript.

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

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.

c2\< c\!
d2\< d\f
e2\< e\>
f2\> f\!
e2\> e\mp
d2\> d\>
c1\!


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.

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

c1\< | 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:

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

c2 b4 a
g1\espressivo


Textual crescendo marks begin with \cresc. Textual decrescendos begin with \decresc or \dim. Extender lines are engraved as required.

g8\cresc a b c b c d e\mf |
f8\decresc e d c e\> d c b |
a1\dim ~ |
a2. r4\! |


Textual marks for dynamic changes can also replace hairpins:

\crescTextCresc
c4\< d e f\! |
\dimTextDecresc
g4\> e d c\! |
\dimTextDecr
e4\> d c b\! |
\dimTextDim
d4\> c b a\! |
\crescHairpin
\dimHairpin
c4\< d\! e\> d\! |


To create new absolute dynamic marks or text that should be aligned with dynamics, see New dynamic marks.

Vertical positioning of dynamics is handled by DynamicLineSpanner.

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.

<<
\new Staff \relative c' {
c2 d4 e |
c4 e e,2 |
g'4 a g a |
c1 |
}
\new Dynamics {
s1\< |
s1\f |
s2\dim s2-"rit." |
s1\p |
}
>>


#### Predefined commands

\dynamicUp, \dynamicDown, \dynamicNeutral, \crescTextCresc, \dimTextDim, \dimTextDecr, \dimTextDecresc, \crescHairpin, \dimHairpin.

#### Selected Snippets

Setting hairpin behavior at bar lines

If the note which ends a hairpin falls on a downbeat, the hairpin stops at the bar line immediately preceding. This behavior can be controlled by overriding the 'to-barline property.

\relative c'' {
e4\< e2.
e1\!
\override Hairpin #'to-barline = ##f
e4\< e2.
e1\!
}


Setting the minimum length of hairpins

If hairpins are too short, they can be lengthened by modifying the minimum-length property of the Hairpin object.

\relative c'' {
c4\< c\! d\> e\!
\override Hairpin #'minimum-length = #5
<< f1 { s4 s\< s\> s\! } >>
}


Printing hairpins using al niente notation

Hairpin dynamics may be printed with a circled tip (“al niente” notation) by setting the circled-tip property of the Hairpin object to #t.

\relative c'' {
\override Hairpin #'circled-tip = ##t
c2\< c\!
c4\> c\< c2\!
}


Vertically aligned dynamics and textscripts

By setting the 'Y-extent property to a suitable value, all DynamicLineSpanner objects (hairpins and dynamic texts) can be aligned to a common reference point, regardless of their actual extent. This way, every element will be vertically aligned, thus producing a more pleasing output.

The same idea is used to align the text scripts along their baseline.

music = \relative c' {
a'2\p b\f
e4\p f\f\> g, b\p
c2^\markup { \huge gorgeous } c^\markup { \huge fantastic }
}

{
\music
\break
\override DynamicLineSpanner #'Y-extent = #'(-1.5 . 1.5)
\override TextScript #'Y-extent = #'(-1.5 . 1.5)
\music
}


Hiding the extender line for text dynamics

Text style dynamic changes (such as cresc. and dim.) are printed with a dashed line showing their extent. This line can be suppressed in the following way:

\relative c'' {
\override DynamicTextSpanner #'style = #'none
\crescTextCresc
c1\< | d | b | c\!
}


Changing text and spanner styles for text dynamics

The text used for crescendos and decrescendos can be changed by modifying the context properties crescendoText and decrescendoText.

The style of the spanner line can be changed by modifying the 'style property of DynamicTextSpanner. The default value is 'dashed-line, and other possible values include 'line, 'dotted-line and 'none.

\relative c'' {
\set crescendoText = \markup { \italic { cresc. poco } }
\set crescendoSpanner = #'text
\override DynamicTextSpanner #'style = #'dotted-line
a2\< a
a2 a
a2 a
a2 a\mf
}


Music Glossary: al niente, crescendo, decrescendo, hairpin.

Learning Manual: Articulation and dynamics.

Snippets: Expressive marks.

Internals Reference: DynamicText, Hairpin, DynamicLineSpanner, Dynamics.

#### New dynamic marks

The easiest way to create dynamic indications is to use \markup objects.

moltoF = \markup { molto \dynamic f }

\relative c' {
<d e>16_\moltoF <d e>
<d e>2..
}


In markup mode, editorial dynamics (within parentheses or square brackets) can be created. The syntax for markup mode is described in Formatting text.

roundF = \markup {
\center-align \concat { \bold { \italic ( }
\dynamic f \bold { \italic ) } } }
boxF = \markup { \bracket { \dynamic f } }
\relative c' {
c1_\roundF
c1_\boxF
}


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

sfzp = #(make-dynamic-script "sfzp")
\relative c' {
c4 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.

roundF = \markup { \center-align \concat {
\normal-text { \bold { \italic ( } }
\dynamic f
\normal-text { \bold { \italic ) } } } }
boxF = \markup { \bracket { \dynamic f } }
mfEspress = \markup { \center-align \line {
\hspace #3.7 mf \normal-text \italic espress. } }
roundFdynamic = #(make-dynamic-script roundF)
boxFdynamic = #(make-dynamic-script boxF)
mfEspressDynamic = #(make-dynamic-script mfEspress)
\relative c' {
c4_\roundFdynamic\< d e f
g,1~_\boxFdynamic\>
g1
g'1~\mfEspressDynamic
g1
}


The Scheme form of markup mode may be used instead. Its syntax is explained in Markup construction in Scheme.

moltoF = #(make-dynamic-script
(markup #:normal-text "molto"
#:dynamic "f"))
\relative c' {
<d e>16 <d e>
<d e>2..\moltoF
}


Font settings in markup mode are described in Selecting font and font size.

Extending LilyPond: Markup construction in Scheme.

Snippets: Expressive marks.

### 1.3.2 Expressive marks as curves

This section explains how to create various expressive marks that are curved: normal slurs, phrasing slurs, breath marks, falls, and doits.

#### Slurs

Slurs are entered using parentheses:

Note: In polyphonic music, a slur must be terminated in the same voice it began.

f4( g a) a8 b(
a4 g2 f4)
<c e>2( <b d>2)


Slurs may be manually placed above or below the staff; see Direction and placement.

Simultaneous or overlapping slurs are not permitted, but a phrasing slur can overlap a slur. This permits two slurs to be printed at once. For details, see Phrasing slurs.

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

c4( e g2)
\slurDashed
g4( e c2)
\slurDotted
c4( e g2)
\slurSolid
g4( e c2)


Slurs can also be made half-dashed (the first half dashed, the second half solid) or half-solid (the first half solid, the second half dashed):

c4( e g2)
\slurHalfDashed
g4( e c2)
\slurHalfSolid
c4( e g2)
\slurSolid
g4( e c2)


Custom dash patterns for slurs can be defined:

c4( e g2)
\slurDashPattern #0.7 #0.75
g4( e c2)
\slurDashPattern #0.5 #2.0
c4( e g2)
\slurSolid
g4( e c2)


#### Predefined commands

\slurUp, \slurDown, \slurNeutral, \slurDashed, \slurDotted, \slurHalfDashed, \slurHalfSolid, \slurDashPattern, \slurSolid.

#### Selected Snippets

Using double slurs for legato chords

Some composers write two slurs when they want legato chords. This can be achieved by setting doubleSlurs.

\relative c' {
\set doubleSlurs = ##t
<c e>4( <d f> <c e> <d f>)
}


Positioning text markups inside slurs

Text markups need to have the outside-staff-priority property set to false in order to be printed inside slurs.

\relative c'' {
\override TextScript #'avoid-slur = #'inside
\override TextScript #'outside-staff-priority = ##f
c2(^\markup { \halign #-10 \natural } d4.) c8
}


Making slurs with complex dash structure

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.

\relative c' {
\once \override
Slur #'dash-definition = #'((0 0.3 0.1 0.75)
(0.3 0.6 1 1)
(0.65 1.0 0.4 0.75))
c4( d e f)
\once \override
Slur #'dash-definition = #'((0 0.25 1 1)
(0.3 0.7 0.4 0.75)
(0.75 1.0 1 1))
c4( d e f)
}


Music Glossary: slur.

Learning Manual: On the un-nestedness of brackets and ties.

Notation Reference: Direction and placement, Phrasing slurs.

Snippets: Expressive marks.

Internals Reference: Slur.

#### Phrasing slurs

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

c4$$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 not permitted.

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

c4$$e g2$$
\phrasingSlurDashed
g4$$e c2$$
\phrasingSlurDotted
c4$$e g2$$
\phrasingSlurSolid
g4$$e c2$$


Phrasing slurs can also be made half-dashed (the first half dashed, the second half solid) or half-solid (the first half solid, the second half dashed):

c4$$e g2$$
\phrasingSlurHalfDashed
g4$$e c2$$
\phrasingSlurHalfSolid
c4$$e g2$$
\phrasingSlurSolid
g4$$e c2$$


Custom dash patterns for phrasing slurs can be defined:

c4$$e g2$$
\phrasingSlurDashPattern #0.7 #0.75
g4$$e c2$$
\phrasingSlurDashPattern #0.5 #2.0
c4$$e g2$$
\phrasingSlurSolid
g4$$e c2$$


Dash pattern definitions for phrasing slurs have the same structure as dash pattern definitions for slurs. For more information about complex dash patterns, see the snippets under Slurs.

#### Predefined commands

\phrasingSlurUp, \phrasingSlurDown, \phrasingSlurNeutral, \phrasingSlurDashed, \phrasingSlurDotted, \phrasingSlurHalfDashed, \phrasingSlurHalfSolid, \phrasingSlurDashPattern, \phrasingSlurSolid.

Learning Manual: On the un-nestedness of brackets and ties.

Notation Reference: Direction and placement, Slurs.

Snippets: Expressive marks.

Internals Reference: PhrasingSlur.

#### Breath marks

Breath marks are entered using \breathe:

c2. \breathe d4


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

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

\relative c'' {
c2
\override BreathingSign #'text =
\markup { \musicglyph #"scripts.rvarcomma" }
\breathe
d2
}


Inserting a caesura

Caesura marks can be created by overriding the 'text property of the BreathingSign object. A curved caesura mark is also available.

\relative c'' {
\override BreathingSign #'text = \markup {
\musicglyph #"scripts.caesura.straight"
}
c8 e4. \breathe g8. e16 c4

\override BreathingSign #'text = \markup {
\musicglyph #"scripts.caesura.curved"
}
g8 e'4. \breathe g8. e16 c4
}


Music Glossary: caesura.

Notation Reference: Divisiones.

Snippets: Expressive marks.

Internals Reference: BreathingEvent, BreathingSign, Breathing_sign_engraver.

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

c2\bendAfter #+4
c2\bendAfter #-4
c2\bendAfter #+6.5
c2\bendAfter #-6.5
c2\bendAfter #+8
c2\bendAfter #-8


#### Selected Snippets

Adjusting the shape of falls and doits

The shortest-duration-space property may be tweaked to adjust the shape of falls and doits.

\relative c'' {
\override Score.SpacingSpanner #'shortest-duration-space = #4.0
c2-\bendAfter #5
c2-\bendAfter #-4.75
c2-\bendAfter #8.5
c2-\bendAfter #-6
}


Music Glossary: fall, doit.

Snippets: Expressive marks.

### 1.3.3 Expressive marks as lines

This section explains how to create various expressive marks that follow a linear path: glissandos, arpeggios, and trills.

#### Glissando

A glissando is created by appending \glissando to a note:

g2\glissando g'
c2\glissando c,
\afterGrace f,1\glissando f'16


A glissando can connect notes across staves:

\new PianoStaff <<
\new Staff = "right" {
e'''2\glissando
\change Staff = "left"
a,,4\glissando
\change Staff = "right"
b''8 r |
}
\new Staff = "left" {
\clef bass
s1
}
>>


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.

<c, e>1\glissando g' |
<c, e>1\glissando |
<g' b> |
\break
\set glissandoMap = #'((0 . 1) (1 . 0))
<c, g'>1\glissando |
<d a'> |
\set glissandoMap = #'((0 . 0) (0 . 1) (0 . 2))
c1\glissando |
<d f a> |
\set glissandoMap = #'((2 . 0) (1 . 0) (0 . 1))
<f d a'>1\glissando |
<c c'> |


Different styles of glissandi can be created. For details, see Line styles.

#### Selected Snippets

Contemporary glissando

A contemporary glissando without a final note can be typeset using a hidden note and cadenza timing.

\relative c'' {
\time 3/4
\override Glissando #'style = #'zigzag
c4 c
c4\glissando
\hideNotes
c,,4
\unHideNotes
\bar "|"
}


Adding timing marks to long glissandi

Skipped beats in very long glissandi are sometimes indicated by timing marks, often consisting of stems without noteheads. Such stems can also be used to carry intermediate expression markings.

If the stems do not align well with the glissando, they may need to be repositioned slightly.

glissandoSkipOn = {
\override NoteColumn #'glissando-skip = ##t
}

glissandoSkipOff = {
\revert NoteColumn #'glissando-skip
}

\relative c'' {
r8 f8\glissando
\glissandoSkipOn
f4 g a a8\noBeam
\glissandoSkipOff
a8

r8 f8\glissando
\glissandoSkipOn
g4 a8
\glissandoSkipOff
a8 |

r4 f\glissando \<
\glissandoSkipOn
a4\f \>
\glissandoSkipOff
b8\! r |
}


Making glissandi breakable

Setting the breakable property to #t in combination with after-line-breaking allows a glissando to break if it occurs at a line break:

glissandoSkipOn = {
\override NoteColumn #'glissando-skip = ##t
}

\relative c'' {
\override Glissando #'breakable = ##t
\override Glissando #'after-line-breaking = ##t
f1\glissando |
\break
a4 r2. |
f1\glissando
\once \glissandoSkipOn
\break
a2 a4 r4 |
}


Music Glossary: glissando.

Notation Reference: Line styles.

Snippets: Expressive marks.

Internals Reference: Glissando.

#### Known issues and warnings

Printing text over the line (such as gliss.) is not supported.

#### Arpeggio

An arpeggio on a chord (also known as a broken chord) is denoted by appending \arpeggio to the chord construct:

<c e g c>1\arpeggio


Different types of arpeggios may be written. \arpeggioNormal reverts to a normal arpeggio:

<c e g c>2\arpeggio

\arpeggioArrowUp
<c e g c>2\arpeggio

\arpeggioArrowDown
<c e g c>2\arpeggio

\arpeggioNormal
<c e g c>2\arpeggio


Special bracketed arpeggio symbols can be created:

<c e g c>2

\arpeggioBracket
<c e g c>2\arpeggio

\arpeggioParenthesis
<c e g c>2\arpeggio

\arpeggioParenthesisDashed
<c e g c>2\arpeggio

\arpeggioNormal
<c e g c>2\arpeggio


The dash properties of the parenthesis arpeggio are controlled with the 'dash-details property, which is described at Slurs.

Arpeggios can be explicitly written out with ties. For more information, see Ties.

#### Predefined commands

\arpeggio, \arpeggioArrowUp, \arpeggioArrowDown, \arpeggioNormal, \arpeggioBracket, \arpeggioParenthesis \arpeggioParenthesisDashed.

#### Selected Snippets

Creating cross-staff arpeggios in a piano staff

In a PianoStaff, it is possible to let an arpeggio cross between the staves by setting the property PianoStaff.connectArpeggios.

\new PianoStaff \relative c'' <<
\set PianoStaff.connectArpeggios = ##t
\new Staff {
<c e g c>4\arpeggio
<g c e g>4\arpeggio
<e g c e>4\arpeggio
<c e g c>4\arpeggio
}
\new Staff {
\clef bass
\repeat unfold 4 {
<c,, e g c>4\arpeggio
}
}
>>


Creating cross-staff arpeggios in other contexts

Cross-staff arpeggios can be created in contexts other than GrandStaff, PianoStaff and StaffGroup if the Span_arpeggio_engraver is included in the Score context.

\score {
\new ChoirStaff {
\set Score.connectArpeggios = ##t
<<
\new Voice \relative c' {
<c e>2\arpeggio
<d f>2\arpeggio
<c e>1\arpeggio
}
\new Voice \relative c {
\clef bass
<c g'>2\arpeggio
<b g'>2\arpeggio
<c g'>1\arpeggio
}
>>
}
\layout {
\context {
\Score
\consists "Span_arpeggio_engraver"
}
}
}


Creating arpeggios across notes in different voices

An arpeggio can be drawn across notes in different voices on the same staff if the Span_arpeggio_engraver is added to the Staff context:

\new Staff \with {
\consists "Span_arpeggio_engraver"
}
\relative c' {
\set Staff.connectArpeggios = ##t
<<
{ <e' g>4\arpeggio <d f> <d f>2 }
\\
{ <d, f>2\arpeggio <g b>2 }
>>
}


Music Glossary: arpeggio.

Notation Reference: Slurs, Ties.

Snippets: Expressive marks.

Internals Reference: Arpeggio, Slur, PianoStaff.

#### Known issues and warnings

It is not possible to mix connected arpeggios and unconnected arpeggios in one PianoStaff at the same point in time.

The parenthesis-style arpeggio brackets do not work for cross-staff arpeggios.

#### Trills

Short trills without an extender line are printed with \trill; see Articulations and ornamentations.

Longer trills with an extender line are made with \startTrillSpan and \stopTrillSpan:

d1\startTrillSpan
d1
c2\stopTrillSpan
r2


A trill spanner crossing a line break will restart exactly above the first note on the new line.

d1\startTrillSpan
\break
d1
c2\stopTrillSpan
r2


Consecutive trill spans will work without explicit \stopTrillSpan commands, since successive trill spanners will automatically become the right bound of the previous trill.

d1\startTrillSpan
d1
b1\startTrillSpan
d2\stopTrillSpan
r2


Trills can also be combined with grace notes. The syntax of this construct and the method to precisely position the grace notes are described in Grace notes.

d1~\afterGrace
d1\startTrillSpan { c32[ d]\stopTrillSpan }
c2 r2


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.

\pitchedTrill
d2\startTrillSpan fis
d2
c2\stopTrillSpan
r2


Subsequent accidentals of the same note in the same measure will need to be added manually. Only the accidental of the first pitched trill in a measure is printed.

\pitchedTrill
eis4\startTrillSpan fis
eis4\stopTrillSpan
\pitchedTrill
eis4\startTrillSpan cis
eis4\stopTrillSpan
\pitchedTrill
eis4\startTrillSpan fis
eis4\stopTrillSpan
\pitchedTrill
eis4\startTrillSpan fis!
eis4\stopTrillSpan


#### Predefined commands

\startTrillSpan, \stopTrillSpan.

Music Glossary: trill.

Notation Reference: Articulations and ornamentations, Grace notes.

Snippets: Expressive marks.

Internals Reference: TrillSpanner.

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

tremolo

This is used to write tremolo beams.

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

#### Normal repeats

The syntax for a normal repeat is

\repeat volta repeatcount musicexpr


where musicexpr is a music expression.

A single repeat without an alternate ending:

\repeat volta 2 { c4 d e f }
c2 d
\repeat volta 2 { d4 e f g }


Alternative endings can be produced using \alternative. Each group of alternatives must be themselves, enclosed in a set of braces.

\repeat volta repeatcount musicexpr
\alternative {
{ musicexpr }
}


where musicexpr is a music expression.

If there are more repeats than there are alternate endings, the earliest repeats are given the first alternative.

A single repeat with one alternate ending:

\repeat volta 2 { c4 d e f | }
\alternative {
{ c2 e | }
{ f2 g | }
}
c1


A single repeat with more than one alternate ending:

\repeat volta 4 { c4 d e f | }
\alternative {
{ c2 e | }
{ f2 g | }
}
c1


Multiple repeats with more than one alternate ending:

\repeat volta 3 { c4 d e f | }
\alternative {
{ c2 e | }
{ f2 g | }
{ a2 g | }
}
c1


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 starts in the middle of a measure and has no alternate endings, normally the end of the repeat will also fall in the middle of a measure, so that the two ends add up to one complete measure. In such cases, the repeat signs do not constitute true bar lines. Do not use \partial commands or bar checks where these repeat signs are printed:

% no \partial here
c4 e g  % no bar check here
% no \partial here
\repeat volta 4 {
e4 |
c2 e |
% no \partial here
g4 g g  % no bar check here
}
% no \partial here
g4 |
a2 a |
g1 |


Similarly, if a repeat begins with the initial partial measure of a score and has no alternate endings, the same conditions apply as in the above example, except that in this case the \partial command is required at the beginning of the score:

\partial 4  % required
\repeat volta 4 {
e4 |
c2 e |
% no \partial here
g4 g g  % no bar check here
}
% no \partial here
g4 |
a2 a |
g1 |


When alternate endings are added to a repeat that begins with an incomplete measure, it becomes necessary to set the Timing.measureLength context property manually, in the following specific places:

• at the start of any incomplete measures in the \alternative block, which normally occur at the end of each alternative, except (in most cases) the last.
• at the start of each alternative, except the first.
\partial 4
\repeat volta 2 { e4 | c2 e | }
\alternative {
{
f2 d |
\set Timing.measureLength = #(ly:make-moment 3 4)
g4 g g  % optional bar check is allowed here
}
{
\set Timing.measureLength = #(ly:make-moment 4 4)
a2 a |
}
}
g1 |


The measureLength property is described in Time administration.

The \inStaffSegno command can be used to place the segno symbol in cooperation with the \repeat volta command. Alternative bar line symbols can be set in a Score context by overriding the properties segnoType, startRepeatSegnoType, endRepeatSegnoType or doubleRepeatSegnoType as required.

e1
\repeat volta 2 {
\inStaffSegno
f2 g a b
}
c1_"D.S." \bar "|."


Ties may be added to a second ending:

c1
\repeat volta 2 { c4 d e f~ }
\alternative {
{ f2 d }
{ f2\repeatTie f, }
}


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

\relative c'' {
\time 3/4
c4 c c
\set Score.voltaSpannerDuration = #(ly:make-moment 3 4)
\repeat volta 5 { d4 d d }
\alternative {
{
e4 e e
f4 f f
}
{ g4 g g }
}
}


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.

<<
\new Staff { \repeat volta 2 { c'1 } \alternative { c' } }
\new Staff { \repeat volta 2 { c'1 } \alternative { c' } }
\new Staff \with { \consists "Volta_engraver" } { c'2 g' e' a' }
\new Staff { \repeat volta 2 { c'1 } \alternative { c' } }
>>


Setting the double repeat default for volte

There are three different styles of double repeats for volte, that can be set using doubleRepeatType.

\relative c'' {
\repeat volta 1 { c1 }
\set Score.doubleRepeatType = #":|:"
\repeat volta 1 { c1 }
\set Score.doubleRepeatType = #":|.|:"
\repeat volta 1 { c1 }
\set Score.doubleRepeatType = #":|.:"
\repeat volta 1 { c1 }
}


Alternative bar numbering

Two alternative methods for bar numbering can be set, especially for when using repeated music.

\relative c'{
\set Score.alternativeNumberingStyle = #'numbers
\repeat volta 3 { c4 d e f | }
\alternative {
{ c4 d e f | c2 d \break }
{ f4 g a b | f4 g a b | f2 a | \break }
{ c4 d e f | c2 d }
}
c1 \break
\set Score.alternativeNumberingStyle = #'numbers-with-letters
\repeat volta 3 { c,4 d e f | }
\alternative {
{ c4 d e f | c2 d \break }
{ f4 g a b | f4 g a b | f2 a | \break }
{ c4 d e f | c2 d }
}
c1
}


Music Glossary: repeat, volta.

Notation Reference: Bar lines, Modifying context plug-ins, Time administration.

Snippets: Repeats.

Internals Reference: VoltaBracket, RepeatedMusic, VoltaRepeatedMusic, UnfoldedRepeatedMusic.

#### Known issues and warnings

Slurs that span from a \repeat block into an \alternative block will only work for the first alternate ending. Also, slurs cannot wrap around from the end of one alternative back to the beginning of the repeat.

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.

start-repeat

Print a |: bar line.

c1
\set Score.repeatCommands = #'(start-repeat)
d4 e f g
c1


As per standard engraving practice, repeat signs are not printed at the beginning of a piece.

end-repeat

Print a :| bar line:

c1
d4 e f g
\set Score.repeatCommands = #'(end-repeat)
c1


(volta number) ... (volta #f)

Create a new volta with the specified number. The volta bracket must be explicitly terminated, or it will not be printed.

f4 g a b
\set Score.repeatCommands = #'((volta "2"))
g4 a g a
\set Score.repeatCommands = #'((volta #f))
c1


Multiple repeat commands may occur at the same point:

f4 g a b
\set Score.repeatCommands = #'((volta "2, 5") end-repeat)
g4 a g a
c1
\set Score.repeatCommands = #'((volta #f) (volta "95") end-repeat)
b1
\set Score.repeatCommands = #'((volta #f))


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.

voltaAdLib = \markup { 1. 2. 3... \text \italic { ad lib. } }
\relative c'' {
c1
\set Score.repeatCommands =
c4 b d e
\set Score.repeatCommands = #'((volta #f) (volta "4.") end-repeat)
f1
\set Score.repeatCommands = #'((volta #f))
}


#### Selected Snippets

Printing a repeat sign at the beginning of a piece

A |: bar line can be printed at the beginning of a piece, by overriding the relevant property:

\relative c'' {
\once \override Score.BreakAlignment #'break-align-orders =
#(make-vector 3 '(instrument-name
left-edge
ambitus
breathing-sign
clef
key-signature
time-signature
staff-bar
custos))
\once \override Staff.TimeSignature #'space-alist =
#'((first-note . (fixed-space . 2.0))
(right-edge . (extra-space . 0.5))
;; free up some space between time signature
;; and repeat bar line
(staff-bar . (extra-space . 1)))
\bar "|:"
c1
d1
d4 e f g
}


Notation Reference: Bar lines, Formatting text.

Snippets: Repeats.

Internals Reference: VoltaBracket, RepeatedMusic, VoltaRepeatedMusic.

#### Written-out repeats

By using the unfold command, repeats can be used to simplify the writing out of repetitious music. The syntax is

\repeat unfold repeatcount musicexpr


where musicexpr is a music expression and repeatcount is the number of times musicexpr is repeated.

\repeat unfold 2 { c4 d e f }
c1


In some cases, especially in a \relative context, the \repeat unfold function is not the same as writing out the music expression multiple times. E.g,

\repeat unfold 2 { a'4 b c }


is not equivalent to

a'4 b c | a'4 b c


Unfold repeats can be made with alternate endings.

\repeat unfold 2 { c4 d e f }
\alternative {
{ c2 g' }
{ c,2 b }
}
c1


If there are more repeats than there are alternate endings, the first alternative is applied multiple times until the remaining alternatives make up the total number of repeats.

\repeat unfold 4 { c4 d e f }
\alternative {
{ c2 g' }
{ c,2 b }
{ e2 d }
}
c1


If there are more alternate endings than repeats then only the first alternatives are applied. The remaining alternatives will be ignored and not printed.

\repeat unfold 2 { c4 d e f }
\alternative {
{ c2 g' }
{ c,2 b }
{ e2 d }
}
c1


It is also possible to nest multiple unfold functions (with or without alternate endings).

\repeat unfold 2 {
\repeat unfold 2 { c4 d e f }
\alternative {
{ c2 g' }
{ c,2 b }
}
}
c1


Chord constructs can be repeated by the chord repetition symbol q. See Chord repetition.

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

Notation Reference: Chord repetition.

Snippets: Repeats.

Internals Reference: RepeatedMusic, UnfoldedRepeatedMusic.

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

#### Percent repeats

Repeated short patterns are printed once, and the repeated pattern is replaced with a special sign.

The syntax is

\repeat percent number musicexpr


where musicexpr is a music expression.

Patterns that are shorter than one measure are replaced by slashes.

\repeat percent 4 { c128 d e f }
\repeat percent 4 { c64 d e f }
\repeat percent 5 { c32 d e f }
\repeat percent 4 { c16 d e f }
\repeat percent 4 { c8 d }
\repeat percent 4 { c4 }
\repeat percent 2 { c2 }


Patterns of one or two measures are replaced by percent-like symbols.

\repeat percent 2 { c4 d e f }
\repeat percent 2 { c2 d }
\repeat percent 2 { c1 }


\repeat percent 3 { c4 d e f | c2 g' }


Patterns that are shorter than one measure but contain mixed durations use a double-percent symbol.

\repeat percent 4 { c8. <d f>16 }
\repeat percent 2 { \times 2/3 { r8 c d } e4 }


#### Selected Snippets

Percent repeat counter

Measure repeats of more than two repeats can get a counter when the convenient property is switched, as shown in this example:

\relative c'' {
\set countPercentRepeats = ##t
\repeat percent 4 { c1 }
}


Percent repeat count visibility

Percent repeat counters can be shown at regular intervals by setting the context property repeatCountVisibility.

\relative c'' {
\set countPercentRepeats = ##t
\set repeatCountVisibility = #(every-nth-repeat-count-visible 5)
\repeat percent 10 { c1 } \break
\set repeatCountVisibility = #(every-nth-repeat-count-visible 2)
\repeat percent 6 { c1 d1 }
}


Isolated percent repeats

Isolated percents can also be printed.

makePercent =
#(define-music-function (parser location note) (ly:music?)
"Make a percent repeat the same length as NOTE."
(make-music 'PercentEvent
'length (ly:music-length note)))

\relative c'' {
\makePercent s1
}


Music Glossary: percent repeat, simile.

Snippets: Repeats.

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

To place tremolo marks between notes, use \repeat with tremolo style:

\repeat tremolo 8 { c16 d }
\repeat tremolo 6 { c16 d }
\repeat tremolo 2 { c16 d }


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 (stored in tremoloFlags) is used:

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

\new PianoStaff <<
\new Staff = "up" \relative c'' {
\key a \major
\time 3/8
s4.
}
\new Staff = "down" \relative c'' {
\key a \major
\time 3/8
\voiceOne
\repeat tremolo 6 {
<a e'>32
{
\change Staff = "up"
\voiceTwo
<cis a' dis>32
}
}
}
>>


Snippets: Repeats.

## 1.5 Simultaneous notes

Polyphony in music refers to having more than one voice occurring in a piece of music. Polyphony in LilyPond refers to having more than one voice on the same staff.

### 1.5.1 Single voice

This section discusses simultaneous notes inside the same voice.

#### Chorded notes

A chord is formed by enclosing a set of pitches between < and >. A chord may be followed by a duration just like simple notes.

<a c e>1 <a c e>2 <f a c e>4 <a c>8. <g c e>16


Chords may also be followed by articulations, again just like simple notes.

<a c e>1\fermata <a c e>2-> <f a c e>4\prall <a c>8.^| <g c e>16-.


The notes within the chord themselves can also be followed by articulation and ornamentation.

<a c\prall e>1 <a-> c-^ e>2 <f-. a c-. e-.>4
<a-+ c-->8. <g\fermata c e\turn>16


However some notation, such as dynamics, hairpins and slurs must be attached to the chord, rather than notes within the chord, otherwise they will not print.

<a\f c( e>1 <a c) e>\f <a\< c e>( <a\! c e>)
<a c e>\< <a c e> <a c e>\!


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

\grace { g8[( a b] }
<> ) \p \< -. -\markup \italic "sempre staccato"
\repeat unfold 4 { c4 e }  c1\f


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.

<a c e>1 <f a c> <a c e> <f' a c> <b, e b,>


Music Glossary: chord.

Learning Manual: Combining notes into chords.

Notation Reference: Chord notation, Articulations and ornamentations, Relative octave entry, Multiple voices.

Snippets: Simultaneous notes.

#### Known issues and warnings

Chords containing more than two pitches within a staff space, such as ‘<e f! fis!>’, create overlapping noteheads. Depending on the situation, better representations might involve

• temporary use of Multiple voices, ‘<< f! \\ <e fis!> >>’,
• enharmonic transcription of one or more pitches, ‘<e f ges>’, or
• Clusters.

#### Chord repetition

In order to save typing, a shortcut can be used to repeat the preceding chord. The chord repetition symbol is q:

<a c e>1 q <f a c>2 q


As with regular chords, the chord repetition symbol can be used with durations, articulations, markups, slurs, beams, etc. as only the pitches of the previous chord are duplicated.

<a c e>1\p^"text" q2\<( q8)[-| q8.]\! q16-1-2-3 q8\prall


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.

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

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

\relative c'' {
\chordRepeats #'(articulation-event)
{ <a-. c\prall e>1\sfz c'4 q2 r8 q8-. } |
q2 c, |
}


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.

\new Voice
\relative c'' {
\chordRepeats #'(articulation-event)
\relative c''
{ <a-. c\prall e>1\sfz c'4 q2 r8 q8-. } |
q2 c |
}


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.

Notation Reference: Chord notation, Articulations and ornamentations.

Installed Files: ‘ly/chord-repetition-init.ly’.

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

The following examples show simultaneous expressions on one staff:

\new Voice {  % explicit single voice
<< { a4 b g2 } { d4 g c,2 } >>
}


% single first note
a << { a4 b g } { d4 g c, } >>


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 singleVoice’ are collected and engraved in musical order:

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

% no single first note
<< { a4 b g2 } { d4 g2 c,4 } >>


Here different rhythms cause no problems because they are interpreted in different voices.

#### Known issues and warnings

If notes from two or more voices, with stems in the same direction, are placed at the same position on the staff and have no shift (or have the same shift specified), the message:

warning: ignoring too many clashing note columns


will appear during compilation. This message can be suppressed by:

\override NoteColumn #'ignore-collision = ##t


However, this not only suppresses the warning but will prevent any collision resolution whatsover and may have other unintended effects (also see Known Issues in Collision resolution).

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

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

Music Glossary: cluster.

Snippets: Simultaneous notes.

Internals Reference: ClusterSpanner, ClusterSpannerBeacon, Cluster_spanner_engraver.

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

Clusters do not produce MIDI output.

### 1.5.2 Multiple voices

This section discusses simultaneous notes in multiple voices or multiple staves.

#### Explicitly instantiating voices

The basic structure needed to achieve multiple independent voices in a single staff is illustrated in the following example:

\new Staff <<
\new Voice = "first"
{ \voiceOne r8 r16 g e8. f16 g8[ c,] f e16 d }
\new Voice= "second"
{ \voiceTwo d16 c d8~ d16 b c8~ c16 b c8~ c16 b8. }
>>


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:

<<
\new Voice = "melody" {
a4
<<
{
\voiceOne
g f
}
\new Voice {
\voiceTwo
d2
}
>>
\oneVoice
e4
}
\new Lyrics \lyricsto "melody" {
This is my song.
}
>>


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.

The first example could be typeset as follows:

<<
{ r8 r16 g e8. f16 g8[ c,] f e16 d }
\\
{ d16 c d8~ d16 b c8~ c16 b c8~ c16 b8. }
>>


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.

<<
{ r8 g g  g g f16 ees f8 d }
\\
{ ees,8 r ees r d r d r }
\\
{ d'8 s c s bes s a s }
>>


In all but the simplest works it is advisable to create explicit Voice contexts as explained in Contexts and engravers and Explicitly instantiating voices.

#### Voice order

When entering multiple voices in the input file, use the following order:

Voice 1: highest
Voice 2: lowest
Voice 3: second highest
Voice 4: second lowest
Voice 5: third highest
Voice 6: third lowest
etc.


Though this may seem counterintuitive, it simplifies the automatic layout process. Note that the odd-numbered voices are given upstems, and the even-numbered voices are given downstems:

\new Staff <<
\time 2/4
{ f''2 }  % 1: highest
\\
{ c'2  }  % 2: lowest
\\
{ d''2 }  % 3: second-highest
\\
{ e'2  }  % 4: second-lowest
\\
{ b'2  }  % 5: third-highest
\\
{ g'2  }  % 6: third-lowest
>>


Note: Lyrics, spanners (such as slurs, ties, hairpins etc.) cannot be created ‘across’ voices.

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

\new Voice <<
{ e4 f8 d e16 f g8 d4 }
{ c4 d8 b c16 d e8 b4 }
>>


This method leads to strange beamings and warnings if the pieces of music do not have the same rhythm.

#### Predefined commands

\voiceOne, \voiceTwo, \voiceThree, \voiceFour, \oneVoice.

Learning Manual: Voices contain music, Explicitly instantiating voices.

Notation Reference: Percussion staves, Invisible rests, Stems.

Snippets: Simultaneous notes.

#### Voice styles

Voices may be given distinct colors and shapes, allowing them to be easily identified:

<<
{ \voiceOneStyle d4 c2 b4 }
\\
{ \voiceTwoStyle e,2 e }
\\
{ \voiceThreeStyle b2. c4 }
\\
{ \voiceFourStyle g'2 g }
>>


The \voiceNeutralStyle command is used to revert to the standard presentation.

#### Predefined commands

\voiceOneStyle, \voiceTwoStyle, \voiceThreeStyle, \voiceFourStyle, \voiceNeutralStyle.

Learning Manual: I'm hearing Voices, Other sources of information.

Snippets: Simultaneous notes.

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

<<
{
c8 d e d c d c4
g'2 fis
} \\ {
c2 c8. b16 c4
e,2 r
} \\ {
\oneVoice
s1
e8 a b c d2
}
>>


Notes with different note heads may be merged, with the exception of half-note heads and quarter-note heads, as shown below. Here the note heads on beat 1 of bar 1 are now merged:

<<
{
c8 d e d c d c4
g'2 fis
} \\ {
c2 c8. b16 c4
e,2 r
} \\ {
\oneVoice
s1
e8 a b c d2
}
>>


Note heads with different dots as shown in beat 3 of bar 1 may be also be merged:

<<
{
\mergeDifferentlyDottedOn
c8 d e d c d c4
g'2 fis
} \\ {
c2 c8. b16 c4
e,2 r
} \\ {
\oneVoice
s1
e8 a b c d2
}
>>


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.

<<
{
\mergeDifferentlyDottedOn
c8 d e d c d c4
\shiftOn
g'2 fis
} \\ {
c2 c8. b16 c4
e,2 r
} \\ {
\oneVoice
s1
e8 a b c d2
}
>>


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!

\new Staff \relative c'' {
%% abbreviated entry
<<
{ f2  }  % 1: highest
\\
{ g,2 }  % 2: lowest
\\
{ d'2 }  % 3: upper middle
\\
{ b2  }  % 4: lower middle
>>
%% internal expansion of the above
<<
\new Voice = "1" { \voiceOne   \shiftOff f'2 }
\new Voice = "2" { \voiceTwo   \shiftOff g,2 }
\new Voice = "3" { \voiceThree \shiftOn  d'2 } % shifts right
\new Voice = "4" { \voiceFour  \shiftOn  b2  } % shifts left
>>
}


Two additional commands, \shiftOnn and \shiftOnnn provide further shift levels which may be specified temporarily to resolve collisions in complex situations – see Real music example.

Notes are only merged if they have opposing stem directions (as they have, for example, in voices one and two by default or when the stems are explicitly set in opposite directions).

#### Predefined commands

\mergeDifferentlyDottedOn, \mergeDifferentlyDottedOff, \mergeDifferentlyHeadedOn, \mergeDifferentlyHeadedOff.

\shiftOn, \shiftOnn, \shiftOnnn, \shiftOff.

#### Selected Snippets

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.

voiceFive = #(context-spec-music (make-voice-props-set 4) 'Voice)

\relative c'' {
\time 3/4
\key d \minor
\partial 2
<<
{
\voiceOne
a4. a8
e'4 e4. e8
f4 d4. c8
}
\\
{
\voiceThree
f,2
bes4 a2
a4 s2
}
\\
{
\voiceFive
s2
g4 g2
f4 f2
}
\\
\bar "||"{
\voiceTwo
d2
d4 cis2
d4 bes2
}
>>
}


Forcing horizontal shift of notes

When the typesetting engine cannot cope, the following syntax can be used to override typesetting decisions. The units of measure used here are staff spaces.

\relative c' <<
{
<d g>2 <d g>
}
\\
{
<b f'>2
\once \override NoteColumn #'force-hshift = #1.7
<b f'>2
}
>>


Music Glossary: polyphony.

Learning Manual: Multiple notes at once, Voices contain music, Real music example.

Snippets: Simultaneous notes.

Internals Reference: NoteColumn, NoteCollision, RestCollision.

#### Known issues and warnings

Using \override NoteColumn #'ignore-collision = ##t will cause differently headed notes in different voices to merge incorrectly.

\mergeDifferentlyHeadedOn
<< { c16 a' b a } \\ { c,2 } >>
\override NoteColumn #'ignore-collision = ##t
<< { c16 a' b a } \\ { c,2 } >>


#### 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 musicexpr1 musicexpr2


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.

instrumentOne = \relative c' {
c4 d e f |
R1 |
d'4 c b a |
b4 g2 f4 |
e1 |
}

instrumentTwo = \relative g' {
R1 |
g4 a b c |
d4 c b a |
g4 f( e) d |
e1 |
}

<<
\new Staff \instrumentOne
\new Staff \instrumentTwo
\new Staff \partcombine \instrumentOne \instrumentTwo
>>


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

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 overriden with the following commands:

Commands ending in ...Once apply only to the next note in the music expression.

• \partcombineApart and \partcombineApartOnce keep the notes as two separate voices, even if they can be combined into a chord or unison.
• \partcombineChords and \partcombineChordsOnce combine the notes into a chord.
• \partcombineUnisono and \partcombineUnisonoOnce combine both voices as “unison”.
• \partcombineSoloI and \partcombineSoloIOnce print only voice one, and mark it as a “Solo”.
• \partcombineSoloII or \partcombineSoloIIOnce print only voice two and mark it as a “Solo”.
• \partcombineAutomatic and \partcombineAutomaticOnce end the functions of the commands above, and revert back to the standard \partcombine functionality.
instrumentOne = \relative c' {
\partcombineApart c2^"apart" e |
\partcombineAutomatic e2^"auto" e |
\partcombineChords e'2^"chord" e |
\partcombineAutomatic c2^"auto" c |
\partcombineApart c2^"apart" \partcombineChordsOnce e^"chord once" |
c2 c |
}
instrumentTwo = \relative c' {
c2 c |
e2 e |
a,2 c |
c2 c' |
c2 c |
c2 c |
}

<<
\new Staff { \instrumentOne }
\new Staff { \instrumentTwo }
\new Staff { \partcombine \instrumentOne \instrumentTwo }
>>


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

musicUp = \relative c'' {
\time 4/4
a4 c4.( g8) a4 |
g4 e' g,( a8 b) |
c b a2.
}

musicDown = \relative c'' {
g4 e4.( d8) c4 |
r2 g'4( f8 e) |
d2 \stemDown a
}

\score {
<<
<<
\new Staff {
\set Staff.instrumentName = #"Standard polyphony"
<< \musicUp \\ \musicDown >>
}
\new Staff \with { printPartCombineTexts = ##f } {
\set Staff.instrumentName = #"PartCombine without texts"
\partcombine \musicUp \musicDown
}
\new Staff {
\set Staff.instrumentName = #"PartCombine with texts"
\partcombine \musicUp \musicDown
}
>>
>>
\layout {
indent = 6.0\cm
\context {
\Score
\override SystemStartBar #'collapse-height = #30
}
}
}


Changing partcombine texts

When using the automatic part combining feature, the printed text for the solo and unison sections may be changed:

\new Staff <<
\set Staff.soloText = #"girl"
\set Staff.soloIIText = #"boy"
\partcombine
\relative c'' {
g4 g r r
a2 g
}
\relative c'' {
r4 r a( b)
a2 g
}
>>


Music Glossary: a due, part.

Notation Reference: Writing parts.

Snippets: Simultaneous notes.

Internals Reference: PartCombineMusic, Voice.

#### Known issues and warnings

All \partcombine... functions can only accept two voices and are not designed to work with lyrics; such that when one of the voices is explicitly named in order to attach lyrics to it, the partcombiner will stop working.

\partcombine... functions cannot be placed inside a \times or \relative block.

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.

Refer also to Known issues and warnings when using \partcombine with tablature in Default tablatures and the Note in Automatic beams when using automatic beaming.

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

\parallelMusic #'(voiceA voiceB voiceC) {
% Bar 1
r8 g'16 c'' e'' g' c'' e'' r8 g'16 c'' e'' g' c'' e'' |
r16 e'8.~   e'4            r16 e'8.~   e'4            |
c'2                        c'2                        |

% Bar 2
r8 a'16 d'' f'' a' d'' f'' r8 a'16 d'' f'' a' d'' f'' |
r16 d'8.~   d'4            r16 d'8.~   d'4            |
c'2                        c'2                        |

}
\new StaffGroup <<
\new Staff << \voiceA \\ \voiceB >>
\new Staff { \clef bass \voiceC }
>>


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.

\parallelMusic #'(voiceA voiceB voiceC) {
% Bar 1
r8 g16 c e g, c e r8 g,16 c e g, c e  |
r16 e8.~ e4       r16 e8.~  e4        |
c2                c                   |

% Bar 2
r8 a,16 d f a, d f r8 a,16 d f a, d f |
r16 d8.~  d4       r16 d8.~  d4       |
c2                 c                  |

}
\new StaffGroup <<
\new Staff << \relative c'' \voiceA \\ \relative c' \voiceB >>
\new Staff \relative c' { \clef bass \voiceC }
>>


This works quite well for piano music. This example maps four consecutive measures to four variables:

global = {
\key g \major
\time 2/4
}

\parallelMusic #'(voiceA voiceB voiceC voiceD) {
% Bar 1
a8    b     c   d     |
d4          e         |
c16 d e fis d e fis g |
a4          a         |

% Bar 2
e8      fis  g     a   |
fis4         g         |
e16 fis g  a fis g a b |
a4           a         |

% Bar 3 ...
}

\score {
\new PianoStaff <<
\new Staff {
\global
<<
\relative c'' \voiceA
\\
\relative c'  \voiceB
>>
}
\new Staff {
\global \clef bass
<<
\relative c \voiceC
\\
\relative c \voiceD
>>
}
>>
}


Learning Manual: Organizing pieces with variables.

Snippets: Simultaneous notes.

## 1.6 Staff notation

This section explains how to influence the appearance of staves, how to print scores with more than one staff, and how to add tempo indications and cue notes to staves.

### 1.6.1 Displaying staves

This section describes the different methods of creating and grouping staves.

#### Instantiating new staves

Staves (singular: staff) are created with the \new or \context commands. For details, see Creating contexts.

The basic staff context is Staff:

\new Staff { c4 d e f }


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

\new GregorianTranscriptionStaff { c4 d e f e d }


New single staff contexts may be defined. For details, see Defining new contexts.

Music Glossary: staff, staves.

Snippets: Staff notation.

Internals Reference: Staff, DrumStaff, GregorianTranscriptionStaff, RhythmicStaff, TabStaff, MensuralStaff, VaticanaStaff, StaffSymbol.

#### Grouping staves

Various contexts exist to group single staves together in order to form multi-stave systems. Each grouping context sets the style of the system start delimiter and the behavior of bar lines.

If no context is specified, the default properties will be used: the group is started with a vertical line, and the bar lines are not connected.

<<
\new Staff { c1 c }
\new Staff { c1 c }
>>


In the StaffGroup context, the group is started with a bracket and bar lines are drawn through all the staves.

\new StaffGroup <<
\new Staff { c1 c }
\new Staff { c1 c }
>>


In a ChoirStaff, the group starts with a bracket, but bar lines are not connected.

\new ChoirStaff <<
\new Staff { c1 c }
\new Staff { c1 c }
>>


In a GrandStaff, the group begins with a brace, and bar lines are connected between the staves.

\new GrandStaff <<
\new Staff { c1 c }
\new Staff { c1 c }
>>


The PianoStaff is identical to a GrandStaff, except that it supports printing the instrument name directly. For details, see Instrument names.

\new PianoStaff <<
\set PianoStaff.instrumentName = #"Piano"
\new Staff { c1 c }
\new Staff { c1 c }
>>


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.

New staff group contexts may be defined. For details, see Defining new contexts.

#### Selected Snippets

Use square bracket at the start of a staff group

The system start delimiter SystemStartSquare can be used by setting it explicitly in a StaffGroup or ChoirStaff context.

\score {
\new StaffGroup { <<
\set StaffGroup.systemStartDelimiter = #'SystemStartSquare
\new Staff { c'4 d' e' f' }
\new Staff { c'4 d' e' f' }
>> }
}


Display bracket with only one staff in a system

If there is only one staff in one of the staff types ChoirStaff or StaffGroup, the bracket and the starting bar line will not be displayed as standard behavior. This can be changed by overriding the relevant properties.

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.

\markup \left-column {
\score {
\new StaffGroup <<
% Must be lower than the actual number of staff lines
\override StaffGroup.SystemStartBracket #'collapse-height = #1
\override Score.SystemStartBar #'collapse-height = #1
\new Staff {
c'1
}
>>
\layout { }
}
\null
\score {
\new PianoStaff <<
\override PianoStaff.SystemStartBrace #'collapse-height = #1
\override Score.SystemStartBar #'collapse-height = #1
\new Staff {
c'1
}
>>
\layout { }
}
}


Mensurstriche layout (bar lines between the staves)

The mensurstriche-layout where the bar lines do not show on the staves but between staves can be achieved with a StaffGroup instead of a ChoirStaff. The bar line on staves is blanked out by setting the transparent property.

global = {
\override Staff.BarLine #'transparent = ##t
s1 s
% the final bar line is not interrupted
\revert Staff.BarLine #'transparent
\bar "|."
}
\new StaffGroup \relative c'' {
<<
\new Staff { << \global { c1 c } >> }
\new Staff { << \global { c c } >> }
>>
}


Music Glossary: brace, bracket, grand staff.

Notation Reference: Instrument names, Defining new contexts.

Snippets: Staff notation.

Internals Reference: Staff, StaffGroup, ChoirStaff, GrandStaff, PianoStaff, SystemStartBar, SystemStartBrace, SystemStartBracket, SystemStartSquare.

#### Known issues and warnings

PianoStaff does not, by default, accept ChordNames.

#### Nested staff groups

Staff-group contexts can be nested to arbitrary depths. In this case, each child context creates a new bracket adjacent to the bracket of its parent group.

\new StaffGroup <<
\new Staff { c2 c | c2 c }
\new StaffGroup <<
\new Staff { g2 g | g2 g }
\new StaffGroup \with {
systemStartDelimiter = #'SystemStartSquare
}
<<
\new Staff { e2 e | e2 e }
\new Staff { c2 c | c2 c }
>>
>>
>>


New nested staff group contexts can be defined. For details, see Defining new contexts.

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

\new StaffGroup
\relative c'' <<
\set StaffGroup.systemStartDelimiterHierarchy
= #'(SystemStartSquare (SystemStartBrace (SystemStartBracket a
(SystemStartSquare b)  ) c ) d)
\new Staff { c1 }
\new Staff { c1 }
\new Staff { c1 }
\new Staff { c1 }
\new Staff { c1 }
>>


Notation Reference: Grouping staves, Instrument names, Defining new contexts.

Snippets: Staff notation.

Internals Reference: StaffGroup, ChoirStaff, SystemStartBar, SystemStartBrace, SystemStartBracket, 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.

\book {
\score {
\new StaffGroup <<
\new Staff {
\relative c'' {
c4 c c c
\break
c4 c c c
}
}
\new Staff {
\relative c'' {
c4 c c c
\break
c4 c c c
}
}
>>
}
\paper {
system-separator-markup = \slashSeparator
% following commands are needed only to format this documentation
paper-width = 100\mm
paper-height = 100\mm
tagline = ##f
}
}


Notation Reference: Page layout.

Snippets: Staff notation.

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

#### Staff symbol

The \stopStaff and \startStaff commands can be used to stop or (re)start the staff lines respectively, from being printed at any point witin a score.

\stopStaff f4 d \startStaff g, e
f'4 d \stopStaff g, e
f'4 d \startStaff g, e


#### Predefined commands

\startStaff, \stopStaff.

The lines of a staff belong to the StaffSymbol grob (including ledger lines) can be modified using StaffSymbol properties, but these modifications must be made before the staff is (re)started.

The number of staff lines can be altered,

f4 d \stopStaff
\override Staff.StaffSymbol #'line-count = #2
\startStaff g, e |

f'4 d \stopStaff
\revert Staff.StaffSymbol #'line-count
\startStaff g, e |


The position of each the staff lines can also be altered. The values used are half staff line spaces and the new position is relative to the normal center line. A single staff line is printed for every value entered so that the number of staff lines, as well as their position in the staff, can be changed with a single override.

f4 d \stopStaff
\override Staff.StaffSymbol #'line-positions = #'(1 3 5 -1 -3)
\startStaff g, e |
f'4 d \stopStaff
\override Staff.StaffSymbol #'line-positions = #'(8 6.5 -6 -8 -0.5)
\startStaff g, e


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.

\new Staff \with {
\override StaffSymbol #'thickness = #3
}
{ f4 d g, e }


However, it is possible to set ledger line thickness independently of staff lines. The two values required multiply the staff line thickness with the staff line spacing and are then added together to give the ledger line thickness.

\new Staff \with {
\override StaffSymbol #'thickness = #2
\override StaffSymbol #'ledger-line-thickness = #'(0.5 . 0.4)
}
{ f'4 a, a,, f }


The vertical positions of ledger lines can be altered,

\new Staff \with {
\override StaffSymbol #'ledger-positions = #'(-3 -2 -1 2 5 6)
}
{ f'4 a, a,, f }


Additional ledger lines can be made to appear above or below note heads depending on the current position relative to other note heads that also have their own ledger lines.

\new Staff \with {
\override StaffSymbol #'ledger-extra = #4
}
{ f'4 a, d, f, }


Legder 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 legder-position is and is not set. The stopStaff is needed in the example to revert the \override for the whole StaffSymbol.

The distance between staff lines can be altered. This affects ledger line spacing as well.

\new Staff \with {
\override StaffSymbol #'staff-space = #1.5
}
{ f'4 d, g, e, }


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

{
\override Staff.StaffSymbol #'line-positions =
#'(-4 -2 -0.2 0 0.2 2 4)
d'4 e' f' g'
}


Music Glossary: line, ledger line, staff.

Notation Reference: Clef.

Snippets: Staff notation.

Internals Reference: StaffSymbol, staff-symbol-interface.

#### Ossia staves

Ossia staves can be set by creating a new simultaneous staff in the appropriate location:

\new Staff \relative c'' {
c4 b d c
<<
{ c4 b d c }
\new Staff { e4 d f e }
>>
c4 b c2
}


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.

\new Staff = main \relative c'' {
c4 b d c
<<
{ c4 b d c }

\new Staff \with {
\remove "Time_signature_engraver"
alignAboveContext = #"main"
fontSize = #-3
\override StaffSymbol #'staff-space = #(magstep -3)
\override StaffSymbol #'thickness = #(magstep -3)
firstClef = ##f
}
{ e4 d f e }
>>
c4 b c2
}


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.

<<
\new Staff = ossia \with {
\remove "Time_signature_engraver"
\override Clef #'transparent = ##t
fontSize = #-3
\override StaffSymbol #'staff-space = #(magstep -3)
\override StaffSymbol #'thickness = #(magstep -3)
}
{ \stopStaff s1*6 }

\new Staff \relative c' {
c4 b c2
<<
{ e4 f e2 }
\context Staff = ossia {
\startStaff e4 g8 f e2 \stopStaff
}
>>
g4 a g2 \break
c4 b c2
<<
{ g4 a g2 }
\context Staff = ossia {
\startStaff g4 e8 f g2 \stopStaff
}
>>
e4 d c2
}
>>


Using the \Staff \RemoveEmptyStaves 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 \Staff \RemoveEmptyStaves, see Hiding staves.

<<
\new Staff = ossia \with {
\remove "Time_signature_engraver"
\override Clef #'transparent = ##t
fontSize = #-3
\override StaffSymbol #'staff-space = #(magstep -3)
\override StaffSymbol #'thickness = #(magstep -3)
} \relative c'' {
R1*3
c4 e8 d c2
}
\new Staff \relative c' {
c4 b c2
e4 f e2
g4 a g2 \break
c4 b c2
g4 a g2
e4 d c2
}
>>

\layout {
\context {
\Staff \RemoveEmptyStaves
\override VerticalAxisGroup #'remove-first = ##t
}
}


#### Selected Snippets

Vertically aligning ossias and lyrics

This snippet demonstrates the use of the context properties alignBelowContext and alignAboveContext to control the positioning of lyrics and ossias.

\paper {
ragged-right = ##t
}

\relative c' <<
\new Staff = "1" { c4 c s2 }
\new Staff = "2" { c4 c s2 }
\new Staff = "3" { c4 c s2 }
{ \skip 2
<<
\lyrics {
\set alignBelowContext = #"1"
lyrics4 below
}
\new Staff \with {
alignAboveContext = #"3"
fontSize = #-2
\override StaffSymbol #'staff-space = #(magstep -2)
\remove "Time_signature_engraver"
} {
\times 4/6 {
c8[^"ossia above" d e d e f]
}
}
>>
}
>>


Music Glossary: ossia, staff, Frenched staff.

Learning Manual: Nesting music expressions, Size of objects, Length and thickness of objects.

Notation Reference: Hiding staves.

Snippets: Staff notation.

Internals Reference: StaffSymbol.

#### Hiding staves

Staff lines can be hidden by removing the Staff_symbol_engraver from the Staff context. As an alternative, \stopStaff may be used.

\new Staff \with {
\remove "Staff_symbol_engraver"
}
\relative c''' { a8 f e16 d c b a2 }


Empty staves can be hidden by setting the \Staff \RemoveEmptyStaves command in the \layout block. In orchestral scores, this style is known as ‘Frenched Score’. By default, this command hides and removes all empty staves in a score except for those in the first system.

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

\layout {
\context {
\Staff \RemoveEmptyStaves
}
}

\relative c' <<
\new Staff {
e4 f g a \break
b1 \break
a4 b c2
}
\new Staff {
c,4 d e f \break
R1 \break
f4 g c,2
}
>>


\Staff \RemoveEmptyStaves can also be used to create ossia sections for a staff. For details, see Ossia staves.

The \VaticanaStaff \RemoveEmptyStaves command may be used to hide empty staves in ancient music contexts. Similarly, \RhythmicStaff \RemoveEmptyStaves may be used to hide empty RhythmicStaff contexts.

#### Predefined commands

\Staff \RemoveEmptyStaves, \VaticanaStaff \RemoveEmptyStaves, \RhythmicStaff \RemoveEmptyStaves.

#### Selected Snippets

Removing the first empty line

The first empty staff can also be removed from the score by setting the VerticalAxisGroup property remove-first. This can be done globally inside the \layout block, or locally inside the specific staff that should be removed. In the latter case, you have to specify the context (Staff applies only to the current staff) in front of the property.

The lower staff of the second staff group is not removed, because the setting applies only to the specific staff inside of which it is written.

\layout {
\context {
\Staff \RemoveEmptyStaves
% To use the setting globally, uncomment the following line:
% \override VerticalAxisGroup #'remove-first = ##t
}
}
\new StaffGroup <<
\new Staff \relative c' {
e4 f g a \break
c1
}
\new Staff {
% To use the setting globally, comment this line,
% uncomment the line in the \layout block above
\override Staff.VerticalAxisGroup #'remove-first = ##t
R1 \break
R
}
>>
\new StaffGroup <<
\new Staff \relative c' {
e4 f g a \break
c1
}
\new Staff {
R1 \break
R
}
>>


Music Glossary: Frenched staff.

Learning Manual: Visibility and color of objects.

Snippets: Staff notation.

Internals Reference: ChordNames, FiguredBass, Lyrics, Staff, VerticalAxisGroup, Staff_symbol_engraver.

#### Known issues and warnings

Removing Staff_symbol_engraver also hides bar lines. If bar line visibility is forced, formatting errors may occur. In this case, use the following overrides instead of removing the engraver:

\override StaffSymbol #'stencil = ##f


For the Known issues and warnings associated with \Staff \RemoveEmptyStaves see Changing context default settings.

### 1.6.3 Writing parts

This section explains how to insert tempo indications and instrument names into a score. Methods to quote other voices and format cue notes are also described.

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

\new Staff \with {
instrumentName = #"Violin "
shortInstrumentName = #"Vln. "
}
{ c4.. g'16 c4.. g'16 \break | c1 }


\markup can be used to create more complex instrument names:

\new Staff \with {
instrumentName = \markup {
\column { "Clarinetti"
\line { "in B" \smaller \flat }
}
}
}
{ c4 c,16 d e f g2 }


When two or more staff contexts are grouped together, the instrument names and short instrument names are centered by default. To center multi-line instrument names, \center-column must be used:

<<
\new Staff \with {
instrumentName = #"Flute"
}
{ f2 g4 f }
\new Staff \with {
instrumentName = \markup {
\center-column { "Clarinet" }
\line { "in B" \smaller \flat }
}
}
{ c4 b c2 }
>>


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.

\relative c'' {
<<
\new Staff \with {
instrumentName = #"Alto Flute in G"
shortInstrumentName = #"Flt."
}
{
f2 g4 f \break
g4 f g2
}
\new Staff \with {
instrumentName = #"Clarinet"
shortInstrumentName = #"Clar."
}
{
c,4 b c2 \break
c2 b4 c
}
>>
}

\layout {
indent = 3.0\cm
short-indent = 1.5\cm
}


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. However, only the first instance of instrumentName will be printed and subsequent changes will be ignored:

\new Staff \with {
instrumentName = #"Flute"
shortInstrumentName = #"Flt."
}
{
c1 c c c \break
c1 c c c \break
\set Staff.instrumentName = #"Clarinet"
\set Staff.shortInstrumentName = #"Clt."
c1 c c c \break
c1 c c c \break
}


If an instrument switch is needed, \addInstrumentDefinition may be used in combination with \instrumentSwitch to create a detailed list of the necessary changes for the switch. The \addInstrumentDefinition command has two arguments: an identifying string, and an association list of context properties and values to be used for the instrument. It must be placed in the toplevel scope. \instrumentSwitch is used in the music expression to declare the instrument switch:

\addInstrumentDefinition #"contrabassoon"
#((instrumentTransposition . ,(ly:make-pitch -1 0 0))
(shortInstrumentName . "Cbsn.")
(clefGlyph . "clefs.F")
(middleCPosition . 6)
(clefPosition . 2)
(instrumentCueName . ,(make-bold-markup "cbsn."))
(midiInstrument . "bassoon"))

\new Staff \with {
instrumentName = #"Bassoon"
}
\relative c' {
\clef tenor
\compressFullBarRests
c2 g'
R1*16
\instrumentSwitch "contrabassoon"
c,,2 g \break
c,1 ~ | c1
}


Notation Reference: \paper variables for shifts and indents, Modifying context plug-ins.

Snippets: Staff notation.

Internals Reference: InstrumentName, PianoStaff, Staff.

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

fluteNotes = \relative c'' {
a4 gis g gis | b4^"quoted" r8 ais\p a4( f)
}

oboeNotes = \relative c'' {
c4 cis c b \quoteDuring #"flute" { s1 }
}

\score {
<<
\new Staff \with { instrumentName = "Flute" } \fluteNotes
\new Staff \with { instrumentName = "Oboe" } \oboeNotes
>>
}


If the music expression used in \quoteDuring contains notes instead of spacer or multimeasure rests then the quote will appear as polyphony and may produce unexpected results.

fluteNotes = \relative c'' {
a4 gis g gis | b4^"quoted" r8 ais\p a4( f)
}

oboeNotes = \relative c'' {
c4 cis c b \quoteDuring #"flute" { e4 r8 ais b4 a }
}

\score {
<<
\new Staff \with { instrumentName = "Flute" } \fluteNotes
\new Staff \with { instrumentName = "Oboe" } \oboeNotes
>>
}


The \quoteDuring command uses the \transposition settings of both quoted and quoting parts to produce notes for the quoting part that have the same sounding pitch as those in the quoted part.

clarinetNotes = \relative c'' {
\transposition bes
\key d \major
b4 ais a ais | cis4^"quoted" r8 bis\p b4( f)
}

oboeNotes = \relative c'' {
c4 cis c b \quoteDuring #"clarinet" { s1 }
}

\score {
<<
\new Staff \with { instrumentName = "Clarinet" } \clarinetNotes
\new Staff \with { instrumentName = "Oboe" } \oboeNotes
>>
}


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.

fluteNotes = \relative c'' {
a2 g2 |
b4\<^"quoted" r8 ais a4\f( c->)
}

oboeNotes = \relative c'' {
c2. b4 |
\quoteDuring #"flute" { s1 }
}

\score {
<<
\set Score.quotedEventTypes = #'(note-event articulation-event
crescendo-event rest-event
slur-event dynamic-event)
\new Staff \with { instrumentName = "Flute" } \fluteNotes
\new Staff \with { instrumentName = "Oboe" } \oboeNotes
>>
}


Quotes can also be tagged, see Using tags.

Notation Reference: Instrument transpositions, Using tags.

Installed Files: ‘scm/define-event-classes.scm’.

Snippets: Staff notation.

Internals Reference: Music classes, QuoteMusic, Voice.

#### 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 simplest way to format cue notes is to explicitly create a CueVoice context within the part.

R1
<<
{ e2\rest r4. e8 }
\new CueVoice {
\stemUp d'8^"flute" c d e fis2
}
>>
d,4 r a r


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.

\clef "bass"
R1
<<
{ e2\rest r4. \cueClefUnset e,8 }
\new CueVoice {
\cueClef "treble" \stemUp d''8^"flute" c d e fis2
}
>>
d,,4 r a r


The \cueClef and \cueClefUnset command can also be used without a CueVoice if required.

\clef "bass"
R1
\cueClef "treble"
d'8^"flute" c d e fis2
\cueClefUnset
d,,4 r a r


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.

fluteNotes = \relative c'' {
r2. c4 | d8 c d e fis2 | g2 d |
}

oboeNotes = \relative c'' {
R1
\new CueVoice { \set instrumentCueName = "flute" }
\cueDuring #"flute" #UP { R1 }
g2 c,
}

\new Staff {
\oboeNotes
}


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.

oboeNotes = \relative c'' {
r2 r8 d16(\f f e g f a)
g8 g16 g g2.
}

\new Voice \relative c'' {
\set Score.quotedCueEventTypes = #'(note-event rest-event tie-event
beam-event tuplet-span-event
dynamic-event slur-event)
\cueDuring #"oboe" #UP { R1 }
g2 c,
}


The name of the instrument playing the cue can be printed by setting the instrumentCueName property in a temporary CueVoice context. The placement and style of the instrumentCueName is controlled by the \instrumentSwitch object, see Instrument names. 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.

fluteNotes = \relative c'' {
r2. c4 d8 c d e fis2 g2 d2
}

bassoonNotes = \relative c {
\clef bass
R1
\clef treble
\new CueVoice { \set instrumentCueName = "flute" }
\cueDuring #"flute" #UP { R1 }
\clef bass
g4. b8 d2
}

\new Staff {
\bassoonNotes
}


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.

fluteNotes = \relative c'' {
r2. c4 d8 c d e fis2 g2 d2
}

bassoonNotes = \relative c {
\clef bass
R1
\new CueVoice { \set instrumentCueName = "flute" }
\cueDuringWithClef #"flute" #UP #"treble" { R1 }
g4. b8 d2
}

\new Staff {
\bassoonNotes
}


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.

piccoloNotes = \relative c''' {
\clef "treble^8"
R1
c8 c c e g2
c4 g g2
}

bassClarinetNotes = \relative c' {
\key d \major
\transposition bes,
d4 r a r
\transposedCueDuring #"piccolo" #UP d { R1 }
d4 r a r
}

<<
\new Staff \piccoloNotes
\new Staff \bassClarinetNotes
>>


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.

fluteNotes = \relative c'' {
r2. c4 d8 c d e fis2 g2 d2
}

bassoonNotes = \relative c {
\clef bass
R1
\tag #'part {
\clef treble
\new CueVoice { \set instrumentCueName = "flute" }
}
\cueDuring #"flute" #UP { R1 }
\tag #'part \clef bass
g4. b8 d2
}

\new Staff {
\bassoonNotes
}

\new StaffGroup <<
\new Staff {
\fluteNotes
}
\new Staff {
\removeWithTag #'part { \killCues { \bassoonNotes } }
}
>>


Alternatively, Clef changes and instrument labels can be collected into an instrument definition for repeated use, using \addInstrumentDefinition described in Instrument names.

Notation Reference: Quoting other voices, Instrument transpositions, Instrument names, Clef, Musical cues, Using tags.

Snippets: Staff notation.

Internals Reference: CueVoice, Voice.

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

## 1.7 Editorial annotations

This section discusses the various ways to change the appearance of notes and add analysis or educational emphasis.

### 1.7.1 Inside the staff

This section discusses how to add emphasis to elements that are inside the staff.

#### Selecting notation font size

The font size of notation elements may be altered. It does not change the size of variable symbols, such as beams or slurs.

Note: For font sizes of text, see Selecting font and font size.

\huge
c4.-> d8---3
\large
c4.-> d8---3
\normalsize
c4.-> d8---3
\small
c4.-> d8---3
\tiny
c4.-> d8---3
\teeny
c4.-> d8---3


Internally, this sets the fontSize property. This in turn causes the font-size property to be set in all layout objects. The value of font-size is a number indicating the size relative to the standard size for the current staff height. Each step up is an increase of approximately 12% of the font size. Six steps is exactly a factor of two. The Scheme function magstep converts a font-size number to a scaling factor. The font-size property can also be set directly, so that only certain layout objects are affected.

\set fontSize = #3
c4.-> d8---3
c4.-> d8---3
\override Script #'font-size = #2
c4.-> d8---3
\override Stem #'font-size = #-5
c4.-> d8---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, a 10pt font is selected.

The font-size property can only be set on layout objects that use fonts. These are the ones supporting the font-interface layout interface.

#### Predefined commands

\teeny, \tiny, \small, \normalsize, \large, \huge.

Snippets: Editorial annotations.

Internals Reference: font-interface.

#### Fingering instructions

Fingering instructions can be entered using ‘note-digit’:

c4-1 d-2 f-4 e-3


Markup texts may be used for finger changes.

c4-1 d-2 f-4 c^\markup { \finger "2 - 3" }


A thumb-script can be added (e.g. cello music) to indicate that a note should be played with the thumb.

<a_\thumb a'-3>2 <b_\thumb b'-3>


Fingerings for chords can also be added to individual notes by adding them after the pitches.

<c-1 e-2 g-3 b-5>2 <d-1 f-2 a-3 c-5>


Fingering instructions may be manually placed above or below the staff, see Direction and placement.

#### Selected Snippets

Controlling the placement of chord fingerings

The placement of fingering numbers can be controlled precisely. For fingering orientation to apply, you must use a chord construct <> even if it is a single note.

\relative c' {
\set fingeringOrientations = #'(left)
<c-1 e-3 a-5>4
\set fingeringOrientations = #'(down)
<c-1 e-3 a-5>4
\set fingeringOrientations = #'(down right up)
<c-1 e-3 a-5>4
\set fingeringOrientations = #'(up)
<c-1 e-3 a-5>4
\set fingeringOrientations = #'(left)
<c-1>2
\set fingeringOrientations = #'(down)
<e-3>2
}


Allowing fingerings to be printed inside the staff

By default, vertically oriented fingerings are positioned outside the staff. However, this behavior can be canceled. Note: you must use a chord construct <>, even if it is only a single note.

\relative c' {
<c-1 e-2 g-3 b-5>2
<c-1 e-2 g-3 b-5>4 <g'-0>
}


Avoiding collisions with chord fingerings

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.

\relative c' {
\set fingeringOrientations = #'(up)
\set stringNumberOrientations = #'(up)
\set strokeFingerOrientations = #'(up)

% Default behavior
r8
<f c'-5>8
<f c'\5>8
<f c'-\rightHandFinger #2 >8

% Corrected to avoid collisions
r8
<f c'-5>8
<f c'\5>8
<f c'-\rightHandFinger #2 >8
}


Notation Reference: Direction and placement.

Snippets: Editorial annotations.

Internals Reference: FingeringEvent, fingering-event, Fingering_engraver, New_fingering_engraver, Fingering.

#### Known issues and warnings

By default, numbers greater than 9 are not supported using ‘note-digit’.

#### Hidden notes

Hidden (or invisible or transparent) notes can be useful in preparing theory or composition exercises.

c4 d
\hideNotes
e4 f
\unHideNotes
g a
\hideNotes
b
\unHideNotes
c


Note heads, stems, and flags, and rests are invisible. Beams are invisible if they start on a hidden note. Objects that are attached to invisible notes are still visible.

e8(\p f g a)--
\hideNotes
e8(\p f g a)--


#### Predefined commands

\hideNotes, \unHideNotes.

Learning Manual: Visibility and color of objects.

Notation Reference: Invisible rests, Visibility of objects, Hiding staves.

Snippets: Editorial annotations.

Internals Reference: Note_spacing_engraver, NoteSpacing.

#### Coloring objects

Individual objects may be assigned colors. Valid color names are listed in the List of colors.

\override NoteHead #'color = #red
c4 c
\override NoteHead #'color = #(x11-color 'LimeGreen)
d
\override Stem #'color = #blue
e


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.

\override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)
\set Staff.instrumentName = \markup {
\with-color #(x11-color 'navy) "Clarinet"
}

gis8 a
\override Beam #'color = #(x11-color "medium turquoise")
gis a
\override Accidental #'color = #(x11-color 'DarkRed)
gis a
\override NoteHead #'color = #(x11-color "LimeGreen")
gis a
% this is deliberate nonsense; note that the stems remain black
\override Stem #'color = #(x11-color 'Boggle)
b2 cis


Exact RGB colors can be specified using the Scheme function rgb-color.

\override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)
\set Staff.instrumentName = \markup {
\with-color #(x11-color 'navy) "Clarinet"
}

\override Stem #'color = #(rgb-color 0 0 0)
gis8 a
\override Stem #'color = #(rgb-color 1 1 1)
gis8 a
\override Stem #'color = #(rgb-color 0 0 0.5)
gis4 a


Notation Reference: List of colors, The \tweak command.

Snippets: Editorial annotations.

#### 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 colored with \override; use \tweak instead, see The \tweak command.

#### Parentheses

Objects may be parenthesized by prefixing \parenthesize to the music event. When prefixed to a chord, it parenthesizes every note. Individual notes inside a chord may also be parenthesized.

c2 \parenthesize d
c2 \parenthesize <c e g>
c2 <c \parenthesize e g>


Non-note objects may be parenthesized as well. For articulations, a hyphen is needed before the \parenthesize command.

c2-\parenthesize -. d
c2 \parenthesize r


Snippets: Editorial annotations.

Internals Reference: Parenthesis_engraver, ParenthesesItem, parentheses-interface.

#### Known issues and warnings

Parenthesizing a chord prints parentheses around each individual note, instead of a single large parenthesis around the entire chord.

#### Stems

Whenever a note is found, a Stem object is created automatically. For whole notes and rests, they are also created but made invisible.

Stems may be manually placed to point up or down; see Direction and placement.

#### Predefined commands

\stemUp, \stemDown, \stemNeutral.

#### Selected Snippets

Default direction of stems on the center line of the staff

The default direction of stems on the center line of the staff is set by the Stem property neutral-direction.

\relative c'' {
a4 b c b
\override Stem #'neutral-direction = #up
a4 b c b
\override Stem #'neutral-direction = #down
a4 b c b
}


Notation Reference: Direction and placement.

Snippets: Editorial annotations.

Internals Reference: Stem_engraver, Stem, stem-interface.

### 1.7.2 Outside the staff

This section discusses how to add emphasis to elements in the staff from outside of the staff.

#### Balloon help

Elements of notation can be marked and named with the help of a square balloon. The primary purpose of this feature is to explain notation.

\new Voice \with { \consists "Balloon_engraver" }
{
\balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
a8
\balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
r
<c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
}


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 normally influences note spacing, but this can be altered:

\new Voice \with { \consists "Balloon_engraver" }
{
\balloonLengthOff
\balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
a8
\balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
r
\balloonLengthOn
<c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
}


#### Predefined commands

\balloonLengthOn, \balloonLengthOff.

Snippets: Editorial annotations.

Internals Reference: Balloon_engraver, BalloonTextItem, balloon-interface.

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

\layout {
\context {
\Staff
\consists "Grid_point_engraver"
gridInterval = #(ly:make-moment 1 4)
}
\context {
\Score
\consists "Grid_line_span_engraver"
}
}

\score {
\new ChoirStaff <<
\new Staff \relative c'' {
\stemUp
c4. d8 e8 f g4
}
\new Staff \relative c {
\clef bass
\stemDown
c4 g' f e
}
>>
}


#### Selected Snippets

Grid lines: changing their appearance

The appearance of grid lines can be changed by overriding some of their properties.

\score {
\new ChoirStaff <<
\new Staff {
\relative c'' {
\stemUp
c'4. d8 e8 f g4
}
}
\new Staff {
\relative c {
% this moves them up one staff space from the default position
\override Score.GridLine #'extra-offset = #'(0.0 . 1.0)
\stemDown
\clef bass
\once \override Score.GridLine #'thickness = #5.0
c4
\once \override Score.GridLine #'thickness = #1.0
g'4
\once \override Score.GridLine #'thickness = #3.0
f4
\once \override Score.GridLine #'thickness = #5.0
e4
}
}
>>
\layout {
\context {
\Staff
% set up grids
\consists "Grid_point_engraver"
% set the grid interval to one quarter note
gridInterval = #(ly:make-moment 1 4)
}
\context {
\Score
\consists "Grid_line_span_engraver"
% this moves them to the right half a staff space
\override NoteColumn #'X-offset = #-0.5
}
}
}


Snippets: Editorial annotations.

Internals Reference: Grid_line_span_engraver, Grid_point_engraver, GridLine, GridPoint, grid-line-interface, grid-point-interface.

#### Analysis brackets

Brackets are used in musical analysis to indicate structure in musical pieces. Simple horizontal brackets are supported.

\layout {
\context {
\Voice
\consists "Horizontal_bracket_engraver"
}
}
\relative c'' {
c2\startGroup
d\stopGroup
}


Analysis brackets may be nested.

\layout {
\context {
\Voice
\consists "Horizontal_bracket_engraver"
}
}
\relative c'' {
c4\startGroup\startGroup
d4\stopGroup
e4\startGroup
d4\stopGroup\stopGroup
}


Snippets: Editorial annotations.

Internals Reference: Horizontal_bracket_engraver, HorizontalBracket, horizontal-bracket-interface, Staff.

## 1.8 Text

This section explains how to include text (with various formatting) in music scores.

Some text elements that are not dealt with here are discussed in other specific sections: Vocal music, Titles and headers.

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

a8^"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.

a8^\markup { \italic pizz. } g f e
a4_\markup { \tiny scherz. \bold molto } f


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.

a8^"pizz." g f e
\textLengthOn
a4_"scherzando" f


In addition to text scripts, articulations can be attached to notes. For more information, see Articulations and ornamentations.

#### Predefined commands

\textLengthOn, \textLengthOff.

Learning Manual: Placement of objects.

Notation Reference: Formatting text, Direction and placement, Articulations and ornamentations.

Snippets: Text.

Internals Reference: TextScript.

#### Known issues and warnings

Checking to make sure that text scripts and lyrics are within the margins requires additonal calculations. In cases where slightly faster performance is desired, use

\override Score.PaperColumn #'keep-inside-line = ##f


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

\override TextSpanner #'(bound-details left text) = "rit."
b1\startTextSpan
e,\stopTextSpan


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.

\override TextSpanner #'(bound-details left text) =
\markup { \upright "rit." }
b1\startTextSpan c
e,\stopTextSpan


The line style, as well as the text string, can be defined as an object property. This syntax is described in Line styles.

#### Predefined commands

\textSpannerUp, \textSpannerDown, \textSpannerNeutral.

#### Known issues and warnings

LilyPond is only able to handle one text spanner per voice.

#### Selected Snippets

Dynamics text spanner postfix

Custom text spanners can be defined and used with hairpin and text crescendos. \< and \> produce hairpins by default, \cresc etc. produce text spanners by default.

% Some sample text dynamic spanners, to be used as postfix operators
crpoco =
#(make-music 'CrescendoEvent
'span-direction START
'span-type 'text
'span-text "cresc. poco a poco")

\relative c' {
c4\cresc d4 e4 f4 |
g4 a4\! b4\crpoco c4 |
c4 d4 e4 f4 |
g4 a4\! b4\< c4 |
g4\dim a4 b4\decresc c4\!
}


Dynamics custom text spanner postfix

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.

% Two functions for (de)crescendo spanners where you can explicitly give the
% spanner text.
mycresc =
#(define-music-function (parser location mymarkup) (markup?)
(make-music 'CrescendoEvent
'span-direction START
'span-type 'text
'span-text mymarkup))
mydecresc =
#(define-music-function (parser location mymarkup) (markup?)
(make-music 'DecrescendoEvent
'span-direction START
'span-type 'text
'span-text mymarkup))

\relative c' {
c4-\mycresc "custom cresc" c4 c4 c4 |
c4 c4 c4 c4 |
c4-\mydecresc "custom decresc" c4 c4 c4 |
c4 c4\! c4 c4
}


Notation Reference: Line styles, Dynamics, Formatting text.

Snippets: Text, Expressive marks.

Internals Reference: TextSpanner.

#### Text marks

Various text elements may be added to a score using the syntax described in Rehearsal marks:

c4
\mark "Allegro"
c c c


This syntax makes it possible to put any text on a bar line; more complex text formatting may be added using a \markup block, as described in Formatting text:

<c e>1
\mark \markup { \italic { colla parte } }
<d f>2 <e g>
<c f aes>1


This syntax also allows to print special signs, like coda, segno or fermata, by specifying the appropriate symbol name as explained in Music notation inside markup:

<bes f>2 <aes d>
\mark \markup { \musicglyph #"scripts.ufermata" }
<e g>1


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.

\mark "Allegro"
c1 c
\mark "assai" \break
c  c


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

\relative c'' {
g2 c
d,2 a'
\once \override Score.RehearsalMark #'break-visibility = #end-of-line-visible
\once \override Score.RehearsalMark #'self-alignment-X = #RIGHT
\mark "D.C. al Fine"
\break
g2 b,
c1 \bar "||"
}


Aligning marks with various notation objects

If specified, text marks may be aligned with notation objects other than bar lines. These objects include ambitus, breathing-sign, clef, custos, staff-bar, left-edge, key-cancellation, key-signature, and time-signature.

In such cases, text marks will be horizontally centered above the object. However this can be changed, as demonstrated on the second line of this example (in a score with multiple staves, this setting should be done for all the staves).

\relative c' {
e1

% the RehearsalMark will be centered above the Clef
\override Score.RehearsalMark #'break-align-symbols = #'(clef)
\key a \major
\clef treble
\mark \markup { \char ##x2193 }
e1

% the RehearsalMark will be centered above the TimeSignature
\override Score.RehearsalMark #'break-align-symbols = #'(time-signature)
\key a \major
\clef treble
\time 3/4
\mark \markup { \char ##x2193 }
e2.

% the RehearsalMark will be centered above the KeySignature
\override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
\key a \major
\clef treble
\time 4/4
\mark \markup { \char ##x2193 }
e1

\break
e1

% the RehearsalMark will be aligned with the left edge of the KeySignature
\once \override Score.KeySignature #'break-align-anchor-alignment = #LEFT
\mark \markup { \char ##x2193 }
\key a \major
e1

% the RehearsalMark will be aligned with the right edge of the KeySignature
\once \override Score.KeySignature #'break-align-anchor-alignment = #RIGHT
\key a \major
\mark \markup { \char ##x2193 }
e1

% the RehearsalMark will be aligned with the left edge of the KeySignature
% and then shifted right by one unit.
\once \override Score.KeySignature #'break-align-anchor = #1
\key a \major
\mark \markup { \char ##x2193 }
e1
}


Printing marks on every staff

Although text marks are normally only printed above the topmost staff, they may also be printed on every staff.

\score {
<<
\new Staff { c''1 \mark "molto" c'' }
\new Staff { c'1 \mark "molto" c' }
>>
\layout {
\context {
\Score
\remove "Mark_engraver"
\remove "Staff_collecting_engraver"
}
\context {
\Staff
\consists "Mark_engraver"
\consists "Staff_collecting_engraver"
}
}
}


Notation Reference: Rehearsal marks, Formatting text, Music notation inside markup, The Feta font.

Snippets: Text.

Internals Reference: MarkEvent, Mark_engraver, RehearsalMark.

#### Separate text

A \markup block can exist by itself, outside of any \score block, as a “top-level expression”. This syntax is described in File structure.

\markup {
Tomorrow, and tomorrow, and tomorrow...
}


This allows printing text separately from the music, which is particularly useful when the input file contains several music pieces, as described in Multiple scores in a book.

\score {
c'1
}
\markup {
Tomorrow, and tomorrow, and tomorrow...
}
\score {
c'1
}


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:

\markup {
\fill-line {
\hspace #1
\column {
\line { O sacrum convivium }
\line { in quo Christus sumitur, }
\line { recolitur memoria passionis ejus, }
\line { mens impletur gratia, }
\line { futurae gloriae nobis pignus datur. }
\line { Amen. }
}
\hspace #2
\column {
\line { \italic { O sacred feast } }
\line { \italic { in which Christ is received, } }
\line { \italic { the memory of His Passion is renewed, } }
\line { \italic { the mind is filled with grace, } }
\line { \italic { and a pledge of future glory is given to us. } }
\line { \italic { Amen. } }
}
\hspace #1
}
}


Notation Reference: Formatting text, File structure, Multiple scores in a book, Multi-page markup.

Snippets: Text.

Internals Reference: TextScript.

### 1.8.2 Formatting text

This section presents basic and advanced text formatting, using the \markup mode specific syntax.

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

a1-\markup intenso
a2^\markup { poco \italic più forte  }
c e1
d2_\markup { \italic "string. assai" }
e
b1^\markup { \bold { molto \italic  agitato } }
c


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.

a1^"\italic markup..."
a_\markup { \italic "... prints \"italic\" letters!" }
a a


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:

c1^\markup { \center-column { a bbb c } }
c1^\markup { \center-column { a { bbb c } } }
c1^\markup { \center-column { a \line { bbb c } } }
c1^\markup { \center-column { a "bbb c" } }


Markups can be stored in variables. Such variables may be directly attached to notes:

allegro = \markup { \bold \large Allegro }

{
d''8.^\allegro
d'16 d'4 r2
}


An exhaustive list of \markup-specific commands can be found in Text markup commands.

Notation Reference: Text markup commands.

Snippets: Text.

Installed Files: ‘scm/markup.scm’.

#### Known issues and warnings

Syntax errors for markup mode can be confusing.

#### Selecting font and font size

Basic font switching is supported in markup mode:

d1^\markup {
\bold { Più mosso }
\italic { non troppo \underline Vivo }
}
r2 r4 r8
d,_\markup { \italic quasi \smallCaps Tromba }
f1 d2 r


The font size can be altered, relative to the global staff size, in a number of different ways

It can be set to predefined size,

b1_\markup { \huge Sinfonia }
b1^\markup { \teeny da }
b1-\markup { \normalsize camera }


It can be set relative to its previous value,

b1_\markup { \larger Sinfonia }
b1^\markup { \smaller da }
b1-\markup { \magnify #0.6  camera }


It can be increased or decreased relative to the value set by the global staff size,

b1_\markup { \fontsize #-2 Sinfonia }
b1^\markup { \fontsize #1 da }
b1-\markup { \fontsize #3 camera }


It can also be set to a fixed point-size, regardless of the global staff size,

b1_\markup { \abs-fontsize #20 Sinfonia }
b1^\markup { \abs-fontsize #8 da }
b1-\markup { \abs-fontsize #14 camera }


Text may be printed as subscript or superscript. By default these are printed in a smaller size, but a normal size can be used as well:

\markup {
\column {
\line { 1 \super st movement }
\line { 1 \normal-size-super st movement
\sub { (part two) }  }
}
}


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.

\markup {
\column {
\line { Act \number 1 }
\line { \sans { Scene I. } }
\line { \typewriter { Verona. An open place. } }
\line { Enter \roman Valentine and Proteus. }
}
}


Some of these font families, used for specific items such as numbers or dynamics, do not provide all characters, as mentioned in New dynamic marks and Manual repeat marks.

When used inside a word, some font-switching or formatting commands may produce an unwanted blank space. This can easily be solved by concatenating the text elements together:

\markup {
\column {
\line {
\concat { 1 \super st }
movement
}
\line {
\concat { \dynamic p , }
\italic { con dolce espressione }
}
}
}


An exhaustive list of font switching commands and custom font usage commands can be found in Font.

Defining custom font sets is also possible, as explained in Fonts.

#### Predefined commands

\teeny, \tiny, \small, \normalsize, \large, \huge, \smaller, \larger.

Notation Reference: Font, New dynamic marks, Manual repeat marks, Fonts.

Installed Files: ‘scm/define-markup-commands.scm’.

Snippets: Text.

Internals Reference: TextScript.

#### Known issues and warnings

Using the font sizing commands \teeny, \tiny, \small, \normalsize, \large, and \huge will lead to inconsistent line spacing compared to using \fontsize.

#### Text alignment

This subsection discusses how to place text in markup mode. Markup objects can also be moved as a whole, using the syntax described in Moving objects.

Markup objects may be aligned in different ways. By default, a text indication is aligned on its left edge: in the following example, there is no difference between the first and the second markup.

d1-\markup { poco }
f
d-\markup { \left-align poco }
f
d-\markup { \center-align { poco } }
f
d-\markup { \right-align poco }


Horizontal alignment may be fine-tuned using a numeric value:

a1-\markup { \halign #-1 poco }
e'
a,-\markup { \halign #0 poco }
e'
a,-\markup { \halign #0.5 poco }
e'
a,-\markup { \halign #2 poco }


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.

d2^\markup {
Acte I
\raise #2 { Scène 1 }
}
a'
g_\markup {
\null
\lower #4 \bold { Très modéré }
}
a
d,^\markup {
\raise #4 \italic { Une forêt. }
}
a'4 a g2 a


Some commands can affect both the horizontal and vertical alignment of text objects in markup mode. Any object affected by these commands must be preceded with an anchor point:

d2^\markup {
Acte I
\translate #'(-1 . 2) "Scène 1"
}
a'
g_\markup {
\null
\general-align #Y #3.2 \bold "Très modéré"
}
a
d,^\markup {
\null
\translate-scaled #'(-1 . 2) \teeny "Une forêt."
}
a'4 a g2 a


A markup object may include several lines of text. In the following example, each element or expression is placed on its own line, either left-aligned or centered:

\markup {
\column {
a
"b c"
\line { d e f }
}
\hspace #10
\center-column {
a
"b c"
\line { d e f }
}
}


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:

\markup {
\fill-line {
\line { William S. Gilbert }
\center-column {
or
\smallCaps "The Town of Titipu"
}
\line { Sir Arthur Sullivan }
}
}
\markup {
\fill-line { 1885 }
}


Long text indications can also be automatically wrapped accordingly to the given line width. These will be either left-aligned or justified, as shown in the following example.

\markup {
\column {
\line  \smallCaps { La vida breve }
\line \bold { Acto I }
\wordwrap \italic {
(La escena representa el corral de una casa de
gitanos en el Albaicín de Granada.  Al fondo una
puerta por la que se ve el negro interior de
una Fragua, iluminado por los rojos resplandores
del fuego.)
}
\hspace #0

\line \bold { Acto II }
\override #'(line-width . 50)
\justify \italic {
y su hermano Manuel con grandes ventanas abiertas
a través de las que se ve el patio
donde se celebra una alegre fiesta)
}
}
}


An exhaustive list of text alignment commands can be found in Align.

Learning Manual: Moving objects.

Notation Reference: Align, Text marks.

Installed Files: ‘scm/define-markup-commands.scm’.

Snippets: Text.

Internals Reference: TextScript.

#### Graphic notation inside markup

Various graphic objects may be added to a score, using markup commands.

Some markup commands allow decoration of text elements with graphics, as demonstrated in the following example.

\markup \fill-line {
\center-column {
\circle Jack
\box "in the box"
\null
\line {
Erik Satie
\hspace #3
\bracket "1866 - 1925"
}
\null
\rounded-box \bold Prelude
}
}


Some commands may require an increase in the padding around the text; this is achieved with some markup commands exhaustively described in Align.

\markup \fill-line {
\center-column {
\box "Charles Ives (1874 - 1954)"
\null
\box \pad-x #8 "A Cosmic Landscape"
\null
}
}
\markup \column {
\line {
\hspace #10
\box \pad-to-box #'(-5 . 20) #'(0 . 5)
\bold "Largo to Presto"
}
"String quartet keeps very even time,
Flute quartet keeps very uneven time."
}


Other graphic elements or symbols may be printed without requiring any text. As with any markup expression, such objects can be combined.

\markup {
\combine
\draw-circle #4 #0.4 ##f
\filled-box #'(-4 . 4) #'(-0.5 . 0.5) #1
\hspace #5

\center-column {
\triangle ##t
\combine
\draw-line #'(0 . 4)
}
}


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:

c1^\markup {
\combine
\epsfile #X #10 #"./context-example.eps"
\with-dimensions #'(0 . 6) #'(0 . 10)
\postscript #"
-2 3 translate
2.7 2 scale
newpath
2 -1 moveto
4 -2 4 1 1 arct
4 2 3 3 1 arct
0 4 0 3 1 arct
0 0 1 -1 1 arct
closepath
stroke"
}
c


An exhaustive list of graphics-specific commands can be found in Graphic.

Notation Reference: Graphic, Editorial annotations, Align.

Installed Files: ‘scm/define-markup-commands.scm’, ‘scm/stencil.scm’.

Snippets: Text.

Internals Reference: TextScript.

#### Music notation inside markup

Various musical notation elements may be added to a score, inside a markup object.

Notes and accidentals can be entered using markup commands:

a2 a^\markup {
\note #"4" #1
=
\note-by-number #1 #1 #1.5
}
b1_\markup {
\natural \semiflat \flat
\sesquiflat \doubleflat
}
\glissando
a1_\markup {
\natural \semisharp \sharp
\sesquisharp \doublesharp
}
\glissando b


Other notation objects may also be printed in markup mode:

g1 bes
ees-\markup {
\finger 4
\tied-lyric #"~"
\finger 1
}
fis_\markup { \dynamic rf }
bes^\markup {
\beam #8 #0.1 #0.5
}
cis
d-\markup {
\markalphabet #8
\markletter #8
}


More generally, any available musical symbol may be included separately in a markup object, as demonstrated below; an exhaustive list of these symbols and their names can be found in The Feta font.

c2
c'^\markup { \musicglyph #"eight" }
c,4
c,8._\markup { \musicglyph #"clefs.G_change" }
c16
c2^\markup { \musicglyph #"timesig.neomensural94" }


Another way of printing non-text glyphs is described in Fonts explained. This is useful for printing braces of various sizes.

The markup mode also supports diagrams for specific instruments:

c1^\markup {
\fret-diagram-terse #"x;x;o;2;3;2;"
}
c^\markup {
\harp-pedal #"^-v|--ov^"
}
c
c^\markup {
\combine
\musicglyph #"accordion.discant"
\combine
\raise #0.5 \musicglyph #"accordion.dot"
\raise #1.5 \musicglyph #"accordion.dot"
}


Such diagrams are documented in Instrument Specific Markup.

A whole score can even be nested inside a markup object. In such a case, the nested \score block must contain a \layout block, as demonstrated here:

c4 d^\markup {
\score {
\relative c' { c4 d e f }
\layout { }
}
}
e f |
c d e f


An exhaustive list of music notation related commands can be found in Music.

Notation Reference: Music, The Feta font, Fonts explained.

Installed Files: ‘scm/define-markup-commands.scm’, ‘scm/fret-diagrams.scm’, ‘scm/harp-pedals.scm’.

Snippets: Text.

Internals Reference: TextScript.

#### Multi-page markup

Although standard markup objects are not breakable, a specific syntax makes it possible to enter lines of text that can spread over multiple pages:

\markuplist {
\justified-lines {
A very long text of justified lines.
...
}
\wordwrap-lines {
Another very long paragraph.
...
}
...
}


This syntax accepts a list of markups, that can be

• the result of a markup list command,
• a list of markups,
• a list of markup lists.

An exhaustive list of markup list commands can be found in Text markup list commands.

Notation Reference: Text markup list commands.

Extending LilyPond: New markup list command definition.

Installed Files: ‘scm/define-markup-commands.scm’.

Snippets: Text.

Internals Reference: TextScript.

#### Predefined commands

\markuplist.

### 1.8.3 Fonts

This section presents the way fonts are handled, and how they may be changed in scores.

#### Fonts explained

Fonts are handled through several libraries. FontConfig is used to detect available fonts on the system; the selected fonts are rendered using Pango.

Music notation fonts can be described as a set of specific glyphs, ordered in several families. The following syntax allows various LilyPond feta non-text fonts to be used directly in markup mode:

a1^\markup {
\vcenter {
\override #'(font-encoding . fetaBraces)
\lookup #"brace120"
\override #'(font-encoding . fetaText)
\column { 1 3 sf }
\override #'(font-encoding . fetaMusic)
}
}


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.

Three families of text fonts are made available: the roman (serif) font, that defaults to New Century Schoolbook, the sans font and the monospaced typewriter font – these last two families are determined by the Pango installation.

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.

\override Score.RehearsalMark #'font-family = #'typewriter
\mark \markup "Ouverture"
\override Voice.TextScript #'font-shape = #'italic
\override Voice.TextScript #'font-series = #'bold
d2.^\markup "Allegro"
\override Voice.TextScript #'font-size = #-3
c4^smaller


A similar syntax may be used in markup mode; however in this case it is preferable to use the simpler syntax explained in Selecting font and font size:

\markup {
\column {
\line {
\override #'(font-shape . italic)
\override #'(font-size . 4)
Idomeneo,
}
\line {
\override #'(font-family . typewriter)
{
\override #'(font-series . bold)
re
di
}
\override #'(font-family . sans)
Creta
}
}
}


Although it is easy to switch between preconfigured fonts, it is also possible to use other fonts, as explained in the following sections: Single entry fonts and Entire document fonts.

Notation Reference: The Feta font, Music notation inside markup, Rotating objects, Selecting font and font size, Font.

#### Single entry fonts

Any font that is installed on the operating system and recognized by FontConfig may be used in a score, using the following syntax:

\override Staff.TimeSignature #'font-name = #"Bitstream Charter"
\override Staff.TimeSignature #'font-size = #2
\time 3/4

a1_\markup {
\override #'(font-name . "Vera Bold")
{ Vera Bold }
}


The following command displays a list of all available fonts on the operating system:

lilypond -dshow-available-fonts x


Notation Reference: Fonts explained, Entire document fonts.

Snippets: Text.

#### 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. For an explanation of fonts, see Fonts explained.

\paper  {
myStaffSize = #20
#(define fonts
(make-pango-font-tree "Times New Roman"
"Nimbus Sans"
"Luxi Mono"
(/ myStaffSize 20)))
}

\relative c'{
c1-\markup {
roman,
\sans sans,
\typewriter typewriter. }
}


Notation Reference: Fonts explained, Single entry fonts, Selecting font and font size, Font.

# 2. Specialist notation

This chapter explains how to create musical notation for specific types of instrument or in specific styles.

## 2.1 Vocal music

This section explains how to typeset vocal music, and make sure that the lyrics will be aligned with the notes of their melody.

### 2.1.1 Common notation for vocal music

This section discusses issues common to most types of vocal music.

#### References for vocal music

This section indicates where to find details of notation issues that may arise in any type of vocal music.

• Most styles of vocal music use written text as lyrics. An introduction to this notation is to be found in Setting simple songs.
• Vocal music is likely to require the use of markup mode, either for lyrics or for other text elements (characters’ names, etc.) This syntax is described in Text markup introduction.
• Ambitus may be added at the beginning of vocal staves, as explained in Ambitus.
• 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, as explained in Score layouts for choral.

Music Glossary: ambitus.

Learning Manual: Setting simple songs.

Notation Reference: Text markup introduction, Ambitus, Score layouts for choral.

Snippets: Vocal music.

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


Similarly, in lyric mode, a period will be included in the alphabetic sequence that it follows. As a consequence, spaces must be inserted around the period in \override commands. Do not write

\override Score.LyricText #'font-shape = #'italic


\override Score . LyricText #'font-shape = #'italic


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.

\relative c'' { d8 c16 a bes8 f e' d c4 }
\addlyrics { „Schad’ um das schö -- ne grü -- ne Band, }


Normal quotes may be used in lyrics, but they have to be preceded with a backslash character and the whole syllable has to be enclosed between additional quotes. For example,

\relative c' { \time 3/4 e4 e4. e8 d4 e d c2. }
\addlyrics { "\"I" am so lone -- "ly,\"" said she }


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.

#### Selected Snippets

Formatting lyrics syllables

Markup mode may be used to format individual syllables in lyrics.

mel = \relative c'' { c4 c c c }
lyr = \lyricmode {
Lyrics \markup { \italic can } \markup { \with-color #red contain }
\markup { \fontsize #8 \bold Markup! }
}

<<
\new Voice = melody \mel
\new Lyrics \lyricsto melody \lyr
>>


Learning Manual: Songs.

Internals Reference: LyricText.

Snippets: Text.

#### Aligning lyrics to a melody

Lyrics are printed by interpreting them in the context called Lyrics, see Contexts explained.

\new Lyrics \lyricmode { … }


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.
<<
\new Staff <<
\time 2/4
\new Voice = "one" \relative c'' {
\voiceOne
c4 b8. a16 g4. r8 a4 ( b ) c2
}
\new Voice = "two" \relative c' {
\voiceTwo
s2 s4. f8 e4 d c2
}
>>

% takes durations and alignment from notes in "one"
\new Lyrics \lyricsto "one" {
Life is __ _ love, live __ life.
}

% takes durations and alignment from notes in "one" initially
% then switches to "two"
\new Lyrics \lyricsto "one" {
No more let
\set associatedVoice = "two"  % must be set one syllable early
sins and sor -- rows grow.
}
>>


The first stanza shows the normal way of entering lyrics.

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.
<<
\new Voice = "one" \relative c'' {
\time 2/4
c4 b8. a16 g4. f8 e4 d c2
}

% uses previous explicit duration of 2;
\new Lyrics \lyricmode {
Joy to the earth!
}

% explicit durations, set to a different rhythm
\new Lyrics \lyricmode {
Life4 is love,2. live4 life.2
}
>>


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.

When entered in this way the words are left-aligned to the notes by default, but may be center-aligned to the notes of a melody by specifying an associated voice, if one exists. For details, see Manual syllable durations.

Learning Manual: Aligning lyrics to a melody.

Internals Reference: Lyrics.

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

<<
\new Voice = "melody" {
a4 a a a
}
\new Lyrics \lyricsto "melody" {
These are the words
}
>>


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, so the \lyricmode keyword may be omitted. 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.

{ MUSIC }


is the same as

\new Voice = "blah" { MUSIC }
\new Lyrics \lyricsto "blah" { LYRICS }


Here is an example,

{
\time 3/4
\relative c' { c2 e4 g2. }
\addlyrics { play the game }
}


More stanzas can be added by adding more \addlyrics sections:

{
\time 3/4
\relative c' { c2 e4 g2. }
\addlyrics { play the game }
\addlyrics { speel het spel }
\addlyrics { joue le jeu }
}


The command \addlyrics cannot handle polyphonic settings. 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.

Here is an example demonstrating its use:

<<
\new Staff <<
\time 2/4
\new Voice = "one" \relative c'' {
\voiceOne
c4 b8. a16 g4. r8 a4 ( b ) c2
}
\new Voice = "two" \relative c' {
\voiceTwo
s2 s4. f8 e8 d4. c2
}
>>
% takes durations and alignment from notes in "one" initially
% then switches to "two"
\new Lyrics \lyricsto "one" {
No more let
\set associatedVoice = "two"  % must be set one syllable early
sins and sor -- rows grow.
}
>>


Notation Reference: Extenders and hyphens, Keeping contexts alive, Placing lyrics vertically.

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

By default, syllables will be left-aligned to the corresponding musical moment. Hyphenated lines may be drawn between syllables as usual, but extender lines cannot be drawn when there is no associated voice.

Here are two examples:

<<
\new Voice = "melody" {
\time 3/4
c2 e4 g2 f
}
\new Lyrics \lyricmode {
play1 the4 game4
}
>>


<<
\new Staff {
\relative c'' {
c2 c2
d1
}
}
\new Lyrics {
\lyricmode {
I2 like4. my8 cat!1
}
}
\new Staff {
\relative c' {
c8 c c c c c c c
c8 c c c c c c c
}
}
>>


This technique is useful when writing dialogue over music, see Dialogue over music.

To center-align syllables on the notes at the corresponding musical moments, set associatedVoice to the name of the Voice context containing those notes. When associatedVoice is set, both double hyphens and double underscores can be used to draw hyphenated lines and extenders under melismata correctly.

<<
\new Voice = "melody" {
\time 3/4
c2 e4 g f g
}
\new Lyrics \lyricmode {
\set associatedVoice = #"melody"
play2 the4 game2. __
}
>>


Notation Reference: Dialogue over music.

Internals Reference: Lyrics, 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.

{
\relative c'' { \autoBeamOff
r8 b c fis, fis c' b e, }
\addlyrics { Che_in ques -- ta_e_in quel -- l'al -- tr'on -- da }
\addlyrics { "Che in" ques -- "ta e in" quel -- l'al -- tr'on -- da }
\addlyrics { Che~in ques -- ta~e~in quel -- l'al -- tr'on -- da }
}


Internals Reference: LyricCombineMusic.

#### Multiple notes to one syllable

Sometimes, particularly in Medieval music, several notes are to be sung on one syllable; such vocalises are called melismata, or melismas. The syllable to a melisma is usually left-aligned with the first note of the melisma.

When a melisma occurs on a syllable other that 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:
<<
\new Voice = "melody" {
\time 3/4
f4 g2 ~ |
g4 e2 ~ |
e8
}
\new Lyrics \lyricsto "melody" {
Ky -- ri -- e __
}
>>


• Melismata can be created automatically from the music by placing slurs over the notes of each melisma. This is the usual way of entering lyrics:
<<
\new Voice = "melody" {
\time 3/4
f4 g8 ( f e f )
e8 ( d e2 )
}
\new Lyrics \lyricsto "melody" {
Ky -- ri -- e __
}
>>


Note that phrasing slurs do not affect the creation of melismata.

• Notes are considered a melisma if they are manually beamed, providing automatic beaming is switched off. See Setting automatic beam behavior.
<<
\new Voice = "melody" {
\time 3/4
\autoBeamOff
f4 g8[ f e f]
e2.
}
\new Lyrics \lyricsto "melody" {
Ky -- ri -- e
}
>>


Clearly this is not suited to melismata over notes which are longer than eighth notes.

• An unslurred group of notes will be treated as a melisma if they are bracketed between \melisma and \melismaEnd.
<<
\new Voice = "melody" {
\time 3/4
f4 g8
\melisma
f e f
\melismaEnd
e2.
}
\new Lyrics \lyricsto "melody" {
Ky -- ri -- e
}
>>


• A melisma can be defined entirely in the lyrics by entering a single underscore character, _, for every extra note that has to be added to the melisma.
<<
\new Voice = "melody" {
\time 3/4
f4 g8 f e f
e8 d e2
}
\new Lyrics \lyricsto "melody" {
Ky -- ri -- _ _ _ e __ _ _
}
>>


It is possible to have ties, slurs and manual beams in the melody without their indicating melismata. To do this, set melismaBusyProperties:

<<
\new Voice = "melody" {
\time 3/4
\set melismaBusyProperties = #'()
c4 d ( e )
g8 [ f ] f4 ~ f
}
\new Lyrics \lyricsto "melody" {
Ky -- ri -- e e -- le -- i -- son
}
>>


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.

Alternatively, if all melismata indications are to be ignored, ignoreMelismata may be set true; see Stanzas with different rhythms.

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:

<<
\new Voice = "melody" {
\time 3/4
\set melismaBusyProperties = #'()
c4 d ( e )
g8 [ f ] ~ f4 ~ f
}
\new Lyrics \lyricsto "melody" {
Ky -- ri -- _ e __ _ _ _
}
>>


#### Predefined commands

\autoBeamOff, \autoBeamOn, \melisma, \melismaEnd.

Musical Glossary: melisma.

Learning Manual: Aligning lyrics to a melody.

Internals Reference: Tunable context properties.

#### Known issues and warnings

Extender lines under melismata are not created automatically; they must be inserted manually with a double underscore.

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

Internals Reference: LyricExtender, LyricHyphen.

### 2.1.2 Techniques specific to lyrics

#### Working with lyrics and variables

Variables containing lyrics can be created, but the lyrics must be entered in lyric mode:

musicOne = \relative c'' {
c4 b8. a16 g4. f8 e4 d c2
}
verseOne = \lyricmode {
Joy to the world, the Lord is come.
}
\score {
<<
\new Voice = "one" {
\time 2/4
\musicOne
}
\new Lyrics \lyricsto "one" {
\verseOne
}
>>
}


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:

sopranoMusic = \relative c'' { c4 c c c }
contraltoMusic = \relative c'' { a4 a a a }
sopranoWords = \lyricmode { Sop -- ra -- no words }
contraltoWords = \lyricmode { Con -- tral -- to words }

\score {
\new ChoirStaff <<
\new Staff {
\new Voice = "sopranos" {
\sopranoMusic
}
}
\new Lyrics = "sopranos"
\new Lyrics = "contraltos"
\new Staff {
\new Voice = "contraltos" {
\contraltoMusic
}
}
\context Lyrics = "sopranos" {
\lyricsto "sopranos" {
\sopranoWords
}
}
\context Lyrics = "contraltos" {
\lyricsto "contraltos" {
\contraltoWords
}
}
>>
}


Notation Reference: Placing lyrics vertically.

Internals Reference: LyricCombineMusic, Lyrics.

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

\score {
<<
\new Staff {
\new Voice = "melody" {
\relative c'' { c4 c c c }
}
}
\new Lyrics {
\lyricsto "melody" {
Here are the words
}
}
>>
}


Lyrics may be positioned above the staff using one of two methods. The simplest (and preferred) method is to use the same syntax as above and explicitly specify the position of the lyrics:

\score {
<<
\new Staff = "staff" {
\new Voice = "melody" {
\relative c'' { c4 c c c }
}
}
\new Lyrics \with { alignAboveContext = "staff" } {
\lyricsto "melody" {
Here are the words
}
}
>>
}


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:

\score {
<<
\new Lyrics = "lyrics" \with {
% lyrics above a staff should have this override
\override VerticalAxisGroup #'staff-affinity = #DOWN
}
\new Staff {
\new Voice = "melody" {
\relative c'' { c4 c c c }
}
}
\context Lyrics = "lyrics" {
\lyricsto "melody" {
Here are the words
}
}
>>
}


When there are two voices on separate staves the lyrics may be placed between the staves using either of these methods. Here is an example of the second method:

\score {
\new ChoirStaff <<
\new Staff {
\new Voice = "sopranos" {
\relative c'' { c4 c c c }
}
}
\new Lyrics = "sopranos"
\new Lyrics = "contraltos" \with {
% lyrics above a staff should have this override
\override VerticalAxisGroup #'staff-affinity = #DOWN
}
\new Staff {
\new Voice = "contraltos" {
\relative c'' { a4 a a a }
}
}
\context Lyrics = "sopranos" {
\lyricsto "sopranos" {
Sop -- ra -- no words
}
}
\context Lyrics = "contraltos" {
\lyricsto "contraltos" {
Con -- tral -- to words
}
}
>>
}


Other combinations of lyrics and staves may be generated by elaborating these examples, or by examining the Vocal ensembles templates in the Learning Manual.

#### Selected Snippets

Obtaining 2.12 lyrics spacing in newer versions

The vertical spacing engine changed for version 2.14. This can cause lyrics to be spaced differently. It is possible to set properties for Lyric and Staff contexts to get the spacing engine to behave as it did in version 2.12.

global = {
\key d \major
\time 3/4
}

sopMusic = \relative c' {
% VERSE ONE
fis4 fis fis | \break
fis4. e8 e4
}

altoMusic = \relative c' {
% VERSE ONE
d4 d d |
d4. b8 b4 |
}

tenorMusic = \relative c' {
a4 a a |
b4. g8 g4 |
}

bassMusic = \relative c {
d4 d d |
g,4. g8 g4 |
}

words = \lyricmode {
Great is Thy faith- ful- ness,
}

\score {
\new ChoirStaff <<
\new Lyrics = sopranos
\new Staff = women <<
\new Voice = "sopranos" {
\voiceOne
\global \sopMusic
}
\new Voice = "altos" {
\voiceTwo
\global \altoMusic
}
>>
\new Lyrics = "altos"
\new Lyrics = "tenors"
\new Staff = men <<
\clef bass
\new Voice = "tenors" {
\voiceOne
\global \tenorMusic
}
\new Voice = "basses" {
\voiceTwo  \global \bassMusic
}
>>
\new Lyrics = basses
\context Lyrics = sopranos \lyricsto sopranos \words
\context Lyrics = altos \lyricsto altos \words
\context Lyrics = tenors \lyricsto tenors \words
\context Lyrics = basses \lyricsto basses \words
>>
\layout {
\context {
\Lyrics
\override VerticalAxisGroup #'staff-affinity = ##f
\override VerticalAxisGroup #'staff-staff-spacing =
#'((basic-distance . 0)
(minimum-distance . 2)
}
\context {
\Staff
\override VerticalAxisGroup #'staff-staff-spacing =
#'((basic-distance . 0)
(minimum-distance . 2)
}
}
}


Learning Manual: Vocal ensembles.

Notation Reference: Context layout order, Creating contexts.

#### Placing syllables horizontally

To increase the spacing between lyrics, set the minimum-distance property of LyricSpace.

{
c c c c
\override Lyrics.LyricSpace #'minimum-distance = #1.0
c c c c
}
longtext longtext longtext longtext
longtext longtext longtext longtext
}


To make this change for all lyrics in the score, set the property in the \layout block.

\score {
\relative c' {
c c c c
c c c c
}
longtext longtext longtext longtext
longtext longtext longtext longtext
}
\layout {
\context {
\Lyrics
\override LyricSpace #'minimum-distance = #1.0
}
}
}


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

\layout { ragged-right = ##f }
\relative c'' {
c1
c1
c1
}
\once \override LyricText #'self-alignment-X = #LEFT
"This is left-aligned"
\once \override LyricText #'self-alignment-X = #CENTER
"This is centered"
\once \override LyricText #'self-alignment-X = #1
"This is right-aligned"
}


Checking to make sure that text scripts and lyrics are within the margins requires additional calculations. To speed up processing slightly, this feature can be disabled:

\override Score.PaperColumn #'keep-inside-line = ##f


To make lyrics avoid bar lines as well, use

\layout {
\context {
\Lyrics
\consists "Bar_engraver"
\consists "Separating_line_group_engraver"
\override BarLine #'transparent = ##t
}
}


### Simple repeats

Repeats in music are fully described elsewhere; see Repeats. This section explains how to add lyrics to repeated sections of music.

Lyrics to a section of music that is repeated should be surrounded by exactly the same repeat construct as the music, if the words are unchanged.

\score {
<<
\new Staff {
\new Voice = "melody" {
\relative c'' {
a4 a a a
\repeat volta 2 { b4 b b b }
}
}
}
\new Lyrics {
\lyricsto "melody" {
Not re -- peat -- ed.
\repeat volta 2 { Re -- peat -- ed twice. }
}
}
>>
}


The words will then be correctly expanded if the repeats are unfolded.

\score {
\unfoldRepeats {
<<
\new Staff {
\new Voice = "melody" {
\relative c'' {
a4 a a a
\repeat volta 2 { b4 b b b }
}
}
}
\new Lyrics {
\lyricsto "melody" {
Not re -- peat -- ed.
\repeat volta 2 { Re -- peat -- ed twice. }
}
}
>>
}
}


If the repeated section is to be unfolded and has different words, simply enter all the words:

\score {
<<
\new Staff {
\new Voice = "melody" {
\relative c'' {
a4 a a a
\repeat unfold 2 { b4 b b b }
}
}
}
\new Lyrics {
\lyricsto "melody" {
Not re -- peat -- ed.
The first time words.
Sec -- ond time words.
}
}
>>
}


When the words to a repeated volta section are different, the words to each repeat must be entered in separate Lyrics contexts, correctly nested in parallel sections:

\score {
<<
\new Staff {
\new Voice = "melody" {
\relative c'' {
a4 a a a
\repeat volta 2 { b4 b b b }
}
}
}
\new Lyrics \lyricsto "melody" {
Not re -- peat -- ed.
<<
{ The first time words. }
\new Lyrics {
\set associatedVoice = "melody"
Sec -- ond time words.
}
>>
}
>>
}


More verses may be added in a similar way:

\score {
<<
\new Staff {
\new Voice = "singleVoice" {
\relative c'' {
a4 a a a
\repeat volta 3 { b4 b b b }
c4 c c c
}
}
}
\new Lyrics \lyricsto "singleVoice" {
Not re -- peat -- ed.
<<
{ The first time words.	}
\new Lyrics {
\set associatedVoice = "singleVoice"
Sec -- ond time words.
}
\new Lyrics {
\set associatedVoice = "singleVoice"
The third time words.
}
>>
The end sec -- tion.
}
>>
}


However, if this construct is embedded within a multi-staved context such as a ChoirStaff the lyrics of the second and third verses will appear beneath the bottom staff.

To position them correctly use alignBelowContext:

\score {
<<
\new Staff {
\new Voice = "melody" {
\relative c'' {
a4 a a a
\repeat volta 3 { b4 b b b }
c4 c c c
}
}
}
\new Lyrics = "firstVerse" \lyricsto "melody" {
Not re -- peat -- ed.
<<
{ The first time words.	}
\new Lyrics = "secondVerse"
\with { alignBelowContext = #"firstVerse" } {
\set associatedVoice = "melody"
Sec -- ond time words.
}
\new Lyrics = "thirdVerse"
\with { alignBelowContext = #"secondVerse" } {
\set associatedVoice = "melody"
The third time words.
}
>>
The end sec -- tion.
}
\new Voice = "harmony" {
\relative c' {
f4 f f f \repeat volta 2 { g8 g g4 g2 } a4 a8. a16 a2
}
}
>>
}


### Repeats with alternative endings

If the words of the repeated section are the same, exactly the same structure can be used for both the lyrics and music.

\score {
<<
\new Staff {
\time 2/4
\new Voice = "melody" {
\relative c'' {
a4 a a a
\repeat volta 2 { b4 b }
\alternative { { b b } { b c } }
}
}
}
\new Lyrics {
\lyricsto "melody" {
Not re -- peat -- ed.
\repeat volta 2 { Re -- peat -- }
\alternative { { ed twice. } { ed twice. } }
}
}
>>
}


But when the repeated section has different words, 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.

\score {
<<
\new Staff {
\time 2/4
\new Voice = "melody" {
\relative c'' {
\repeat volta 2 { b4 b }
\alternative { { b b } { b c } }
c4 c
}
}
}
\new Lyrics {
\lyricsto "melody" {
The first time words.
\repeat unfold 2 { \skip 1 }
End here.
}
}
\new Lyrics {
\lyricsto "melody" {
Sec -- ond
\repeat unfold 2 { \skip 1 }
time words.
}
}
>>
}


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.

\score {
<<
\new Staff {
\time 2/4
\new Voice = "melody" {
\relative c'' {
\set melismaBusyProperties = #'()
\repeat volta 2 { b4 b ~}
\alternative { { b b } { b \repeatTie c } }
\unset melismaBusyProperties
c4 c
}
}
}
\new Lyrics {
\lyricsto "melody" {
\repeat volta 2 { Here's a __ }
\alternative {
{ \skip 1 verse }
{ \skip 1 sec }
}
ond one.
}
}
>>
}


Note that if \unfoldRepeats is used around a section containing \repeatTie, the \repeatTie should be removed to avoid both types of tie being printed.

When the repeated section has different words a \repeat cannot be used around the lyrics and \skip commands need to be inserted manually, as before.

\score {
<<
\new Staff {
\time 2/4
\new Voice = "melody" {
\relative c'' {
\repeat volta 2 { b4 b ~}
\alternative { { b b } { b \repeatTie c } }
c4 c
}
}
}
\new Lyrics {
\lyricsto "melody" {
Here's a __ verse.
\repeat unfold 2 { \skip 1 }
}
}
\new Lyrics {
\lyricsto "melody" {
Here's one
\repeat unfold 2 { \skip 1 }
more to sing.
}
}
>>
}


If you wish to show extenders and hyphens into and out of alternative sections these must be inserted manually.

\score {
<<
\new Staff {
\time 2/4
\new Voice = "melody" {
\relative c'' {
\repeat volta 2 { b4 b ~}
\alternative { { b b } { b \repeatTie c } }
c4 c
}
}
}
\new Lyrics {
\lyricsto "melody" {
Here's a __ verse.
\repeat unfold 2 { \skip 1 }
}
}
\new Lyrics {
\lyricsto "melody" {
Here's "a_"
\skip 1
"_" sec -- ond one.
}
}
>>
}


Notation Reference: Keeping contexts alive, Repeats.

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

\score {
<<
\new Voice = "melody" {
\relative c' {
\set melismaBusyProperties = #'()
\slurDown
\slurDashed
e4 e8 ( e ) c4 c |
\unset melismaBusyProperties
c
}
}
\new Lyrics \lyricsto "melody" {
They shall not o -- ver -- come
}
\new Lyrics \lyricsto "melody" {
We will _
}
>>
}


When both music and words differ it may be better to display the differing music and lyrics by naming voice contexts and attaching lyrics to those specific contexts:

\score {
<<
\new Voice = "melody" {
\relative c' {
<<
{
\voiceOne
e4 e8 e
}
\new Voice = "splitpart" {
\voiceTwo
c4 c
}
>>
\oneVoice
c4 c |
c
}
}
\new Lyrics \lyricsto "melody" {
They shall not o -- ver -- come
}
\new Lyrics \lyricsto "splitpart" {
We will
}
>>
}


### 2.1.3 Stanzas

Stanza numbers can be added by setting stanza, e.g.,

\new Voice {
\time 3/4 g2 e4 a2 f4 g2.
\set stanza = #"1. "
Hi, my name is Bert.
\set stanza = #"2. "
Oh, ché -- ri, je t'aime
}


These numbers are put just before the start of the first syllable.

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

text = {
\set stanza = \markup { \dynamic "ff" "1. " }
\lyricmode {
Big bang
}
}

<<
\new Voice = "tune" {
\time 3/4
g'4 c'2
}
\new Lyrics \lyricsto "tune" \text
>>


#### Adding singers’ names to stanzas

Names of singers can also be added. They are printed at the start of the line, just like instrument names. They are created by setting vocalName. A short version may be entered as shortVocalName.

\new Voice {
\time 3/4 g2 e4 a2 f4 g2.
\set vocalName = #"Bert "
Hi, my name is Bert.
\set vocalName = #"Ernie "
Oh, ché -- ri, je t'aime
}


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

<<
\relative c' \new Voice = "lahlah" {
\set Staff.autoBeaming = ##f
c4
\slurDotted
f8.[( g16])
a4
}
\new Lyrics \lyricsto "lahlah" {
more slow -- ly
}
\new Lyrics \lyricsto "lahlah" {
go
\set ignoreMelismata = ##t
fas -- ter
\unset ignoreMelismata
still
}
>>


#### Known issues and warnings

Unlike most \set commands, \set ignoreMelismata does not work if prefixed with \once. It is necessary to use \set and \unset to bracket the lyrics where melismata are to be ignored.

#### Adding syllables to grace notes

By default, grace notes (e.g. via \grace) do not get assigned syllables when using \lyricsto, but this behavior can be changed:

<<
\new Voice = melody \relative c' {
f4 \appoggiatura a32 b4
\grace { f16[ a16] } b2
\afterGrace b2 { f16[ a16] }
\appoggiatura a32 b4
\acciaccatura a8 b4
}
\new Lyrics
\lyricsto melody {
normal
\set includeGraceNotes = ##t
case,
gra -- ce case,
after -- grace case,
\set ignoreMelismata = ##t
app. case,
acc. case.
}
>>


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

<<
\new Voice = melody \relative c' {
\grace { c16[( d e f] }
g1) f
}
\new Lyrics \with { includeGraceNotes = ##t }
\lyricsto melody {
Ah __ fa
}
>>


#### Switching to an alternative melody

More complex variations in setting lyrics to music are possible. The melody to which the lyrics are being set can be changed from within the lyrics by setting the associatedVoice property:

<<
\relative c' \new Voice = "lahlah" {
\set Staff.autoBeaming = ##f
c4
<<
\new Voice = "alternative" {
\voiceOne
\times 2/3 {
% show associations clearly.
\override NoteColumn #'force-hshift = #-3
f8 f g
}
}
{
\voiceTwo
f8.[ g16]
\oneVoice
} >>
a8( b) c
}
\new Lyrics \lyricsto "lahlah" {
Ju -- ras -- sic Park
}
\new Lyrics \lyricsto "lahlah" {
% Tricky: need to set associatedVoice
% one syllable too soon!
\set associatedVoice = "alternative" % applies to "ran"
Ty --
ran --
no --
\set associatedVoice = "lahlah" % applies to "rus"
sau -- rus Rex
} >>


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:

\set associatedVoice = "alternative" % applies to "ran"
Ty --
ran --
no --
\set associatedVoice = "lahlah" % applies to "rus"
sau -- rus Rex


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.

melody = \relative c' {
e d c d | e e e e |
d d e d | c1 |
}

text = \lyricmode {
\set stanza = #"1." Ma- ry had a lit- tle lamb,
its fleece was white as snow.
}

\score{ <<
\new Voice = "one" { \melody }
\new Lyrics \lyricsto "one" \text
>>
\layout { }
}
\markup { \column{
\line{ Verse 2. }
\line{ All the children laughed and played }
\line{ To see a lamb at school. }
}
}
\markup{
\wordwrap-string #"
Verse 3.

Mary took it home again,

It was against the rule."
}


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

melody = \relative c' {
c4 c c c | d d d d
}

text = \lyricmode {
\set stanza = #"1." This is verse one.
It has two lines.
}

\score {
<<
\new Voice = "one" { \melody }
\new Lyrics \lyricsto "one" \text
>>
\layout { }
}

\markup {
\fill-line {
\hspace #0.1 % moves the column off the left margin;
% can be removed if space on the page is tight
\column {
\line { \bold "2."
\column {
"This is verse two."
"It has two lines."
}
}
\vspace #0.1 % adds vertical spacing between verses
\line { \bold "3."
\column {
"This is verse three."
"It has two lines."
}
}
}
\hspace #0.1 % adds horizontal spacing between columns;
\column {
\line { \bold "4."
\column {
"This is verse four."
"It has two lines."
}
}
\vspace #0.1 % adds vertical spacing between verses
\line { \bold "5."
\column {
"This is verse five."
"It has two lines."
}
}
}
\hspace #0.1 % gives some extra space on the right margin;
% can be removed if page space is tight
}
}


Internals Reference: LyricText, StanzaNumber.

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

Learning Manual: Songs.

Snippets: Vocal music.

Lead sheets may be printed by combining vocal parts and ‘chord mode’; this syntax is explained in Chord notation.

#### Selected Snippets

When put together, chord names, a melody, and lyrics form a lead sheet:

<<
\chords { c2 g:sus4 f e }
\relative c'' {
a4 e c8 e r4
b2 c4( d)
}
\addlyrics { One day this shall be free __ }
>>


Notation Reference: Chord notation.

### 2.1.5 Choral

This section discusses notation issues that relate most directly to choral music. This includes anthems, part songs, oratorio, etc.

#### 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 a capella 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.
• Several templates suitable for various styles of choral music can also be found in the Learning Manual, see Vocal ensembles.
• For information about ChoirStaff and PianoStaff see Grouping staves.
• 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.

#### Predefined commands

\oneVoice, \voiceOne, \voiceTwo.

Learning Manual: Four-part SATB vocal score, Vocal ensembles.

Notation Reference: Context layout order, Grouping staves, Shape note heads, Single-staff polyphony.

Snippets: Vocal music.

Internals Reference: ChoirStaff, Lyrics, PianoStaff.

#### 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.
• For details of other page formatting properties, see Page layout.

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:

\score {
\new ChoirStaff <<
\new Staff {
\new Voice {
\relative c'' { g4\f g g g }
}
}
\new Staff {
\new Voice {
\relative c' { d4 d d\p d }
}
}
>>
\layout {
\context {
\Score
\override DynamicText #'direction = #UP
\override DynamicLineSpanner #'direction = #UP
}
}
}


#### Predefined commands

\dynamicUp, \dynamicDown, \dynamicNeutral.

Internals Reference: VerticalAxisGroup, StaffGrouper.

#### Divided voices

Using arpeggioBracket to make divisi more visible

The arpeggioBracket can be used to indicate the division of voices where there are no stems to provide the information. This is often seen in choral music.

\include "english.ly"

\score {
\relative c'' {
\key a \major
\time 2/2
<<
\new Voice = "upper"
<<
{ \voiceOne \arpeggioBracket
a2( b2
<b d>1\arpeggio)
<cs e>\arpeggio ~
<cs e>4
}
\addlyrics { \lyricmode { A -- men. } }
>>
\new Voice = "lower"
{ \voiceTwo
a1 ~
a
a ~
a4 \bar "|."
}
>>
}
\layout { ragged-right = ##t }
}


Notation Reference: Expressive marks as lines.

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

• A conductors’ score contains many grouped staves and lyrics. Ways of grouping staves is shown in Grouping staves. To nest groups of staves see Nested staff groups.
• 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.
• For details of other page formatting properties, see Page layout.
• 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.

Musical Glossary: Frenched score, Frenched staves, transposing instrument.

Snippets: Vocal music.

#### Character names

Character names are usually shown to the left of the staff when the staff is dedicated to that character alone:

\score {
<<
\new Staff {
\set Staff.vocalName = \markup \smallCaps Kaspar
\set Staff.shortVocalName = \markup \smallCaps Kas.
\relative c' {
\clef "G_8"
c4 c c c
\break
c4 c c c
}
}
\new Staff {
\set Staff.vocalName = \markup \smallCaps Melchior
\set Staff.shortVocalName = \markup \smallCaps Mel
\clef "bass"
\relative c' {
a4 a a a
a4 a a a
}
}
>>
}


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.

\clef "G_8"
c4^\markup \fontsize #1 \smallCaps Kaspar
c c c
\clef "bass"
a4^\markup \fontsize #1 \smallCaps Melchior
a a a
\clef "G_8"
c4^\markup \fontsize #1 \smallCaps Kaspar
c c c


Alternatively, if there are many character changes, it may be easier to set up “instrument” definitions for each character at the top level so that \instrumentSwitch can be used to indicate each change.

\addInstrumentDefinition #"kaspar"
#((instrumentTransposition . ,(ly:make-pitch -1 0 0))
(shortInstrumentName . "Kas.")
(clefGlyph . "clefs.G")
(clefOctavation . -7)
(middleCPosition . 1)
(clefPosition . -2)
(instrumentCueName . ,(markup #:fontsize 1 #:smallCaps "Kaspar"))
(midiInstrument . "voice oohs"))

#((instrumentTransposition . ,(ly:make-pitch 0 0 0))
(shortInstrumentName . "Mel.")
(clefGlyph . "clefs.F")
(clefOctavation . 0)
(middleCPosition . 6)
(clefPosition . 2)
(instrumentCueName . ,(markup #:fontsize 1 #:smallCaps "Melchior"))
(midiInstrument . "voice aahs"))

\relative c' {
\instrumentSwitch "kaspar"
c4 c c c
\instrumentSwitch "melchior"
a4 a a a
\instrumentSwitch "kaspar"
c4 c c c
}


Notation Reference: Instrument names, Scheme functions, Text, Text markup commands.

Extending LilyPond: Markup construction in Scheme.

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

flute = \relative c'' {
s4 s4 e g
}

pianoRH = \relative c'' {
c4. g8
% position name of cue-ing instrument just before the cue notes,
% and above the staff
\new CueVoice {
\override InstrumentSwitch #'self-alignment-X = #RIGHT
\set instrumentCueName = "Flute"
}
\cueDuring "flute" #UP { g4 bes4 }
}
pianoLH = \relative c { c4 <c' e> e, <g c> }

\score {
\new PianoStaff <<
\new Staff {
\pianoRH
}
\new Staff {
\clef "bass"
\pianoLH
}
>>
}


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. Note also that the piano right-hand voice is explicitly declared. This is because the cue notes in this example begin at the start of the first bar and this would otherwise cause the entire piano right-hand notes to be placed in a CueVoice context.

clarinet = \relative c' {
\transposition bes
fis4 d d c
}

pianoRH = \relative c'' {
\transposition c'
% position name of cue-ing instrument below the staff
\new CueVoice {
\override InstrumentSwitch #'self-alignment-X = #RIGHT
\override InstrumentSwitch #'direction = #DOWN
\set instrumentCueName = "Clar."
}
\cueDuring "clarinet" #DOWN { c4. g8 }
g4 bes4
}
pianoLH = \relative c { c4 <c' e> e, <g c> }

\score {
<<
\new PianoStaff <<
\new Staff {
\new Voice {
\pianoRH
}
}
\new Staff {
\clef "bass"
\pianoLH
}
>>
>>
}


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.

cueWhile =
#(define-music-function
(parser location instrument name dir music)
(string? string? ly:dir? ly:music?)
#{
\cueDuring instrument #dir { \once \override TextScript #'self-alignment-X = #RIGHT \once \override TextScript #'direction =dir
<>-\markup { \tiny #name }
\$music
}
#})

flute = \relative c'' {
\transposition c'
s4 s4 e g
}

clarinet = \relative c' {
\transposition bes
fis4 d d c
}

singer = \relative c'' { c4. g8 g4 bes4 }
words = \lyricmode { here's the lyr -- ics }

pianoRH = \relative c'' {
\transposition c'
\cueWhile "clarinet" "Clar." #DOWN { c4. g8 }
\cueWhile "flute" "Flute" #UP { g4 bes4 }
}
pianoLH = \relative c { c4 <c' e> e, <g c> }

\score {
<<
\new Staff {
\new Voice = "singer" {
\singer
}
}
\new Lyrics {
\lyricsto "singer"
\words
}
\new PianoStaff <<
\new Staff {
\new Voice {
\pianoRH
}
}
\new Staff {
\clef "bass"
\pianoLH
}
>>
>>
}


Musical Glossary: cue-notes.

Snippets: Vocal music.

Internals Reference: InstrumentSwitch, CueVoice.

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

#### Spoken music

Such effects as ‘parlato’ or ‘Sprechgesang’ require performers to speak without pitch but still with rhythm; these are notated by cross note heads, as demonstrated in Special note heads.

#### Dialogue over music

Dialogue over music is usually printed over the staves in an italic font, with the start of each phrase keyed in to a particular music moment.

For short interjections a simple markup suffices.

a4^\markup { \smallCaps { Alex - } \italic { He's gone } } a a a
a4 a a^\markup { \smallCaps { Bethan - } \italic Where? } a
a4 a a a


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.

Here is an example illustrating how this might be done.

music = \relative c'' {
\repeat unfold 3 { a4 a a a }
}

dialogue = \lyricmode {
\markup {
\fontsize #1 \upright \smallCaps Abe:
"Say this over measures one and"
}4*7
"two"4 |
\break
"and this over measure"4*3
"three"4 |
}

\score {
<<
\new Lyrics \with {
\override LyricText #'font-shape = #'italic
\override LyricText #'self-alignment-X = #LEFT
}
{ \dialogue }
\new Staff {
\new Voice { \music }
}
>>
}


Notation Reference: Manual syllable durations, Text.

Internal Reference: LyricText.

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

#### References for chants and psalms

Typesetting Gregorian chant in various styles of ancient notation is described in Ancient notation.

Notation reference: Ancient notation.

Snippets: Vocal music.

#### Setting a chant

Modern chant settings use modern notation with varying numbers of elements taken from ancient notation. Some of the elements and methods to consider are shown here.

Chants often use quarter notes without stems to indicate the pitch, with the rhythm being taken from the spoken rhythm of the words.

stemOff = { \override Staff.Stem #'transparent = ##t }

\relative c' {
\stemOff
a'4 b c2 |
}



Chants often omit the bar lines or use shortened or dotted bar lines to indicate pauses in the music. To omit all bar lines from all staves remove the bar line engraver completely:

\score {
\new StaffGroup <<
\new Staff {
\relative c'' {
a4 b c2 |
a4 b c2 |
a4 b c2 |
}
}
\new Staff {
\relative c'' {
a4 b c2 |
a4 b c2 |
a4 b c2 |
}
}
>>
\layout {
\context {
\Staff
\remove "Bar_engraver"
}
}
}


Bar lines can also be removed on a staff-by-staff basis:

\score {
\new ChoirStaff <<
\new Staff
\with { \remove "Bar_engraver" } {
\relative c'' {
a4 b c2 |
a4 b c2 |
a4 b c2 |
}
}
\new Staff {
\relative c'' {
a4 b c2 |
a4 b c2 |
a4 b c2 |
}
}
>>
}


To remove bar lines from just a section of music treat it as a cadenza. If the section is long you may need to insert dummy bar lines with \bar "" to show where the line should break.

a4 b c2 |
a4 b c2
a4 b c2
\bar ""
a4 b c2
a4 b c2
a4 b c2 |
a4 b c2 |


Rests or pauses in chants can be indicated by modified bar lines.

a4
b c2
a4 b c2
\bar "'"
a4 b c2
a4 b c2
\bar ":"
a4 b c2
\bar "dashed"
a4 b c2
\bar "||"


Alternatively, the notation used in Gregorian chant for pauses or rests is sometimes used even though the rest of the notation is modern. This uses a modified \breathe mark:

divisioMinima = {
\once \override BreathingSign  #'stencil = #ly:breathing-sign::divisio-minima
\once \override BreathingSign  #'Y-offset = #0
\breathe
}
divisioMaior = {
\once \override BreathingSign  #'stencil = #ly:breathing-sign::divisio-maior
\once \override BreathingSign  #'Y-offset = #0
\breathe
}
divisioMaxima = {
\once \override BreathingSign  #'stencil = #ly:breathing-sign::divisio-maxima
\once \override BreathingSign  #'Y-offset = #0
\breathe
}
finalis = {
\once \override BreathingSign  #'stencil = #ly:breathing-sign::finalis
\once \override BreathingSign  #'Y-offset = #0
\breathe
}

\score {
\relative c'' {
g2 a4 g
\divisioMinima
g2 a4 g
\divisioMaior
g2 a4 g
\divisioMaxima
g2 a4 g
\finalis
}
\layout {
\context {
\Staff
\remove "Bar_engraver"
}
}
}


Chants usually omit the time signature and often omit the clef too.

\score {
\new Staff {
\relative c'' {
a4 b c2 |
a4 b c2 |
a4 b c2 |
}
}
\layout {
\context {
\Staff
\remove "Bar_engraver"
\remove "Time_signature_engraver"
\remove "Clef_engraver"
}
}
}


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.

SopranoMusic = \relative g' {
g1 | c2 b | a1 | \bar "||"
a1 | d2 c | c b | c1 | \bar "||"
}

AltoMusic = \relative c' {
e1 | g2 g | f1 |
f1 | f2 e | d d | e1 |
}

TenorMusic = \relative a {
c1 | c2 c | c1 |
d1 | g,2 g | g g | g1 |
}

BassMusic =  \relative c {
c1 | e2 e | f1 |
d1 | b2 c | g' g | c,1 |
}

global = {
\time 2/2
}

% Use markup to center the chant on the page
\markup {
\fill-line {
\score {  % centered
<<
\new ChoirStaff <<
\new Staff <<
\global
\clef "treble"
\new Voice = "Soprano" <<
\voiceOne
\SopranoMusic
>>
\new Voice = "Alto" <<
\voiceTwo
\AltoMusic
>>
>>
\new Staff <<
\clef "bass"
\global
\new Voice = "Tenor" <<
\voiceOne
\TenorMusic
>>
\new Voice = "Bass" <<
\voiceTwo
\BassMusic
>>
>>
>>
>>
\layout {
\context {
\Score
\override SpacingSpanner
#'base-shortest-duration = #(ly:make-moment 1 2)
}
\context {
\Staff
\remove "Time_signature_engraver"
}
}
}  % End score
}
}  % End markup


Some other approaches to setting such a chant are shown in the first of the following snippets.

#### Selected Snippets

Chant or psalms notation

This form of notation is used for the chant of the Psalms, where verses aren’t always the same length.

stemOn = {
\revert Staff.Stem #'transparent
\revert Staff.Flag #'transparent
}

stemOff = {
\override Staff.Stem #'transparent = ##t
\override Staff.Flag #'transparent = ##t
}

\score {
\new Staff \with { \remove "Time_signature_engraver" }
{
\key g \minor
\stemOff a'\breve bes'4 g'4
\stemOn a'2 \bar "||"
\stemOff a'\breve g'4 a'4
\stemOn f'2 \bar "||"
\stemOff a'\breve^\markup { \italic flexe }
\stemOn g'2 \bar "||"
}
}


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.

\include "gregorian.ly"

chant = \relative c' {
\set Score.timing = ##f
f4 a2 \divisioMinima
g4 b a2 f2 \divisioMaior
g4( f) f( g) a2 \finalis
}

verba = \lyricmode {
Lo -- rem ip -- sum do -- lor sit a -- met
}

\score {
\new Staff <<
\new Voice = "melody" \chant
\new Lyrics = "one" \lyricsto melody \verba
>>
\layout {
\context {
\Staff
\remove "Time_signature_engraver"
\remove "Bar_engraver"
\override Stem #'transparent = ##t
\override Flag #'transparent = ##t
}
\context {
\Voice
\override Stem #'length = #0
}
\context {
\Score
barAlways = ##t
}
}
}


Learning Manual: Visibility and color of objects, Vocal ensembles.

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

\markup {
\fill-line {
\column {
\left-align {
\line { O come let us sing | unto the | Lord : let }
\line { us heartily rejoice in the | strength of | our }
\line { sal- | -vation. }
}
}
}
}


Other symbols may require glyphs from the fetaMusic fonts. For details, see Fonts.

tick = \markup {
\raise #1 \fontsize #-5 \musicglyph #"scripts.rvarcomma"
}
\markup {
\fill-line {
\column {
\left-align {
\line { O come let us sing \tick unto the \tick Lord : let }
\line {
us heartily rejoice in the \tick strength of \tick our
}
\line { sal \tick vation. }
}
}
}
}


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.

dot = \markup {
\raise #0.7 \musicglyph #"dots.dot"
}
tick = \markup {
\raise #1 \fontsize #-5 \musicglyph #"scripts.rvarcomma"
}
\markup {
\fill-line {
\column {
\left-align {
\line {
O come let us sing \tick unto \dot the \tick Lord : let
}
\line {
us heartily rejoice in the \tick strength of \tick our
}
\line { sal \tick vation. }
}
}
}
}


In some psalters an asterisk is used to indicate a break in a recited section instead of a comma, and stressed or slightly lengthened syllables are indicated in bold text.

dot = \markup {
\raise #0.7 \musicglyph #"dots.dot"
}
tick = \markup {
\raise #1 \fontsize #-5 \musicglyph #"scripts.rvarcomma"
}
\markup {
\fill-line {
\column {
\left-align {
\line { Today if ye will hear his voice * }
\line {
\concat { \bold hard en }
| not your | hearts : as in the pro-
}
\line { vocation * and as in the \bold day of tempt- | }
\line { -ation | in the | wilderness. }
}
}
}
}


In other psalters an accent is placed over the syllable to indicate stress.

tick = \markup {
\raise #2 \fontsize #-5 \musicglyph #"scripts.rvarcomma"
}
\markup {
\fill-line {
\column {
\left-align {
\line {
O come let us \concat {
si \combine \tick ng
}
| unto the | Lord : let
}
\line {
us heartily \concat {
rejo \combine \tick ice
}
in the | strength of | our
}
\line { sal- | -vation. }
}
}
}
}


The use of markup to center text, and arrange lines in columns is described in Formatting text.

Most of these elements are shown in one or other of the two verses in the template, see “Psalms” in Vocal ensembles.

Learning Manual: Vocal ensembles.

Notation Reference: Fonts, Formatting text.

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

Timeline = {
\time 4/4
\tempo 4=96
\partial 2
s2 | s1 | s2 \breathe s2 | s1 | s2 \bar "||" \break
s2 | s1 | s2 \breathe s2 | s1 | s2 \bar "||"
}

SopranoMusic = \relative g' {
g4 g | g g g g | g g g g | g g g g | g2
g4 g | g g g g | g g g g | g g g g | g2
}

AltoMusic = \relative c' {
d4 d | d d d d | d d d d | d d d d | d2
d4 d | d d d d | d d d d | d d d d | d2
}

TenorMusic = \relative a {
b4 b | b b b b | b b b b | b b b b | b2
b4 b | b b b b | b b b b | b b b b | b2
}

BassMusic =  \relative g {
g4 g | g g g g | g g g g | g g g g | g2
g4 g | g g g g | g g g g | g g g g | g2
}

global = {
\key g \major
}

\score {  % Start score
<<
\new PianoStaff <<  % Start pianostaff
\new Staff <<  % Start Staff = RH
\global
\clef "treble"
\new Voice = "Soprano" <<  % Start Voice = "Soprano"
\Timeline
\voiceOne
\SopranoMusic
>>  % End Voice = "Soprano"
\new Voice = "Alto" <<  % Start Voice = "Alto"
\Timeline
\voiceTwo
\AltoMusic
>>  % End Voice = "Alto"
>>  % End Staff = RH
\new Staff <<  % Start Staff = LH
\global
\clef "bass"
\new Voice = "Tenor" <<  % Start Voice = "Tenor"
\Timeline
\voiceOne
\TenorMusic
>>  % End Voice = "Tenor"
\new Voice = "Bass" <<  % Start Voice = "Bass"
\Timeline
\voiceTwo
\BassMusic
>>  % End Voice = "Bass"
>>  % End Staff = LH
>>  % End pianostaff
>>
}  % End score

\markup {
\fill-line {
""
{
\column {
\left-align {
"This is line one of the first verse"
"This is line two of the same"
"And here's line three of the first verse"
"And the last line of the same"
}
}
}
""
}
}

\paper {  % Start paper block
indent = 0     % don't indent first system
line-width = 130   % shorten line length to suit music
}  % End paper block


### 2.1.8 Ancient vocal music

Ancient vocal music is supported, as explained in Ancient notation.

Notation Reference: Ancient notation.

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

### 2.2.1 Common notation for keyboards

This section discusses notation issues that may arise for most keyboard instruments.

#### 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.
• Keyboard music can be written in parallel, as described in Writing music in parallel.
• Dynamics may be placed in a Dynamics context, between the two Staff contexts to align the dynamic marks on a horizontal line centered between the staves; see Dynamics.
• Fingerings are indicated with Fingering instructions.
• Organ pedal indications are inserted as articulations, see List of articulations.
• Vertical grid lines can be shown with Grid lines.
• Keyboard music often contains Laissez vibrer ties as well as ties on arpeggios and tremolos, described in Ties.
• Placing arpeggios across multiple voices and staves is covered in Arpeggio.
• Tremolo marks are described in Tremolo repeats.
• Several of the tweaks that can occur in keyboard music are demonstrated in Real music example.
• Hidden notes can be used to produce ties that cross voices, as shown in Other uses for tweaks.

Learning Manual: Real music example, Other uses for tweaks.

Internals Reference: PianoStaff.

Snippets: Keyboards.

#### Changing staff manually

Voices can be switched between staves manually, using the command

\change Staff = staffname


The string staffname is the name of the staff. It switches the current voice from its current staff to the staff called staffname. Typical values for staffname are "up" and "down", or "RH" and "LH".

The staff to which the voice is being switched must exist at the time of the switch. If necessary, staves should be “kept alive”, see Keeping contexts alive.

Cross-staff notes are beamed automatically:

\new PianoStaff <<
\new Staff = "up" {
<e' c'>8
\change Staff = "down"
g8 fis g
\change Staff = "up"
<g'' c''>8
\change Staff = "down"
e8 dis e
\change Staff = "up"
}
\new Staff = "down" {
\clef bass
% keep staff alive
s1
}
>>


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.

Overlapping notation can result when voices cross staves:

\new PianoStaff <<
\new Staff = "up" {
\voiceOne
% Make space for fingering in the cross-staff voice
e''2\p\< d''\>
c''1\!
}
\new Staff = "down" <<
{
\clef bass
s4. e,8\rest g,2\rest
c1
} \\ {
c8$$g c' \change Staff = "up" e' g' b'-3 a' g'$$
f'1
}
>>
>>


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.

Learning Manual: Fixing overlapping notation.

Notation Reference: Stems, Automatic beams, Keeping contexts alive.

Snippets: Keyboards.

Internals Reference: Beam, ContextChange.

#### Known issues and warnings

Beam collision avoidance does not work for automatic beams that end right before a change in staff. In this case use manual beams.

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


A \relative section that is outside of \autochange has no effect on the pitches of the music, so if necessary, put \relative inside \autochange.

If additional control is needed over the individual staves, they can be created manually with the names "up" and "down". The \autochange command will then switch its voice between the existing staves.

Note: If staves are created manually, they must be named "up" and "down".

For example, staves must be created manually in order to place a key signature in the lower staff:

\new PianoStaff <<
\new Staff = "up" {
\new Voice = "melOne" {
\key g \major
\autochange \relative c' {
g8 b a c b d c e
d8 r fis, g a2
}
}
}
\new Staff = "down" {
\key g \major
\clef bass
}
>>


Notation Reference: Changing staff manually.

Snippets: Keyboards.

Internals Reference: AutoChangeMusic.

#### Known issues and warnings

The staff switches may not end up in optimal places. For high quality output, staff switches should be specified manually.

Chords will not be split across the staves; they will be assigned to a staff based on the first note named in the chord construct.

#### Staff-change lines

Whenever a voice switches to another staff, a line connecting the notes can be printed automatically:

\new PianoStaff <<
\new Staff = "one" {
\showStaffSwitch
c1
\change Staff = "two"
b2 a
}
\new Staff = "two" {
\clef bass
s1*2
}
>>


#### Predefined commands

\showStaffSwitch, \hideStaffSwitch.

Snippets: Keyboards.

#### Cross-staff stems

Chords that cross staves may be produced using the Span_stem_engraver. Care must be taken to ensure that automatic beams do not beam the notes on one staff when it’s not required on the other.

\layout {
\context {
\PianoStaff
\consists #Span_stem_engraver
}
}

{
\new PianoStaff <<
\new Staff {
<b d'>4 r d'16\> e'8. g8 r\!
e'8 f' g'4 e'2
}
\new Staff {
\clef bass
\voiceOne
\autoBeamOff
\crossStaff { <e g>4 e, g16 a8. c8} d
\autoBeamOn
g8 f g4 c2
}
>>
}


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.

(Debussy, Les collines d’Anacapri, m. 65)

\new PianoStaff <<
\set PianoStaff.connectArpeggios = ##t
\override PianoStaff.Arpeggio #'stencil = #ly:arpeggio::brew-chord-bracket
\new Staff {
\relative c' {
\key b \major
\time 6/8
b8-.(\arpeggio fis'-.\> cis-. e-. gis-. b-.)\!\fermata^\laissezVibrer
\bar "||"
}
}
\new Staff {
\relative c' {
\clef bass
\key b \major
<<
{
<a e cis>2.\arpeggio
}
\\
{
<a, e a,>2.
}
>>
}
}
>>


Snippets: Keyboards.

Internals Reference: Stem.

### 2.2.2 Piano

This section discusses notation issues that relate most directly to the piano.

#### Piano pedals

Pianos generally have three pedals that alter the way sound is produced: sustain, sostenuto (sos.), and una corda (U.C.). Sustain pedals are also found on vibraphones and celestas.

c4\sustainOn d e g
<c, f a>1\sustainOff
c4\sostenutoOn e g c,
<bes d f>1\sostenutoOff
c4\unaCorda d e g
<d fis a>1\treCorde


There are three styles of pedal indications: text, bracket, and mixed. The sustain pedal and the una corda pedal use the text style by default while the sostenuto pedal uses mixed by default.

c4\sustainOn g c2\sustainOff
\set Staff.pedalSustainStyle = #'mixed
c4\sustainOn g c d
d\sustainOff\sustainOn g, c2\sustainOff
\set Staff.pedalSustainStyle = #'bracket
c4\sustainOn g c d
d\sustainOff\sustainOn g, c2
\bar "|."


The placement of the pedal commands matches the physical movement of the sustain pedal during piano performance. Pedalling to the final bar line is indicated by omitting the final pedal off command.

Pedal indications may be placed in a Dynamics context, which aligns them on a horizontal line.

Notation Reference: Ties.

Snippets: Keyboards.

### 2.2.3 Accordion

This section discusses notation that is unique to the accordion.

#### 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-discant symbols

Accordion discant-specific symbols are added using \markup. The vertical placement of the symbols can be tweaked by changing the \raise arguments.

discant = \markup {
\musicglyph #"accordion.discant"
}
dot = \markup {
\musicglyph #"accordion.dot"
}

\layout { ragged-right = ##t }

% 16 voets register
accBasson = ^\markup {
\combine
\discant
\raise #0.5 \dot
}

% een korig 8 en 16 voets register
accBandon = ^\markup {
\combine
\discant
\combine
\raise #0.5 \dot
\raise #1.5 \dot
}

accVCello = ^\markup {
\combine
\discant
\combine
\raise #0.5 \dot
\combine
\raise #1.5 \dot
\translate #'(1 . 0) \raise #1.5 \dot
}

% 4-8-16 voets register
accHarmon = ^\markup {
\combine
\discant
\combine
\raise #0.5 \dot
\combine
\raise #1.5 \dot
\raise #2.5 \dot
}

accTrombon = ^\markup {
\combine
\discant
\combine
\raise #0.5 \dot
\combine
\raise #1.5 \dot
\combine
\translate #'(1 . 0) \raise #1.5 \dot
\translate #'(-1 . 0) \raise #1.5 \dot
}

% eenkorig 4 en 16 voets register
accOrgan = ^\markup {
\combine
\discant
\combine
\raise #0.5 \dot
\raise #2.5 \dot
}

accMaster = ^\markup {
\combine
\discant
\combine
\raise #0.5 \dot
\combine
\raise #1.5 \dot
\combine
\translate #'(1 . 0) \raise #1.5 \dot
\combine
\translate #'(-1 . 0) \raise #1.5 \dot
\raise #2.5 \dot
}

accAccord = ^\markup {
\combine
\discant
\combine
\raise #1.5 \dot
\combine
\translate #'(1 . 0) \raise #1.5 \dot
\combine
\translate #'(-1 . 0) \raise #1.5 \dot
\raise #2.5 \dot
}

accMusette = ^\markup {
\combine
\discant
\combine
\raise #1.5 \dot
\combine
\translate #'(1 . 0) \raise #1.5 \dot
\translate #'(-1 . 0) \raise #1.5 \dot
}

accCeleste = ^\markup {
\combine
\discant
\combine
\raise #1.5 \dot
\translate #'(-1 . 0) \raise #1.5 \dot
}

accOboe = ^\markup {
\combine
\discant
\combine
\raise #1.5 \dot
\raise #2.5 \dot
}

accClarin = ^\markup {
\combine
\discant
\raise #1.5 \dot
}

accPiccolo = ^\markup {
\combine
\discant
\raise #2.5 \dot
}

accViolin = ^\markup {
\combine
\discant
\combine
\raise #1.5 \dot
\combine
\translate #'(1 . 0) \raise #1.5 \dot
\raise #2.5 \dot
}

\relative c'' {
c4 d\accBasson e f
c4 d\accBandon e f
c4 d\accVCello e f
c4 d\accHarmon e f
c4 d\accTrombon e f
\break
c4 d\accOrgan e f
c4 d\accMaster e f
c4 d\accAccord e f
c4 d\accMusette e f
c4 d\accCeleste e f
\break
c4 d\accOboe e f
c4 d\accClarin e f
c4 d\accPiccolo e f
c4 d\accViolin e f
}


Snippets: Keyboards.

### 2.2.4 Harp

This section discusses notation issues that are unique to the harp.

#### References for harps

Some common characteristics of harp music are covered elsewhere:

• The glissando is the most characteristic harp technique, Glissando.
• A bisbigliando is written as a tremelo Tremolo repeats.
• Natural harmonics are covered under Harmonics.
• For directional arpeggios and non-arpeggios, see Arpeggio.

Notation Reference: Tremolo repeats, Glissando, Arpeggio, Harmonics.

#### Harp pedals

Harps have seven strings per octave that may be sounded at the natural, flattened, or sharpened pitch. In lever harps, each string is adjusted individually, but in pedal harps every string with the same pitch name is controlled by a single pedal. From the player’s left to right, the pedals are D, C, and B on the left and E, F, G, and A on the right. The position of the pedals may be indicated with text marks:

\textLengthOn
cis1_\markup \concat \vcenter {
[D \flat C \sharp B|E \sharp F \sharp G A \flat] }
c!1_\markup \concat \vcenter {
[ C \natural ] }


or pedal diagrams:

\textLengthOn
cis1_\markup { \harp-pedal #"^v-|vv-^" }
c!1_\markup { \harp-pedal #"^o--|vv-^" }


The \harp-pedal command accepts a string of characters, where ^ is the highest pedal position (flattened pitch), - is the middle pedal position (natural pitch), v is the lowest pedal position (sharpened pitch), and | is the divider. A prefixed o will circle the following pedal symbol.

Notation Reference: Text scripts, Instrument Specific Markup.

## 2.3 Unfretted string instruments

This section provides information and references which are helpful when writing for unfretted string instruments, principally orchestral strings.

### 2.3.1 Common notation for unfretted strings

There is little specialist notation for unfretted string instruments. The music is notated on a single staff, and usually only a single voice is required. Two voices might be required for some double-stopped or divisi passages.

#### References for unfretted strings

Most of the notation which is useful for orchestral strings and other bowed instruments is covered elsewhere:

• Textual indications such as “pizz.” and “arco” are added as simple text – see Text scripts.
• Fingerings, including the thumb indication, are described in Fingering instructions.
• Double stopping is normally indicated by writing a chord, see Chorded notes. Directives for playing chords may be added, see Arpeggio.
• A template for a string quartet can be found in String quartet. Others are shown in the snippets.

Learning Manual: String quartet.

Notation Reference: Text scripts, Fingering instructions, Chorded notes, Arpeggio.

Snippets: Unfretted strings.

#### Bowing indications

Bowing indications are created as articulations, which are described in Articulations and ornamentations.

The bowing commands, \upbow and \downbow, are used with slurs as follows:

c4(\downbow d) e(\upbow f)


and the following example shows three ways in which an open A string on a violin might be indicated:

a4 \open
a^\markup { \teeny "II" }
a2^\markup { \small "sul A" }


#### Predefined commands

\downbow, \upbow, \open.

Notation Reference: Articulations and ornamentations, Slurs.

#### Harmonics

Natural harmonics

Natural harmonics can be notated in several ways. A diamond-shaped note head generally means to touch the string where you would stop the note if it were not a diamond.

d4 e4.
\harmonicsOn
d8 e e
d4 e4.
\harmonicsOff
d8 e e


Alternatively a normal note head is shown at the pitch to be sounded together with a small circle to indicate it should be played as a harmonic:

d2^\flageolet d_\flageolet


A smaller circle may be created, see the snippet list in References for unfretted strings.

Artificial harmonics

Artificial harmonics are notated with two notes, one with a normal note head indicating the stopped position and one with an open diamond note head to indicate the harmonic position.

Artificial harmonics indicated with \harmonic do not show the dots. The context property harmonicDots should be set if dots are required.

<e a\harmonic>2.  <c g'\harmonic>4
\set harmonicDots = ##t
<e a\harmonic>2.  <c g'\harmonic>4


Note: \harmonic must be placed inside a chord construct even if there is only a single note. Normally \harmonicsOn would be used in this situation.

Music Glossary: harmonics.

Notation Reference: Special note heads, References for unfretted strings.

#### Snap (Bartók) pizzicato

A snap pizzicato (also known as “Bartok pizz”) is a type of pizzicato where the string is deliberately plucked upwards (rather than sideways) such that it hits the fingerboard.

c4\snappizzicato
<c' e g>4\snappizzicato
<c' e g>4^\snappizzicato
<c, e g>4_\snappizzicato