LilyPond Notation Reference

# LilyPond — Notation Reference

This manual provides a reference for all notation that can be produced with LilyPond version 2.14.1. 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
>     }

#### See also

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

#### See also

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 beginning of a new system

This shows how to hide accidentals on tied notes at the beginning 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
>     }

#### See also

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

Learning Manual: Accidentals and key signatures.

Notation Reference: Automatic accidentals, Annotational accidentals (musica ficta), Note names in other languages.

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.

#### See also

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

#### See also

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 }

For more information about transposing instruments, see Instrument transpositions.

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

#### See also

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

#### Inversion

A music expression can be inverted with:

>     \inversion from-pitch to-pitch musicexpr

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

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

#### See also

Notation Reference: Modal transformations, Retrograde, Transpose.

#### Retrograde

A music expression can be reversed to produce its retrograde:

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

>     \new Staff {
>       \music
>       \retrograde \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.

#### See also

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

The combined operation of inversion and retrograde produce the retrograde-inversion:

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

#### See also

Notation Reference: Inversion, Retrograde, Transpose.

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

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

>       % Return to the normal clef:

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

#### See also

Notation Reference: Mensural clefs, Gregorian clefs, Default tablatures, Custom tablatures.

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

Non-traditional key signatures

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

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

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

#### See also

Music Glossary: church mode, scordatura.

Learning Manual: Accidentals and key signatures.

Snippets: Pitches.

Internals Reference: KeyChangeEvent, Key_engraver, Key_performer, KeyCancellation, KeySignature, key-cancellation-interface, key-signature-interface.

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

#### See also

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
>     s1*0^\markup { Switch to B\flat clarinet }
>     R1

>     \key bes \major
>     \transposition bes
>     c2 g

#### See also

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 <<
>       #(set-accidental-style '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:

>     #(set-accidental-style 'voice 'StaffGroup)

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" {
>           #(set-accidental-style 'default)
>           \musicA
>         }
>         \context Staff = "down" {
>           #(set-accidental-style '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:
>           #(set-accidental-style 'default 'Score)
>           \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 accidentals that reduce or reverse the direction of a previous alteration. The `modern` rule prints the same accidentals as `default`, with two exceptions 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.

#### See also

Snippets: Pitches.

Internals Reference: Accidental, Accidental_engraver, GrandStaff, PianoStaff, Staff, AccidentalSuggestion, AccidentalPlacement, accidental-suggestion-interface.

#### 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?) #{
>       #(set-accidental-style 'forget)
>       $music
>       #(set-accidental-style 'modern)
>     #})
>     {
>       #(set-accidental-style '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

Adding ambitus per voice

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''
>     }

#### See also

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.

### 1.1.4 Note heads

This section suggests ways of altering note heads.

#### Special note heads

The appearance of note heads may be altered:

>     c4 b
>     \override NoteHead #'style = #'cross
>     c4 b
>     \revert NoteHead #'style
>     a b
>     \override NoteHead #'style = #'harmonic
>     a b
>     \revert NoteHead #'style
>     c4 d e f

To see all note head styles, see Note head styles.

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

#### See also

Snippets: Pitches.

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

Internals Reference: note-event, Note_heads_engraver, Ledger_line_engraver, NoteHead, LedgerLineSpanner, note-head-interface, ledger-line-spanner-interface.

#### Easy notation note heads

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

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

#### Predefined commands

`\easyHeadsOn`, `\easyHeadsOff`.

#### Selected Snippets

Numbers as easy note heads

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

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

>     #(define Ez_numbers_engraver
>        (list
>         (cons 'acknowledgers
>               (list
>                (cons 'note-head-interface
>                      (lambda (engraver grob source-engraver)
>                        (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' {
>       \easyHeadsOn
>       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
>     }

#### See also

Notation Reference: Setting the staff size.

Snippets: Pitches.

Internals Reference: note-event, Note_heads_engraver, NoteHead, note-head-interface.

#### Shape note heads

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

>     \aikenHeads
>     c, d e f g2 a b1 c \break
>     \sacredHarpHeads
>     c,4 d e f g2 a b1 c \break
>     \southernHarmonyHeads
>     c,4 d e f g2 a b1 c \break
>     \funkHeads
>     c,4 d e f g2 a b1 c \break
>     \walkerHeads
>     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
>     \aikenHeads
>     a b c d e2 f g1 a \break
>     \aikenHeadsMinor
>     a,4 b c d e2 f g1 a \break
>     \sacredHarpHeadsMinor
>     a,2 b c d \break
>     \southernHarmonyHeadsMinor
>     a2 b c d \break
>     \funkHeadsMinor
>     a2 b c d \break
>     \walkerHeadsMinor
>     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
>       }
>     }

To see all note head styles, see Note head styles.

#### See also

Snippets: Pitches.

Notation Reference: Note head styles.

Internals Reference: note-event, Note_heads_engraver, NoteHead, note-head-interface.

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

#### See also

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 notehead with double vertical lines

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
>       \override Staff.NoteHead #'style = #'altdefault
>       c\breve | b\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 |
>     }

#### See also

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

#### See also

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

You can alter the duration of single notes, rests or chords 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 such as `*L*M/N`.

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 gis4*2/3 a4*2/3
>     % Normal durations
>     a4 a4
>     % Double the duration of chord
>     <a d>4*2
>     % Duration of quarter, appears like sixteenth
>     b16*4 c4

The duration of spacing notes 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. The spaces around the dot are required. 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.

#### See also

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 the snippets under Slurs.

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

#### See also

Music Glossary: tie, laissez vibrer.

Notation Reference: Slurs, Automatic note splitting.

Snippets: 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 {
>       \cadenzaOn
>       \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
>     }

#### See also

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

#### See also

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
>     \override TextScript #'padding = #5
>     R1^"wrong"
>     % This is the correct object name to be specified
>     \override MultiMeasureRestText #'padding = #5
>     R1^"right"

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

#### Predefined commands

`\textLengthOn`, `\textLengthOff`, `\fermataMarkup`, `\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'' {
>       % MMR - Multi-Measure Rest
>       % MMRs by default are set under the fourth line
>       R1
>       % They can be moved with an override
>       \override MultiMeasureRest #'staff-position = #-2
>       R1
>       % A value of 0 is the default position;
>       % the following trick moves the rest to the center line
>       \override MultiMeasureRest #'staff-position = #-0.01
>       R1
>       % MMRs in odd-numbered voices are under the top line
>       << { R1 } \\ { a1 } >>
>       % MMRs in even-numbered voices are under the bottom line
>       << { c1 } \\ { R1 } >>
>       % They remain separated even in empty measures
>       << { R1 } \\ { R1 } >>
>       % This brings them together even though there are two voices
>       \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
>     }

#### See also

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 time-signature-based default values for the properties `baseMoment`, `beatStructure`, and `beamExceptions`. The predefined default values for these properties can be found in ‘`scm/time-signature-settings.scm`’. The existing default values can be changed, or new default values can be added:

>     \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 Scheme pair describing the time signature.
2. `baseMomentFraction`, a Scheme pair 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"
>         }
>       }
>     }

#### Predefined commands

`\numericTimeSignature`, `\defaultTimeSignature`.

#### Selected Snippets

Changing the time signature without affecting the beaming

The `\time` command sets the properties `timeSignatureFraction`, `beatLength`, `beatGrouping` and `measureLength` in the `Timing` context, which is normally aliased to `Score`. Changing the value of `timeSignatureFraction` causes the new time signature symbol to be printed without changing any of the other properties:

>     \markup {
>       This snippet is deprecated as of 2.13.5 and will be removed in 2.14
>     }

Compound time signatures

Odd 20th century time signatures (such as "5/8") can often be played as compound time signatures (e.g. "3/8 + 2/8"), which combine two or more inequal metrics. LilyPond can make such music quite easy to read and play, by explicitly printing the compound time signatures and adapting the automatic beaming behavior. (Graphic measure grouping indications can also be added; see the appropriate snippet in this database.)

>     #(define ((compound-time one two num) grob)
>        (grob-interpret-markup grob
>                               (markup #:override '(baseline-skip . 0) #:number
>                                       (#:line ((#:column (one num))
>                                                #:vcenter "+"
>                                                (#:column (two num)))))))

>     \relative c' {
>       \override Staff.TimeSignature #'stencil = #(compound-time "2" "3" "8")
>       \time 5/8
>       \set Staff.beatStructure = #'(2 3)
>       c8 d e fis gis
>       c8 fis, gis e d
>       c8 d e4 gis8
>     }

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

#### See also

Music Glossary: time signature

Notation Reference: Mensural time signatures, Time administration.

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.

#### See also

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 upbeat, are entered using the `\partial` command, with the syntax

>     \partial duration

where `duration` is the rhythmic length of the remaining interval of the current measure before the start of the next.

>     \partial 4 e4 |
>     a2. c,4 |

The partial measure can be any duration less than the full measure:

>     \partial 8*3 c8 d e |
>     a2. c,4 |

Internally, `\partial duration` is translated into:

>     \set Timing.measurePosition -duration

For example, `\partial 8*3` becomes:

>     \set Timing.measurePosition = #(ly:make-moment -3 8)

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

#### See also

Music Glossary: anacrusis.

Notation Reference: Grace notes.

Snippets: Rhythms.

Internal Reference: Timing_translator.

#### Known issues and warnings

The `\partial` command is intended to be used only at the beginning of a piece. If you use it after the beginning, some odd warnings or effects may occur, in this case use `\set Timing.measurePosition` instead.

#### Unmetered music

Bar lines and bar numbers are calculated automatically. For unmetered music (some cadenzas, for example), this is not desirable. To turn off automatic calculation of bar lines and bar numbers, use the command `\cadenzaOn`, and use `\cadenzaOff` to turn them on again.

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

Bar numbering is resumed at the end of the cadenza as if the cadenza were not there:

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

Automatic beaming is disabled by `\cadenzaOn` and enabled by `\cadenzaOff`. Therefore, all beaming in cadenzas must be entered manually (Manual beams).

>     \repeat unfold 8 { c8 }
>     \cadenzaOn
>     \repeat unfold 5 { c8 }
>     \bar"|"
>     \cadenzaOff
>     \repeat unfold 8 { c8 }

Note that these predefined commands affect all staves in the score, even when they are placed in just one `Voice` context. To change this, move the `Timing_translator` from the `Score` context to the `Staff` context, as shown in Polymetric notation.

#### Predefined commands

`\cadenzaOn`, `\cadenzaOff`.

#### See also

Music Glossary: cadenza.

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

Snippets: Rhythms.

#### Known issues and warnings

LilyPond will insert line breaks and page breaks only at a bar line. Unless the unmetered music ends before the end of the staff line, you will need to insert invisible bar lines with

>     \bar ""

to indicate where breaks can occur.

You should explicitly create a `Voice` context when starting a piece with `\cadenzaOn`, otherwise strange errors may occur.

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

#### Polymetric notation

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

Staves with different time signatures, equal measure lengths

This notation can be created by setting a common time signature for each staff but replacing the symbol manually by setting `timeSignatureFraction` to the desired fraction and scaling the printed durations in each staff to the common time signature; see Time signature. The scaling is done with `\scaleDurations`, which is used in a similar way to `\times`, but does not create a tuplet bracket; see Scaling durations.

In this 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, as 2/3 * 9/8 = 3/4, and in the third staff, shown durations are multiplied by 3/5, as 3/5 * 10/8 = 3/4. It will often be necessary to insert beams manually, as the duration scaling affects the autobeaming rules.

>     \relative c' <<
>       \new Staff {
>         \time 3/4
>         c4 c c |
>         c 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. c4. \times 2/3 { c8[ c c] } c4
>         }
>       }
>     >>

Staves with different time signatures, unequal bar lengths

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

#### Selected Snippets

Compound time signatures

Odd 20th century time signatures (such as "5/8") can often be played as compound time signatures (e.g. "3/8 + 2/8"), which combine two or more inequal metrics. LilyPond can make such music quite easy to read and play, by explicitly printing the compound time signatures and adapting the automatic beaming behavior. (Graphic measure grouping indications can also be added; see the appropriate snippet in this database.)

>     #(define ((compound-time one two num) grob)
>        (grob-interpret-markup grob
>                               (markup #:override '(baseline-skip . 0) #:number
>                                       (#:line ((#:column (one num))
>                                                #:vcenter "+"
>                                                (#:column (two num)))))))

>     \relative c' {
>       \override Staff.TimeSignature #'stencil = #(compound-time "2" "3" "8")
>       \time 5/8
>       \set Staff.beatStructure = #'(2 3)
>       c8 d e fis gis
>       c8 fis, gis e d
>       c8 d e4 gis8
>     }

#### See also

Music Glossary: polymetric, polymetric time signature, meter.

Notation Reference: 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 "Note_heads_engraver"
>       \consists "Completion_heads_engraver"
>       \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.

#### See also

Music Glossary: tie

Learning Manual: Engravers explained, Adding and removing engravers.

Snippets: Rhythms.

Internals Reference: Note_heads_engraver, Completion_heads_engraver, Rest_engraver, Completion_rest_engraver, Forbid_line_break_engraver.

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

#### See also

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.

Note: Using `\partcombine` with `\autoBeamOff` can produce unintended results. See the snippet below 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 |
>       }
>     }

#### See also

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.

#### Setting automatic beam behavior

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 the one over numerator 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 |

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

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 (3) due to beamExceptions
>     \repeat unfold 6 {a8} |
>     % This will beam (1 1 1) due to beatLength
>     \set Timing.beamExceptions = #'()
>     \repeat unfold 6 {a8}

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]
>     }

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, the Scheme function `set-time-signature` can be used to both set the time signature and establish the beat structure. `set-time-signature`, takes three arguments: the number of beats, the beat length, and the internal grouping of beats in the measure. `\time` and `set-time-signature` both apply to the `Timing` context, so they 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) |
>         #(set-time-signature 9 8 '(4 5))
>         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

Beat structure 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
>             }
>           >>
>         }
>       >>
>     }

#### See also

Installed Files: ‘`scm/beam-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
>         }
>       >>
>     }

#### See also

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

#### See also

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

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

#### See also

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

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

#### See also

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.

#### See also

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.

#### See also

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

Installed Files: ‘`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.

Snippets: Rhythms.

Internals Reference: MarkEvent, Mark_engraver, RehearsalMark.

### 1.2.6 Special rhythmic concerns

#### Grace notes

Grace notes are ornaments that are written out. Grace notes are printed in a smaller font and take up no logical time in a measure.

>     c4 \grace c16 c4
>     \grace { c16[ d16] } c2

LilyPond also supports two special types of grace notes, the acciaccatura – an unmeasured grace note indicated by a slurred small note with a slashed stem – and the appoggiatura, which takes a fixed fraction of the main note and appears in small print without a slash.

>     \grace c8 b4
>     \acciaccatura d8 c4
>     \appoggiatura e8 d4
>     \acciaccatura { g16[ f] } e4

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 Stem #'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 = {
>       s1*0(
>       \override Stem #'stroke-style = #"grace"
>       \slurDashed
>     }

>     stopAcciaccaturaMusic = {
>       \revert Stem #'stroke-style
>       \slurSolid
>       s1*0)
>     }

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

#### See also

Music Glossary: grace notes, acciaccatura, appoggiatura.

Notation Reference: 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'] } }

See Scaling durations.

#### Aligning to cadenzas

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

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

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

>     \new GrandStaff <<
>       \new Staff {
>         \MyCadenza c'1
>         \MyCadenza c'1
>       }
>       \new Staff {
>         #(ly:export (mmrest-of-length MyCadenza))
>         c'1
>         #(ly:export (skip-of-length MyCadenza))
>         c'1
>       }
>     >>

#### See also

Music Glossary: cadenza.

Snippets: Rhythms.

#### Time administration

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

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

`currentBarNumber`

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

`measureLength`

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

`measurePosition`

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

`timing`

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

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

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

#### See also

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

#### See also

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 #'staff-padding = #2.0
>       \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 `'hairpin`, and other possible values include `'line`, `'dashed-line` and `'dotted-line`.

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

#### See also

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

Learning Manual: Articulation and dynamics.

Notation Reference: Direction and placement, New dynamic marks, What goes into the MIDI output?, Controlling MIDI 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.

#### See also

Notation Reference: Formatting text, Selecting font and font size, What goes into the MIDI output?, Controlling MIDI dynamics.

Snippets: Expressive marks.

Extend: Markup construction in Scheme.

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

#### See also

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

#### See also

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

#### See also

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

The dash `-` immediately preceding the `\bendAfter` command is required when writing falls and doits.

#### Selected Snippets

Adjusting the shape of falls and doits

The `shortest-duration-space` property may have to 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
>     }

#### See also

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 attaching `\glissando` to a note:

>     g2\glissando g'
>     c2\glissando 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
>       \cadenzaOn
>       c4\glissando
>       \hideNotes
>       c,,4
>       \unHideNotes
>       \cadenzaOff
>       \bar "|"
>     }

#### See also

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

#### See also

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

#### See also

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.

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

Adding volta brackets to additional staves

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

#### See also

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 = #(list(list 'volta voltaAdLib) 'start-repeat)
>       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
>     }

#### See also

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

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 the first alternatives are applied, LilyPond will ignore the remaining alternatives which will not be 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

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

#### See also

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

#### See also

Music Glossary: percent repeat, simile.

Snippets: Repeats.

Internals Reference: RepeatSlash, RepeatSlashEvent, DoubleRepeatSlash, PercentRepeat, PercentRepeatCounter, PercentRepeatedMusic, Percent_repeat_engraver, DoublePercentEvent, DoublePercentRepeat, DoublePercentRepeatCounter, Double_percent_repeat_engraver, Slash_repeat_engraver.

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

#### See also

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

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

For more information about chords, see Chord notation.

#### See also

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 c4 q2 r8 q8

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 c4 q2 r8 q8

#### See also

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.

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.

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

#### See also

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.

#### Single-staff polyphony

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

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

#### See also

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

#### See also

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:

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

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

>     <<
>       {
>         \mergeDifferentlyHeadedOn
>         \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

Additional voices to avoid collisions

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

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

#### See also

Music Glossary: polyphony.

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

Snippets: Simultaneous notes.

Internals Reference: NoteColumn, NoteCollision, RestCollision.

#### Automatic part combining

Automatic part combining is used to merge two parts of music onto a staff. It is aimed at typesetting orchestral scores. When the two parts are identical for a period of time, only one is shown. In places where the two parts differ, they are typeset as separate voices, and stem directions are set automatically. Also, solo and a due parts are identified and marked by default.

The syntax for part combining is:

>     \partcombine musicexpr1 musicexpr2

The following example demonstrates the basic functionality of the part combiner: putting parts on one staff and setting stem directions and polyphony. 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
>       d c b a
>       g f( e) d
>       e1
>     }

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

The notes in the third measure appear only once, although they were specified in both parts. Stem, slur, and tie directions are set automatically, depending whether there is a solo or unison. When needed in polyphony situations, the first part (with context called `one`) always 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 by default with the text “a2”.

Both arguments to `\partcombine` will be interpreted as `Voice` contexts. If using relative octaves, `\relative` should be specified for both music expressions, i.e.,

>     \partcombine
>       \relative … musicexpr1
>       \relative … musicexpr2

A `\relative` section that is outside of `\partcombine` has no effect on the pitches of `musicexpr1` and `musicexpr2`.

In professional scores, voices are often kept apart for long periods, even if one or two notes actually coincide and could 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. For this reason, the `\partcombine` function can be overriden with the following commands:

- `\partcombineApart`, `\partcombineApartOnce`: Keep the notes as two separate voices, even if they can be combined to a chord or unison.
- `\partcombineChords`, `\partcombineChordsOnce`: Combine the notes to a chord.
- `\partcombineUnisono`, `\partcombineUnisonoOnce`: The two voices are unison.
- `\partcombineSoloI`, `\partcombineSoloIOnce`: Show only voice one and mark it as solo.
- `\partcombineSoloII`, `\partcombineSoloIIOnce`: Show only voice two and mark it as solo.
- `\partcombineAutomatic`, `\partcombineAutomaticOnce`: Ends the effect of the special commands above, and returns to the default part combining mechanism.

All commands ending in `...Once` apply only to the following note.

>     instrumentOne = \relative c' {
>       \partcombineApart c2^"apart" e |
>       \partcombineAutomatic e^"auto" e |
>       \partcombineChords e'^"chord" e |
>       \partcombineAutomatic c^"auto" c |
>       \partcombineApart c^"apart" \partcombineChordsOnce e^"chord once" |
>       c 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"
>       \set Staff.aDueText = #"together"
>       \partcombine
>         \relative c'' {
>           g4 g r r
>           a2 g
>         }
>         \relative c'' {
>           r4 r a( b)
>           a2 g
>         }
>     >>

#### See also

Music Glossary: a due, part.

Notation Reference: Writing parts.

Snippets: Simultaneous notes.

Internals Reference: PartCombineMusic, Voice.

#### Known issues and warnings

`\partcombine` can only accept two voices.

When `printPartCombineTexts` is set, if the two voices play the same notes on and off, the part combiner may typeset `a2` more than once in a measure.

`\partcombine` cannot be inside `\times`.

`\partcombine` cannot be inside `\relative`.

Internally, the `\partcombine` interprets both arguments as `Voice`s and decides when the parts can be combined. When they have different durations they cannot be combined and are given the names `one` and `two`. Consequently, if the arguments switch to differently named Voice contexts, the events in those will be ignored. Likewise, partcombining isn’t designed to work with lyrics; when one of the voices is explicitly named in order to attach lyrics to it, the partcombining stops working.

`\partcombine` only observes onset times of notes. It cannot determine whether a previously started note is playing or not, leading to various problems.

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

#### See also

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.

#### See also

Music Glossary: staff, staves.

Notation Reference: Creating contexts, Percussion staves, Showing melody rhythms, Default tablatures, Pre-defined contexts, Staff symbol, Gregorian chant contexts, Mensural contexts, Defining new contexts.

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 `ChoirStaffGroup` 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 } >> }
>       >>
>     }

#### See also

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

#### See also

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

#### See also

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 lines of a staff belong to the `StaffSymbol` grob. `StaffSymbol` properties can be modified to change the appearance of a staff, but they must be modified before the staff is created.

The number of staff lines may be changed. The clef position and the position of middle C may need to be modified to fit the new staff. For an explanation, refer to the snippet section in Clef.

>     \new Staff \with {
>       \override StaffSymbol #'line-count = #3
>     }
>     { d4 d d d }

Staff line thickness can be modified. The thickness of ledger lines and stems are also affected, since they depend on staff line thickness.

>     \new Staff \with {
>       \override StaffSymbol #'thickness = #3
>     }
>     { e4 d c b }

Ledger line thickness can be set independently of staff line thickness. In the example the two numbers are factors multiplying the staff line thickness and the staff line spacing. The two contributions are added to give the ledger line thickness.

>     \new Staff \with {
>       \override StaffSymbol #'ledger-line-thickness = #'(1 . 0.2)
>     }
>     { e4 d c b }

The distance between staff lines can be changed. This setting affects the spacing of ledger lines as well.

>     \new Staff \with {
>       \override StaffSymbol #'staff-space = #1.5
>     }
>     { a4 b c d }

Further details about the properties of `StaffSymbol` can be found in staff-symbol-interface.

Modifications to staff properties in the middle of a score can be placed between `\stopStaff` and `\startStaff`:

>     c2 c
>     \stopStaff
>     \override Staff.StaffSymbol #'line-count = #2
>     \startStaff
>     b2 b
>     \stopStaff
>     \revert Staff.StaffSymbol #'line-count
>     \startStaff
>     a2 a

In general, `\startStaff` and `\stopStaff` can be used to stop or start a staff in the middle of a score.

>     c4 b a2
>     \stopStaff
>     b4 c d2
>     \startStaff
>     e4 d c2

#### Predefined commands

`\startStaff`, `\stopStaff`.

#### Selected Snippets

Making some staff lines thicker than the others

For pedagogical 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'
>     }

#### See also

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 {
>               \override TextScript #'padding = #3
>               c8[^"ossia above" d e d e f]
>             }
>           }
>         >>
>       }
>     >>

#### See also

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

#### See also

Music Glossary: Frenched staff.

Learning Manual: Visibility and color of objects.

Notation Reference: Changing context default settings, Staff symbol, Ossia staves, Hidden notes, Invisible rests, Visibility 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
>     \override NoteHead #'no-ledgers = ##t

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.

>     \set Staff.instrumentName = #"Violin "
>     \set Staff.shortInstrumentName = #"Vln "
>     c4.. g'16 c4.. g'16
>     \break
>     c1

Markup mode can be used to create more complicated instrument names:

>     \set Staff.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 {
>         \set Staff.instrumentName = #"Flute"
>         f2 g4 f
>       }
>       \new Staff {
>         \set Staff.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.

>     \layout {
>       indent = 3.0\cm
>       short-indent = 1.5\cm
>     }

>     \relative c'' <<
>       \new Staff {
>         \set Staff.instrumentName = #"Alto Flute in G"
>         \set Staff.shortInstrumentName = #"Fl."
>         f2 g4 f \break
>         g4 f g2
>       }
>       \new Staff {
>         \set Staff.instrumentName = #"Clarinet"
>         \set Staff.shortInstrumentName = #"Clar."
>         c,4 b c2 \break
>         c2 b4 c
>       }
>     >>

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.

Instrument names may be changed in the middle of a piece. However, remember that `instrumentName` will not be displayed in the middle of the piece, as it only appears on the first staff:

>     \set Staff.instrumentName = #"First"
>     \set Staff.shortInstrumentName = #"one"
>     c1 c c c \break
>     c1 c c c \break
>     \set Staff.instrumentName = #"Second"
>     \set Staff.shortInstrumentName = #"two"
>     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
>     }

#### See also

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

>     \addQuote "flute" { \fluteNotes }

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

>     \addQuote "flute" { \fluteNotes }

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

>     \addQuote "clarinet" { \clarinetNotes }

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

>     \addQuote "flute" { \fluteNotes }

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

#### Selected Snippets

Quoting another voice with transposition

Quotations take into account the transposition of both source and target. In this example, all instruments play sounding middle C; the target is an instrument in F. The target part may be transposed using `\transpose`. In this case, all the pitches (including the quoted ones) are transposed.

>     \addQuote clarinet {
>       \transposition bes
>       \repeat unfold 8 { d'16 d' d'8 }
>     }

>     \addQuote sax {
>       \transposition es'
>       \repeat unfold 16 { a8 }
>     }

>     quoteTest = {
>       % french horn
>       \transposition f
>       g'4
>       << \quoteDuring #"clarinet" { \skip 4 } s4^"clar." >>
>       << \quoteDuring #"sax" { \skip 4 } s4^"sax." >>
>       g'4
>     }

>     {
>       \set Staff.instrumentName =
>         \markup {
>           \center-column { Horn \line { in F } }
>         }
>       \quoteTest
>       \transpose c' d' << \quoteTest s4_"up a tone" >>
>     }

Quoting another voice

The `quotedEventTypes` property determines the music event types which should be quoted. The default value is `(note-event rest-event tie-event beam-event tuplet-span-event)`, which means that only the notes, rests, ties, beams and tuplets of the quoted voice will appear in the `\quoteDuring` expression. In the following example, a 16th rest is not quoted since `rest-event` is not in `quotedEventTypes`.

For a list of event types, consult the “Music classes” section of the Internals Reference.

>     quoteMe = \relative c' {
>       fis4 r16 a8.-> b4\ff c
>     }
>     \addQuote quoteMe \quoteMe

>     original = \relative c'' {
>       c8 d s2
>       \once \override NoteColumn #'ignore-collision = ##t
>       es8 gis8
>     }

>     <<
>       \new Staff {
>         \set Staff.instrumentName = #"quoteMe"
>         \quoteMe
>       }
>       \new Staff {
>         \set Staff.instrumentName = #"orig"
>         \original
>       }
>       \new Staff \relative c'' <<
>         \set Staff.instrumentName = #"orig+quote"
>         \set Staff.quotedEventTypes =
>           #'(note-event articulation-event)
>         \original
>         \new Voice {
>           s4
>           \set fontSize = #-4
>           \override Stem #'length-fraction = #(magstep -4)
>           \quoteDuring #"quoteMe" { \skip 2. }
>         }
>       >>
>     >>

#### See also

Notation Reference: Instrument transpositions, Using tags.

Snippets: Staff notation.

Internals Reference: Music classes, QuoteMusic, Voice.

Installed Files: ‘`scm/define-event-classes.scm`’.

#### Known issues and warnings

Only the contents of the first `Voice` occurring in an `\addQuote` command will be considered for quotation, so `music` cannot contain `\new` and `\context Voice` statements that would switch to a different Voice.

Quoting grace notes is broken and can even cause LilyPond to crash.

Quoting nested triplets may result in poor notation.

In earlier versions of LilyPond (pre 2.11), `addQuote` was written entirely in lower-case letters: `\addquote`.

#### Formatting cue notes

The previous section explains how to create quotations. The `\cueDuring` command is a more specialized form of `\quoteDuring`, being particularly useful for inserting cue notes into a part. The syntax is as follows:

>     \cueDuring #partname #voice music

This command copies only the notes and rests from the corresponding measures from `partname` into a `CueVoice` context. The `CueVoice` is created implicitly, and occurs simultaneously with `music`, which creates a polyphonic situation. The `voice` argument determines whether the cue notes should be notated as a first or second voice; `UP` corresponds to the first voice, and `DOWN` corresponds to the second.

>     oboe = \relative c'' {
>       r2 r8 d16(\f f e g f a)
>       g8 g16 g g2.
>     }
>     \addQuote "oboe" { \oboe }

>     \new Voice \relative c'' {
>       \cueDuring #"oboe" #UP { R1 }
>       g2 c,
>     }

In the above example, the `Voice` context had to be explicitly declared, or else the entire music expression would belong to the `CueVoice` context.

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.

>     oboe = \relative c'' {
>       r2 r8 d16(\f f e g f a)
>       g8 g16 g g2.
>     }
>     \addQuote "oboe" { \oboe }

>     \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,
>     }

Markup can be used to show the name of the quoted instrument. Also, if the cue notes require a change in clef, the original clef should be restored at the end of the cue notes.

>     flute = \relative c'' {
>       r2. c4 d8 c d e fis2 g2 d2
>     }
>     bassoon = \relative c {
>       \clef bass
>       R1
>       \clef treble
>       s1*0^\markup { \tiny "flute" }
>       \cueDuring #"flute" #UP { R1 }
>       \clef bass
>       g4. b8 d2
>     }
>     \addQuote "flute" { \flute }
>     \new Staff {
>       \bassoon
>     }

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.

>     flute = \relative c'' {
>       r2. c4 d8 c d e fis2 g2 d2
>     }
>     bassoon = \relative c {
>       \clef bass
>       R1
>       \tag #'part {
>         \clef treble
>         s1*0^\markup { \tiny "flute" }
>       }
>       \cueDuring #"flute" #UP { R1 }
>       \tag #'part \clef bass
>       g4. b8 d2
>     }
>     \addQuote "flute" { \flute }

>     \new Staff {
>       \bassoon
>     }
>     \new StaffGroup <<
>       \new Staff {
>         \flute
>       }
>       \new Staff {
>         \removeWithTag #'part { \killCues { \bassoon } }
>       }
>     >>

Alternatively, Clef changes and instrument labels can be collected into an instrument definition for repeated use, using `\addInstrumentDefinition` described in Instrument names.

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.

>     piccolo = \relative c''' {
>       \clef "treble^8"
>       R1
>       c8 c c e g2
>       c4 g g2
>     }
>     bassClarinet = \relative c' {
>       \key d \major
>       \transposition bes,
>       d4 r a r
>       \transposedCueDuring #"piccolo" #UP d { R1 }
>       d4 r a r
>     }

>     \addQuote "piccolo" { \piccolo }

>     <<
>       \new Staff \piccolo
>       \new Staff \bassClarinet
>     >>

A `CueVoice` context may be created explicitly if notes of a smaller size are required, for example to set an alternative sequence of notes more suitable for a higher or lower voice.

    \time 12/8
    \key ees \major
    g4 ees8 f4 g8
    \stemDown
    <<
      { d4. bes4 c8 }
      \new CueVoice
      { g'4. f4 ees8 }
    >>
    \stemUp
    d2. d2.

#### See also

Notation Reference: Instrument transpositions, Instrument names, 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.

## 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
>     \override NoteHead #'font-size = #-4
>     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`.

#### See also

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
>       \override Fingering #'staff-padding = #'()
>       <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
>       \override Fingering #'add-stem-support = ##t
>       <f c'-5>8
>       \override StringNumber #'add-stem-support = ##t
>       <f c'\5>8
>       \override StrokeFinger #'add-stem-support = ##t
>       <f c'-\rightHandFinger #2 >8
>     }

#### See also

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

Notation objects which are attached to invisible notes are still visible.

>     c4( d)
>     \hideNotes
>     e4(\p f)--

#### Predefined commands

`\hideNotes`, `\unHideNotes`.

#### See also

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

#### See also

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

#### See also

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

#### See also

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

#### See also

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

#### See also

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

#### See also

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.

For more information about the relative ordering of text scripts and articulations, see Placement of objects.

#### Predefined commands

`\textLengthOn`, `\textLengthOff`.

#### See also

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

#### See also

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 "↓"
>       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"
>         }
>       }
>     }

#### See also

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`, `\markuplines`.

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

#### See also

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.

#### See also

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 size of the characters can also be altered in different ways:

- the font size can be set to predefined standard sizes,
- the font size can be set to an absolute value,
- the font size can also be changed relatively to its previous value.

The following example demonstrates these three methods:

>     f1_\markup {
>       \tiny espressivo
>       \large e
>       \normalsize intenso
>     }
>     a^\markup {
>       \fontsize #5 Sinfonia
>       \fontsize #2 da
>       \fontsize #3 camera
>     }
>     bes^\markup { (con
>       \larger grande
>       \smaller emozione
>       \magnify #0.6 { e sentimento } )
>     }
>     d c2 r8 c bes a g1

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

#### See also

Notation Reference: Font, New dynamic marks, Manual repeat marks, Fonts.

Snippets: Text.

Internals Reference: TextScript.

Installed Files: ‘`scm/define-markup-commands.scm`’.

#### 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 {
>           \huge \smallCaps "The Mikado"
>           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 {
>           (Calle de Granada.  Fachada de la casa de Carmela
>           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.

#### See also

Learning Manual: Moving objects.

Notation Reference: Align, Text marks.

Snippets: Text.

Internals Reference: TextScript.

Installed Files: ‘`scm/define-markup-commands.scm`’.

#### 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-markup #2 "THE UNANSWERED QUESTION"
>         \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"
>       }
>       \pad-around #3
>           "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)
>           \arrow-head #Y #DOWN ##f
>       }
>     }

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.

#### See also

Notation Reference: Graphic, Editorial annotations, Align.

Snippets: Text.

Internals Reference: TextScript.

Installed Files: ‘`scm/define-markup-commands.scm`’, ‘`scm/stencil.scm`’.

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

#### See also

Notation Reference: Music, The Feta font, Fonts explained.

Snippets: Text.

Internals Reference: TextScript.

Installed Files: ‘`scm/define-markup-commands.scm`’, ‘`scm/fret-diagrams.scm`’, ‘`scm/harp-pedals.scm`’.

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

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

#### See also

Notation Reference: Text markup list commands,

Snippets: Text.

Extending: New markup list command definition.

Internals Reference: TextScript.

Installed Files: ‘`scm/define-markup-commands.scm`’.

#### Predefined commands

`\markuplines`.

### 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)
>         \lookup #"noteheads.s0petrucci"
>       }
>     }

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.

#### See also

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

#### See also

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

#### See also

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.

#### See also

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

but instead use

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

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

#### See also

Learning Manual: Songs.

Notation Reference: Automatic syllable durations, Fonts, Formatting text, Input modes, Manual syllable durations, Text encoding.

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.

#### See also

Learning Manual: Aligning lyrics to a melody.

Notation Reference: Contexts explained, Automatic syllable durations. Stanzas, Manual syllable durations, Dialogue over music, Manual syllable durations.

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 }
>     \addlyrics { LYRICS }

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

#### See also

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

#### See also

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 code the tilde symbol (`~`) to get a lyric tie. The lyric tie is implemented with the Unicode character U+203F, so be sure to use a font for this glyph which actually contains it. Freely available fonts with a lyric tie are, for example, ‘FreeSerif’ (a Times clone), ‘DejaVuSans’ (but not ‘DejaVuSerif’), or ‘TeXGyreSchola’ (a Century Schoolbook clone).

>     {
>       \time 3/4
>       \relative c' { c2 e4 g2 e4 }
>       \addlyrics { gran- de_a- mi- go }
>       \addlyrics { pu- "ro y ho-" nes- to }
>       \addlyrics { pu- ro~y~ho- nes- to }
>     }

#### See also

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 __
  >       }
  >     >>

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

  Note that this method cannot be used to indicate two melismata if the first one is immediately followed by another.

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

#### See also

Musical Glossary: melisma.

Learning Manual: Aligning lyrics to a melody.

Notation Reference: Aligning lyrics to a melody, Automatic syllable durations, Setting automatic beam behavior, Stanzas with different rhythms.

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

#### See also

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

#### See also

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)
>     	   (padding . 2))
>         }
>         \context {
>           \Staff
>           \override VerticalAxisGroup #'staff-staff-spacing =
>             #'((basic-distance . 0)
>     	   (minimum-distance . 2)
>     	   (padding . 2))
>         }
>       }
>     }

#### See also

Learning Manual: Vocal ensembles.

Notation Reference: Aligning contexts, 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
>     }
>     \addlyrics {
>       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
>       }
>       \addlyrics {
>       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 cam 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
>     }
>     \addlyrics {
>       \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
>       }
>     }

#### Lyrics and repeats

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

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

#### See also

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

#### Adding stanza numbers

Stanza numbers can be added by setting `stanza`, e.g.,

>     \new Voice {
>       \time 3/4 g2 e4 a2 f4 g2.
>     } \addlyrics {
>       \set stanza = #"1. "
>       Hi, my name is Bert.
>     } \addlyrics {
>       \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.
>     } \addlyrics {
>       \set vocalName = #"Bert "
>       Hi, my name is Bert.
>     } \addlyrics {
>       \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' {
>       c 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."
>             }
>           }
>           \hspace #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;
>             % if they are still too close, add more " " pairs
>             % until the result looks good
>          \column {
>           \line { \bold "4."
>             \column {
>               "This is verse four."
>               "It has two lines."
>             }
>           }
>           \hspace #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
>       }
>     }

#### See also

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:

- For constructing the staff layout, see Displaying staves.
- For writing piano music, see Keyboard and other multi-staff instruments.
- For writing the lyrics to a melody line, see Common notation for vocal music.
- For placing the lyrics, see Placing lyrics vertically.
- For entering stanzas, see Stanzas.
- Songs are frequently printed with the chording indicated by chord names above the staves. This is described in Displaying chords.
- To print fret diagrams of the chords for guitar accompaniment or accompaniment by other fretted instruments, see “Fret diagram markups” in Common notation for fretted strings.

#### See also

Learning Manual: Songs.

Notation Reference: Common notation for vocal music, Displaying chords, Displaying staves, Keyboard and other multi-staff instruments, Placing lyrics vertically, Stanzas.

Snippets: Vocal music.

#### Lead sheets

Lead sheets may be printed by combining vocal parts and ‘chord mode’; this syntax is explained in Chord notation.

#### Selected Snippets

Simple lead sheet

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 __ }
>     >>

#### See also

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 `Voice`s).

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

#### See also

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

#### See also

Notation Reference: Changing spacing, Displaying spacing, Fitting music onto fewer pages, Page layout, Score layout, Separating systems, Setting the staff size, Using an extra voice for breaks, Vertical spacing.

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

#### See also

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 and stage directions can be inserted with markup. See Text. Extensive stage directions can be inserted with a section of stand-alone markup between two `\score` blocks. See Separate text.

#### See also

Musical Glossary: Frenched score, Frenched staves, transposing instrument.

Notation Reference: Grouping staves, Hiding staves, Instrument transpositions, Nested staff groups, Page layout, Separating systems, Transpose, Writing parts, Writing text.

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

>     \addInstrumentDefinition #"melchior"
>       #`((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
>     }

#### See also

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
>     }
>     \addQuote "flute" { \flute }

>     pianoRH = \relative c'' {
>       c4. g8
>       % position name of cue-ing instrument just before the cue notes,
>       % and above the staff
>       s1*0^\markup { \right-align { \tiny "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
>     }
>     \addQuote "clarinet" { \clarinet }

>     pianoRH = \relative c'' {
>       \transposition c'
>       % position name of cue-ing instrument below the staff
>       s1*0_\markup { \right-align { \tiny "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
>            s1*0-\markup { \tiny $name }
>            $music
>          }
>        #})

>     flute = \relative c'' {
>       \transposition c'
>       s4 s4 e g
>     }
>     \addQuote "flute" { \flute }

>     clarinet = \relative c' {
>       \transposition bes
>       fis4 d d c
>     }
>     \addQuote "clarinet" { \clarinet }

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

#### See also

Musical Glossary: cue-notes.

Notation Reference: Aligning objects, Direction and placement, Formatting cue notes, Quoting other voices, Using music functions.

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 `\break`s 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 }
>         }
>       >>
>     }

#### See also

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.

#### See also

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 |
>     \cadenzaOn
>     a4 b c2
>     a4 b c2
>     \bar ""
>     a4 b c2
>     a4 b c2
>     \cadenzaOff
>     a4 b c2 |
>     a4 b c2 |

Rests or pauses in chants can be indicated by modified bar lines.

>     a4
>     \cadenzaOn
>     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 }
>     stemOff = { \override Staff.Stem #'transparent = ##t }

>     \score {
>       \new Staff \with { \remove "Time_signature_engraver" }
>       {
>         \key g \minor
>         \cadenzaOn
>         \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
>         }
>         \context {
>           \Voice
>           \override Stem #'length = #0
>         }
>         \context {
>           \Score
>           barAlways = ##t
>         }
>       }
>     }

#### See also

Learning Manual: Visibility and color of objects, Vocal ensembles.

Notation Reference: Ancient notation, Bar lines, Modifying context plug-ins, Typesetting Gregorian chant, Unmetered music, Visibility of objects.

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

#### See also

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.

#### See also

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.

#### See also

Learning Manual: Real music example, Other uses for tweaks.

Notation Reference: Grouping staves, Instrument names, Collision resolution, Writing music in parallel, Fingering instructions, List of articulations, Grid lines, Ties, Arpeggio, Tremolo repeats.

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
>         \once\override DynamicLineSpanner #'staff-padding = #3.4
>         e''2\p\< d''\> s1*0\!
>       }
>       \new Staff = "down" <<
>         {
>           \clef bass
>           s4. e,8\rest g,2\rest
>         } \\ {
>           c8\( g c'
>           \change Staff = "up"
>           e' g' b'-3 a' g'\)
>         }
>       >>
>     >>

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.

#### Known issues and warnings

Beam collision avoidance does not work for automatic beams that end right before a change in staff. To make the latter work, use manual beaming.

#### See also

Learning Manual: Fixing overlapping notation.

Notation Reference: Stems, Automatic beams, Keeping contexts alive.

Snippets: Keyboards.

Internals Reference: Beam, ContextChange.

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

#### See also

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

#### See also

Snippets: Keyboards.

Internals Reference: Note_head_line_engraver, VoiceFollower.

#### Cross-staff stems

Chords that cross staves may be produced:

>     \new PianoStaff <<
>       \new Staff {
>         \relative c' {
>           f8 e4 d8 d f e4
>         }
>       }
>       \new Staff {
>         \relative c' {
>           << {
>             \clef bass
>             % stems may overlap the other staff
>             \override Stem #'cross-staff = ##t
>             % extend the stems to reach the other staff
>             \override Stem #'length = #12
>             % do not print extra flags
>             \override Stem #'flag-style = #'no-flag
>             % prevent beaming as needed
>             a8 g4 f8 f bes\noBeam g4
>           }
>           \\
>           {
>             f,2 bes4 c
>           } >>
>         }
>       }
>     >>

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

#### See also

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.

#### See also

Notation Reference: Ties.

Snippets: Keyboards.

Internals Reference: SustainPedal, SustainPedalLineSpanner, SustainEvent, SostenutoPedal, SostenutoPedalLineSpanner, SostenutoEvent, UnaCordaPedal, UnaCordaPedalLineSpanner, UnaCordaEvent, PianoPedalBracket, Piano_pedal_engraver.

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

#### See also

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.

#### See also

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.

#### See also

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.

#### See also

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

#### See also

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.

#### See also

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

## 2.4 Fretted string instruments

This section discusses several aspects of music notation that are unique to fretted string instruments.

### 2.4.1 Common notation for fretted strings

This section discusses common notation that is unique to fretted string instruments.

#### References for fretted strings

Music for fretted string instruments is normally notated on a single staff, either in traditional music notation or in tablature. Sometimes the two types are combined, and it is especially common in popular music to use chord diagrams above a staff of traditional notation. The guitar and the banjo are transposing instruments, sounding an octave lower than written. Scores for these instruments should use the `"treble_8"` clef (or `\transposition c` to get correct MIDI output). Some other elements pertinent to fretted string instruments are covered elsewhere:

- Fingerings are indicated as shown in Fingering instructions.
- Instructions for Laissez vibrer ties as well as ties on arpeggios and tremolos can be found in Ties.
- Instructions for handling multiple voices can be found in Collision resolution.
- Instructions for indicating harmonics can be found in Harmonics.

#### See also

Notation Reference: Fingering instructions, Ties, Collision resolution, Instrument names, Writing music in parallel, Arpeggio, List of articulations, Clef, Instrument transpositions.

#### String number indications

The string on which a note should be played may be indicated by appending `\number` to a note inside a chord construct `<>`.

Note: String numbers must be defined inside a chord construct even if there is only a single note.

>     \clef "treble_8"
>     <c\5>4 <e\4> <g\3>2
>     <c,\5 e\4 g\3>1

When fingerings and string indications are used together, their placement is controlled by the order in which the two items appear in the code:

>     \clef "treble_8"
>     <g\3-0>2
>     <g-0\3>

#### 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
>       \override Fingering #'staff-padding = #'()
>       <c-1 e-2 g-3 b-5>4 <g'-0>
>     }

#### See also

Notation Reference: Fingering instructions.

Snippets: Fretted strings.

Internals Reference: StringNumber, Fingering.

#### Default tablatures

Music for plucked string instruments is frequently notated using a finger/touch notation or tablature. In contrast to traditional notation pitches are not denoted with note heads, but by numbers (or letter-like symbols in historical intavolatura). The staff lines in tablature indicate the string on which the note is to be played, and a number placed on a staff line indicated the fret at which the corresponding string is to be pressed. Notes that are to be played simultaneously are vertically aligned.

By default, string 1 is the highest string, and corresponds to the top line on the `TabStaff`. The tuning of the `TabStaff` strings defaults to the standard guitar tuning (with 6 strings). The notes are printed as tablature, by using `TabStaff` and `TabVoice` contexts. A calligraphic tablature clef is added automatically.

>     \new TabStaff \relative c' {
>       a,8 a' <c e> a
>       d,8 a' <d f> a
>     }

Default tablatures do not contain any symbols for tone duration nor any other musical symbols such as e.g. expressive marks.

>     symbols = {
>       \time 3/4
>       c4-.^"Allegro" d( e)
>       f4-.\f g a^\fermata
>       \mark \default
>       c8_.\<\( c16 c~ c2\!
>       c'2.\prall\)
>     }

>     \score {
>       <<
>         \new Staff { \clef "G_8" \symbols }
>         \new TabStaff { \symbols }
>       >>
>     }

If all musical symbols used in traditional notation should also show up in tablature one has to apply the command `\tabFullNotation` in a `TabStaff`-context. Please bear in mind that half notes are double-stemmed in tablature in order to distinguish them from quarter notes.

>     symbols = {
>       \time 3/4
>       c4-.^"Allegro" d( e)
>       f4-.\f g a^\fermata
>       \mark \default
>       c8_.\<\( c16 c~ c2\!
>       c'2.\prall\)
>     }

>     \score {
>       \new TabStaff {
>         \tabFullNotation
>         \symbols
>       }
>     }

By default pitches are assigned to the lowest playing position on the fret-board (first position). Open strings are automatically preferred. If you would like a certain pitch to be played on a specific string you can add a string number indication to the pitch name. If you define pitch names and string numbers without a chord construct (`<>`) the string number indications do not appear in traditional notation. It is much more comfortable to define the playing position by using the value of `minimumFret`. The default value for minimumFret is 0.

>     \new StaffGroup <<
>        \new Staff \relative c {
>          \clef "treble_8"
>          \time 2/4
>          c16 d e f g4
>          c,16\5 d\5 e\4 f\4 g4\4
>          c,16 d e f g4
>        }
>        \new TabStaff \relative c {
>          c16 d e f g4
>          c,16\5 d\5 e\4 f\4 g4\4
>          \set TabStaff.minimumFret = #5
>          c,16 d e f g4
>        }
>     >>

Chord constructs can be repeated by the chord repetition symbol `q`. To use this feature in combination with tablature, `\tabChordRepetition` is provided. It preserves the string information explicitly given within chord constructs so repeated chords get identical tablature representations.

>     \tabChordRepetition

>     guitar = \relative c' {
>       r8 <gis\4 cis\3 b\2>~ q4 q8~ q q4
>     }

>     \new StaffGroup <<
>       \new Staff {
>         \clef "treble_8"
>         \override Voice.StringNumber #'transparent = ##t
>         \guitar
>       }
>       \new TabStaff {
>         \guitar
>       }
>     >>

Ties over a line break are parenthesized by default. The same holds for the second alternative of a repeat.

>     ties = \relative c' {
>       \repeat volta 2 {
>         e2. f4~
>         f2 g2~
>       }
>       \alternative {
>          { g4 f2. }
>          { g4\repeatTie c,2. }
>       }
>       b1~
>       \break
>       b1
>       \bar "|."
>     }

>     \score {
>       <<
>         \new StaffGroup  <<
>           \context Staff {
>             \clef "treble_8"
>             \ties
>           }
>           \context TabStaff {
>             \ties
>           }
>         >>
>       >>
>       \layout {
>       indent = #0
>       ragged-right = ##t
>       }
>     }

The command `\hideSplitTiedTabNotes` cancels the behavior of engraving fret numbers in parentheses:

>     ties = \relative c' {
>       \repeat volta 2 {
>         e2. f4~
>         f2 g2~ }
>       \alternative {
>         { g4 f2. }
>         { g4\repeatTie c,2. }
>       }
>       b1~
>       \break
>       b1
>       \bar "|."
>     }

>     \score {
>       <<
>         \new StaffGroup  <<
>           \context Staff {
>             \clef "treble_8"
>             \ties
>           }
>           \context TabStaff {
>           \hideSplitTiedTabNotes
>             \ties
>           }
>         >>
>       >>
>       \layout {
>       indent = #0
>       ragged-right = ##t
>       }
>     }

Harmonic indications can be added to tablature notation as sounding pitches:

>     firstHarmonic = {
>       <d'\4\harmonic>4
>       <g'\3\harmonic>4
>       <b'\2\harmonic>2
>     }
>     \score {
>       <<
>         \new Staff { \firstHarmonic }
>         \new TabStaff { \firstHarmonic }
>       >>
>     }

Note that the command `\harmonic` must always be defined inside a chord construct. It only makes sense for open-string harmonics in the 12th fret. All other harmonics should be calculated by LilyPond. This can be achieved by indicating the fret where a finger of the fretting hand should touch a string.

>     fretHarmonics = {
>       \harmonicByFret #5 d16\4
>       \harmonicByFret #4 d16\4
>       \harmonicByFret #3 d8\4
>       \harmonicByFret #5 <g\3 b\2>2.
>     }
>     \score {
>       <<
>         \new Staff { \fretHarmonics }
>         \new TabStaff { \fretHarmonics }
>       >>
>     }

Alternatively, harmonics can be computed by defining the ratio of string lengths above and below the harmonic fingering.

>     ratioHarmonics = {
>       \harmonicByRatio #1/2 <g\3 b\2 e'\1>4
>       \harmonicByRatio #1/3 <g\3 b\2 e'\1>4
>       \harmonicByRatio #1/4 { g8\3 b8\2 e'4\1 }
>     }
>     \score {
>       <<
>         \new Staff { \ratioHarmonics }
>         \new TabStaff { \ratioHarmonics }
>       >>
>     }

#### Selected Snippets

Stem and beam behavior in tablature

The direction of stems is controlled the same way in tablature as in traditional notation. Beams can be made horizontal, as shown in this example.

>     \new TabStaff {
>       \relative c {
>         \tabFullNotation
>         g16 b d g b d g b
>         \stemDown
>         \override Beam #'damping = #+inf.0
>         g,,16 b d g b d g b
>       }
>     }

Polyphony in tablature

Polyphony is created the same way in a `TabStaff` as in a regular staff.

>     upper = \relative c' {
>       \time 12/8
>       \key e \minor
>       \voiceOne
>       r4. r8 e, fis g16 b g e e' b c b a g fis e
>     }

>     lower = \relative c {
>       \key e \minor
>       \voiceTwo
>       r16 e d c b a g4 fis8 e fis g a b c
>     }

>     \score {
>       <<
>         \new StaffGroup = "tab with traditional" <<
>           \new Staff = "guitar traditional" <<
>             \clef "treble_8"
>             \context Voice = "upper" \upper
>             \context Voice = "lower" \lower
>           >>
>           \new TabStaff = "guitar tab" <<
>             \context TabVoice = "upper" \upper
>             \context TabVoice = "lower" \lower
>           >>
>         >>
>       >>
>     }

Reference for open-string harmonics

Reference for open-string harmonics:

>     openStringHarmonics = {
>       %first harmonic
>       \harmonicByFret #12 e,2\6_\markup{"1st harm."}
>       \harmonicByRatio #1/2 e,\6
>       %second harmonic
>       \harmonicByFret #7 e,\6_\markup{"2nd harm. - - - -"}
>       \harmonicByRatio #1/3 e,\6
>       \harmonicByFret #19 e,\6
>       \harmonicByRatio #2/3 e,\6
>       %\harmonicByFret #19 < e,\6 a,\5 d\4 >
>       %\harmonicByRatio #2/3 < e,\6 a,\5 d\4 >
>       %third harmonic
>       \harmonicByFret #5 e,\6_\markup{"3rd harm. - - - -"}
>       \harmonicByRatio #1/4 e,\6
>       \harmonicByFret #24 e,\6
>       \harmonicByRatio #3/4 e,\6
>       \break
>       %fourth harmonic
>       \harmonicByFret #4 e,\6_\markup{"4th harm. - - - - - - - - - - - - -"}
>       \harmonicByRatio #1/5 e,\6
>       \harmonicByFret #9 e,\6
>       \harmonicByRatio #2/5 e,\6
>       \harmonicByFret #16 e,\6
>       \harmonicByRatio #3/5 e,\6
>       %fifth harmonic
>       \harmonicByFret #3 e,\6_\markup{"5th harm."}
>       \harmonicByRatio #1/6 e,\6
>       \break
>       %sixth harmonic
>       \harmonicByFret #2.7 e,\6_\markup{"6th harm."}
>       \harmonicByRatio #1/7 e,\6
>       %seventh harmonic
>       \harmonicByFret #2.3 e,\6_\markup{"7th harm."}
>       \harmonicByRatio #1/8 e,\6
>       %eighth harmonic
>       \harmonicByFret #2 e,\6_\markup{"8th harm."}
>       \harmonicByRatio #1/9 e,\6
>     }

>     \score {
>       <<
>         \new Staff {
>           \new Voice {
>             \clef "treble_8"
>             \openStringHarmonics
>           }
>         }
>         \new TabStaff {
>           \new TabVoice {
>             \openStringHarmonics
>           }
>         }
>       >>
>     }

Fretted-string harmonics in tablature

Fretted-string harmonics:

>     pinchedHarmonics = {
>        \textSpannerDown
>        \override TextSpanner #'bound-details #'left #'text =
>           \markup {\halign #-0.5 \teeny "PH" }
>           \override TextSpanner #'style =
>              #'dashed-line
>        \override TextSpanner #'dash-period = #0.6
>        \override TextSpanner #'bound-details #'right #'attach-dir = #1
>        \override TextSpanner #'bound-details #'right #'text =
>           \markup { \draw-line #'(0 . 1) }
>        \override TextSpanner #'bound-details #'right #'padding = #-0.5
>     }

>     harmonics = {
>       %artificial harmonics (AH)
>       \textLengthOn
>       <\parenthesize b b''\harmonic>4_\markup{ \teeny "AH 16" }
>       <\parenthesize g g''\harmonic>4_\markup{ \teeny "AH 17" }
>       <\parenthesize d' d'''\harmonic>2_\markup{ \teeny "AH 19" }
>       %pinched harmonics (PH)
>       \pinchedHarmonics
>       <a'\harmonic>2\startTextSpan
>       <g'\harmonic>4
>       <e'\harmonic>4\stopTextSpan
>       %tapped harmonics (TH)
>       <\parenthesize g\4 g'\harmonic>4_\markup{ \teeny "TH 17" }
>       <\parenthesize a\4 a'\harmonic>4_\markup{ \teeny "TH 19" }
>       <\parenthesize c'\3 c''\harmonic>2_\markup{ \teeny "TH 17" }
>       %touch harmonics (TCH)
>       a4( <e''\harmonic>2. )_\markup{ \teeny "TCH" }
>     }

>     frettedStrings = {
>       %artificial harmonics (AH)
>       \harmonicByFret #4 g4\3
>       \harmonicByFret #5 d4\4
>       \harmonicByFret #7 g2\3
>       %pinched harmonics (PH)
>       \harmonicByFret #7 d2\4
>       \harmonicByFret #5 d4\4
>       \harmonicByFret #7 a4\5
>       %tapped harmonics (TH)
>       \harmonicByFret #5 d4\4
>       \harmonicByFret #5 d4\4
>       \harmonicByFret #4 g2\3
>       %touch harmonics (TCH)
>       a4 \harmonicByFret #9 g2.\3
>     }

>     \score {
>       <<
>         \new Staff {
>           \new Voice {
>             \clef "treble_8"
>             \harmonics
>           }
>         }
>         \new TabStaff {
>           \new TabVoice {
>             \frettedStrings
>           }
>         }
>       >>
>     }

Slides in tablature

Slides can be typeset in both `Staff` and `TabStaff` contexts:

>     slides = {
>       c'8\3(\glissando d'8\3)
>       c'8\3\glissando d'8\3
>       \hideNotes
>       \grace { g16\3\glissando }
>       \unHideNotes
>       c'4\3
>       \afterGrace d'4\3\glissando {
>       \stemDown \hideNotes
>       g16\3 }
>       \unHideNotes
>     }

>     \score {
>       <<
>         \new Staff { \clef "treble_8" \slides }
>         \new TabStaff { \slides }
>       >>
>       \layout {
>         \context {
>           \Score
>           \override Glissando #'minimum-length = #4
>           \override Glissando #'springs-and-rods =
>                               #ly:spanner::set-spacing-rods
>           \override Glissando #'thickness = #2
>         }
>       }
>     }

Chord glissando in tablature

Slides for chords can be indicated in both Staff and TabStaff. String numbers are necessary for TabStaff because automatic string calculations are different for chords and for single notes, and `\chordGlissando` draws lines between single notes.

>     myMusic = \relative c' {
>       \chordGlissando
>       <c\3 e\2 g\1>8 <f\3 a\2 c\1>
>     }

>     \score {
>       <<
>         \new Staff {
>           \clef "treble_8"
>           \myMusic
>         }
>         \new TabStaff {
>           \myMusic
>         }
>       >>
>     }

#### See also

Notation Reference: Stems, Harmonics, Glissando.

Snippets: Fretted strings.

Internals Reference: TabNoteHead, TabStaff, TabVoice, Beam.

#### Known issues and warnings

Chords are not handled in a special way, and hence the automatic string selector may easily select the same string for two notes in a chord.

In order to handle `\partcombine`, a `TabStaff` must use specially-created voices:

>     melodia = \partcombine { e4 g g g } { e4 e e e }
>     <<
>       \new TabStaff <<
>         \new TabVoice = "one" s1
>         \new TabVoice = "two" s1
>         \new TabVoice = "shared" s1
>         \new TabVoice = "solo" s1
>         { \melodia }
>       >>
>     >>

Guitar special effects are limited to harmonics and slides.

#### Custom tablatures

LilyPond tablature automatically calculates the fret for a note based on the string to which the note is assigned. In order to do this, the tuning of the strings must be specified. The tuning of the strings is given in the `stringTunings` property.

LilyPond comes with predefined string tunings for banjo, mandolin, guitar, bass guitar, ukulele, violin, viola, cello, and double bass. LilyPond automatically sets the correct transposition for predefined tunings. The following example is for bass guitar, which sounds an octave lower than written.

>     <<
>       \new Staff {
>         \clef "bass_8"
>         \relative c, {
>           c4 d e f
>         }
>       }
>       \new TabStaff {
>         \set TabStaff.stringTunings = #bass-tuning
>         \relative c, {
>           c4 d e f
>         }
>       }
>     >>

The default string tuning is `guitar-tuning`, which is the standard EADGBE tuning. Some other predefined tunings are `guitar-open-g-tuning`, `mandolin-tuning` and `banjo-open-g-tuning`. The predefined string tunings are found in ‘`ly/string-tuning-init.ly`’.

Any desired string tuning can be created. The `\contextStringTuning` function can be used to define a string tuning and set it as the `stringTunings` for the current context. `\contextStringTuning` takes two arguments: the symbol in which the string tuning will be stored, and a chord construct that defines the pitches of each string in the tuning. The chord construct must be in absolute octave mode, see Absolute octave entry. The string with the highest number (generally the lowest string) must come first in the chord. For example, we can define a string tuning for a four-string instrument with pitches of `a''`, `d''`, `g'`, and `c'`:

>     mynotes = {
>       c'4 e' g' c'' |
>       e''4 g'' b'' c'''
>     }

>     <<
>       \new Staff {
>         \clef treble
>         \mynotes
>       }
>       \new TabStaff {
>         \contextStringTuning #'custom-tuning <c' g' d'' a''>
>         \mynotes
>       }
>     >>

The `stringTunings` property is also used by `FretBoards` to calculate automatic fret diagrams.

String tunings are used as part of the hash key for predefined fret diagrams (see Predefined fret diagrams). The `\makeStringTuning` function is used to create a string tuning without setting the `stringTunings` property in the current context. The arguments to `\makeStringTuning` are the symbol to be used for the new string tuning and a chord construct used to define the tuning. The previous example could also be written as follows:

>     \makeStringTuning #'custom-tuning <c' g' d'' a''>

>     mynotes = {
>       c'4 e' g' c'' |
>       e''4 g'' b'' c'''
>     }

>     <<
>       \new Staff {
>         \clef treble
>         \mynotes
>       }
>       \new TabStaff {
>         \set TabStaff.stringTunings = #custom-tuning
>         \mynotes
>       }
>     >>

Internally, a string tuning is a Scheme list of string pitches, one for each string, ordered by string number from 1 to N, where string 1 is at the top of the tablature staff and string N is at the bottom. This ordinarily results in ordering from highest pitch to lowest pitch, but some instruments (e.g. ukulele) do not have strings ordered by pitch.

A string pitch in a string tuning list is a LilyPond pitch object. Pitch objects are created with the Scheme function `ly:make-pitch` (see Scheme functions).

If desired, a string tuning can be created as a Scheme literal. The example below recreates the examples above, but the string tuning is not saved as a separate object:

>     mynotes = {
>       c'4 e' g' c'' |
>       e''4 g'' b'' c'''
>     }

>     <<
>       \new Staff {
>         \clef treble
>         \mynotes
>       }
>       \new TabStaff {
>         \set TabStaff.stringTunings = #`(,(ly:make-pitch 1 5 0)
>     				     ,(ly:make-pitch 1 1 0)
>     				     ,(ly:make-pitch 0 4 0)
>     				     ,(ly:make-pitch 0 0 0))
>         \mynotes
>       }
>     >>

LilyPond automatically calculates the number of lines in the `TabStaff` and the number of strings in an automatically calculated `FretBoard` as the number of elements in `stringTunings`.

A modern tab clef can also be used.

>     \new TabStaff {
>       \clef moderntab
>       <a, e a>1
>       \break
>       \clef tab
>       <a, e a>1
>     }

The modern tab clef supports tablatures from 4 to 7 strings.

#### See also

Notation Reference: Absolute octave entry, Predefined fret diagrams, Scheme functions.

Installed Files: ‘`ly/string-tuning-init.ly`’ ‘`scm/tablature.scm`’.

Snippets: Fretted strings.

Internals Reference: Tab_note_heads_engraver.

#### Known issues and warnings

Automatic tablature calculations do not work properly in most cases for instruments where string pitches do not vary monotonically with string number, such as ukuleles.

#### Fret diagram markups

Fret diagrams can be added to music as a markup to the desired note. The markup contains information about the desired fret diagram. There are three different fret-diagram markup interfaces: standard, terse, and verbose. The three interfaces produce equivalent markups, but have varying amounts of information in the markup string. Details about the syntax of the different markup strings used to define fret diagrams are found at Instrument Specific Markup.

The standard fret diagram markup string indicates the string number and the fret number for each dot to be placed on the string. In addition, open and unplayed (muted) strings can be indicated.

>     <<
>       \context ChordNames {
>         \chordmode {
>           c1 d:m
>         }
>       }
>       \context Staff {
>         \clef "treble_8"
>         <c e g c' e'>1^\markup {
>           \fret-diagram #"6-x;5-3;4-2;3-o;2-1;1-o;"
>         }
>         <d a d' f'>1^\markup {
>           \fret-diagram #"6-x;5-x;4-o;3-2;2-3;1-1;"
>         }
>       }
>     >>

Barre indications can be added to the diagram from the fret-diagram markup string.

>     <<
>       \context ChordNames {
>          \chordmode {
>            f1 g
>          }
>       }
>       \context Staff {
>         \clef "treble_8"
>         <f, c f a c' f'>1^\markup {
>           \fret-diagram #"c:6-1-1;6-1;5-3;4-3;3-2;2-1;1-1;"
>         }
>         <g, d g b d' g'>1^\markup {
>           \fret-diagram #"c:6-1-3;6-3;5-5;4-5;3-4;2-3;1-3;"
>         }
>       }
>     >>

The size of the fret diagram, and the number of frets in the diagram can be changed in the fret-diagram markup string.

>     <<
>       \context ChordNames {
>          \chordmode {
>            f1 g
>          }
>       }
>       \context Staff {
>         \clef "treble_8"
>         <f, c f a c' f'>1^\markup {
>           \fret-diagram #"s:1.5;c:6-1-1;6-1;5-3;4-3;3-2;2-1;1-1;"
>         }
>         <g, b, d g b g'>1^\markup {
>           \fret-diagram #"h:6;6-3;5-2;4-o;3-o;2-o;1-3;"
>         }
>       }
>     >>

The number of strings in a fret diagram can be changed to accommodate different instruments such as banjos and ukuleles with the fret-diagram markup string.

>     <<
>       \context ChordNames {
>         \chordmode {
>           a1
>         }
>       }
>       \context Staff {
>         % An 'A' chord for ukulele
>         a'1^\markup {
>           \fret-diagram #"w:4;4-2-2;3-1-1;2-o;1-o;"
>         }
>       }
>     >>

Fingering indications can be added, and the location of fingering labels can be controlled by the fret-diagram markup string.

>     <<
>       \context ChordNames {
>         \chordmode {
>           c1 d:m
>         }
>       }
>       \context Staff {
>         \clef "treble_8"
>         <c e g c' e'>1^\markup {
>           \fret-diagram #"f:1;6-x;5-3-3;4-2-2;3-o;2-1-1;1-o;"
>         }
>         <d a d' f'>1^\markup {
>           \fret-diagram #"f:2;6-x;5-x;4-o;3-2-2;2-3-3;1-1-1;"
>         }
>       }
>     >>

Dot radius and dot position can be controlled with the fret-diagram markup string.

>     <<
>       \context ChordNames {
>         \chordmode {
>           c1 d:m
>         }
>       }
>       \context Staff {
>         \clef "treble_8"
>         <c e g c' e'>1^\markup {
>           \fret-diagram #"d:0.35;6-x;5-3;4-2;3-o;2-1;1-o;"
>         }
>         <d a d' f'>1^\markup {
>           \fret-diagram #"p:0.2;6-x;5-x;4-o;3-2;2-3;1-1;"
>         }
>       }
>     >>

The fret-diagram-terse markup string omits string numbers; the string number is implied by the presence of semicolons. There is one semicolon for each string in the diagram. The first semicolon corresponds to the highest string number and the last semicolon corresponds to the first string. Mute strings, open strings, and fret numbers can be indicated.

>     <<
>       \context ChordNames {
>         \chordmode {
>           c1 d:m
>         }
>       }
>       \context Staff {
>         \clef "treble_8"
>         <c e g c' e'>1^\markup {
>           \fret-diagram-terse #"x;3;2;o;1;o;"
>         }
>         <d a d' f'>1^\markup {
>           \fret-diagram-terse #"x;x;o;2;3;1;"
>         }
>       }
>     >>

Barre indicators can be included in the fret-diagram-terse markup string.

>     <<
>       \context ChordNames {
>         \chordmode {
>           f1 g
>         }
>       }
>       \context Staff {
>         \clef "treble_8"
>         <f, c f a c' f'>1^\markup {
>           \fret-diagram-terse #"1-(;3;3;2;1;1-);"
>         }
>         <g, d g b d' g'>1^\markup {
>           \fret-diagram-terse #"3-(;5;5;4;3;3-);"
>         }
>       }
>     >>

Fingering indications can be included in the fret-diagram-terse markup string.

>     <<
>       \context ChordNames {
>         \chordmode {
>           c1 d:m
>         }
>       }
>       \context Staff {
>         \override Voice.TextScript
>           #'(fret-diagram-details finger-code) = #'below-string
>         \clef "treble_8"
>         <c e g c' e'>1^\markup {
>           \fret-diagram-terse #"x;3-3;2-2;o;1-1;o;"
>         }
>         <d a d' f'>1^\markup {
>           \fret-diagram-terse #"x;x;o;2-2;3-3;1-1;"
>         }
>       }
>     >>

Other fret diagram properties must be adjusted using `\override` when using the fret-diagram-terse markup.

The fret-diagram-verbose markup string is in the format of a Scheme list. Each element of the list indicates an item to be placed on the fret diagram.

>     <<
>         \context ChordNames {
>           \chordmode {
>             c1 d:m
>           }
>         }
>       \context Staff {
>         \clef "treble_8"
>         <c e g c' e'>1^\markup {
>           \fret-diagram-verbose #'(
>             (mute 6)
>             (place-fret 5 3)
>             (place-fret 4 2)
>             (open 3)
>             (place-fret 2 1)
>             (open 1)
>           )
>         }
>         <d a d' f'>1^\markup {
>           \fret-diagram-verbose #'(
>             (mute 6)
>             (mute 5)
>             (open 4)
>             (place-fret 3 2)
>             (place-fret 2 3)
>             (place-fret 1 1)
>           )
>         }
>       }
>     >>

Fingering indications and barres can be included in a fret-diagram-verbose markup string. Unique to the fret-diagram-verbose interface is a capo indication that can be placed on the fret diagram. The capo indication is a thick bar that covers all strings. The fret with the capo will be the lowest fret in the fret diagram.

>     <<
>         \context ChordNames {
>           \chordmode {
>             f1 g c
>           }
>         }
>       \context Staff {
>         \clef "treble_8"
>         \override Voice.TextScript
>           #'(fret-diagram-details finger-code) = #'below-string
>         <f, c f a c' f'>1^\markup {
>           \fret-diagram-verbose #'(
>             (place-fret 6 1)
>             (place-fret 5 3)
>             (place-fret 4 3)
>             (place-fret 3 2)
>             (place-fret 2 1)
>             (place-fret 1 1)
>             (barre 6 1 1)
>           )
>         }
>         <g, b, d g b g'>1^\markup {
>           \fret-diagram-verbose #'(
>             (place-fret 6 3 2)
>             (place-fret 5 2 1)
>             (open 4)
>             (open 3)
>             (open 2)
>             (place-fret 1 3 3)
>           )
>         }
>         <c e g c' e'>1^\markup {
>           \fret-diagram-verbose #'(
>             (capo 3)
>             (mute 6)
>             (place-fret 4 5 1)
>             (place-fret 3 5 2)
>             (place-fret 2 5 3)
>           )
>         }
>       }
>     >>

All other fret diagram properties must be adjusted using `\override` when using the fret-diagram-verbose markup.

The graphical layout of a fret diagram can be customized according to user preference through the properties of the `fret-diagram-interface`. Details are found at fret-diagram-interface. For a fret diagram markup, the interface properties belong to `Voice.TextScript`.

#### Selected Snippets

Changing fret orientations

Fret diagrams can be oriented in three ways. By default the top string or fret in the different orientations will be aligned.

>     \include "predefined-guitar-fretboards.ly"

>     <<
>       \chords {
>         c1
>         c1
>         c1
>       }
>       \new FretBoards {
>         \chordmode {
>           c1
>           \override FretBoard #'(fret-diagram-details orientation) =
>             #'landscape
>           c1
>           \override FretBoard #'(fret-diagram-details orientation) =
>             #'opposing-landscape
>           c1
>         }
>       }
>       \new Voice {
>         c'1
>         c'1
>         c'
>       }
>     >>

Customizing markup fret diagrams

Fret diagram properties can be set through `'fret-diagram-details`. For markup fret diagrams, overrides can be applied to the `Voice.TextScript` object or directly to the markup.

>     <<
>       \chords { c1 | c | c | d }

>       \new Voice = "mel" {
>         \textLengthOn
>         % Set global properties of fret diagram
>         \override TextScript #'size = #'1.2
>         \override TextScript
>           #'(fret-diagram-details finger-code) = #'in-dot
>         \override TextScript
>           #'(fret-diagram-details dot-color) = #'white

>         %% C major for guitar, no barre, using defaults
>            % terse style
>         c'1^\markup { \fret-diagram-terse #"x;3-3;2-2;o;1-1;o;" }

>         %% C major for guitar, barred on third fret
>            % verbose style
>            % size 1.0
>            % roman fret label, finger labels below string, straight barre
>         c'1^\markup {
>           % standard size
>           \override #'(size . 1.0) {
>             \override #'(fret-diagram-details . (
>                          (number-type . roman-lower)
>                          (finger-code . in-dot)
>                          (barre-type . straight))) {
>               \fret-diagram-verbose #'((mute 6)
>                                        (place-fret 5 3 1)
>                                        (place-fret 4 5 2)
>                                        (place-fret 3 5 3)
>                                        (place-fret 2 5 4)
>                                        (place-fret 1 3 1)
>                                        (barre 5 1 3))
>             }
>           }
>         }

>         %% C major for guitar, barred on third fret
>            % verbose style
>            % landscape orientation, arabic numbers, M for mute string
>            % no barre, fret label down or left, small mute label font
>         c'1^\markup {
>           \override #'(fret-diagram-details . (
>                        (finger-code . below-string)
>                        (number-type . arabic)
>                        (label-dir . -1)
>                        (mute-string . "M")
>                        (orientation . landscape)
>                        (barre-type . none)
>                        (xo-font-magnification . 0.4)
>                        (xo-padding . 0.3))) {
>             \fret-diagram-verbose #'((mute 6)
>                                      (place-fret 5 3 1)
>                                      (place-fret 4 5 2)
>                                      (place-fret 3 5 3)
>                                      (place-fret 2 5 4)
>                                      (place-fret 1 3 1)
>                                      (barre 5 1 3))
>           }
>         }

>         %% simple D chord
>            % terse style
>            % larger dots, centered dots, fewer frets
>            % label below string
>         d'1^\markup {
>           \override #'(fret-diagram-details . (
>                        (finger-code . below-string)
>                        (dot-radius . 0.35)
>                        (dot-position . 0.5)
>                        (fret-count . 3))) {
>             \fret-diagram-terse #"x;x;o;2-1;3-2;2-3;"
>           }
>         }
>       }
>     >>

#### See also

Notation Reference: Instrument Specific Markup.

Snippets: Fretted strings.

Internals Reference: fret-diagram-interface.

#### Predefined fret diagrams

Fret diagrams can be displayed using the `FretBoards` context. By default, the `FretBoards` context will display fret diagrams that are stored in a lookup table:

>     \include "predefined-guitar-fretboards.ly"
>     \context FretBoards {
>       \chordmode {
>         c1 d
>       }
>     }

The default predefined fret diagrams are contained in the file ‘`predefined-guitar-fretboards.ly`’. Fret diagrams are stored based on the pitches of a chord and the value of `stringTunings` that is currently in use. ‘`predefined-guitar-fretboards.ly`’ contains predefined fret diagrams only for `guitar-tuning`. Predefined fret diagrams can be added for other instruments or other tunings by following the examples found in ‘`predefined-guitar-fretboards.ly`’.

Fret diagrams for the ukulele are contained in the file ‘`predefined-ukulele-fretboards.ly`’.

>     \include "predefined-ukulele-fretboards.ly"

>     myChords = \chordmode { a1 a:m a:aug }

>     \new ChordNames {
>       \myChords
>     }

>     \new FretBoards {
>       \set stringTunings = #ukulele-tuning
>       \myChords
>     }

Fret diagrams for the mandolin are contained in the file ‘`predefined-mandolin-fretboards.ly`’.

>     \include "predefined-mandolin-fretboards.ly"

>     myChords = \chordmode { c1 c:m7.5- c:aug }

>     \new ChordNames {
>       \myChords
>     }

>     \new FretBoards {
>       \set stringTunings = #mandolin-tuning
>       \myChords
>     }

Chord pitches can be entered either as simultaneous music or using chord mode (see Chord mode overview).

>     \include "predefined-guitar-fretboards.ly"
>     \context FretBoards {
>       \chordmode { c1 }
>       <c' e' g'>1
>     }

It is common that both chord names and fret diagrams are displayed together. This is achieved by putting a `ChordNames` context in parallel with a `FretBoards` context and giving both contexts the same music.

>     \include "predefined-guitar-fretboards.ly"
>     mychords = \chordmode{
>       c1 f g
>     }

>     <<
>       \context ChordNames {
>         \mychords
>       }
>       \context FretBoards {
>         \mychords
>       }
>     >>

Predefined fret diagrams are transposable, as long as a diagram for the transposed chord is stored in the fret diagram table.

>     \include "predefined-guitar-fretboards.ly"
>     mychords = \chordmode{
>       c1 f g
>     }

>     mychordlist = {
>       \mychords
>       \transpose c e { \mychords }
>     }
>     <<
>       \context ChordNames {
>         \mychordlist
>       }
>       \context FretBoards {
>         \mychordlist
>       }
>     >>

The predefined fret diagram table for guitar contains eight chords (major, minor, augmented, diminished, dominant seventh, major seventh, minor seventh, dominant ninth) for each of 17 keys. The predefined fret diagram table for ukulele contains these chords plus an additional three chords (major sixth, suspended second, and suspended fourth). A complete list of the predefined fret diagrams is shown in Predefined fretboard diagrams. If there is no entry in the table for a chord, the FretBoards engraver will calculate a fret-diagram using the automatic fret diagram functionality described in Automatic fret diagrams.

>     \include "predefined-guitar-fretboards.ly"
>     mychords = \chordmode{
>       c1 c:maj9
>     }

>     <<
>       \context ChordNames {
>         \mychords
>       }
>       \context FretBoards {
>         \mychords
>       }
>     >>

Fret diagrams can be added to the fret diagram table. To add a diagram, you must specify the hash table for the diagram, the chord for the diagram, the tuning to be used, and a definition for the diagram. Normally, the hash table will be default-fret-table. The diagram definition can be either a fret-diagram-terse definition string or a fret-diagram-verbose marking list.

>     \include "predefined-guitar-fretboards.ly"

>     \storePredefinedDiagram #default-fret-table
>                             \chordmode { c:maj9 }
>                             #guitar-tuning
>                             #"x;3-2;o;o;o;o;"

>     mychords = \chordmode {
>       c1 c:maj9
>     }

>     <<
>       \context ChordNames {
>         \mychords
>       }
>       \context FretBoards {
>         \mychords
>       }
>     >>

Different fret diagrams for the same chord name can be stored using different octaves of pitches. The different octave should be at least two octaves above or below the default octave, because the octaves above and below the default octave are used for transposing fretboards.

>     \include "predefined-guitar-fretboards.ly"

>     \storePredefinedDiagram #default-fret-table
>                             \chordmode { c'' }
>                             #guitar-tuning
>                             #(offset-fret 2 (chord-shape 'bes guitar-tuning))

>     mychords = \chordmode {
>       c1 c''
>     }

>     <<
>       \context ChordNames {
>         \mychords
>       }
>       \context FretBoards {
>         \mychords
>       }
>     >>

In addition to fret diagrams, LilyPond stores an internal list of chord shapes. The chord shapes are fret diagrams that can be shifted along the neck to different positions to provide different chords. Chord shapes can be added to the internal list and then used to define predefined fret diagrams. Because they can be moved to various positions on the neck, chord shapes will normally not contain any open strings. Like fret diagrams, chord shapes can be entered as either fret-diagram-terse strings or fret-diagram-verbose marking lists.

>     \include "predefined-guitar-fretboards.ly"

>     % Add a new chord shape

>     \addChordShape #'powerf #guitar-tuning #"1-1;3-3;3-4;x;x;x;"

>     % add some new chords based on the power chord shape

>     \storePredefinedDiagram #default-fret-table
>                             \chordmode { f'' }
>                             #guitar-tuning
>                             #(chord-shape 'powerf guitar-tuning)
>     \storePredefinedDiagram #default-fret-table
>                             \chordmode { g'' }
>                             #guitar-tuning
>                             #(offset-fret 2 (chord-shape 'powerf guitar-tuning))

>     mychords = \chordmode{
>       f1 f'' g g''
>     }

>     <<
>       \context ChordNames {
>         \mychords
>       }
>       \context FretBoards {
>         \mychords
>       }
>     >>

The graphical layout of a fret diagram can be customized according to user preference through the properties of the `fret-diagram-interface`. Details are found at fret-diagram-interface. For a predefined fret diagram, the interface properties belong to `FretBoards.FretBoard`.

#### Selected Snippets

Customizing fretboard fret diagrams

Fret diagram properties can be set through `'fret-diagram-details`. For FretBoard fret diagrams, overrides are applied to the `FretBoards.FretBoard` object. Like `Voice`, `FretBoards` is a bottom level context, therefore can be omitted in property overrides.

>     \include "predefined-guitar-fretboards.ly"
>     \storePredefinedDiagram #default-fret-table \chordmode { c' }
>                             #guitar-tuning
>                             #"x;1-1-(;3-2;3-3;3-4;1-1-);"
>     <<
>       \new ChordNames {
>         \chordmode { c1 | c | c | d }
>       }
>       \new FretBoards {
>         % Set global properties of fret diagram
>         \override FretBoards.FretBoard #'size = #'1.2
>         \override FretBoard
>           #'(fret-diagram-details finger-code) = #'in-dot
>         \override FretBoard
>           #'(fret-diagram-details dot-color) = #'white
>         \chordmode {
>           c
>           \once \override FretBoard #'size = #'1.0
>           \once \override FretBoard
>             #'(fret-diagram-details barre-type) = #'straight
>           \once \override FretBoard
>             #'(fret-diagram-details dot-color) = #'black
>           \once \override FretBoard
>             #'(fret-diagram-details finger-code) = #'below-string
>           c'
>           \once \override FretBoard
>             #'(fret-diagram-details barre-type) = #'none
>           \once \override FretBoard
>             #'(fret-diagram-details number-type) = #'arabic
>           \once \override FretBoard
>             #'(fret-diagram-details orientation) = #'landscape
>           \once \override FretBoard
>             #'(fret-diagram-details mute-string) = #"M"
>           \once \override FretBoard
>             #'(fret-diagram-details label-dir) = #LEFT
>           \once \override FretBoard
>             #'(fret-diagram-details dot-color) = #'black
>           c'
>           \once \override FretBoard
>             #'(fret-diagram-details finger-code) = #'below-string
>           \once \override FretBoard
>             #'(fret-diagram-details dot-radius) = #0.35
>           \once \override FretBoard
>             #'(fret-diagram-details dot-position) = #0.5
>           \once \override FretBoard
>             #'(fret-diagram-details fret-count) = #3
>           d
>         }
>       }
>       \new Voice {
>         c'1 | c' | c' | d'
>       }
>     >>

Defining predefined fretboards for other instruments

Predefined fret diagrams can be added for new instruments in addition to the standards used for guitar. This file shows how this is done by defining a new string-tuning and a few predefined fretboards for the Venezuelan cuatro.

This file also shows how fingerings can be included in the chords used as reference points for the chord lookup, and displayed in the fret diagram and the `TabStaff`, but not the music.

These fretboards are not transposable because they contain string information. This is planned to be corrected in the future.

>     % add FretBoards for the Cuatro
>     %   Note: This section could be put into a separate file
>     %      predefined-cuatro-fretboards.ly
>     %      and \included into each of your compositions

>     cuatroTuning = #`(,(ly:make-pitch 0 6 0)
>                       ,(ly:make-pitch 1 3 SHARP)
>     		  ,(ly:make-pitch 1 1 0)
>     		  ,(ly:make-pitch 0 5 0))

>     dSix = { <a\4 b\1 d\3 fis\2> }
>     dMajor = { <a\4 d\1 d\3 fis \2> }
>     aMajSeven = { <a\4 cis\1 e\3 g\2> }
>     dMajSeven = { <a\4 c\1 d\3 fis\2> }
>     gMajor = { <b\4 b\1 d\3 g\2> }

>     \storePredefinedDiagram #default-fret-table \dSix
>                             #cuatroTuning
>                             #"o;o;o;o;"
>     \storePredefinedDiagram #default-fret-table \dMajor
>                             #cuatroTuning
>                             #"o;o;o;3-3;"
>     \storePredefinedDiagram #default-fret-table \aMajSeven
>                             #cuatroTuning
>                             #"o;2-2;1-1;2-3;"
>     \storePredefinedDiagram #default-fret-table \dMajSeven
>                             #cuatroTuning
>                             #"o;o;o;1-1;"
>     \storePredefinedDiagram #default-fret-table \gMajor
>                             #cuatroTuning
>                             #"2-2;o;1-1;o;"

>     % end of potential include file /predefined-cuatro-fretboards.ly

>     #(set-global-staff-size 16)

>     primerosNames = \chordmode {
>       d:6 d a:maj7 d:maj7
>       g
>     }
>     primeros = {
>       \dSix \dMajor \aMajSeven \dMajSeven
>       \gMajor
>     }

>     \score {
>       <<
>         \new ChordNames {
>           \set chordChanges = ##t
>           \primerosNames
>         }

>         \new Staff {
>           \new Voice \with {
>             \remove "New_fingering_engraver"
>           }
>           \relative c'' {
>             \primeros
>           }
>         }

>         \new FretBoards {
>           \set stringTunings = #cuatroTuning
>     %      \override FretBoard
>     %        #'(fret-diagram-details string-count) = #'4
>           \override FretBoard
>             #'(fret-diagram-details finger-code) = #'in-dot
>           \primeros
>         }

>         \new TabStaff \relative c'' {
>           \set TabStaff.stringTunings = #cuatroTuning
>           \primeros
>         }

>       >>

>       \layout {
>         \context {
>           \Score
>           \override SpacingSpanner
>             #'base-shortest-duration = #(ly:make-moment 1 16)
>         }
>       }
>       \midi { }
>     }

chordChanges for FretBoards

FretBoards can be set to display only when the chord changes or at the beginning of a new line.

>     \include "predefined-guitar-fretboards.ly"

>     myChords = \chordmode {
>       c1 c1 \break
>       \set chordChanges = ##t
>       c1 c1 \break
>       c1 c1 \break
>     }

>     <<
>       \new ChordNames { \myChords }
>       \new FretBoards { \myChords }
>       \new Staff { \myChords }
>     >>

Alternate fretboard tables

Alternate fretboard tables can be created. These would be used in order to have alternate fretboards for a given chord.

In order to use an alternate fretboard table, the table must first be created. Fretboards are then added to the table.

The created fretboard table can be blank, or it can be copied from an existing table.

The table to be used in displaying predefined fretboards is selected by the property `\predefinedDiagramTable`.

>     \include "predefined-guitar-fretboards.ly"

>     % Make a blank new fretboard table
>     #(define custom-fretboard-table-one (make-fretboard-table))

>     % Make a new fretboard table as a copy of default-fret-table
>     #(define custom-fretboard-table-two (make-fretboard-table default-fret-table))

>     % Add a chord to custom-fretboard-table-one
>     \storePredefinedDiagram #custom-fretboard-table-one
>                             \chordmode{c}
>                             #guitar-tuning
>                             "3-(;3;5;5;5;3-);"

>     % Add a chord to custom-fretboard-table-two
>     \storePredefinedDiagram #custom-fretboard-table-two
>                             \chordmode{c}
>                             #guitar-tuning
>                             "x;3;5;5;5;o;"

>     <<
>       \chords {
>         c1 | d1 |
>         c1 | d1 |
>         c1 | d1 |
>       }
>       \new FretBoards {
>         \chordmode {
>           \set predefinedDiagramTable = #default-fret-table
>           c1 | d1 |
>           \set predefinedDiagramTable = #custom-fretboard-table-one
>           c1 | d1 |
>           \set predefinedDiagramTable = #custom-fretboard-table-two
>           c1 | d1 |
>         }
>       }
>       \new Staff {
>         \clef "treble_8"
>         <<
>           \chordmode {
>             c1 | d1 |
>             c1 | d1 |
>             c1 | d1 |
>           }
>           {
>             s1_\markup "Default table" | s1 |
>             s1_\markup \column {"New table" "from empty"} | s1 |
>             s1_\markup \column {"New table" "from default"} | s1 |
>           }
>         >>
>       }
>     >>

#### See also

Notation Reference: Custom tablatures, Automatic fret diagrams, Chord mode overview, Predefined fretboard diagrams.

Installed Files: ‘`ly/predefined-guitar-fretboards.ly`’, ‘`ly/predefined-guitar-ninth-fretboards.ly`’, ‘`ly/predefined-ukulele-fretboards.ly`’, ‘`ly/predefined-mandolin-fretboards.ly`’.

Snippets: Fretted strings.

Internals Reference: fret-diagram-interface.

#### Automatic fret diagrams

Fret diagrams can be automatically created from entered notes using the `FretBoards` context. If no predefined diagram is available for the entered notes in the active `stringTunings`, this context calculates strings and frets that can be used to play the notes.

>     <<
>       \context ChordNames {
>         \chordmode {
>           f1 g
>         }
>       }
>       \context FretBoards {
>         <f, c f a c' f'>1
>         <g,\6 b, d g b g'>1
>       }
>       \context Staff {
>         \clef "treble_8"
>         <f, c f a c' f'>1
>         <g, b, d g b' g'>1
>       }
>     >>

As no predefined diagrams are loaded by default, automatic calculation of fret diagrams is the default behavior. Once default diagrams are loaded, automatic calculation can be enabled and disabled with predefined commands:

>     \storePredefinedDiagram #default-fret-table
>                             <c e g c' e'>
>                             #guitar-tuning
>                             #"x;3-1-(;5-2;5-3;5-4;3-1-1-);"
>     <<
>       \context ChordNames {
>         \chordmode {
>           c1 c c
>         }
>       }
>       \context FretBoards {
>         <c e g c' e'>1
>         \predefinedFretboardsOff
>         <c e g c' e'>1
>         \predefinedFretboardsOn
>         <c e g c' e'>1
>       }
>       \context Staff {
>         \clef "treble_8"
>         <c e g c' e'>1
>         <c e g c' e'>1
>         <c e g c' e'>1
>       }
>     >>

Sometimes the fretboard calculator will be unable to find an acceptable diagram. This can often be remedied by manually assigning a note to a string. In many cases, only one note need be manually placed on a string; the rest of the notes will then be placed appropriately by the `FretBoards` context.

Fingerings can be added to FretBoard fret diagrams.

>     <<
>       \context ChordNames {
>         \chordmode {
>           c1 d:m
>         }
>       }
>       \context FretBoards {
>         <c-3 e-2 g c'-1 e'>1
>         <d a-2 d'-3 f'-1>1
>       }
>       \context Staff {
>         \clef "treble_8"
>         <c e g c' e'>1
>         <d a d' f'>1
>       }
>     >>

The minimum fret to be used in calculating strings and frets for the FretBoard context can be set with the `minimumFret` property.

>     <<
>       \context ChordNames {
>         \chordmode {
>           d1:m d:m
>         }
>       }
>       \context FretBoards {
>         <d a d' f'>1
>         \set FretBoards.minimumFret = #5
>         <d a d' f'>1
>       }
>       \context Staff {
>         \clef "treble_8"
>         <d a d' f'>1
>         <d a d' f'>1
>       }
>     >>

The strings and frets for the `FretBoards` context depend on the `stringTunings` property, which has the same meaning as in the TabStaff context. See Custom tablatures for information on the `stringTunings` property.

The graphical layout of a fret diagram can be customized according to user preference through the properties of the `fret-diagram-interface`. Details are found at fret-diagram-interface. For a `FretBoards` fret diagram, the interface properties belong to `FretBoards.FretBoard`.

#### Predefined commands

`\predefinedFretboardsOff`, `\predefinedFretboardsOn`.

#### See also

Notation Reference: Custom tablatures.

Snippets: Fretted strings.

Internals Reference: fret-diagram-interface.

#### Known issues and warnings

Automatic fretboard calculations do not work properly for instruments with non-monotonic tunings.

#### Right-hand fingerings

Right-hand fingerings p-i-m-a must be entered within a chord construct `<>` for them to be printed in the score, even when applied to a single note.

Note: There must be a hyphen before `\rightHandFinger` and a space before the closing `>`.

>     \clef "treble_8"
>     <c-\rightHandFinger #1 >4
>     <e-\rightHandFinger #2 >
>     <g-\rightHandFinger #3 >
>     <c-\rightHandFinger #4 >
>     <c,-\rightHandFinger #1 e-\rightHandFinger #2
>      g-\rightHandFinger #3 c-\rightHandFinger #4 >1

For convenience, you can abbreviate `\rightHandFinger` to something short, for example `RH`,

>     #(define RH rightHandFinger)

#### Selected Snippets

Placement of right-hand fingerings

It is possible to exercise greater control over the placement of right-hand fingerings by setting a specific property, as demonstrated in the following example. Note: you must use a chord construct

>     #(define RH rightHandFinger)

>     \relative c {
>       \clef "treble_8"

>       \set strokeFingerOrientations = #'(up down)
>       <c-\RH #1 e-\RH #2 g-\RH #3 c-\RH #4 >4

>       \set strokeFingerOrientations = #'(up right down)
>       <c-\RH #1 e-\RH #2 g-\RH #3 c-\RH #4 >4

>       \set strokeFingerOrientations = #'(left)
>       <c-\RH #1 e-\RH #2 g-\RH #3 c-\RH #4 >2
>     }

Fingerings string indications and right-hand fingerings

This example combines left-hand fingering, string indications, and right-hand fingering.

>     #(define RH rightHandFinger)

>     \relative c {
>       \clef "treble_8"
>       <c-3\5-\RH #1 >4
>       <e-2\4-\RH #2 >4
>       <g-0\3-\RH #3 >4
>       <c-1\2-\RH #4 >4
>     }

#### See also

Snippets: Fretted strings.

Internals Reference: StrokeFinger.

### 2.4.2 Guitar

Most of the notational issues associated with guitar music are covered sufficiently in the general fretted strings section, but there are a few more worth covering here. Occasionally users want to create songbook-type documents having only lyrics with chord indications above them. Since LilyPond is a music typesetter, it is not recommended for documents that have no music notation in them. A better alternative is a word processor, text editor, or, for experienced users, a typesetter like GuitarTeX.

#### Indicating position and barring

This example demonstrates how to include guitar position and barring indications.

>     \clef "treble_8"
>     b16 d g b e
>     \textSpannerDown
>     \override TextSpanner #'(bound-details left text) = #"XII "
>     g16\startTextSpan
>     b16 e g e b g\stopTextSpan
>     e16 b g d

#### See also

Notation Reference: Text spanners.

Snippets: Fretted strings, Expressive marks.

#### Indicating harmonics and dampened notes

Special note heads can be used to indicate dampened notes or harmonics. Harmonics are normally further explained with a text markup.

>     \relative c' {
>       \clef "treble_8"
>       \override Staff.NoteHead #'style = #'harmonic-mixed
>       d^\markup { \italic { \fontsize #-2 { "harm. 12" }}} <g b>1
>     }

Dampened notes (also called dead notes) are supported within normal and tablature staves:

>     music = \relative c' {
>       < a\3 \deadNote c\2 a'\1 >4
>       < b\3 \deadNote d\2 b'\1 >
>       < c\3 \deadNote e\2 c'\1 >
>       \deadNotesOn
>       \times 2/3 { g8 b e }
>       \deadNotesOff
>       < a,\3 c\2 e\1 >1
>     }
>     \new StaffGroup <<
>       \new Staff {
>         \clef "treble_8"
>         \music
>       }
>       \new TabStaff {
>         \music
>       }
>     >>

Another playing technique (especially used on electric guitars) is called palm mute. The string is hereby partly muted by the palm of the striking hand (hence the name). Lilypond supports the notation of palm mute-style notes by changing the note head to a triangle shape.

>     \new Voice { % Warning: explicit Voice instantiation is
>                  %    required to have palmMuteOff work properly
>                  %    when palmMuteOn comes at the beginning of
>                  %    the piece.
>       \relative c, {
>         \clef "G_8"
>         \palmMuteOn
>         e8^\markup { \musicglyph #"noteheads.u2do"  = palm mute }
>         < e b' e > e
>         \palmMuteOff
>         e e  \palmMute e e e |
>         e8 \palmMute { e e e } e e e e |
>         < \palmMute e b' e >8 \palmMute { e e e } < \palmMute e b' e >2
>       }
>     }

#### See also

Snippets: Fretted strings.

Notation Reference: Special note heads, Note head styles.

#### Indicating power chords

Power chords and their symbols can be engraved in chord mode or as chord constructs:

>     ChordsAndSymbols = {
>       \chordmode {
>         \powerChords
>         e,,1:1.5
>         a,,1:1.5.8
>         \set minimumFret = #8
>         c,1:1.5
>         f,1:1.5.8
>       }
>       \set minimumFret = #5
>       <a, e>1
>       <g d' g'>1
>     }
>     \score {
>       <<
>         \new ChordNames {
>         \ChordsAndSymbols
>         }
>         \new Staff {
>           \clef "treble_8"
>           \ChordsAndSymbols
>         }
>         \new TabStaff {
>           \ChordsAndSymbols
>         }
>       >>
>     }

Power chord symbols are automatically switched off as soon as one of the other common chord modifier is used:

>     mixedChords = \chordmode {
>       c,1
>       \powerChords
>       b,,1:1.5
>       fis,,1:1.5.8
>       g,,1:m
>     }
>     \score {
>       <<
>         \new ChordNames {
>           \mixedChords
>         }
>         \new Staff {
>           \clef "treble_8"
>           \mixedChords
>         }
>         \new TabStaff {
>           \mixedChords
>         }
>       >>
>     }

#### See also

Music Glossary: power chord.

Notation Reference: Extended and altered chords, Printing chord names.

Snippets: Fretted strings.

### 2.4.3 Banjo

#### Banjo tablatures

LilyPond has basic support for the five-string banjo. When making tablatures for five-string banjo, use the banjo tablature format function to get correct fret numbers for the fifth string:

>     \new TabStaff <<
>       \set TabStaff.tablatureFormat = #fret-number-tablature-format-banjo
>       \set TabStaff.stringTunings = #banjo-open-g-tuning
>       {
>         \stemDown
>         g8 d' g'\5 a b g e d' |
>         g4 d''8\5 b' a'\2 g'\5 e'\2 d' |
>         g4
>       }
>     >>

A number of common tunings for banjo are predefined in LilyPond: `banjo-c-tuning` (gCGBD), `banjo-modal-tuning` (gDGCD), `banjo-open-d-tuning` (aDF#AD) and `banjo-open-dm-tuning` (aDFAD).

These tunings may be converted to four-string banjo tunings using the `four-string-banjo` function:

>     \set TabStaff.stringTunings = #(four-string-banjo banjo-c-tuning)

#### See also

Snippets: Fretted strings.

Installed Files: ‘`scm/string-tunings-init.scm`’ contains predefined banjo tunings.

## 2.5 Percussion

### 2.5.1 Common notation for percussion

Rhythmic music is primarily used for percussion and drum notation, but it can also be used to show the rhythms of melodies.

#### References for percussion

- Some percussion may be notated on a rhythmic staff; this is discussed in Showing melody rhythms, and Instantiating new staves.
- MIDI output is discussed in a separate section; please see Percussion in MIDI.

#### See also

Notation Reference: Showing melody rhythms, Instantiating new staves. Percussion in MIDI.

Snippets: Percussion.

#### Basic percussion notation

Percussion notes may be entered in `\drummode` mode, which is similar to the standard mode for entering notes. The simplest way to enter percussion notes is to use the `\drums` command, which creates the correct context and entry mode for percussion:

>     \drums {
>       hihat4 hh bassdrum bd
>     }

This is shorthand for:

>     \new DrumStaff {
>       \drummode {
>         hihat4 hh bassdrum bd
>       }
>     }

Each piece of percussion has a full name and an abbreviated name, and both can be used in input files. The full list of percussion note names may be found in Percussion notes.

Note that the normal notation of pitches (such as `cis4`) in a `DrumStaff` context will cause an error message. Percussion clefs are added automatically to a `DrumStaff` context but they can also be set explicitly. Other clefs may be used as well.

>     \drums {
>       \clef treble
>       hh4 hh hh hh
>       \break
>       \clef percussion
>       bd4 bd bd bd
>     }

There are a few issues concerning MIDI support for percussion instruments; for details please see Percussion in MIDI.

#### See also

Notation Reference: Percussion in MIDI, Percussion notes.

File: ‘`ly/drumpitch-init.ly`’

Snippets: Percussion.

#### Drum rolls

Drum rolls are indicated with three slashes across the stem. For quarter notes or longer the three slashes are shown explicitly, eighth notes are shown with two slashes (the beam being the third), and drum rolls shorter than eighths have one stem slash to supplement the beams. This is achieved with the tremolo notation, `:32`, as described in Tremolo repeats. Here is an example of some snare rolls:

>     \drums {
>       \time 2/4
>       sn16 sn8 sn16 sn8 sn8:32 ~
>       sn8 sn8 sn4:32 ~
>       sn4 sn8 sn16 sn16
>       sn4 r4
>     }

Sticking can be indicated by placing `^"R"` or `^"L"` after the note. The `staff-padding` property may be overridden to achieve a pleasing baseline.

>     \drums {
>       \repeat unfold 2 {
>         sn16 ^"L" sn^"R" sn^"L" sn^"L" sn^"R" sn^"L"  sn^"R" sn^"R"
>       }
>     }

#### See also

Snippets: Percussion.

#### Pitched percussion

Certain pitched percussion instruments (e.g. xylophone, vibraphone, and timpani) are written using normal staves. This is covered in other sections of the manual.

#### See also

Notation Reference: Percussion in MIDI.

Snippets: Percussion.

#### Percussion staves

A percussion part for more than one instrument typically uses a multiline staff where each position in the staff refers to one piece of percussion. To typeset the music, the notes must be interpreted in `DrumStaff` and `DrumVoice` context.

>     up = \drummode {
>       crashcymbal4 hihat8 halfopenhihat hh hh hh openhihat
>     }
>     down = \drummode {
>       bassdrum4 snare8 bd r bd sn4
>     }
>     \new DrumStaff <<
>       \new DrumVoice { \voiceOne \up }
>       \new DrumVoice { \voiceTwo \down }
>     >>

The above example shows verbose polyphonic notation. The short polyphonic notation, described in I'm hearing Voices, can also be used. For example,

>     \new DrumStaff <<
>       \drummode {
>         bd4 sn4 bd4 sn4
>         << {
>           \repeat unfold 16 hh16
>         } \\ {
>           bd4 sn4 bd4 sn4
>         } >>
>       }
>     >>

There are also other layout possibilities. To use these, set the property `drumStyleTable` in context `DrumVoice`. The following variables have been predefined:

`drums-style`

  This is the default. It typesets a typical drum kit on a five-line staff:

  The drum scheme supports six different toms. When there are fewer toms, simply select the toms that produce the desired result. For example, to get toms on the three middle lines you use `tommh`, `tomml`, and `tomfh`.

`timbales-style`

  This typesets timbales on a two line staff:

`congas-style`

  This typesets congas on a two line staff:

`bongos-style`

  This typesets bongos on a two line staff:

`percussion-style`

  To typeset all kinds of simple percussion on one line staves:

#### Custom percussion staves

If you do not like any of the predefined lists you can define your own list at the top of your file.

>     #(define mydrums '(
>              (bassdrum        default   #f           -1)
>              (snare           default   #f           0)
>              (hihat           cross     #f           1)
>              (halfopenhihat   cross     "halfopen"   1)
>              (pedalhihat      xcircle   "stopped"    2)
>              (lowtom          diamond   #f           3)))
>     up = \drummode { hh8 hh hhho hhho hhp4 hhp }
>     down = \drummode { bd4 sn bd toml8 toml }

>     \new DrumStaff <<
>       \set DrumStaff.drumStyleTable = #(alist->hash-table mydrums)
>       \new DrumVoice { \voiceOne \up }
>       \new DrumVoice { \voiceTwo \down }
>     >>

#### Selected Snippets

Here are some examples:

Two Woodblocks, entered with wbh (high woodblock) and wbl (low woodblock)

>     % These lines define the position of the woodblocks in the stave;
>     % if you like, you can change it or you can use special note heads
>     % for the woodblocks.
>     #(define mydrums '((hiwoodblock default #t  3)
>                        (lowoodblock default #t -2)))

>     woodstaff = {
>       % This defines a staff with only two lines.
>       % It also defines the positions of the two lines.
>       \override Staff.StaffSymbol #'line-positions = #'(-2 3)

>       % This is necessary; if not entered, the barline would be too short!
>       \override Staff.BarLine #'bar-extent = #'(-1.5 . 1.5)
>     }

>     \new DrumStaff {
>       \set DrumStaff.drumStyleTable = #(alist->hash-table mydrums)

>       % with this you load your new drum style table
>       \woodstaff

>       \drummode {
>         \time 2/4
>         wbl8 wbl16 wbl wbh8-> wbl |
>         wbl8 wbl16 wbh-> ~ wbh wbl16 r8 |
>       }
>     }

Note that in this special case the length of the barline must altered with `\override Staff.BarLine #'bar-extent #'(from . to)`. Otherwise it would be too short. And you have also to define the positions of the two stafflines. For more information about these delicate things have a look at Staff symbol.

A tambourine, entered with ‘tamb’:

>     #(define mydrums '((tambourine default #t 0)))

>     tambustaff = {
>       \override Staff.StaffSymbol #'line-positions = #'( 0 )
>       \override Staff.BarLine #'bar-extent = #'(-1.5 . 1.5)
>       \set DrumStaff.instrumentName = #"Tambourine"
>     }

>     \new DrumStaff {
>       \tambustaff
>       \set DrumStaff.drumStyleTable = #(alist->hash-table mydrums)

>       \drummode {
>         \time 6/8
>         tamb8. tamb16 tamb8 tamb tamb tamb |
>         tamb4. tamb8 tamb tamb |
>         % the trick with the scaled duration and the shorter rest
>         % is neccessary for the correct ending of the trill-span!
>         tamb2.*5/6 \startTrillSpan s8 \stopTrillSpan |
>       }
>     }

Music for Tam-Tam (entered with ‘tt’):

>     #(define mydrums '((tamtam default #t 0)))

>     tamtamstaff = {
>       \override Staff.StaffSymbol #'line-positions = #'( 0 )
>       \override Staff.BarLine #'bar-extent = #'(-1.5 . 1.5)
>       \set DrumStaff.instrumentName = #"Tamtam"
>     }

>     \new DrumStaff {
>       \tamtamstaff
>       \set DrumStaff.drumStyleTable = #(alist->hash-table mydrums)

>       \drummode {
>         tt 1 \pp \laissezVibrer
>       }
>     }

Two different bells, entered with ‘cb’ (cowbell) and ‘rb’ (ridebell)

>     #(define mydrums '((ridebell default #t  3)
>                        (cowbell  default #t -2)))

>     bellstaff = {
>       \override DrumStaff.StaffSymbol #'line-positions = #'(-2 3)
>       \set DrumStaff.drumStyleTable = #(alist->hash-table mydrums)
>       \override Staff.BarLine #'bar-extent = #'(-1.5 . 1.5)
>       \set DrumStaff.instrumentName = #"Different Bells"
>     }

>     \new DrumStaff {
>       \bellstaff
>       \drummode {
>         \time 2/4
>         rb8 rb cb cb16 rb-> ~ |
>         rb16 rb8 rb16 cb8 cb |
>       }
>     }

Here a short example taken from Stravinsky’s ‘L’histoire du Soldat’.

>     #(define mydrums '((bassdrum   default #t  4)
>                        (snare      default #t -4)
>                        (tambourine default #t  0)))

>     global = {
>       \time 3/8 s4.
>       \time 2/4 s2*2
>       \time 3/8 s4.
>       \time 2/4 s2
>     }

>     drumsA = {
>       \context DrumVoice <<
>         { \global }
>         { \drummode {
>             \autoBeamOff
>             \stemDown sn8 \stemUp tamb s8 |
>             sn4 \stemDown sn4 |
>             \stemUp tamb8 \stemDown sn8 \stemUp sn16 \stemDown sn \stemUp sn8 |
>             \stemDown sn8 \stemUp tamb s8 |
>             \stemUp sn4 s8 \stemUp tamb
>           }
>         }
>       >>
>     }

>     drumsB = {
>       \drummode {
>         s4 bd8 s2*2 s4 bd8 s4 bd8 s8
>       }
>     }

>     \layout {
>       indent = #40
>     }

>     \score {
>       \new StaffGroup <<
>         \new DrumStaff {
>           \set DrumStaff.instrumentName = \markup {
>             \column {
>               "Tambourine"
>               "et"
>               "caisse claire s. timbre"
>             }
>           }
>           \set DrumStaff.drumStyleTable = #(alist->hash-table mydrums)
>           \drumsA
>         }

>        \new DrumStaff {
>          \set DrumStaff.instrumentName = #"Grosse Caisse"
>          \set DrumStaff.drumStyleTable = #(alist->hash-table mydrums)
>          \drumsB }
>       >>
>     }

#### See also

Snippets: Percussion.

Internals Reference: DrumStaff, DrumVoice.

#### Ghost notes

Ghost notes for drums and percussion may be created using the `\parenthesize` command detailed in Parentheses. However, the default `\drummode` does not include the `Parenthesis_engraver` plugin which allows this.

>     \new DrumStaff \with {
>       \consists "Parenthesis_engraver"
>     }
>     <<
>       \context DrumVoice  = "1" { s1 }
>       \context DrumVoice  = "2" { s1 }
>       \drummode {
>         <<
>           {
>             hh8[ hh] <hh sn> hh16
>             < \parenthesize sn > hh
>             < \parenthesize sn > hh8 <hh sn> hh
>           } \\
>           {
>             bd4 r4 bd8 bd r8 bd
>           }
>         >>
>       }
>     >>

Also note that you must add chords (`< >` brackets) around each `\parenthesize` statement.

#### See also

Snippets: Percussion.

## 2.6 Wind instruments

This section includes elements of music notation that arise when writing specifically for wind instruments.

### 2.6.1 Common notation for wind instruments

This section discusses notation common to most wind instruments.

#### References for wind instruments

Many notation issues for wind instruments pertain to breathing and tonguing:

- Breathing can be specified by rests or Breath marks.
- Legato playing is indicated by Slurs.
- Different types of tonguings, ranging from legato to non-legato to staccato are usually shown by articulation marks, sometimes combined with slurs, see Articulations and ornamentations and List of articulations.
- Flutter tonguing is usually indicated by placing a tremolo mark and a text markup on the note. See Tremolo repeats.

Other aspects of musical notation that can apply to wind instruments:

- Many wind instruments are transposing instruments, see Instrument transpositions.
- The slide glissando are characteristic of the trombone, but other winds may perform keyed or valved glissandi. See Glissando.
- Harmonic series glissandi, which are possible on all brass instruments but common for French Horns, are usually written out as Grace notes.
- Pitch inflections at the end of a note are discussed in Falls and doits.
- Key slaps or valve slaps are often shown by the `cross` style of Special note heads.
- Woodwinds can overblow low notes to sound harmonics. These are shown by the `flageolet` articulation. See List of articulations.
- The use of brass mutes is usually indicated by a text markup, but where there are many rapid changes it is better to use the `stopped` and `open` articulations. See Articulations and ornamentations and List of articulations.
- Stopped horns are indicated by the `stopped` articulation. See Articulations and ornamentations.

#### Selected Snippets

Changing \flageolet mark size

To make the `\flageolet` circle smaller use the following Scheme function.

>     smallFlageolet =
>     #(let ((m (make-articulation "flageolet")))
>        (set! (ly:music-property m 'tweaks)
>              (acons 'font-size -3
>                     (ly:music-property m 'tweaks)))
>        m)

>     \layout { ragged-right = ##f }

>     \relative c'' {
>       d4^\flageolet_\markup { default size } d_\flageolet
>       c4^\smallFlageolet_\markup { smaller } c_\smallFlageolet
>     }

#### See also

Notation Reference: Breath marks, Slurs, Articulations and ornamentations, List of articulations, Tremolo repeats, Instrument transpositions, Glissando, Grace notes, Falls and doits, Special note heads,

Snippets: Winds.

#### Fingerings

All wind instruments other than the trombone require the use of several fingers to produce each pitch. Some fingering examples are shown in the snippets below.

Woodwind diagrams can be produced and are described in Woodwind diagrams.

#### Selected Snippets

Fingering symbols for wind instruments

Special symbols can be achieved by combining existing glyphs, which is useful for wind instruments.

>     centermarkup = {
>       \once \override TextScript #'self-alignment-X = #CENTER
>       \once \override TextScript #'X-offset =#(ly:make-simple-closure
>         `(,+
>           ,(ly:make-simple-closure (list
>             ly:self-alignment-interface::centered-on-x-parent))
>           ,(ly:make-simple-closure (list
>             ly:self-alignment-interface::x-aligned-on-self))))
>     }
>     \score
>     {\relative c'
>       {
>         g\open
>         \once \override TextScript #'staff-padding = #-1.0 \centermarkup
>         g^\markup{\combine \musicglyph #"scripts.open" \musicglyph
>         #"scripts.tenuto"}
>         \centermarkup g^\markup{\combine \musicglyph #"scripts.open"
>         \musicglyph #"scripts.stopped"}
>         g\stopped
>       }
>     }

Recorder fingering chart

The following example demonstrates how fingering charts for wind instruments can be realized.

>     % range chart for paetzold contrabass recorder

>     centermarkup = {
>       \once \override TextScript #'self-alignment-X = #CENTER
>       \once \override TextScript #'X-offset =#(ly:make-simple-closure
>       `(,+
>       ,(ly:make-simple-closure (list
>       ly:self-alignment-interface::centered-on-x-parent))
>       ,(ly:make-simple-closure (list
>       ly:self-alignment-interface::x-aligned-on-self))))
>     }

>     \score {
>       \new Staff \with {
>         \remove "Time_signature_engraver"
>         \override Stem #'stencil = ##f
>         \consists "Horizontal_bracket_engraver"
>       }
>       {
>         \clef bass
>         \set Score.timing = ##f
>         f,1*1/4 \glissando
>         \clef violin
>         gis'1*1/4
>         \stemDown a'4^\markup{1)}
>         \centermarkup
>         \once \override TextScript #'padding = #2
>         bes'1*1/4_\markup{\override #'(baseline-skip . 1.7) \column
>           { \fontsize #-5 \slashed-digit #0 \finger 1 \finger 2 \finger 3 \finger 4
>         \finger 5 \finger 6 \finger 7} }
>         b'1*1/4
>         c''4^\markup{1)}
>         \centermarkup
>         \once \override TextScript #'padding = #2
>         cis''1*1/4
>         deh''1*1/4
>         \centermarkup
>         \once \override TextScript #'padding = #2
>         \once \override Staff.HorizontalBracket #'direction = #UP
>         e''1*1/4_\markup{\override #'(baseline-skip . 1.7) \column
>           { \fontsize #-5 \slashed-digit #0 \finger 1 \finger 2 \finger 4
>         \finger 5} }\startGroup
>         f''1*1/4^\markup{2)}\stopGroup
>       }
>     }

#### See also

Notation Reference: Woodwind diagrams.

Snippets: Winds.

### 2.6.2 Bagpipes

This section discusses notation common bagpipes.

#### Bagpipe definitions

LilyPond contains special definitions for Scottish, Highland Bagpipe music; to use them, add

>     \include "bagpipe.ly"

to the top of your input file. This lets you add the special grace notes common to bagpipe music with short commands. For example, you could write `\taor` instead of

>     \grace { \small G32[ d G e] }

‘`bagpipe.ly`’ also contains pitch definitions for the bagpipe notes in the appropriate octaves, so you do not need to worry about `\relative` or `\transpose`.

>     \include "bagpipe.ly"
>     { \grg G4 \grg a \grg b \grg c \grg d \grg e \grg f \grA g A }

Bagpipe music nominally uses the key of D Major (even though that isn’t really true). However, since that is the only key that can be used, the key signature is normally not written out. To set this up correctly, always start your music with `\hideKeySignature`. If you for some reason want to show the key signature, you can use `\showKeySignature` instead.

Some modern music use cross fingering on c and f to flatten those notes. This can be indicated by `cflat` or `fflat`. Similarly, the piobaireachd high g can be written `gflat` when it occurs in light music.

#### See also

Winds.

#### Bagpipe example

This is what the well known tune Amazing Grace looks like in bagpipe notation.

>     \include "bagpipe.ly"
>     \layout {
>       indent = 0.0\cm
>       \context { \Score \remove "Bar_number_engraver" }
>     }

>     \header {
>       title = "Amazing Grace"
>       meter = "Hymn"
>       arranger = "Trad. arr."
>     }

>     {
>       \hideKeySignature
>       \time 3/4
>       \grg \partial 4 a8. d16
>       \slurd d2 \grg f8[ e32 d16.]
>       \grg f2 \grg f8 e
>       \thrwd d2 \grg b4
>       \grG a2 \grg a8. d16
>       \slurd d2 \grg f8[ e32 d16.]
>       \grg f2 \grg e8. f16
>       \dblA A2 \grg A4
>       \grg A2 f8. A16
>       \grg A2 \hdblf f8[ e32 d16.]
>       \grg f2 \grg f8 e
>       \thrwd d2 \grg b4
>       \grG a2 \grg a8. d16
>       \slurd d2 \grg f8[ e32 d16.]
>       \grg f2 e4
>       \thrwd d2.
>       \slurd d2
>       \bar "|."
>     }

#### See also

Winds.

### 2.6.3 Woodwinds

This section discusses notation specifically for woodwind instruments.

#### 2.6.3.1 Woodwind diagrams

Woodwind diagrams can be used to indicate the fingering to be used for specific notes and are available for the following instruments:

- piccolo
- flute
- oboe
- clarinet
- bass clarinet
- saxophone
- bassoon
- contrabassoon

Woodwind diagrams are created as markups:

>     c1^\markup {
>       \woodwind-diagram #'piccolo #'((lh . (gis))
>                                      (cc . (one three))
>                                      (rh . (ees)))
>     }

Keys can be open, partially-covered, ring-depressed, or fully covered:

>     \textLengthOn
>     c1^\markup {
>       \center-column {
>         "one quarter"
>         \woodwind-diagram #'flute #'((cc . (one1q))
>                                      (lh . ())
>                                      (rh . ()))
>       }
>     }

>     c1^\markup {
>       \center-column {
>         "one half"
>         \woodwind-diagram #'flute #'((cc . (one1h))
>                                      (lh . ())
>                                      (rh . ()))
>       }
>     }

>     c1^\markup {
>       \center-column {
>         "three quarter"
>         \woodwind-diagram #'flute #'((cc . (one3q))
>                                      (lh . ())
>                                      (rh . ()))
>       }
>     }

>     c1^\markup {
>       \center-column {
>         "ring"
>         \woodwind-diagram #'flute #'((cc . (oneR))
>                                      (lh . ())
>                                      (rh . ()))
>       }
>     }

>     c1^\markup {
>       \center-column {
>         "full"
>         \woodwind-diagram #'flute #'((cc . (oneF two))
>                                      (lh . ())
>                                      (rh . ()))
>       }
>     }

Trills are indicated as shaded keys:

>     c1^\markup {
>       \woodwind-diagram #'bass-clarinet
>                         #'((cc . (threeT four))
>                            (lh . ())
>                            (rh . (b fis)))
>     }

A variety of trills can be displayed:

>     \textLengthOn
>     c1^\markup {
>       \center-column {
>         "one quarter to ring"
>         \woodwind-diagram #'flute #'((cc . (one1qTR))
>                                      (lh . ())
>                                      (rh . ()))
>       }
>     }

>     c1^\markup {
>       \center-column {
>         "ring to shut"
>         \woodwind-diagram #'flute #'((cc . (oneTR))
>                                      (lh . ())
>                                      (rh . ()))
>       }
>     }

>     c1^\markup {
>       \center-column {
>         "ring to open"
>         \woodwind-diagram #'flute #'((cc . (oneRT))
>                                      (lh . ())
>                                      (rh . ()))
>       }
>     }

>     c1^\markup {
>       \center-column {
>         "open to shut"
>         \woodwind-diagram #'flute #'((cc . (oneT))
>                                      (lh . ())
>                                      (rh . ()))
>       }
>     }

>     c1^\markup {
>       \center-column {
>         "one quarter to three quarters"
>         \woodwind-diagram #'flute #'((cc . (one1qT3q))
>                                      (lh . ())
>                                      (rh . ()))
>       }
>     }

The list of all possible keys and settings for a given instrument can be displayed on the console or in the log file, although they will not show up in the music output:

>     #(print-keys-verbose 'flute)

New diagrams can be created by following the patterns in ‘`scm/define-woodwind-diagrams.scm`’ and ‘`scm/display-woodwind-diagrams.scm`’. However, this will require Scheme ability and may not be accessible to all users.

#### Predefined commands

#### Selected Snippets

Woodwind diagrams listing

The following music shows all of the woodwind diagrams currently defined in LilyPond.

>     \relative c' {
>       \textLengthOn
>       c1^
>       \markup {
>         \center-column {
>           'piccolo
>           " "
>            \woodwind-diagram
>                       #'piccolo
>                       #'()
>         }
>       }

>       c1^
>       \markup {
>         \center-column {
>            'flute
>            " "
>            \woodwind-diagram
>               #'flute
>               #'()
>         }
>       }
>       c1^\markup {
>         \center-column {
>           'oboe
>           " "
>           \woodwind-diagram
>             #'oboe
>             #'()
>         }
>       }

>       c1^\markup {
>         \center-column {
>           'clarinet
>           " "
>           \woodwind-diagram
>             #'clarinet
>             #'()
>         }
>       }

>       c1^\markup {
>         \center-column {
>           'bass-clarinet
>           " "
>           \woodwind-diagram
>             #'bass-clarinet
>             #'()
>         }
>       }

>       c1^\markup {
>         \center-column {
>           'saxophone
>           " "
>           \woodwind-diagram
>             #'saxophone
>             #'()
>         }
>       }

>       c1^\markup {
>         \center-column {
>           'bassoon
>           " "
>           \woodwind-diagram
>             #'bassoon
>             #'()
>         }
>       }

>       c1^\markup {
>         \center-column {
>           'contrabassoon
>           " "
>           \woodwind-diagram
>             #'contrabassoon
>             #'()
>         }
>       }
>     }

Graphical and text woodwind diagrams

In may cases, the keys other than the central column can be displayed by key name as well as by graphical means.

>     \relative c'' {
>       \textLengthOn
>       c1^\markup
>         \woodwind-diagram
>           #'piccolo
>           #'((cc . (one three))
>              (lh . (gis))
>              (rh . (ees)))

>       c^\markup
>         \override #'(graphical . #f) {
>           \woodwind-diagram
>             #'piccolo
>             #'((cc . (one three))
>                (lh . (gis))
>                (rh . (ees)))
>         }
>     }

Changing the size of woodwind diagrams

The size and thickness of woodwind diagrams can be changed.

>     \relative c'' {
>       \textLengthOn
>       c1^\markup
>         \woodwind-diagram
>           #'piccolo
>           #'()

>       c^\markup
>         \override #'(size . 1.5) {
>           \woodwind-diagram
>             #'piccolo
>             #'()
>         }
>       c^\markup
>         \override #'(thickness . 0.15) {
>           \woodwind-diagram
>             #'piccolo
>             #'()
>         }
>     }

Woodwind diagrams key lists

The snippet below produces a list of all possible keys and key settings for woodwind diagrams as defined in ‘`scm/define-woodwind-diagrams.scm`’. The list will be displayed on the console and in the log file, but not in the music.

>     #(print-keys-verbose 'piccolo)
>     #(print-keys-verbose 'flute)
>     #(print-keys-verbose 'flute-b-extension)
>     #(print-keys-verbose 'oboe)
>     #(print-keys-verbose 'clarinet)
>     #(print-keys-verbose 'bass-clarinet)
>     #(print-keys-verbose 'low-bass-clarinet)
>     #(print-keys-verbose 'saxophone)
>     #(print-keys-verbose 'baritone-saxophone)
>     #(print-keys-verbose 'bassoon)
>     #(print-keys-verbose 'contrabassoon)

#### See also

Installed Files: ‘`scm/define-woodwind-diagrams.scm`’, ‘`scm/display-woodwind-diagrams.scm`’.

Snippets: Winds.

Internals Reference: TextScript, instrument-specific-markup-interface.

## 2.7 Chord notation

Chords can be entered either as normal notes or in chord mode and displayed using a variety of traditional European chord naming conventions. Chord names and figured bass notation can also be displayed.

### 2.7.1 Chord mode

Chord mode is used to enter chords using an indicator of the chord structure, rather than the chord pitches.

#### Chord mode overview

Chords can be entered as simultaneous music, as discussed in Chorded notes.

Chords can also be entered in “chord mode”, which is an input mode that focuses on the structures of chords in traditional European music, rather than on specific pitches. This is convenient for those who are familiar with using chord names to describe chords. More information on different input modes can be found at Input modes.

>     \chordmode { c1 g a g c }

Chords entered using chord mode are music elements, and can be transposed just like chords entered using simultaneous music. `\chordmode` is absolute, as `\relative` has no effect on `chordmode` blocks. However, in `\chordmode` the absolute pitches are one octave higher than in note mode.

Chord mode and note mode can be mixed in sequential music:

>     <c e g>2 <g b d>
>     \chordmode { c2 f }
>     <c e g>2 <g' b d>
>     \chordmode { f2 g }

#### See also

Music Glossary: chord.

Notation Reference: Chorded notes, Input modes.

Snippets: Chords.

#### Known issues and warnings

Predefined shorthands for articulations and ornaments cannot be used on notes in chord mode, see Articulations and ornamentations.

When chord mode and note mode are mixed in sequential music, and chord mode comes first, the note mode will create a new `Staff` context:

>     \chordmode { c2 f }
>     <c e g>2 <g' b d>

To avoid this behavior, explicitly create the `Staff` context:

>     \new Staff {
>       \chordmode { c2 f }
>       <c e g>2  <g' b d>
>     }

#### Common chords

Major triads are entered by including the root and an optional duration:

>     \chordmode { c2 f4 g }

Minor, augmented, and diminished triads are entered by placing `:` and a quality modifier string after the duration:

>     \chordmode { c2:m f4:aug g:dim }

Seventh chords can be created:

>     \chordmode { c1:7 c:m7 c:maj7 c:dim7 c:aug7 }

The table below shows the actions of the quality modifiers on triads and seventh chords. The default seventh step added to chords is a minor or flatted seventh, which makes the dominant seventh the basic seventh chord. All alterations are relative to the dominant seventh. A more complete table of modifier usage is found at Common chord modifiers.

Modifier | Action | Example
None | The default action; produces a major triad. |
m, m7 | The minor chord. This modifier lowers the 3rd. |
dim, dim7 | The diminished chord. This modifier lowers the 3rd, 5th and (if present) the 7th step. |
aug | The augmented chord. This modifier raises the 5th step. |
maj, maj7 | The major 7th chord. This modifier adds a raised 7th step. The `7` following `maj` is optional. Do NOT use this modifier to create a major triad. |

#### See also

Notation Reference: Common chord modifiers, Extended and altered chords.

Snippets: Chords.

#### Known issues and warnings

Only one quality modifier should be used per chord, typically on the highest step present in the chord. Chords with more than quality modifier will be parsed without an error or warning, but the results are unpredictable. Chords that cannot be achieved with a single quality modifier should be altered by individual pitches, as described in Extended and altered chords.

#### Extended and altered chords

Chord structures of arbitrary complexity can be created in chord mode. The modifier string can be used to extend a chord, add or remove chord steps, raise or lower chord steps, and add a bass note or create an inversion.

The first number following the `:` is taken to be the extent of the chord. The chord is constructed by sequentially adding thirds to the root until the specified number has been reached. Note that the seventh step added as part of an extended chord will be the minor or flatted seventh, not the major seventh. If the extent is not a third (e.g., 6), thirds are added up to the highest third below the extent, and then the step of the extent is added. The largest possible value for the extent is 13. Any larger value is interpreted as 13.

>     \chordmode {
>       c1:2 c:3 c:4 c:5
>       c1:6 c:7 c:8 c:9
>       c1:10 c:11 c:12 c:13
>       c1:14
>     }

Note that both `c:5` and `c` produce a C major triad.

Since an unaltered 11 does not sound good when combined with an unaltered 13, the 11 is removed from a `:13` chord (unless it is added explicitly).

>     \chordmode {
>       c1:13 c:13.11 c:m13
>     }

Individual steps can be added to a chord. Additions follow the extent and are prefixed by a dot (`.`). The basic seventh step added to a chord is the minor or flatted seventh, rather than the major seventh.

>     \chordmode {
>       c1:5.6 c:3.7.8 c:3.6.13
>     }

Added steps can be as high as desired.

>     \chordmode {
>       c4:5.15 c:5.20 c:5.25 c:5.30
>     }

Added chord steps can be altered by suffixing a `-` or `+` sign to the number. To alter a step that is automatically included as part of the basic chord structure, add it as an altered step.

>     \chordmode {
>       c1:7+ c:5+.3- c:3-.5-.7-
>     }

Following any steps to be added, a series of steps to be removed is introduced in a modifier string with a prefix of `^`. If more than one step is to be removed, the steps to be removed are separated by `.` following the initial `^`.

>     \chordmode {
>       c1^3 c:7^5 c:9^3 c:9^3.5 c:13.11^3.7
>     }

The modifier `sus` can be added to the modifier string to create suspended chords. This removes the 3rd step from the chord. Append either `2` or `4` to add the 2nd or 4th step to the chord. `sus` is equivalent to `^3`; `sus4` is equivalent to `.4^3`.

>     \chordmode {
>       c1:sus c:sus2 c:sus4 c:5.4^3
>     }

Inversions (putting a pitch other than the root on the bottom of the chord) and added bass notes can be specified by appending `/`pitch to the chord.

>     \chordmode {
>       c1 c/g c/f
>     }

A bass note that is part of the chord can be added, instead of moved as part of an inversion, by using `/+`pitch.

>     \chordmode {
>       c1 c/g c/+g
>     }

Chord modifiers that can be used to produce a variety of standard chords are shown in Common chord modifiers.

#### See also

Notation Reference: Common chord modifiers.

Snippets: Chords.

#### Known issues and warnings

Each step can only be present in a chord once. The following simply produces the augmented chord, since `5+` is interpreted last.

>     \chordmode { c1:5.5-.5+ }

Only the second inversion can be created by adding a bass note. The first inversion requires changing the root of the chord.

>     \chordmode {
>       c'1: c':/g e:6-3-^5 e:m6-^5
>     }

### 2.7.2 Displaying chords

Chords can be displayed by name, in addition to the standard display as notes on a staff.

#### Printing chord names

Chord names are printed in the `ChordNames` context:

>     \new ChordNames {
>       \chordmode {
>         c2 f4. g8
>       }
>     }

Chords can be entered as simultaneous notes or through the use of chord mode. The displayed chord name will be the same, regardless of the mode of entry, unless there are inversions or added bass notes:

>     <<
>       \new ChordNames {
>         <c e g>2  <f bes c>
>         <f c' e g>1
>         \chordmode {
>           c2 f:sus4 c1:/f
>         }
>       }
>       {
>         <c e g>2  <f bes c>
>         <f, c' e g>1
>         \chordmode {
>           c2 f:sus4 c1:/f
>         }
>       }
>     >>

Rests passed to a `ChordNames` context will cause the `noChordSymbol` markup to be displayed.

>     <<
>       \new ChordNames \chordmode {
>         c1
>         r1
>         g1
>         c1
>       }
>       \chordmode {
>         c1
>         r1
>         g1
>         c1
>       }
>     >>

`\chords { ... }` is a shortcut notation for `\new ChordNames { \chordmode { ... } }`.

>     \chords {
>       c2 f4.:m g8:maj7
>     }

>     \new ChordNames {
>       \chordmode {
>         c2 f4.:m g8:maj7
>       }
>     }

#### Selected Snippets

Showing chords at changes

Chord names can be displayed only at the start of lines and when the chord changes.

>     harmonies = \chordmode {
>       c1:m c:m \break c:m c:m d
>     }
>     <<
>       \new ChordNames {
>         \set chordChanges = ##t
>         \harmonies
>       }
>       \new Staff {
>         \relative c' { \harmonies }
>       }
>     >>

Simple lead sheet

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 __ }
>     >>

#### See also

Music Glossary: chord.

Notation Reference: Writing music in parallel.

Snippets: Chords.

Internals Reference: ChordNames, ChordName, Chord_name_engraver, Volta_engraver, Bar_engraver.

#### Known issues and warnings

Chords containing inversions or altered bass notes are not named properly if entered using simultaneous music.

#### Customizing chord names

There is no unique system for naming chords. Different musical traditions use different names for the same set of chords. There are also different symbols displayed for a given chord name. The names and symbols displayed for chord names are customizable.

The basic chord name layout is a system for Jazz music, proposed by Klaus Ignatzek (see Literature list). The chord naming system can be modified as described below. An alternate jazz chord system has been developed using these modifications. The Ignatzek and alternate Jazz notation are shown on the chart in Chord name chart.

In addition to the different naming systems, different note names are used for the root in different languages. The predefined variables `\germanChords`, `\semiGermanChords`, `\italianChords` and `\frenchChords` set these variables. The effect is demonstrated here:

German songbooks may indicate minor chords as lowercase letters, without any m suffix. This can be obtained by setting the `chordNameLowercaseMinor` property:

>     \chords {
>       \set chordNameLowercaseMinor = ##t
>       c2 d:m e:m f
>     }

If none of the existing settings give the desired output, the chord name display can be tuned through the following properties.

`chordRootNamer`

  The chord name is usually printed as a letter for the root with an optional alteration. The transformation from pitch to letter is done by this function. Special note names (for example, the German ‘H’ for a B-chord) can be produced by storing a new function in this property.

`majorSevenSymbol`

  This property contains the markup object used to follow the output of `chordRootNamer` to identify a major 7 chord. Predefined options are `whiteTriangleMarkup` and `blackTriangleMarkup`.

`chordNoteNamer`

  When the chord name contains additional pitches other than the root (e.g., an added bass note), this function is used to print the additional pitch. By default the pitch is printed using `chordRootNamer`. The `chordNoteNamer` property can be set to a specialized function to change this behavior. For example, the bass note can be printed in lower case.

`chordNameSeparator`

  Different parts of a chord name are normally separated by a slash. By setting `chordNameSeparator`, you can use any desired markup for a separator.

`chordNameExceptions`

  This property is a list of pairs. The first item in each pair is a set of pitches used to identify the steps present in the chord. The second item is a markup that will follow the `chordRootNamer` output to create the chord name.

`chordPrefixSpacer`

  The ‘m’ for minor chords is usually printed immediately to the right of the root of the chord. A spacer can be placed between the root and ‘m’ by setting `chordPrefixSpacer`. The spacer is not used when the root is altered.

#### Predefined commands

`\whiteTriangleMarkup`, `\blackTriangleMarkup`, `\germanChords`, `\semiGermanChords`, `\italianChords`, `\frenchChords`.

#### Selected Snippets

Chord name exceptions

The property `chordNameExceptions` can be used to store a list of special notations for specific chords.

>     % modify maj9 and 6(add9)
>     % Exception music is chords with markups
>     chExceptionMusic = {
>       <c e g b d'>1-\markup { \super "maj9" }
>       <c e g a d'>1-\markup { \super "6(add9)" }
>     }

>     % Convert music to list and prepend to existing exceptions.
>     chExceptions = #( append
>       ( sequential-music-to-chord-exceptions chExceptionMusic #t)
>       ignatzekExceptions)

>     theMusic = \chordmode {
>       g1:maj9 g1:6.9
>       \set chordNameExceptions = #chExceptions
>       g1:maj9 g1:6.9
>     }

>     \layout {
>       ragged-right = ##t
>     }

>     << \context ChordNames \theMusic
>        \context Voice \theMusic
>     >>

chord name major7

The layout of the major 7 can be tuned with `majorSevenSymbol`.

>     \chords {
>       c:7+
>       \set majorSevenSymbol = \markup { j7 }
>       c:7+
>     }

Adding bar lines to ChordNames context

To add bar line indications in the `ChordNames` context, add the `Bar_engraver`.

>     \new ChordNames \with {
>       \override BarLine #'bar-extent = #'(-2 . 2)
>       \consists "Bar_engraver"
>     }
>     \chordmode {
>       f1:maj7 f:7 bes:7
>     }

Volta below chords

By adding the `Volta_engraver` to the relevant staff, volte can be put under chords.

>     \score {
>       <<
>         \chords {
>           c1
>           c1
>         }
>         \new Staff \with {
>           \consists "Volta_engraver"
>         }
>         {
>           \repeat volta 2 { c'1 }
>           \alternative { c' }
>         }
>       >>
>       \layout {
>         \context {
>           \Score
>           \remove "Volta_engraver"
>         }
>       }
>     }

Changing chord separator

The separator between different parts of a chord name can be set to any markup.

>     \chords {
>       c:7sus4
>       \set chordNameSeparator
>         = \markup { \typewriter | }
>       c:7sus4
>     }

#### See also

Notation Reference: Chord name chart, Common chord modifiers.

Essay on automated music engraving: Literature list.

Installed Files: ‘`scm/chords-ignatzek.scm`’, ‘`scm/chord-entry.scm`’, ‘`ly/chord-modifier-init.ly`’.

Snippets: Chords.

#### Known issues and warnings

Chord names are determined from both the pitches that are present in the chord and the information on the chord structure that may have been entered in `\chordmode`. If the simultaneous pitches method of entering chords is used, undesired names result from inversions or bass notes.

>     myChords = \relative c' {
>       \chordmode { c1 c/g c/f }
>       <c e g>1 <g c e> <f c' e g>
>     }
>     <<
>       \new ChordNames { \myChords }
>       \new Staff { \myChords }
>     >>

### 2.7.3 Figured bass

Figured bass notation can be displayed.

#### Introduction to figured bass

LilyPond has support for figured bass, also called thorough bass or basso continuo:

>     <<
>       \new Voice { \clef bass dis4 c d ais g fis}
>       \new FiguredBass {
>         \figuremode {
>           < 6 >4 < 7\+ >8 < 6+ [_!] >
>           < 6 >4 <6 5 [3+] >
>           < _ >4 < 6 5/>4
>         }
>       }
>     >>

The support for figured bass consists of two parts: there is an input mode, introduced by `\figuremode`, that accepts entry of bass figures, and there is a context named `FiguredBass` that takes care of displaying `BassFigure` objects. Figured bass can also be displayed in `Staff` contexts.

`\figures{ ... }` is a shortcut notation for `\new FiguredBass { \figuremode { ... } }`.

Although the support for figured bass may superficially resemble chord support, it is much simpler. `\figuremode` mode simply stores the figures and the `FiguredBass` context prints them as entered. There is no conversion to pitches.

#### See also

Music Glossary: figured bass.

Snippets: Chords.

#### Entering figured bass

`\figuremode` is used to switch the input mode to figure mode. More information on different input modes can be found at Input modes.

In figure mode, a group of bass figures is delimited by `<` and `>`. The duration is entered after the `>`.

>     \new FiguredBass {
>       \figuremode {
>         <6 4>2
>       }
>     }

Accidentals (including naturals) can be added to figures:

>     \figures {
>       <7! 6+ 4-> <5++> <3-->
>     }

Augmented and diminished steps can be indicated:

>     \figures {
>       <6\+ 5/> <7/>
>     }

A backward slash through a figure (typically used for raised sixth steps) can be created:

>     \figures {
>       <6> <6\\>
>     }

Vertical spaces and brackets can be included in figures:

>     \figures {
>       <[12 _!] 8 [6  4]>
>     }

Any text markup can be inserted as a figure:

>     \figures {
>       <\markup { \tiny \number 6 \super (1) } 5>
>     }

Continuation lines can be used to indicate repeated figures:

>     <<
>       {
>         \clef bass
>         e4 d c b,
>         e4 d c b,
>       }
>       \figures {
>         \bassFigureExtendersOn
>         <6 4>4 <6 3> <7 3> <7 3>
>         \bassFigureExtendersOff
>         <6 4>4 <6 3> <7 3> <7 3>
>       }
>     >>

In this case, the extender lines replace existing figures, unless the continuation lines have been explicitly terminated.

>     <<
>       \figures {
>         \bassFigureExtendersOn
>         <6 4>4 <6 4> <6\! 4\!> <6 4>
>       }
>       {
>         \clef bass
>         d4 d c c
>       }
>     >>

The table below summarizes the figure modifiers available.

Modifier | Purpose | Example
+, -, ! | Accidentals |
\+, / | Augmented and diminished steps |
\\ | Raised sixth step |
\! | End of continuation line |

#### Predefined commands

`\bassFigureExtendersOn`, `\bassFigureExtendersOff`.

#### Selected Snippets

Changing the positions of figured bass alterations

Accidentals and plus signs can appear before or after the numbers, depending on the `figuredBassAlterationDirection` and `figuredBassPlusDirection` properties.

>     \figures {
>       <6\+> <5+> <6 4-> r
>       \set figuredBassAlterationDirection = #RIGHT
>       <6\+> <5+> <6 4-> r
>       \set figuredBassPlusDirection = #RIGHT
>       <6\+> <5+> <6 4-> r
>       \set figuredBassAlterationDirection = #LEFT
>       <6\+> <5+> <6 4-> r
>     }

#### See also

Snippets: Chords.

Internals Reference: BassFigure, BassFigureAlignment, BassFigureLine, BassFigureBracket, BassFigureContinuation, FiguredBass.

#### Displaying figured bass

Figured bass can be displayed using the `FiguredBass` context, or in most staff contexts.

When displayed in a `FiguredBass` context, the vertical location of the figures is independent of the notes on the staff.

>     <<
>       \relative c'' {
>         c4 c'8 r8 c,4 c'
>       }
>       \new FiguredBass {
>         \figuremode {
>           <4>4 <10 6>8 s8
>           <6 4>4 <6 4>
>         }
>       }
>     >>

In the example above, the `FiguredBass` context must be explicitly instantiated to avoid creating a second (empty) staff.

Figured bass can also be added to `Staff` contexts directly. In this case, the vertical position of the figures is adjusted automatically.

>     <<
>       \new Staff = myStaff
>       \figuremode {
>         <4>4 <10 6>8 s8
>         <6 4>4 <6 4>
>       }
>       %% Put notes on same Staff as figures
>       \context Staff = myStaff
>       {
>         \clef bass
>         c4 c'8 r8 c4 c'
>       }
>     >>

When added in a `Staff` context, figured bass can be displayed above or below the staff.

>     <<
>       \new Staff = myStaff
>       \figuremode {
>         <4>4 <10 6>8 s8
>         \bassFigureStaffAlignmentDown
>         <6 4>4 <6 4>
>       }
>       %% Put notes on same Staff as figures
>       \context Staff = myStaff
>       {
>         \clef bass
>         c4 c'8 r8 c4 c'
>       }
>     >>

#### Predefined commands

`\bassFigureStaffAlignmentDown`, `\bassFigureStaffAlignmentUp`, `\bassFigureStaffAlignmentNeutral`.

#### See also

Snippets: Chords.

Internals Reference: BassFigure, BassFigureAlignment, BassFigureLine, BassFigureBracket, BassFigureContinuation, FiguredBass.

#### Known issues and warnings

To ensure that continuation lines work properly, it is safest to use the same rhythm in the figure line as in the bass line.

>     <<
>       {
>         \clef bass
>         \repeat unfold 4 { f16. g32 } f8. es16 d8 es
>       }
>       \figures {
>         \bassFigureExtendersOn
>         % The extenders are correct here, with the same rhythm as the bass
>         \repeat unfold 4 { <6 4->16. <6 4->32 }
>         <5>8. r16 <6>8 <6\! 5->
>       }
>     >>
>     <<
>       {
>         \clef bass
>         \repeat unfold 4 { f16. g32 } f8. es16 d8 es
>       }
>       \figures {
>         \bassFigureExtendersOn
>         % The extenders are incorrect here, even though the timing is the same
>         <6 4->4 <6 4->4
>         <5>8. r16 <6>8 <6\! 5->
>       }
>     >>

When using extender lines, adjacent figures with the same number in a different figure location can cause the figure positions to invert.

>     <<
>       { fis4 g g, e' }
>       \figures {
>         \bassFigureExtendersOn
>         <6 5>4 <5\! 4> < 5 _!> <6>
>       }
>     >>

To avoid this problem, simply turn on extenders after the figure that begins the extender line and turn them off at the end of the extender line.

>     <<
>       { fis4 g g, e' }
>       \figures {
>         <6 5>4 <5 4>
>         \bassFigureExtendersOn
>         < 5 _!>4 <6>
>         \bassFigureExtendersOff
>       }
>     >>

## 2.8 Contemporary music

From the beginning of the 20th Century there has been a massive expansion of compositional style and technique. New harmonic and rhythmic developments, an expansion of the pitch spectrum and the development of a wide range of new instrumental techniques have been accompanied by a parallel evolution and expansion of musical notation. The purpose of this section is to provide references and information relevant to working with these new notational techniques.

### 2.8.1 Pitch and harmony in contemporary music

This section highlights issues that are relevant to notating pitch and harmony in contemporary music.

#### References for pitch and harmony in contemporary music

- Standard quarter-tone notation is addressed in Note names in other languages.
- Non-standard key signatures are addressed in Key signature.
- Contemporary practises in displaying accidentals are addressed in Automatic accidentals.

#### Microtonal notation

#### Contemporary key signatures and harmony

### 2.8.2 Contemporary approaches to rhythm

This section highlights issues that are relevant to the notation of rhythm in contemporary music.

#### References for contemporary approaches to rhythm

- Compound time signatures are addressed in Time signature.
- Basic polymetric notation is addressed in Polymetric notation.
- Feathered beams are addressed in Feathered beams.
- Mensurstriche bar lines (bar lines between staves only) are addressed in Grouping staves.

#### Tuplets in contemporary music

#### Contemporary time signatures

#### Extended polymetric notation

#### Beams in contemporary music

#### Bar lines in contemporary music

### 2.8.3 Graphical notation

### 2.8.4 Contemporary scoring techniques

### 2.8.5 New instrumental techniques

### 2.8.6 Further reading and scores of interest

This section suggests books, musical examples and other resources useful in studying contemporary musical notation.

#### Books and articles on contemporary musical notation

- Music Notation in the Twentieth Century: A Practical Guidebook by Kurt Stone [W. W. Norton, 1980]
- Music Notation: A Manual of Modern Practice by Gardner Read [Taplinger, 1979]
- Instrumentation and Orchestration by Alfred Blatter [Schirmer, 2nd ed. 1997]

#### Scores and musical examples

## 2.9 Ancient notation

Support for ancient notation includes features for mensural notation and Gregorian chant notation. These features can be accessed either by modifying style properties of graphical objects such as note heads and rests, or by using one of the pre-defined contexts for mensural or Gregorian notation.

Many graphical objects, such as note heads and flags, accidentals, time signatures, and rests, provide a `style` property, which can be changed to emulate several different styles of ancient notation. See

- Mensural note heads,
- Mensural accidentals and key signatures,
- Mensural rests,
- Mensural clefs,
- Gregorian clefs,
- Mensural flags,
- Mensural time signatures.

Some notational concepts are introduced specifically for ancient notation,

- Custodes,
- Divisiones,
- Ligatures.

#### See also

Music Glossary: custos, ligature, mensural notation.

Notation Reference: Mensural note heads, Mensural accidentals and key signatures, Mensural rests, Gregorian clefs, Mensural flags, Mensural time signatures, Custodes, Divisiones, Ligatures.

### 2.9.1 Overview of the supported styles

Three styles are available for typesetting Gregorian chant:

- Editio Vaticana is a complete style for Gregorian chant, following the appearance of the Solesmes editions, the official chant books of the Vatican since 1904. LilyPond has support for all the notational signs used in this style, including ligatures, custodes, and special signs such as the quilisma and the oriscus.
- The Editio Medicaea style offers certain features used in the Medicaea (or Ratisbona) editions which were used prior to the Solesmes editions. The most significant differences from the Vaticana style are the clefs, which have downward-slanted strokes, and the note heads, which are square and regular.
- The Hufnagel (“horseshoe nail”) or Gothic style mimics the writing style in chant manuscripts from Germany and Central Europe during the middle ages. It is named after the basic note shape (the virga), which looks like a small nail.

Three styles emulate the appearance of late-medieval and renaissance manuscripts and prints of mensural music:

- The Mensural style most closely resembles the writing style used in late-medieval and early renaissance manuscripts, with its small and narrow, diamond-shaped note heads and its rests which approach a hand-drawn style.
- The Neomensural style is a modernized and stylized version of the former: the note heads are broader and the rests are made up of straight lines. This style is particularly suited, e.g., for incipits of transcribed pieces of mensural music.
- The Petrucci style is named after Ottaviano Petrucci (1466-1539), the first printer to use movable type for music (in his Harmonice musices odhecaton, 1501). The style uses larger note heads than the other mensural styles.

Baroque and Classical are not complete styles but differ from the default style only in some details: certain note heads (Baroque) and the quarter rest (Classical).

Only the mensural style has alternatives for all aspects of the notation. Thus, there are no rests or flags in the Gregorian styles, since these signs are not used in plainchant notation, and the Petrucci style has no flags or accidentals of its own.

Each element of the notation can be changed independently of the others, so that one can use mensural flags, petrucci note heads, classical rests and vaticana clefs in the same piece, if one wishes.

#### See also

Music Glossary: mensural notation, flag.

### 2.9.2 Ancient notation—common features

#### Pre-defined contexts

For Gregorian chant and mensural notation, there are pre-defined voice and staff contexts available, which set all the various notation signs to values suitable for these styles. If one is satisfied with these defaults, one can proceed directly with note entry without worrying about the details on how to customize a context. See one of the pre-defined contexts `VaticanaVoice`, `VaticanaStaff`, `MensuralVoice`, and `MensuralStaff`. See further

- Gregorian chant contexts,
- Mensural contexts.

#### See also

Music Glossary: mensural notation.

Notation Reference: Gregorian chant contexts, Mensural contexts.

#### Ligatures

A ligature is a graphical symbol that represents at least two distinct notes. Ligatures originally appeared in the manuscripts of Gregorian chant notation to denote ascending or descending sequences of notes on the same syllable. They are also used in mensural notation.

Ligatures are entered by enclosing them in `\[` and `\]`. Some ligature styles may need additional input syntax specific for this particular type of ligature. By default, the `LigatureBracket` engraver just puts a square bracket above the ligature.

>     \transpose c c' {
>       \[ g c a f d' \]
>       a g f
>       \[ e f a g \]
>     }

Two other ligature styles are available: the Vaticana for Gregorian chant, and the Mensural for mensural music (only white mensural ligatures are supported for mensural music, and with certain limitations). To use any of these styles, the default `Ligature_bracket_engraver` has to be replaced with one of the specialized ligature engravers in the `Voice` context, as explained in White mensural ligatures and Gregorian square neume ligatures.

#### See also

Music Glossary: ligature.

Notation Reference: White mensural ligatures, Gregorian square neume ligatures.

#### Known issues and warnings

Ligatures need special spacing that has not yet been implemented. As a result, there is too much space between ligatures most of the time, and line breaking often is unsatisfactory. Also, lyrics do not correctly align with ligatures.

Accidentals must not be printed within a ligature, but instead need to be collected and printed in front of it.

The syntax still uses the deprecated infix style `\[ music expr \]`. For consistency reasons, it will eventually be changed to postfix style `note\[ ... note\]`.

#### Custodes

A custos (plural: custodes; Latin word for “guard”) is a symbol that appears at the end of a staff. It anticipates the pitch of the first note of the following line, thus helping the performer to manage line breaks during performance.

Custodes were frequently used in music notation until the seventeenth century. Nowadays, they have survived only in a few particular forms of musical notation such as contemporary editions of Gregorian chant like the Editio Vaticana. There are different custos glyphs used in different flavors of notational style.

For typesetting custodes, just put a `Custos_engraver` into the `Staff` context when declaring the `\layout` block, and change the style of the custos with an `\override` if desired, as shown in the following example:

The custos glyph is selected by the `style` property. The styles supported are `vaticana`, `medicaea`, `hufnagel`, and `mensural`. They are demonstrated in the following fragment.

#### See also

Music Glossary: custos.

Internals Reference: Custos.

Snippets: Ancient notation.

#### Figured bass support

There is limited support for figured bass notation from the Baroque period; see Figured bass.

#### See also

Music Glossary: figured bass.

Notation Reference: Figured bass.

### 2.9.3 Typesetting mensural music

#### Mensural contexts

The predefined `MensuralVoice` and `MensuralStaff` contexts can be used to engrave a piece in mensural style. These contexts initialize all relevant context properties and grob properties to proper values, so you can immediately go ahead entering the chant, as the following excerpt demonstrates:

>     \score {
>       <<
>         \new MensuralVoice = "discantus" \transpose c c' {
>           \override Score.BarNumber #'transparent = ##t {
>             c'1\melisma bes a g\melismaEnd
>             f\breve
>             \[ f1\melisma a c'\breve d'\melismaEnd \]
>             c'\longa
>             c'\breve\melisma a1 g1\melismaEnd
>             fis\longa^\signumcongruentiae
>           }
>         }
>         \new Lyrics \lyricsto "discantus" {
>           San -- ctus, San -- ctus, San -- ctus
>         }
>       >>
>     }

#### See also

Music Glossary: mensural notation.

#### Mensural clefs

The following table shows all mensural clefs that are supported via the `\clef` command. Some of the clefs use the same glyph, but differ only with respect to the line they are printed on. In such cases, a trailing number in the name is used to enumerate these clefs, numbered from the lowest to the highest line. Still, you can manually force a clef glyph to be typeset on an arbitrary line, as described in Clef. The note printed to the right side of each clef in the example column denotes the `c'` with respect to that clef.

Petrucci used C clefs with differently balanced left-side vertical beams, depending on which staff line it is printed.

Description | Supported Clefs | Example
mensural C clef | `mensural-c1`, `mensural-c2`, `mensural-c3`, `mensural-c4` |
mensural F clef | `mensural-f` |
mensural G clef | `mensural-g` |
neomensural C clef | `neomensural-c1`, `neomensural-c2`, `neomensural-c3`, `neomensural-c4` |
petrucci style C clefs, for use on different staff lines (the example shows the 2nd staff line C clef) | `petrucci-c1`, `petrucci-c2`, `petrucci-c3`, `petrucci-c4`, `petrucci-c5` |
petrucci style F clefs, for use on different staff lines (the example shows the 3rd staff line F clef) | `petrucci-f3`, `petrucci-f4`, `petrucci-f5` |
petrucci style G clef | `petrucci-g` |

#### See also

Music Glossary: mensural notation, clef.

Notation Reference: Clef.

#### Known issues and warnings

The mensural g clef is mapped to the Petrucci g clef.

#### Mensural time signatures

There is limited support for mensuration signs (which are similar to, but not exactly the same as time signatures). The glyphs are hard-wired to particular time fractions. In other words, to get a particular mensuration sign with the `\time n/m` command, `n` and `m` have to be chosen according to the following table

Use the `style` property of grob `TimeSignature` to select ancient time signatures. Supported styles are `neomensural` and `mensural`. The above table uses the `neomensural` style. The following examples show the differences in style:

Time signature, gives a general introduction to the use of time signatures.

#### See also

Music Glossary: mensural notation.

Notation Reference: Time signature.

#### Known issues and warnings

Ratios of note durations cannot change with the time signature, as those are not constant. For example, the ratio of 1 breve = 3 semibreves (tempus perfectum) can be made by hand, by setting

>     breveTP = #(ly:make-duration -1 0 3 2)
>     …
>     { c\breveTP f1 }

This sets `breveTP` to 3/2 times 2 = 3 times a whole note.

The `mensural68alt` and `neomensural68alt` symbols (alternate symbols for 6/8) are not addressable with `\time`. Use `\markup {\musicglyph #"timesig.mensural68alt" }` instead.

#### Mensural note heads

For ancient notation, a note head style other than the `default` style may be chosen. This is accomplished by setting the `style` property of the `NoteHead` object to `baroque`, `neomensural`, `mensural`, `petrucci`, `blackpetrucci` or `semipetrucci`.

The `baroque` style differs from the `default` style by:

- Providing a `maxima` note head, and
- Using a square shape for `\breve` note heads.

The `neomensural`, `mensural`, and `petrucci` styles differ from the `baroque` style by:

- Using rhomboidal heads for semibreves and all smaller durations, and
- Centering the stems on the note heads.

The `blackpetrucci` style produces note heads usable in black mensural notation or coloratio sections in white mensural notation. Because note head style does not influence flag count, in this style a semiminima should be notated as `a8*2`, not `a4`, otherwise it will look like a minima. The multiplyer can be different if coloratio is used e.g. to notate triplets.

Use `semipetrucci` style to draw half-colored note heads (breves, longas and maximas).

The following example demonstrates the `petrucci` style:

>     \set Score.skipBars = ##t
>     \autoBeamOff
>     \override NoteHead #'style = #'petrucci
>     a'\maxima a'\longa a'\breve a'1 a'2 a'4 a'8 a'16 a'
>     \override NoteHead #'style = #'semipetrucci
>     a'\breve*5/6
>     \override NoteHead #'style = #'blackpetrucci
>     a'8*4/3 a'
>     \override NoteHead #'style = #'petrucci
>     a'\longa

Note head styles, gives an overview of all available note head styles.

#### See also

Music Glossary: mensural notation, note head.

Notation Reference: Note head styles.

#### Mensural flags

Use the `flag-style` property of grob `Stem` to select ancient flags. Besides the `default` flag style, only the `mensural` style is supported.

>     \override Stem #'flag-style = #'mensural
>     \override Stem #'thickness = #1.0
>     \override NoteHead #'style = #'mensural
>     \autoBeamOff
>     c'8 d'8 e'8 f'8 c'16 d'16 e'16 f'16 c'32 d'32 e'32 f'32 s8
>     c''8 d''8 e''8 f''8 c''16 d''16 e''16 f''16 c''32 d''32 e''32 f''32

Note that the innermost flare of each mensural flag always is vertically aligned with a staff line.

There is no particular flag style for neo-mensural or Petrucci notation. There are no flags in Gregorian chant notation.

#### See also

Music Glossary: mensural notation, flag.

#### Known issues and warnings

The attachment of ancient flags to stems is slightly off.

Vertically aligning each flag with a staff line assumes that stems always end either exactly on or exactly in the middle between two staff lines. This may not always be true when using advanced layout features of classical notation (which however are typically out of scope for mensural notation).

#### Mensural rests

Use the `style` property of grob `Rest` to select ancient rests. Supported styles are `classical`, `neomensural`, and `mensural`. `classical` differs from the `default` style only in that the quarter rest looks like a horizontally mirrored 8th rest. The `mensural` and the `neomensural` styles mimic the appearance of rests in manuscripts and prints up to the 16th century.

The following example demonstrates the `mensural` and `neomensural` styles:

>     \set Score.skipBars = ##t
>     \override Rest #'style = #'classical
>     r\longa^"classical" r\breve r1 r2 r4 r8 r16 s \break
>     \override Rest #'style = #'mensural
>     r\longa^"mensural" r\breve r1 r2 r4 r8 r16 s \break
>     \override Rest #'style = #'neomensural
>     r\longa^"neomensural" r\breve r1 r2 r4 r8 r16

There are no 32th and 64th rests specifically for the mensural or neo-mensural style. Instead, the rests from the default style will be taken.

#### See also

Music Glossary: mensural notation.

Notation Reference: Rests.

Snippets: Ancient notation.

#### Known issues and warnings

The glyph for the maxima rest in mensural style is actually a perfect longa rest; use two (or three) longa rests to print a maxima rest. Longa rests are not grouped automatically, so have to be done manually by using pitched rests.

#### Mensural accidentals and key signatures

The `mensural` style provides a sharp and a flat sign different from the default style. If called for, the natural sign will be taken from the `vaticana` style.

The style for accidentals and key signatures is controlled by the `glyph-name-alist` property of the grobs `Accidental` and `KeySignature`, respectively; e.g.:

`\override Staff.Accidental #'glyph-name-alist = #alteration-mensural-glyph-name-alist`

#### See also

Music Glossary: mensural notation, Pitch names, accidental, key signature.

Notation Reference: Pitches, Accidentals, Automatic accidentals, Key signature.

Internals Reference: KeySignature.

#### Annotational accidentals (musica ficta)

In European music from before about 1600, singers were expected to chromatically alter notes at their own initiative according to certain rules. This is called musica ficta. In modern transcriptions, these accidentals are usually printed over the note.

Support for such suggested accidentals is included, and can be switched on by setting `suggestAccidentals` to true.

    fis gis
    \set suggestAccidentals = ##t
    ais bis

This will treat every subsequent accidental as musica ficta until it is unset with `\set suggestAccidentals = ##f`. A more practical way is to use `\once \set suggestAccidentals = ##t`, which can even be defined as a convenient shorthand:

>     ficta = { \once \set suggestAccidentals = ##t }
>     \score { \relative c''
>       \new MensuralVoice  {
>     	\once \set suggestAccidentals = ##t
>       bes4 a2 g2 \ficta fis8 \ficta e! fis2 g1
>       }
>     }

#### See also

Internals Reference: Accidental_engraver, AccidentalSuggestion.

#### White mensural ligatures

There is limited support for white mensural ligatures.

To engrave white mensural ligatures, in the layout block, replace the `Ligature_bracket_engraver` with the `Mensural_ligature_engraver` in the `Voice` context:

>     \layout {
>       \context {
>         \Voice
>         \remove Ligature_bracket_engraver
>         \consists Mensural_ligature_engraver
>       }
>     }

There is no additional input language to describe the shape of a white mensural ligature. The shape is rather determined solely from the pitch and duration of the enclosed notes. While this approach may take a new user a while to get accustomed to, it has the great advantage that the full musical information of the ligature is known internally. This is not only required for correct MIDI output, but also allows for automatic transcription of the ligatures.

At certain places two consecutive notes can be represented either as two squares or as an oblique parallelogram (flexa shape). In such cases the default is the two squares, but a flexa can be required by setting the `ligature-flexa` property of the second note head. The length of a flexa can be set by the note head property `flexa-width`.

For example,

>     \score {
>       \transpose c c' {
>         \set Score.timing = ##f
>         \set Score.defaultBarType = "empty"
>         \override NoteHead #'style = #'petrucci
>         \override Staff.TimeSignature #'style = #'mensural
>         \clef "petrucci-g"
>         \[ c'\maxima g \]
>         \[ d\longa
>            \override NoteHead #'ligature-flexa = ##t
>            \once \override NoteHead #'flexa-width = #3.2
>            c\breve f e d \]
>         \[ c'\maxima d'\longa \]
>         \[ e'1 a g\breve \]
>       }
>       \layout {
>         \context {
>           \Voice
>           \remove Ligature_bracket_engraver
>           \consists Mensural_ligature_engraver
>         }
>       }
>     }

Without replacing `Ligature_bracket_engraver` with `Mensural_ligature_engraver`, the same music transcribes to the following

#### See also

Music Glossary: ligature.

Notation Reference: Gregorian square neume ligatures, Ligatures.

#### Known issues and warnings

Horizontal spacing of ligatures is poor. Accidentals may collide with previous notes.

### 2.9.4 Typesetting Gregorian chant

When typesetting a piece in Gregorian chant notation, the `Vaticana_ligature_engraver` automatically selects the proper note heads, so there is no need to explicitly set the note head style. Still, the note head style can be set, e.g., to `vaticana_punctum` to produce punctum neumes. Similarly, the `Mensural_ligature_engraver` automatically assembles mensural ligatures.

#### See also

Music Glossary: ligature.

Notation Reference: White mensural ligatures, Ligatures.

#### Gregorian chant contexts

The predefined `VaticanaVoiceContext` and `VaticanaStaffContext` can be used to engrave a piece of Gregorian chant in the style of the Editio Vaticana. These contexts initialize all relevant context properties and grob properties to proper values, so you can immediately go ahead entering the chant, as the following excerpt demonstrates:

>     \include "gregorian.ly"
>     \score {
>       <<
>         \new VaticanaVoice = "cantus" {
>           \[ c'\melisma c' \flexa a \]
>           \[ a \flexa \deminutum g\melismaEnd \]
>           f \divisioMinima
>           \[ f\melisma \pes a c' c' \pes d'\melismaEnd \]
>           c' \divisioMinima \break
>           \[ c'\melisma c' \flexa a \]
>           \[ a \flexa \deminutum g\melismaEnd \] f \divisioMinima
>         }
>         \new Lyrics \lyricsto "cantus" {
>           San- ctus, San- ctus, San- ctus
>         }
>       >>
>     }

#### Gregorian clefs

The following table shows all Gregorian clefs that are supported via the `\clef` command. Some of the clefs use the same glyph, but differ only with respect to the line they are printed on. In such cases, a trailing number in the name is used to enumerate these clefs, numbered from the lowest to the highest line. Still, you can manually force a clef glyph to be typeset on an arbitrary line, as described in Clef. The note printed to the right side of each clef in the example column denotes the `c'` with respect to that clef.

Description | Supported Clefs | Example
Editio Vaticana style do clef | `vaticana-do1`, `vaticana-do2`, `vaticana-do3` |
Editio Vaticana style fa clef | `vaticana-fa1`, `vaticana-fa2` |
Editio Medicaea style do clef | `medicaea-do1`, `medicaea-do2`, `medicaea-do3` |
Editio Medicaea style fa clef | `medicaea-fa1`, `medicaea-fa2` |
hufnagel style do clef | `hufnagel-do1`, `hufnagel-do2`, `hufnagel-do3` |
hufnagel style fa clef | `hufnagel-fa1`, `hufnagel-fa2` |
hufnagel style combined do/fa clef | `hufnagel-do-fa` |

#### See also

Music Glossary: clef.

Notation Reference: Clef.

#### Gregorian accidentals and key signatures

Accidentals for the three different Gregorian styles are available:

As shown, not all accidentals are supported by each style. When trying to access an unsupported accidental, LilyPond will switch to a different style.

The style for accidentals and key signatures is controlled by the `glyph-name-alist` property of the grobs `Accidental` and `KeySignature`, respectively; e.g.:

`\override Staff.Accidental #'glyph-name-alist = #alteration-mensural-glyph-name-alist`

#### See also

Music Glossary: accidental, key signature.

Notation Reference: Pitches, Accidentals, Automatic accidentals, Key signature.

Internals Reference: KeySignature.

#### Divisiones

There are no rests in Gregorian chant notation; instead, it uses Divisiones.

A divisio (plural: divisiones; Latin word for ‘division’) is a staff context symbol that is used to indicate the phrase and section structure of Gregorian music. The musical meaning of divisio minima, divisio maior, and divisio maxima can be characterized as short, medium, and long pause, somewhat like the breath marks from Breath marks. The finalis sign not only marks the end of a chant, but is also frequently used within a single antiphonal/responsorial chant to mark the end of each section.

To use divisiones, include the file ‘`gregorian.ly`’. It contains definitions that you can apply by just inserting `\divisioMinima`, `\divisioMaior`, `\divisioMaxima`, and `\finalis` at proper places in the input. Some editions use virgula or caesura instead of divisio minima. Therefore, ‘`gregorian.ly`’ also defines `\virgula` and `\caesura`

#### Predefined commands

`\virgula`, `\caesura`, `\divisioMinima`, `\divisioMaior`, `\divisioMaxima`, `\finalis`.

#### See also

Music Glossary: caesura, divisio.

Notation Reference: Breath marks.

Installed Files: ‘`gregorian.ly`’.

#### Gregorian articulation signs

In addition to the standard articulation signs described in section Articulations and ornamentations, articulation signs specifically designed for use with notation in Editio Vaticana style are provided.

>     \include "gregorian.ly"
>     \score {
>       \new VaticanaVoice {
>         \override TextScript #'font-family = #'typewriter
>         \override TextScript #'font-shape = #'upright
>         \override Script #'padding = #-0.1
>         a\ictus_"ictus " \bar "" \break
>         a\circulus_"circulus " \bar "" \break
>         a\semicirculus_"semicirculus " \bar "" \break
>         a\accentus_"accentus " \bar "" \break
>         \[ a_"episema" \episemInitium \pes b \flexa a b \episemFinis \flexa a \]
>       }
>     }

#### See also

Notation Reference: Articulations and ornamentations.

Snippets: Ancient notation.

Internals Reference: Episema, EpisemaEvent, Episema_engraver, Script, ScriptEvent, Script_engraver.

#### Known issues and warnings

Some articulations are vertically placed too closely to the corresponding note heads.

#### Augmentum dots (morae)

Augmentum dots, also called morae, are added with the music function `\augmentum`. Note that `\augmentum` is implemented as a unary music function rather than as head prefix. It applies to the immediately following music expression only. That is, `\augmentum \virga c` will have no visible effect. Instead, say `\virga \augmentum c` or `\augmentum {\virga c}`. Also note that you can say `\augmentum {a g}` as a shortcut for `\augmentum a \augmentum g`.

>     \include "gregorian.ly"
>     \score {
>       \new VaticanaVoice {
>         \[ \augmentum a \flexa \augmentum g \]
>         \augmentum g
>       }
>     }

#### See also

Notation Reference: Breath marks.

Internals Reference: BreathingSign.

Snippets: Ancient notation.

#### Gregorian square neume ligatures

There is limited support for Gregorian square neumes notation (following the style of the Editio Vaticana). Core ligatures can already be typeset, but essential issues for serious typesetting are still lacking, such as (among others) horizontal alignment of multiple ligatures, lyrics alignment, and proper handling of accidentals.

The support for Gregorian neumes is enabled by `\include`ing ‘`gregorian.ly`’ at the beginning of the file. This makes available a number of extra commands to produce the neume symbols used in plainchant notation.

Note heads can be modified and/or joined.

- The shape of the note head can be modified by prefixing the note name with any of the following commands: `\virga`, `\stropha`, `\inclinatum`, `\auctum`, `\descendens`, `\ascendens`, `\oriscus`, `\quilisma`, `\deminutum`, `\cavum`, `\linea`.
- Ligatures, properly speaking (i.e. notes joined together), are produced by placing one of the joining commands `\pes` or `\flexa`, for upwards and downwards movement, respectively, between the notes to be joined.

A note name without any qualifiers will produce a punctum. All other neumes, including the single-note neumes with a different shape such as the virga, are in principle considered as ligatures and should therefore be placed between `\[...\]`.

Single-note neumes:

- The punctum is the basic note shape (in the Vaticana style: a square with some curvation for typographical finesse). In addition to the regular punctum, there is also the oblique punctum inclinatum, produced with the prefix `\inclinatum`. The regular punctum can be modified with `\cavum`, which produces a hollow note, and `\linea`, which draws vertical lines on either side of the note.
- The virga has a descending stem on the right side. It is produced by the modifier `\virga`.

Ligatures

Unlike most other neumes notation systems, the typographical appearance of ligatures is not directly dictated by the input commands, but follows certain conventions dependent on musical meaning. For example, a three-note ligature with the musical shape low-high-low, such as `\[ a \pes b \flexa g \]`, produces a Torculus consisting of three Punctum heads, while the shape high-low-high, such as `\[ a \flexa g \pes b \]`, produces a Porrectus with a curved flexa shape and only a single Punctum head. There is no command to explicitly typeset the curved flexa shape; the decision of when to typeset a curved flexa shape is based on the musical input. The idea of this approach is to separate the musical aspects of the input from the notation style of the output. This way, the same input can be reused to typeset the same music in a different style of Gregorian chant notation.

Liquescent neumes

Another main category of notes in Gregorian chant is the so-called liquescent neumes. They are used under certain circumstances at the end of a syllable which ends in a ‘liquescent’ letter, i.e. the sounding consonants that can hold a tone (the nasals, l, r, v, j, and their diphthong equivalents). Thus, the liquescent neumes are never used alone (although some of them can be produced), and they always fall at the end of a ligature.

Liquescent neumes are represented graphically in two different, more or less interchangeable ways: with a smaller note or by ‘twisting’ the main note upwards or downwards. The first is produced by making a regular `pes` or `flexa` and modifying the shape of the second note: `\[ a \pes \deminutum b \]` , the second by modifying the shape of a single-note neume with `\auctum` and one of the direction markers `\descendens` or `\ascendens`, e.g., `\[ \auctum \descendens a \]` .

Special signs

A third category of signs is made up of a small number of signs with a special meaning (which, incidentally, in most cases is only vaguely known): the quilisma, the oriscus, and the strophicus. These are all produced by prefixing a note name with the corresponding modifier, `\quilisma`, `\oriscus`, or `\stropha`.

Virtually, within the ligature delimiters `\[` and `\]`, any number of heads may be accumulated to form a single ligature, and head prefixes like `\pes`, `\flexa`, `\virga`, `\inclinatum`, etc. may be mixed in as desired. The use of the set of rules that underlies the construction of the ligatures in the above table is accordingly extrapolated. This way, infinitely many different ligatures can be created.

Note that the use of these signs in the music itself follows certain rules, which are not checked by LilyPond. E.g., the quilisma is always the middle note of an ascending ligature, and usually falls on a half-tone step, but it is perfectly possible, although incorrect, to make a single-note quilisma.

In addition to the note signs, ‘`gregorian.ly`’ also defines the commands `\versus`, `\responsum`, `\ij`, `\iij`, `\IJ`, and `\IIJ`, that will produce the corresponding characters, e.g., for use in lyrics, as section markers, etc. These commands use special Unicode characters and will only work if a font is used which supports them.

The following table shows a limited, but still representative pool of Gregorian ligatures, together with the code fragments that produce the ligatures. The table is based on the extended neumes table of the 2nd volume of the Antiphonale Romanum (Liber Hymnarius), published 1983 by the monks of Solesmes. The first column gives the name of the ligature, with the main form in boldface and the liquescent forms in italics. The third column shows the code fragment that produces this ligature, using `g`, `a`, and `b` as example pitches.

Single-note neums

Basic and Liquescent forms | Output | LilyPond code
Punctum |  | `\[ b \]`
|  | `\[ \cavum b \]`
|  | `\[ \linea b \]`
Punctum Auctum Ascendens |  | `\[ \auctum \ascendens b \]`
Punctum Auctum Descendens |  | `\[ \auctum \descendens b \]`
Punctum inclinatum |  | `\[ \inclinatum b \]`
Punctum Inclinatum Auctum |  | `\[ \inclinatum \auctum b \]`
Punctum Inclinatum Parvum |  | `\[ \inclinatum \deminutum b \]`
Virga |  |

Two-note ligatures

Clivis vel Flexa |  | `\[ b \flexa g \]`
Clivis Aucta Descendens |  | `\[ b \flexa \auctum \descendens g \]`
Clivis Aucta Ascendens |  | `\[ b \flexa \auctum \ascendens g \]`
Cephalicus |  | `\[ b \flexa \deminutum g \]`
Podatus/Pes |  | `\[ g \pes b \]`
Pes Auctus Descendens |  | `\[ g \pes \auctum \descendens b \]`
Pes Auctus Ascendens |  | `\[ g \pes \auctum \ascendens b \]`
Epiphonus |  | `\[ g \pes \deminutum b \]`
Pes Initio Debilis |  | `\[ \deminutum g \pes b \]`
Pes Auctus Descendens Initio Debilis |  | `\[ \deminutum g \pes \auctum \descendens b \]`

Multi-note ligatures

Torculus |  | `\[ a \pes b \flexa g \]`
Torculus Auctus Descendens |  | `\[ a \pes b \flexa \auctum \descendens g \]`
Torculus Deminutus |  | `\[ a \pes b \flexa \deminutum g \]`
Torculus Initio Debilis |  | `\[ \deminutum a \pes b \flexa g \]`
Torculus Auctus Descendens Initio Debilis |  | `\[ \deminutum a \pes b \flexa \auctum \descendens g \]`
Torculus Deminutus Initio Debilis |  | `\[ \deminutum a \pes b \flexa \deminutum g \]`
Porrectus |  | `\[ a \flexa g \pes b \]`
Porrectus Auctus Descendens |  | `\[ a \flexa g \pes \auctum \descendens b \]`
Porrectus Deminutus |  | `\[ a \flexa g \pes \deminutum b \]`
Climacus |  | `\[ \virga b \inclinatum a \inclinatum g \]`
Climacus Auctus |  | `\[ \virga b \inclinatum a \inclinatum \auctum g \]`
Climacus Deminutus |  | `\[ \virga b \inclinatum a \inclinatum \deminutum g \]`
Scandicus |  | `\[ g \pes a \virga b \]`
Scandicus Auctus Descendens |  | `\[ g \pes a \pes \auctum \descendens b \]`
Scandicus Deminutus |  | `\[ g \pes a \pes \deminutum b \]`

Special Signs

Quilisma |  | `\[ g \pes \quilisma a \pes b \]`
Quilisma Pes Auctus Descendens |  | `\[ \quilisma g \pes \auctum \descendens b \]`
Oriscus |  | `\[ \oriscus b \]`
Pes Quassus |  | `\[ \oriscus g \pes \virga b \]`
Pes Quassus Auctus Descendens |  | `\[ \oriscus g \pes \auctum \descendens b \]`
Salicus |  | `\[ g \oriscus a \pes \virga b \]`
Salicus Auctus Descendens |  | `\[ g \oriscus a \pes \auctum \descendens b \]`
(Apo)stropha |  | `\[ \stropha b \]`
Stropha Aucta |  | `\[ \stropha \auctum b \]`
Bistropha |  | `\[ \stropha b \stropha b \]`
Tristropha |  | `\[ \stropha b \stropha b \stropha b \]`
Trigonus |  | `\[ \stropha b \stropha b \stropha a \]`

#### Predefined commands

The following head prefixes are supported: `\virga`, `\stropha`, `\inclinatum`, `\auctum`, `\descendens`, `\ascendens`, `\oriscus`, `\quilisma`, `\deminutum`, `\cavum`, `\linea`.

Head prefixes can be accumulated, though restrictions apply. For example, either `\descendens` or `\ascendens` can be applied to a head, but not both to the same head.

Two adjacent heads can be tied together with the `\pes` and `\flexa` infix commands for a rising and falling line of melody, respectively.

Use the unary music function `\augmentum` to add augmentum dots.

#### See also

Music Glossary: ligature.

Notation Reference: Gregorian square neume ligatures, White mensural ligatures, Ligatures.

#### Known issues and warnings

When an `\augmentum` dot appears at the end of the last staff within a ligature, it is sometimes vertically placed wrong. As a workaround, add an additional skip note (e.g., `s8`) as last note of the staff.

`\augmentum` should be implemented as a head prefix rather than a unary music function, such that `\augmentum` can be intermixed with head prefixes in arbitrary order.

### 2.9.5 Working with ancient music—scenarios and solutions

Working with ancient music frequently involves particular tasks which differ considerably from the modern notation for which LilyPond is designed. In the rest of this section, a number of typical scenarios are outlined, with suggestions of solutions. These involve:

- how to make incipits (i.e. prefatory material to indicate what the original has looked like) to modern transcriptions of mensural music;
- how to achieve the Mensurstriche layout frequently used for modern transcriptions of polyphonic music;
- how to transcribe Gregorian chant in modern notation;
- how to generate both ancient and modern notation from the same source.

#### Incipits

TBC

#### Mensurstriche layout

Mensurstriche (‘mensuration lines’) is the accepted term for bar lines that are drawn between the staves of a system but not through the staves themselves. It is a common way to preserve the rhythmic appearance of the original, i.e. not having to break syncopated notes at bar lines, while still providing the orientation aids that bar lines give.

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

#### Transcribing Gregorian chant

Gregorian chant can be transcribed into modern notation with a number of simple tweaks.

Stems. Stems can be left out altogether by `\remove`-ing the `Stem_engraver` from the Voice context:

>     \layout {
>       ...
>       \context {
>         \Voice
>           \remove "Stem_engraver"
>       }
>     }

However, in some transcription styles, stems are used occasionally, for example to indicate the transition from a single-tone recitative to a fixed melodic gesture. In these cases, one can use either `\override Stem #'transparent = ##t` or `\override Stem #'length = #0` instead, and restore the stem when needed with the corresponding `\once \override Stem #'transparent = ##f` (see example below).

Timing. For unmetered chant, there are several alternatives.

The Time_signature_engraver can be removed from the Staff context without any negative side effects. The alternative, to make it transparent, will leave an empty space in the score, since the invisible signature will still take up space.

In many cases, `\set Score.timing = ##f` will give good results. Another alternative is to use `\CadenzaOn` and `\CadenzaOff`.

To remove the bar lines, the radical approach is to `\remove` the Bar_engraver from the Staff context. Again, one may want to use `\override BarLine #'transparent = ##t` instead, if an occasional barline is wanted.

A common type of transcription is recitativic chant where the repeated notes are indicated with a single breve. The text to the recitation tone can be dealt with in two different ways: either set as a single, left-aligned syllable:

    \include "gregorian.ly"
    chant = \relative c' {
      \clef "G_8"
      c\breve c4 b4 a c2 c4  \divisioMaior
      c\breve c4 c f, f \finalis
    }

    verba = \lyricmode {
      \once \override LyricText #'self-alignment-X = #-1
      "Noctem quietam et" fi -- nem per -- fec -- tum
      \once \override LyricText #'self-alignment-X = #-1
      "concedat nobis Dominus" om -- ni -- po -- tens.
    }
    \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
        }
      }
    }

This works fine, as long as the text doesn’t span a line break. If that is the case, an alternative is to add hidden notes to the score, here in combination with changing stem visibility:

    \include "gregorian.ly"
    chant = \relative c' {
      \clef "G_8"
      \set Score.timing = ##f
      c\breve \override NoteHead #'transparent = ##t  c c c c c
      \revert NoteHead #'transparent
      \override Stem #'transparent = ##f \stemUp c4 b4 a
      \override Stem #'transparent = ##t c2 c4  \divisioMaior
      c\breve \override NoteHead #'transparent = ##t c c c c c c c
      \revert NoteHead #'transparent c4 c f, f \finalis
    }

    verba = \lyricmode {
      No -- ctem qui -- e -- tam et fi -- nem per -- fec -- tum
      con -- ce -- dat no -- bis Do -- mi -- nus om -- ni -- po -- tens.
    }

    \score {
      \new Staff <<
        \new Voice = "melody" \chant
        \new Lyrics \lyricsto "melody" \verba
      >>
      \layout {
        \context {
          \Staff
          \remove "Time_signature_engraver"
          \override BarLine #'transparent = ##t
          \override Stem #'transparent = ##t
        }
      }
    }

Another common situation is transcription of neumatic or melismatic chants, i.e. chants with a varying number of notes to each syllable. In this case, one would want to set the syllable groups clearly apart, usually also the subdivisions of a longer melisma. One way to achieve this is to use a fixed `\time`, e.g., 1/4, and let each syllable or note group fill one of these measures, with the help of tuplets or shorter durations. If the bar lines and all other rhythmical indications are made transparent, and the space around the bar lines is increased, this will give a fairly good representation in modern notation of the original.

To avoid that syllables of different width (such as “-ri” and “-rum”) spread the syllable note groups unevenly apart, the `#'X-extent` property of the `LyricText` object may be set to a fixed value. Another, more cumbersome way would be to add the syllables as `\markup` elements. If further adjustments are necessary, this can be easily done with `s` ‘notes’.

>     spiritus = \relative c' {
>       \time 1/4
>       \override Lyrics.LyricText #'X-extent  = #'(0 . 3)
>       d4 \times 2/3 { f8 a g } g a a4 g f8 e
>       d4 f8 g g8 d f g a g f4 g8 a a4  s
>       \times 2/3 { g8 f d } e f g a g4
>     }

>     spirLyr = \lyricmode {
>       Spi -- ri -- _ _ tus  _ Do -- mi -- ni  _ re -- ple -- _ vit _
>       or -- _ bem _  ter -- ra -- _ rum, al -- _ _ le -- _ lu
>       -- _ ia.
>     }
>     \score {
>       \new Staff <<
>         \new Voice = "chant" \spiritus
>         \new Lyrics = "one" \lyricsto "chant" \spirLyr
>       >>
>       \layout {
>         \context {
>           \Staff
>           \remove "Time_signature_engraver"
>           \override BarLine #'X-extent = #'(-1 . 1)
>           \override Stem #'transparent = ##t
>           \override Beam #'transparent = ##t
>           \override BarLine #'transparent = ##t
>           \override TupletNumber #'transparent = ##t
>         }
>       }
>     }

#### Ancient and modern from one source

TBC

#### Editorial markings

## 2.10 World music

The purpose of this section is to highlight musical notation issues that are relevant to traditions outside the Western tradition.

### 2.10.1 Common notation for non-Western music

This section discusses how to enter and print music scores that do not belong to the Western classical tradition, also referred to as Common Practice Period.

#### Extending notation and tuning systems

Standard classical notation (also known as Common Practice Period notation) is commonly used in all sorts of music, not limited to ‘classical’ Western music. This notation is discussed in Writing pitches, and the various note names that may be used are explained in Note names in other languages.

However, many types of non-Western music (and some types of Western folk and traditional music) employ alternative or extended tuning systems that do not fit readily into standard classical notation.

In some cases standard notation is still used, with the pitch differences being implicit. For example, Arabic music is notated with standard semitone and quarter-tone accidentals, with the precise pitch alterations being determined by context. Italian note names are typically used, while the init file ‘`arabic.ly`’ provides a suitable set of macros and definitions extending the standard notation. For more details, see Arabic music.

Other types of music require extended or unique notations. Turkish classical music or Ottoman music, for example, employs melodic forms known as makamlar, whose intervals are based on 1/9 divisions of the whole tone. Standard Western staff notes are still used, but with special accidentals unique to Turkish music, that are defined in the file ‘`makam.ly`’. For further information on Turkish classical music and makamlar, see Turkish classical music.

To locate init files such as ‘`arabic.ly`’ or ‘`makam.ly`’ on your system, see Other sources of information.

#### Selected Snippets

Makam example

Makam is a type of melody from Turkey using 1/9th-tone microtonal alterations. Consult the initialization file ‘`ly/makam.ly`’ for details of pitch names and alterations.

>     % Initialize makam settings
>     \include "makam.ly"

>     \relative c' {
>       \set Staff.keySignature = #`((6 . ,(- KOMA)) (3 . ,BAKIYE))
>       c4 cc db fk
>       gbm4 gfc gfb efk
>       fk4 db cc c
>     }

#### See also

Music Glossary: Common Practice Period, makamlar.

Learning Manual: Other sources of information.

Notation Reference: Writing pitches, Note names in other languages, Arabic music, Turkish classical music.

### 2.10.2 Arabic music

This section highlights issues that are relevant to notating Arabic music.

#### References for Arabic music

Arabic music so far has been mainly an oral tradition. When music is transcribed, it is usually in a sketch format, on which performers are expected to improvise significantly. Increasingly, Western notation, with a few variations, is adopted in order to communicate and preserve Arabic music.

Some elements of Western musical notation such as the transcription of chords or independent parts, are not required to typeset the more traditional Arabic pieces. There are however some different issues, such as the need to indicate medium intervals that are somewhere between a semi-tone and a tone, in addition to the minor and major intervals that are used in Western music. There is also the need to group and indicate a large number of different maqams (modes) that are part of Arabic music.

In general, Arabic music notation does not attempt to precisely indicate microtonal elements that are present in musical practice.

Several issues that are relevant to Arabic music are covered elsewhere:

- Note names and accidentals (including quarter tones) can be tailored as discussed in Common notation for non-Western music.
- Additional key signatures can also be tailored as described in Key signature.
- Complex time signatures may require that notes be grouped manually as described in Manual beams.
- Takasim which are rhythmically free improvisations may be written down omitting bar lines as described in Unmetered music.

#### See also

Notation Reference: Common notation for non-Western music, Key signature, Manual beams.

Snippets: World music.

#### Arabic note names

The more traditional Arabic note names can be quite long and are not suitable for the purpose of music writing, so they are not used. English note names are not very familiar in Arabic music education, so Italian or Solfege note names (`do, re, mi, fa, sol, la, si`) are used instead; modifiers (accidentals) can also be used. Italian note names and accidentals are explained in Note names in other languages; the use of standard Western notation to notate non-Western music is discussed in Common notation for non-Western music.

For example, this is how the Arabic rast scale can be notated:

>     \include "arabic.ly"
>     \relative do' {
>       do re misb fa sol la sisb do sisb la sol fa misb re do
>     }

The symbol for semi-flat does not match the symbol which is used in Arabic notation. The `\dwn` symbol defined in ‘`arabic.ly`’ may be used preceding a flat symbol as a work around if it is important to use the specific Arabic semi-flat symbol. The appearance of the semi-flat symbol in the key signature cannot be altered by using this method.

>     \include "arabic.ly"
>     \relative do' {
>       \set Staff.extraNatural = ##f
>       dod dob dosd \dwn dob dobsb dodsd do do
>     }

#### See also

Notation Reference: Note names in other languages, Common notation for non-Western music.

Snippets: World music.

#### Arabic key signatures

In addition to the minor and major key signatures, the following key signatures are defined in ‘`arabic.ly`’: bayati, rast, sikah, iraq, and kurd. These key signatures define a small number of maqam groups rather than the large number of maqams that are in common use.

In general, a maqam uses the key signature of its group, or a neighbouring group, and varying accidentals are marked throughout the music.

For example to indicate the key signature of a maqam muhayer piece:

>     \key re \bayati

Here re is the default pitch of the muhayer maqam, and bayati is the name of the base maqam in the group.

While the key signature indicates the group, it is common for the title to indicate the more specific maqam, so in this example, the name of maqam muhayer should appear in the title.

Other maqams in the same bayati group, as shown in the table below: (bayati, hussaini, saba, and ushaq) can be indicated in the same way. These are all variations of the base and most common maqam in the group, which is bayati. They usually differ from the base maqam in their upper tetrachords, or certain flow details that don’t change their fundamental nature, as siblings.

The other maqam in the same group (Nawa) is related to bayati by modulation which is indicated in the table in parenthesis for those maqams that are modulations of their base maqam. Arabic maqams admit of only limited modulations, due to the nature of Arabic musical instruments. Nawa can be indicated as follows:

>     \key sol \bayati

In Arabic music, the same term such as bayati that is used to indicate a maqam group, is also a maqam which is usually the most important in the group, and can also be thought of as a base maqam.

Here is one suggested grouping that maps the more common maqams to key signatures:

maqam group | key | finalis | Other maqmas in group (finalis)
--- | --- | --- | ---
ajam | major | sib | jaharka (fa)
bayati | bayati | re | hussaini, muhayer, saba, ushaq, nawa (sol)
hijaz | kurd | re | shahnaz, shad arban (sol), hijazkar (do)
iraq | iraq | sisb | -
kurd | kurd | re | hijazkar kurd (do)
nahawand | minor | do | busalik (re), farah faza (sol)
nakriz | minor | do | nawa athar, hisar (re)
rast | rast | do | mahur, yakah (sol)
sikah | sikah | misb | huzam

#### Selected Snippets

Non-traditional key signatures

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

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

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

#### See also

Music Glossary: maqam, bayati, rast, sikah, iraq, kurd.

Notation Reference: Key signature.

Learning Manual: Accidentals and key signatures.

Internals Reference: KeySignature.

Snippets: World music, Pitches.

#### Arabic time signatures

Some Arabic and Turkish music classical forms such as Semai use unusual time signatures such as 10/8. This may lead to an automatic grouping of notes that is quite different from existing typeset music, where notes may not be grouped on the beat, but in a manner that is difficult to match by adjusting automatic beaming. The alternative is to switch off automatic beaming and beam the notes manually. Even if a match to existing typeset music is not required, it may still be desirable to adjust the automatic beaming behaviour and/or use compound time signatures.

#### Selected Snippets

Compound time signatures

Odd 20th century time signatures (such as "5/8") can often be played as compound time signatures (e.g. "3/8 + 2/8"), which combine two or more inequal metrics. LilyPond can make such music quite easy to read and play, by explicitly printing the compound time signatures and adapting the automatic beaming behavior. (Graphic measure grouping indications can also be added; see the appropriate snippet in this database.)

>     #(define ((compound-time one two num) grob)
>        (grob-interpret-markup grob
>                               (markup #:override '(baseline-skip . 0) #:number
>                                       (#:line ((#:column (one num))
>                                                #:vcenter "+"
>                                                (#:column (two num)))))))

>     \relative c' {
>       \override Staff.TimeSignature #'stencil = #(compound-time "2" "3" "8")
>       \time 5/8
>       \set Staff.beatStructure = #'(2 3)
>       c8 d e fis gis
>       c8 fis, gis e d
>       c8 d e4 gis8
>     }

Arabic improvisation

For improvisations or taqasim which are temporarily free, the time signature can be omitted and `\cadenzaOn` can be used. Adjusting the accidental style might be required, since the absence of bar lines will cause the accidental to be marked only once. Here is an example of what could be the start of a hijaz improvisation:

>     \include "arabic.ly"

>     \relative sol' {
>       \key re \kurd
>       #(set-accidental-style 'forget)
>       \cadenzaOn
>       sol4 sol sol sol fad mib sol1 fad8 mib re4. r8 mib1 fad sol
>     }

#### See also

Music Glossary: semai, taqasim.

Notation Reference: Manual beams, Automatic beams, Unmetered music, Automatic accidentals, Setting automatic beam behavior, Time signature.

Snippets: World music.

#### Arabic music example

Here is a template that also uses the start of a Turkish Semai that is familiar in Arabic music education in order to illustrate some of the peculiarities of Arabic music notation, such as medium intervals and unusual modes that are discussed in this section.

>     \include "arabic.ly"
>     \score {
>       \relative re' {
>         \set Staff.extraNatural = ##f
>         \set Staff.autoBeaming = ##f
>         \key re \bayati
>         \time 10/8

>         re4 re'8 re16 [misb re do] sisb [la sisb do] re4 r8
>         re16 [misb do re] sisb [do] la [sisb sol8] la [sisb] do [re] misb
>         fa4 fa16 [misb] misb8. [re16] re8 [misb] re  [do] sisb
>         do4 sisb8 misb16 [re do sisb] la [do sisb la] la4 r8
>       }
>       \header {
>         title = "Semai Muhayer"
>         composer = "Jamil Bek"
>       }
>     }

#### See also

Snippets: World music.

#### Further reading for Arabic music

1. The music of the Arabs by Habib Hassan Touma [Amadeus Press, 1996], contains a discussion of maqams and their method of groupings.

   There are also various web sites that explain maqams and some provide audio examples such as :

   - http://www.maqamworld.com/
   - http://www.turath.org/

   There are some variations in the details of how maqams are grouped, despite agreement on the criteria of grouping maqams that are related through common lower tetra chords, or through modulation.

2. There is not a complete consistency, sometimes even in the same text on how key signatures for particular maqams should be specified. It is common, however, to use a key signature per group, rather than a different key signature for each different maqam.

   Method books by the following authors for the Oud, the Arabic lute, contain examples of mainly Turkish and Arabic compositions.

   - Charbel Rouhana
   - George Farah
   - Ibrahim Ali Darwish Al-masri

### 2.10.3 Turkish classical music

This section highlights issues that are relevant to notating Turkish classical music.

#### References for Turkish classical music

Turkish classical music developed in the Ottoman Empire in a period roughly contemporaneous with classical music in Europe, and has continued on into the 20th and 21st centuries as a vibrant and distinct tradition with its own compositional forms, theory and performance styles. Among its striking features is the use of microtonal intervals based on ‘commas’ of 1/9 of a tone, from which are constructed the melodic forms known as makam (plural makamlar).

Some issues relevant to Turkish classical music are covered elsewhere:

- Special note names and accidentals are explained in Common notation for non-Western music.

#### Turkish note names

Pitches in Turkish classical music traditionally have unique names, and the basis of pitch on 1/9-tone divisions means makamlar employ a completely different set of intervals from Western scales and modes: koma (1/9 of a tone), eksik bakiye (3/9), bakiye (4/9), kücük mücenneb (5/9), büyük mücenneb (8/9), tanîni (a whole tone) and artık ikili (12/9 or 13/9 of a tone).

From a modern notational point of view it is convenient to use the standard Western staff notes (c, d, e, ...) with special accidentals that raise or lower notes by intervals of 1/9, 4/9, 5/9 and 8/9 of a tone. These accidentals are defined in the file ‘`makam.ly`’.

The following table lists:

- the name of these special accidentals,
- the accidental suffix that must be added to notes,
- and their pitch alteration as a fraction of one whole tone.

> Accidental name | suffix | pitch alteration
> --- | --- | ---
> büyük mücenneb (sharp) | -bm | +8/9
> kücük mücenneb (sharp) | -k | +5/9
> bakiye (sharp) | -b | +4/9
> koma (sharp) | -c | +1/9
> koma (flat) | -fc | -1/9
> bakiye (flat) | -fb | -4/9
> kücük mücenneb (flat) | -fk | -5/9
> büyük mücenneb (flat) | -fbm | -8/9

For a more general explanation of non-Western music notation, see Common notation for non-Western music.

#### See also

Music Glossary: makam, makamlar.

Notation Reference: Common notation for non-Western music.

# 3. General input and output

This section deals with general LilyPond input and output issues, rather than specific notation.

## 3.1 Input structure

The main format of input for LilyPond are text files. By convention, these files end with ‘`.ly`’.

### 3.1.1 Structure of a score

A `\score` block must contain a single music expression delimited by curly brackets:

>     \score {
>     ...
>     }

Note: There must be only one outer music expression in a `score` block, and it must be surrounded by curly brackets.

This single music expression may be of any size, and may contain other music expressions to any complexity. All of these examples are music expressions:

>     { c'4 c' c' c' }

>     {
>       { c'4 c' c' c' }
>       { d'4 d' d' d' }
>     }

>     <<
>       \new Staff { c'4 c' c' c' }
>       \new Staff { d'4 d' d' d' }
>     >>

>     {
>       \new GrandStaff <<
>         \new StaffGroup <<
>           \new Staff { \flute }
>           \new Staff { \oboe }
>         >>
>         \new StaffGroup <<
>           \new Staff { \violinI }
>           \new Staff { \violinII }
>         >>
>       >>
>     }

Comments are one exception to this general rule. (For others see File structure.) Both single-line comments and comments delimited by `%{ .. %}` may be placed anywhere within an input file. They may be placed inside or outside a `\score` block, and inside or outside the single music expression within a `\score` block.

Remember that even in a file containing only a `\score` block, it is implicitly enclosed in a \book block. A \book block in a source file produces at least one output file, and by default the name of the output file produced is derived from the name of the input file, so ‘`fandangoforelephants.ly`’ will produce ‘`fandangoforelephants.pdf`’.

(For more details about `\book` blocks, see Multiple scores in a book, Multiple output files from one input file File structure.)

#### See also

Learning Manual: Working on input files, Music expressions explained, Score is a (single) compound musical expression.

### 3.1.2 Multiple scores in a book

A document may contain multiple pieces of music and text. Examples of these are an etude book, or an orchestral part with multiple movements. Each movement is entered with a `\score` block,

>     \score {
>       ..music..
>     }

and texts are entered with a `\markup` block,

>     \markup {
>       ..text..
>     }

All the movements and texts which appear in the same ‘`.ly`’ file will normally be typeset in the form of a single output file.

>     \score {
>       ..
>     }
>     \markup {
>       ..
>     }
>     \score {
>       ..
>     }

One important exception is within lilypond-book documents, where you explicitly have to add a `\book` block, otherwise only the first `\score` or `\markup` will appear in the output.

The header for each piece of music can be put inside the `\score` block. The `piece` name from the header will be printed before each movement. The title for the entire book can be put inside the `\book`, but if it is not present, the `\header` which is at the top of the file is inserted.

>     \header {
>       title = "Eight miniatures"
>       composer = "Igor Stravinsky"
>     }
>     \score {
>       …
>       \header { piece = "Romanze" }
>     }
>     \markup {
>        ..text of second verse..
>     }
>     \markup {
>        ..text of third verse..
>     }
>     \score {
>       …
>       \header { piece = "Menuetto" }
>     }

Pieces of music may be grouped into book parts using `\bookpart` blocks. Book parts are separated by a page break, and can start with a title, like the book itself, by specifying a `\header` block.

>     \bookpart {
>       \header {
>         title = "Book title"
>         subtitle = "First part"
>       }
>       \score { … }
>       …
>     }
>     \bookpart {
>       \header {
>         subtitle = "Second part"
>       }
>       \score { … }
>       …
>     }

### 3.1.3 Multiple output files from one input file

If you want multiple output files from the same ‘`.ly`’ file, then you can add multiple `\book` blocks, where each such \book block will result in a separate output file. If you do not specify any `\book` block in the input file, LilyPond will implicitly treat the whole file as a single \book block, see File structure.

When producing multiple files from a single source file, Lilypond ensures that none of the output files from any `\book` block overwrites the output file produced by a preceding `\book` from the same input file.

It does this by adding a suffix to the output name for each `\book` which uses the default output file name derived from the input source file.

The default behaviour is to append a version-number suffix for each name which may clash, so

>     \book {
>       \score { … }
>       \layout { … }
>     }
>     \book {
>       \score { … }
>       \layout { … }
>     }
>     \book {
>       \score { … }
>       \layout { … }
>     }

in source file ‘`eightminiatures.ly`’ will produce

- ‘`eightminiatures.pdf`’,
- ‘`eightminiatures-1.pdf`’ and
- ‘`eightminiatures-2.pdf`’.

### 3.1.4 Output file names

Lilypond provides facilities to allow you to control what file names are used by the various back-ends when producing output files.

In the previous section, we saw how Lilypond prevents name-clashes when producing several ouputs from a single source file. You also have the ability to specify your own suffixes for each `\book` block, so for example you can produce files called ‘`eightminiatures-Romanze.pdf`’, ‘`eightminiatures-Menuetto.pdf`’ and ‘`eightminiatures-Nocturne.pdf`’ by adding a `\bookOutputSuffix` declaration inside each `\book` block.

>     \book {
>       \bookOutputSuffix "Romanze"
>       \score { … }
>       \layout { … }
>     }
>     \book {
>       \bookOutputSuffix "Menuetto"
>       \score { … }
>       \layout { … }
>     }
>     \book {
>       \bookOutputSuffix "Nocturne"
>       \score { … }
>       \layout { … }
>     }

You can also specify a different output filename for `book` block, by using `\bookOutputName` declarations

>     \book {
>       \bookOutputName "Romanze"
>       \score { … }
>       \layout { … }
>     }
>     \book {
>       \bookOutputName "Menuetto"
>       \score { … }
>       \layout { … }
>     }
>     \book {
>       \bookOutputName "Nocturne"
>       \score { … }
>       \layout { … }
>     }

The file above will produce these output files:

- ‘`Romanze.pdf`’,
- ‘`Menuetto.pdf`’ and
- ‘`Nocturne.pdf`’.

### 3.1.5 File structure

A ‘`.ly`’ file may contain any number of toplevel expressions, where a toplevel expression is one of the following:

- An output definition, such as `\paper`, `\midi`, and `\layout`. Such a definition at the toplevel changes the default book-wide settings. If more than one such definition of the same type is entered at the top level any definitions in the later expressions have precedence.
- A direct scheme expression, such as `#(set-default-paper-size "a7" 'landscape)` or `#(ly:set-option 'point-and-click #f)`.
- A `\header` block. This sets the global header block. This is the block containing the definitions for book-wide settings, like composer, title, etc.
- A `\score` block. This score will be collected with other toplevel scores, and combined as a single `\book`. This behavior can be changed by setting the variable `toplevel-score-handler` at toplevel. The default handler is defined in the init file ‘`../scm/lily.scm`’.
- A `\book` block logically combines multiple movements (i.e., multiple `\score` blocks) in one document. If there are a number of `\score`s, one output file will be created for each `\book` block, in which all corresponding movements are concatenated. The only reason to explicitly specify `\book` blocks in a ‘`.ly`’ file is if you wish to create multiple output files from a single input file. One exception is within lilypond-book documents, where you explicitly have to add a `\book` block if you want more than a single `\score` or `\markup` in the same example. This behavior can be changed by setting the variable `toplevel-book-handler` at toplevel. The default handler is defined in the init file ‘`../scm/lily.scm`’.
- A `\bookpart` block. A book may be divided into several parts, using `\bookpart` blocks, in order to ease the page breaking, or to use different `\paper` settings in different parts.
- A compound music expression, such as

  >     { c'4 d' e'2 }

  This will add the piece in a `\score` and format it in a single book together with all other toplevel `\score`s and music expressions. In other words, a file containing only the above music expression will be translated into

  >     \book {
  >       \score {
  >         \new Staff {
  >           \new Voice {
  >             { c'4 d' e'2 }
  >           }
  >         }
  >       }
  >     	\layout { }
  >     	\header { }
  >     }

  This behavior can be changed by setting the variable `toplevel-music-handler` at toplevel. The default handler is defined in the init file ‘`../scm/lily.scm`’.

- A markup text, a verse for example

  >     \markup {
  >        2.  The first line verse two.
  >     }

  Markup texts are rendered above, between or below the scores or music expressions, wherever they appear.

- A variable, such as

  >     foo = { c4 d e d }

  This can be used later on in the file by entering `\foo`. The name of a variable should have alphabetic characters only; no numbers, underscores or dashes.

The following example shows three things that may be entered at toplevel

>     \layout {
>       % Don't justify the output
>       ragged-right = ##t
>     }

>     \header {
>        title = "Do-re-mi"
>     }

>     { c'4 d' e2 }

At any point in a file, any of the following lexical instructions can be entered:

- `\version`
- `\include`
- `\sourcefilename`
- `\sourcefileline`
- A single-line comment, introduced by a leading `%` sign.
- A multi-line comment delimited by `%{ .. %}`.

Whitespace between items in the input stream is generally ignored, and may be freely omitted or extended to enhance readability. However, whitespace should always be used in the following circumstances to avoid errors:

- Around every opening and closing curly bracket.
- After every command or variable, i.e. every item that begins with a `\` sign.
- After every item that is to be interpreted as a Scheme expression, i.e. every item that begins with a `#` sign.
- To separate all elements of a Scheme expression.
- In `lyricmode` to separate all the terms in both `\override` and `\set` commands. In particular, spaces must be used around the dot and the equals sign in commands like `\override Score . LyricText #'font-size = #5` and before and after the entire command.

#### See also

Learning Manual: How LilyPond input files work.

## 3.2 Titles and headers

Almost all printed music includes a title and the composer’s name; some pieces include a lot more information.

### 3.2.1 Creating titles, headers, and footers

#### Title blocks explained

There are two types of title blocks: the main title block that appears above of the first `\score` of a book, and individual title blocks that appear within each `\score` block. Text fields for both types are entered using a `\header` block.

If the book only has a single score, the `\header` block may be placed inside or outside of the `\score` block.

Note: Remember when adding a \`header` block inside a \`score` block, that the music expression must come before the \`header` block.

>     \header {
>       title = "SUITE I."
>       composer = "J. S. Bach."
>     }

>     \score {
>       \new Staff \relative g, {
>         \clef bass
>         \key g \major
>         \repeat unfold 2 { g16( d' b') a b d, b' d, } |
>         \repeat unfold 2 { g,16( e' c') b c e, c' e, } |
>       }
>       \header {
>         piece = "Prélude."
>       }
>     }

>     \score {
>       \new Staff \relative b {
>         \clef bass
>         \key g \major
>         \partial 16 b16 |
>         <g, d' b'~>4 b'16 a( g fis) g( d e fis) g( a b c) |
>         d16( b g fis) g( e d c) b(c d e) fis( g a b) |
>       }
>       \header {
>         piece = "Allemande."
>       }
>     }

Text fields from the main title block of a book can be displayed in all `\score` blocks, or manually suppressed:

>     \book {
>       \paper {
>         print-all-headers = ##t
>       }
>       \header {
>         title = "DAS WOHLTEMPERIRTE CLAVIER"
>         subtitle = "TEIL I"
>         % Do not display the tagline for this book
>         tagline = ##f
>       }
>       \markup { \vspace #1 }
>       \score {
>         \new PianoStaff <<
>           \new Staff { s1 }
>           \new Staff { \clef "bass" s1 }
>         >>
>         \header {
>           title = "PRAELUDIUM I"
>           opus = "BWV 846"
>           % Do not display the subtitle for this score
>           subtitle = ##f
>         }
>       }
>       \score {
>         \new PianoStaff <<
>           \new Staff { s1 }
>           \new Staff { \clef "bass" s1 }
>         >>
>         \header {
>           title = "FUGA I"
>           subsubtitle = "A 4 VOCI"
>           opus = "BWV 846"
>           % Do not display the subtitle for this score
>           subtitle = ##f
>         }
>       }
>     }

#### See also

Notation Reference: File structure, Custom layout for title blocks.

#### Default layout of book and score title blocks

The layout and formatting of title blocks are controlled by two `\paper` variables; `bookTitleMarkup` for the main `\header` title block and `scoreTitleMarkup` for individual `\header` blocks within a `\score`.

>     \header {
>       % The following fields are centered
>       dedication = "Dedication"
>       title = "Title"
>       subtitle = "Subtitle"
>       subsubtitle = "Subsubtitle"
>       instrument = "Instrument"

>       % The following fields are left-aligned on the left side
>       poet = "Poet"
>       meter = "Meter"

>       % The following fields are right-aligned on the right side
>       composer = "Composer"
>       arranger = "Arranger"
>     }

>     \score {
>       { s1 }
>       \header {
>         % The following fields are placed at opposite ends of the same line
>         piece = "Piece"
>         opus = "Opus"
>       }
>     }

Text fields left unset in a `\header` block are replaced with `\null` markups so that the space is not wasted.

The default settings for `scoreTitleMarkup` place the `piece` and `opus` text fields at opposite ends of the same line.

Use the `breakbefore` variable inside a `\header` block that is itself in a `\score` block, to make the top-level `\header` block titles appear on the first page on their own, with the music (defined in the `\score` block) starting on the next.

    \book {
      \header {
        title = "This is my Title"
        subtitle = "This is my Subtitle"
        copyright = "This is the bottom of the first page"
      }
      \score {
        \repeat unfold 4 { e'' e'' e'' e'' }
        \header {
          piece = "This is the Music"
          breakbefore = ##t
        }
      }
    }

#### See also

Learning Manual: How LilyPond input files work,

Notation Reference: File structure.

Installed Files: ‘`ly/titling-init.ly`’.

#### Default layout of headers and footers

Headers and footers are lines of text appearing at the top and bottom of pages, separate from the main text of a book. They are controlled by the following `\paper` variables:

- `oddHeaderMarkup`
- `evenHeaderMarkup`
- `oddFooterMarkup`
- `evenFooterMarkup`

These markup variables can only access text fields from top-level `\header` blocks (which apply to all scores in the book) and are defined in ‘`ly/titling-init.ly`’. By default:

- page numbers are automatically placed on the top far left (if even) or top far right (if odd), starting from the second page.
- the `instrument` text field is placed in the center of every page, starting from the second page.
- the `copyright` text is centered on the bottom of the first page.
- the `tagline` is centered on the bottom of the last page, and below the `copyright` text if there is only a single page.

The default tagline can be changed by adding a `tagline` in the top-level `\header` block.

    \book {
      \header {
        tagline = "... music notation for Everyone"
      }
      \score {
        \relative c' {
          c4 d e f
        }
      }
    }

To remove the `tagline` set the value to `##f`.

### 3.2.2 Custom headers, footers, and titles

#### Custom text formatting for title blocks

Standard `\markup` commands can be used to customize any header, footer and title text within the `\header` block.

>     \score {
>       { s1 }
>       \header {
>         piece = \markup { \fontsize #4 \bold "PRAELUDIUM I" }
>         subtitle = \markup { \italic "(Excerpt)" }
>       }
>     }

#### See also

Notation Reference: Formatting text.

#### Custom layout for title blocks

`\markup` commands in the `\header` block are useful for simple text formatting, but they do not allow precise control over the placement of titles. To customize the placement of the text fields, use either or both of the following `\paper` variables:

- `bookTitleMarkup`
- `scoreTitleMarkup`

These markup variables are discussed in Default layout of book and score title blocks.

The default settings for `scoreTitleMarkup` as defined in ‘`ly/titling-init.ly`’ are:

>     scoreTitleMarkup = \markup { \column {
>       \on-the-fly #print-all-headers { \bookTitleMarkup \hspace #1 }
>       \fill-line {
>         \fromproperty #'header:piece
>         \fromproperty #'header:opus
>       }
>     }
>     }

This places the `piece` and `opus` text fields at opposite ends of the same line:

>     \score {
>       { s1 }
>       \header {
>         piece = "PRAELUDIUM I"
>         opus = "BWV 846"
>       }
>     }

This example redefines `scoreTitleMarkup` so that the `piece` text field is centered and in a large, bold font.

>     \book {
>       \paper {
>         indent = 0\mm
>         scoreTitleMarkup = \markup {
>           \fill-line {
>             \null
>             \fontsize #4 \bold \fromproperty #'header:piece
>             \fromproperty #'header:opus
>           }
>         }
>       }
>       \header { tagline = ##f }
>       \score {
>         { s1 }
>         \header {
>           piece = "PRAELUDIUM I"
>           opus = "BWV 846"
>         }
>       }
>     }

Text fields normally reserved for the main title block can be included in individual score title blocks with the `print-all-headers` placed inside the `\paper` block. A disadvantage of using this method is that the text fields that are intended specifically for the top-level `\header` block need to be manually suppressed in every `\score` block. See Title blocks explained.

To avoid this, add the desired text field to the `scoreTitleMarkup` definition. In the following example, the `composer` text field (normally associated with `bookTitleMarkup`) is added to `scoreTitleMarkup`, allowing each score to list a different composer:

>     \book {
>       \paper {
>         indent = 0\mm
>         scoreTitleMarkup = \markup {
>           \fill-line {
>             \null
>             \fontsize #4 \bold \fromproperty #'header:piece
>             \fromproperty #'header:composer
>           }
>         }
>       }
>       \header { tagline = ##f }
>       \score {
>         { s1 }
>         \header {
>           piece = "MENUET"
>           composer = "Christian Petzold"
>         }
>       }
>       \score {
>         { s1 }
>         \header {
>           piece = "RONDEAU"
>           composer = "François Couperin"
>         }
>       }
>     }

It is also possible to create your own custom text fields, and refer to them in the markup definition.

>     \book {
>       \paper {
>         indent = 0\mm
>         scoreTitleMarkup = \markup {
>           \fill-line {
>             \null
>             \override #`(direction . ,UP) {
>               \dir-column {
>                 \center-align \fontsize #-1 \bold
>                   \fromproperty #'header:mycustomtext %% User-defined field
>                 \center-align \fontsize #4 \bold
>                   \fromproperty #'header:piece
>               }
>             }
>             \fromproperty #'header:opus
>           }
>         }
>       }
>       \header { tagline = ##f }
>       \score {
>         { s1 }
>         \header {
>           piece = "FUGA I"
>           mycustomtext = "A 4 VOCI" %% User-defined field
>           opus = "BWV 846"
>         }
>       }
>     }

#### Custom layout for headers and footers

`\markup` commands in the `\header` block are useful for simple text formatting, but they do not allow precise control over the placement of headers and footers. To customize the placement of the text fields, use either or both of the following `\paper` variables:

- `oddHeaderMarkup`
- `evenHeaderMarkup`
- `oddFooterMarkup`
- `evenFooterMarkup`

These markup variables are discussed in Default layout of book and score title blocks.

The following example centers page numbers at the bottom of every page. First, the default settings for `oddHeaderMarkup` and `evenHeaderMarkup` are removed by defining each as a null markup. Then, `oddFooterMarkup` is redefined with the page number centered. Finally, `evenFooterMarkup` is given the same layout by defining it as `\oddFooterMarkup`:

>     \book {
>       \paper {
>         print-page-number = ##t
>         print-first-page-number = ##t
>         oddHeaderMarkup = \markup \null
>         evenHeaderMarkup = \markup \null
>         oddFooterMarkup = \markup {
>           \fill-line {
>             \on-the-fly #print-page-number-check-first
>             \fromproperty #'page:page-number-string
>           }
>         }
>         evenFooterMarkup = \oddFooterMarkup
>       }
>       \score {
>         \new Staff { s1 \break s1 \break s1 }
>       }
>     }

### 3.2.3 Reference to page numbers

A particular place of a score can be marked using the `\label` command, either at top-level or inside music. This label can then be referred to in a markup, to get the number of the page where the marked point is placed, using the `\page-ref` markup command.

    \header { tagline = ##f }
    \book {
      \label #'firstScore
      \score {
        {
          c'1
          \pageBreak \mark A \label #'markA
          c'1
        }
      }
      \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
      \markup { Mark A is on page \page-ref #'markA "0" "?" }
    }

The `\page-ref` markup command takes three arguments:

1. the label, a scheme symbol, eg. `#'firstScore`;
2. a markup that will be used as a gauge to estimate the dimensions of the markup;
3. a markup that will be used in place of the page number if the label is not known;

The reason why a gauge is needed is that, at the time markups are interpreted, the page breaking has not yet occurred, so the page numbers are not yet known. To work around this issue, the actual markup interpretation is delayed to a later time; however, the dimensions of the markup have to be known before, so a gauge is used to decide these dimensions. If the book has between 10 and 99 pages, it may be "00", ie. a two digit number.

#### Predefined commands

`\label`, `\page-ref`.

### 3.2.4 Table of contents

A table of contents is included using the `\markuplines \table-of-contents` command. The elements which should appear in the table of contents are entered with the `\tocItem` command, which may be used either at top-level, or inside a music expression.

    \markuplines \table-of-contents
    \pageBreak

    \tocItem \markup "First score"
    \score {
      {
        c'4  % ...
        \tocItem \markup "Some particular point in the first score"
        d'4  % ...
      }
    }

    \tocItem \markup "Second score"
    \score {
      {
        e'4 % ...
      }
    }

The markups which are used to format the table of contents are defined in the `\paper` block. The default ones are `tocTitleMarkup`, for formatting the title of the table, and `tocItemMarkup`, for formatting the toc elements, composed of the element title and page number. These variables may be changed by the user:

    \paper {
      %% Translate the toc title into French:
      tocTitleMarkup = \markup \huge \column {
        \fill-line { \null "Table des matières" \null }
        \hspace #1
      }
      %% use larger font size
      tocItemMarkup = \markup \large \fill-line {
        \fromproperty #'toc:text \fromproperty #'toc:page
      }
    }

Note how the toc element text and page number are referred to in the `tocItemMarkup` definition.

New commands and markups may also be defined to build more elaborated table of contents:

- first, define a new markup variable in the `\paper` block
- then, define a music function which aims at adding a toc element using this markup paper variable.

In the following example, a new style is defined for entering act names in the table of contents of an opera:

    \paper {
      tocActMarkup = \markup \large \column {
        \hspace #1
        \fill-line { \null \italic \fromproperty #'toc:text \null }
        \hspace #1
      }
    }

    tocAct =
    #(define-music-function (parser location text) (markup?)
       (add-toc-item! 'tocActMarkup text))

Dots can be added to fill the line between an item and its page number:

>     \header { tagline = ##f }
>     \paper {
>       tocItemMarkup = \tocItemWithDotsMarkup
>     }

>     \book {
>       \markuplines \table-of-contents
>       \tocItem \markup { Allegro }
>       \tocItem \markup { Largo }
>       \markup \null
>     }

#### See also

Init files: ‘`../ly/toc-init.ly`’.

#### Predefined commands

`\table-of-contents`, `\tocItem`.

## 3.3 Working with input files

### 3.3.1 Including LilyPond files

A large project may be split up into separate files. To refer to another file, use

>     \include "otherfile.ly"

The line `\include "otherfile.ly"` is equivalent to pasting the contents of ‘`otherfile.ly`’ into the current file at the place where the `\include` appears. For example, in a large project you might write separate files for each instrument part and create a “full score” file which brings together the individual instrument files. Normally the included file will define a number of variables which then become available for use in the full score file. Tagged sections can be marked in included files to assist in making them usable in different places in a score, see Different editions from one source.

Files in the current working directory may be referenced by specifying just the file name after the `\include` command. Files in other locations may be included by giving either a full path reference or a relative path reference (but use the UNIX forward slash, /, rather than the DOS/Windows back slash, \, as the directory separator.) For example, if ‘`stuff.ly`’ is located one directory higher than the current working directory, use

>     \include "../stuff.ly"

or if the included orchestral parts files are all located in a subdirectory called ‘`parts`’ within the current directory, use

>     \include "parts/VI.ly"
>     \include "parts/VII.ly"
>     ... etc

Files which are to be included can also contain `\include` statements of their own. By default, these second-level `\include` statements are not interpreted until they have been brought into the main file, so the file names they specify must all be relative to the directory containing the main file, not the directory containing the included file. However, this behavior can be changed by passing the option `-drelative-includes` option at the command line (or by adding `#(ly:set-option 'relative-includes #t)` at the top of the main input file). With `relative-includes` set, the path for each `\include` command will be taken relative to the file containing that command. This behavior is recommended and it will become the default behavior in a future version of lilypond.

Files can also be included from a directory in a search path specified as an option when invoking LilyPond from the command line. The included files are then specified using just their file name. For example, to compile ‘`main.ly`’ which includes files located in a subdirectory called ‘`parts`’ by this method, cd to the directory containing ‘`main.ly`’ and enter

>     lilypond --include=parts main.ly

and in main.ly write

>     \include "VI.ly"
>     \include "VII.ly"
>     ... etc

Files which are to be included in many scores may be placed in the LilyPond directory ‘`../ly`’. (The location of this directory is installation-dependent - see Other sources of information). These files can then be included simply by naming them on an `\include` statement. This is how the language-dependent files like ‘`english.ly`’ are included.

LilyPond includes a number of files by default when you start the program. These includes are not apparent to the user, but the files may be identified by running `lilypond --verbose` from the command line. This will display a list of paths and files that LilyPond uses, along with much other information. Alternatively, the more important of these files are discussed in Other sources of information. These files may be edited, but changes to them will be lost on installing a new version of LilyPond.

Some simple examples of using `\include` are shown in Scores and parts.

#### See also

Learning Manual: Other sources of information, Scores and parts.

#### Known issues and warnings

If an included file is given a name which is the same as one in LilyPond’s installation files, LilyPond’s file from the installation files takes precedence.

### 3.3.2 Different editions from one source

Several mechanisms are available to facilitate the generation of different versions of a score from the same music source. Variables are perhaps most useful for combining lengthy sections of music and/or annotation in various ways, while tags are more useful for selecting one from several alternative shorter sections of music. Whichever method is used, separating the notation from the structure of the score will make it easier to change the structure while leaving the notation untouched.

#### Using variables

If sections of the music are defined in variables they can be reused in different parts of the score, see pieces with variables Organizing pieces with variables. For example, an a cappella vocal score frequently includes a piano reduction of the parts for rehearsal purposes which is identical to the vocal music, so the music need be entered only once. Music from two variables may be combined on one staff, see Automatic part combining. Here is an example:

>     sopranoMusic = \relative c'' { a4 b c b8( a) }
>     altoMusic = \relative g' { e4 e e f }
>     tenorMusic = \relative c' { c4 b e d8( c) }
>     bassMusic = \relative c' { a4 gis a d, }
>     allLyrics = \lyricmode {King of glo -- ry }
>     <<
>       \new Staff = "Soprano" \sopranoMusic
>       \new Lyrics \allLyrics
>       \new Staff = "Alto" \altoMusic
>       \new Lyrics \allLyrics
>       \new Staff = "Tenor" {
>         \clef "treble_8"
>         \tenorMusic
>       }
>       \new Lyrics \allLyrics
>       \new Staff = "Bass" {
>         \clef "bass"
>         \bassMusic
>       }
>       \new Lyrics \allLyrics
>       \new PianoStaff <<
>         \new Staff = "RH" {
>           \set Staff.printPartCombineTexts = ##f
>           \partcombine
>           \sopranoMusic
>           \altoMusic
>         }
>         \new Staff = "LH" {
>           \set Staff.printPartCombineTexts = ##f
>           \clef "bass"
>           \partcombine
>           \tenorMusic
>           \bassMusic
>         }
>       >>
>     >>

Separate scores showing just the vocal parts or just the piano part can be produced by changing just the structural statements, leaving the musical notation unchanged.

For lengthy scores, the variable definitions may be placed in separate files which are then included, see Including LilyPond files.

#### Using tags

The `\tag #'partA` command marks a music expression with the name partA. Expressions tagged in this way can be selected or filtered out by name later, using either `\keepWithTag #'name` or `\removeWithTag #'name`. The result of applying these filters to tagged music is as follows:

Filter | Result
--- | ---
Tagged music preceded by `\keepWithTag #'name` | Untagged music and music tagged with name is included; music tagged with any other tag name is excluded.
Tagged music preceded by `\removeWithTag #'name` | Untagged music and music tagged with any tag name other than name is included; music tagged with name is excluded.
Tagged music not preceded by either `\keepWithTag` or `\removeWithTag` | All tagged and untagged music is included.

The arguments of the `\tag`, `\keepWithTag` and `\removeWithTag` commands should be a symbol (such as `#'score` or `#'part`), followed by a music expression.

In the following example, we see two versions of a piece of music, one showing trills with the usual notation, and one with trills explicitly expanded:

>     music = \relative g' {
>       g8. c32 d
>       \tag #'trills { d8.\trill }
>       \tag #'expand { \repeat unfold 3 { e32 d } }
>       c32 d
>      }

>     \score {
>       \keepWithTag #'trills \music
>     }
>     \score {
>       \keepWithTag #'expand \music
>     }

Alternatively, it is sometimes easier to exclude sections of music:

>     music = \relative g' {
>       g8. c32 d
>       \tag #'trills { d8.\trill }
>       \tag #'expand {\repeat unfold 3 { e32 d } }
>       c32 d
>      }

>     \score {
>       \removeWithTag #'expand
>       \music
>     }
>     \score {
>       \removeWithTag #'trills
>       \music
>     }

Tagged filtering can be applied to articulations, texts, etc. by prepending

>     -\tag #'your-tag

to an articulation. For example, this would define a note with a conditional fingering indication and a note with a conditional annotation:

>     c1-\tag #'finger ^4
>     c1-\tag #'warn ^"Watch!"

Multiple tags may be placed on expressions with multiple `\tag` entries:

>     music = \relative c'' {
>       \tag #'a \tag #'both { a4 a a a }
>       \tag #'b \tag #'both { b4 b b b }
>     }
>     <<
>     \keepWithTag #'a \music
>     \keepWithTag #'b \music
>     \keepWithTag #'both \music
>     >>

Multiple `\removeWithTag` filters may be applied to a single music expression to remove several differently named tagged sections:

>     music = \relative c'' {
>     \tag #'A { a4 a a a }
>     \tag #'B { b4 b b b }
>     \tag #'C { c4 c c c }
>     \tag #'D { d4 d d d }
>     }
>     {
>     \removeWithTag #'B
>     \removeWithTag #'C
>     \music
>     }

Two or more `\keepWithTag` filters applied to a single music expression will cause all tagged sections to be removed, as the first filter will remove all tagged sections except the one named, and the second filter will remove even that tagged section.

#### See also

Learning Manual: Organizing pieces with variables.

Notation Reference: Automatic part combining, Including LilyPond files.

#### Using global settings

Global settings can be included from a separate file:

>     lilypond -dinclude-settings=MY_SETTINGS.ly MY_SCORE.ly

Groups of settings such as page size, font or type face can be stored in separate files. This allows different editions from the same score as well as standard settings to be applied to many scores, simply by specifying the proper settings file.

This technique also works well with the use of style sheets, as discussed in Style sheets.

#### See also

Learning Manual: Organizing pieces with variables, Style sheets.

Notation Reference: Including LilyPond files.

### 3.3.3 Text encoding

LilyPond uses the character repertoire defined by the Unicode consortium and ISO/IEC 10646. This defines a unique name and code point for the character sets used in virtually all modern languages and many others too. Unicode can be implemented using several different encodings. LilyPond uses the UTF-8 encoding (UTF stands for Unicode Transformation Format) which represents all common Latin characters in one byte, and represents other characters using a variable length format of up to four bytes.

The actual appearance of the characters is determined by the glyphs defined in the particular fonts available - a font defines the mapping of a subset of the Unicode code points to glyphs. LilyPond uses the Pango library to layout and render multi-lingual texts.

LilyPond does not perform any input-encoding conversions. This means that any text, be it title, lyric text, or musical instruction containing non-ASCII characters, must be encoded in UTF-8. The easiest way to enter such text is by using a Unicode-aware editor and saving the file with UTF-8 encoding. Most popular modern editors have UTF-8 support, for example, vim, Emacs, jEdit, and GEdit do. All MS Windows systems later than NT use Unicode as their native character encoding, so even Notepad can edit and save a file in UTF-8 format. A more functional alternative for Windows is BabelPad.

If a LilyPond input file containing a non-ASCII character is not saved in UTF-8 format the error message

>     FT_Get_Glyph_Name () error: invalid argument

will be generated.

Here is an example showing Cyrillic, Hebrew and Portuguese text:

To enter a single character for which the Unicode code point is known but which is not available in the editor being used, use either `\char ##xhhhh` or `\char #dddd` within a `\markup` block, where `hhhh` is the hexadecimal code for the character required and `dddd` is the corresponding decimal value. Leading zeroes may be omitted, but it is usual to specify all four characters in the hexadecimal representation. (Note that the UTF-8 encoding of the code point should not be used after `\char`, as UTF-8 encodings contain extra bits indicating the number of octets.) Unicode code charts and a character name index giving the code point in hexadecimal for any character can be found on the Unicode Consortium website, http://www.unicode.org/.

For example, `\char ##x03BE` and `\char #958` would both enter the Unicode U+03BE character, which has the Unicode name “Greek Small Letter Xi”.

Any Unicode code point may be entered in this way and if all special characters are entered in this format it is not necessary to save the input file in UTF-8 format. Of course, a font containing all such encoded characters must be installed and available to LilyPond.

The following example shows Unicode hexadecimal values being entered in four places – in a rehearsal mark, as articulation text, in lyrics and as stand-alone text below the score:

>     \score {
>       \relative c'' {
>         c1 \mark \markup { \char ##x03EE }
>         c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } }
>       }
>       \addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
>     }
>     \markup { "Copyright 2008--2011" \char ##x00A9 }

To enter the copyright sign in the copyright notice use:

>     \header {
>       copyright = \markup { \char ##x00A9 "2008" }
>     }

### 3.3.4 Displaying LilyPond notation

Displaying a music expression in LilyPond notation can be done with the music function `\displayLilyMusic` but only when using the command line. For example,

>     {
>       \displayLilyMusic \transpose c a, { c4 e g a bes }
>     }

will display

>     { a,4 cis e fis g }

By default, LilyPond will print these messages to the console along with all the other LilyPond compilation messages. To split up these messages and save the results of `\display{STUFF}`, redirect the output to a file.

>     lilypond file.ly >display.txt

## 3.4 Controlling output

### 3.4.1 Extracting fragments of music

It is possible to quote small fragments of a large score directly from the output. This can be compared to clipping a piece of a paper score with scissors.

This is done by defining the measures that need to be cut out separately. For example, including the following definition

    \layout {
      clip-regions
      = #(list
          (cons
           (make-rhythmic-location 5 1 2)
           (make-rhythmic-location 7 3 4)))
    }

will extract a fragment starting halfway the fifth measure, ending in the seventh measure. The meaning of `5 1 2` is: after a 1/2 note in measure 5, and `7 3 4` after 3 quarter notes in measure 7.

More clip regions can be defined by adding more pairs of rhythmic-locations to the list.

In order to use this feature, LilyPond must be invoked with `-dclip-systems`. The clips are output as EPS files, and are converted to PDF and PNG if these formats are switched on as well.

For more information on output formats, see Invoking lilypond.

### 3.4.2 Skipping corrected music

When entering or copying music, usually only the music near the end (where you are adding notes) is interesting to view and correct. To speed up this correction process, it is possible to skip typesetting of all but the last few measures. This is achieved by putting

    showLastLength = R1*5
    \score { ... }

in your source file. This will render only the last 5 measures (assuming 4/4 time signature) of every `\score` in the input file. For longer pieces, rendering only a small part is often an order of magnitude quicker than rendering it completely. When working on the beginning of a score you have already typeset (e.g. to add a new part), the `showFirstLength` property may be useful as well.

Skipping parts of a score can be controlled in a more fine-grained fashion with the property `Score.skipTypesetting`. When it is set, no typesetting is performed at all.

This property is also used to control output to the MIDI file. Note that it skips all events, including tempo and instrument changes. You have been warned.

>     c8 d
>     \set Score.skipTypesetting = ##t
>     e8 e e e e e e e
>     \set Score.skipTypesetting = ##f
>     c8 d b bes a g c2

In polyphonic music, `Score.skipTypesetting` will affect all voices and staves, saving even more time.

### 3.4.3 Alternative output formats

The default output formats for the printed score are Portable Document Format (PDF) and PostScript (PS). Scalable Vector Graphics (SVG), Encapsulated PostScript (EPS) and Portable Network Graphics (PNG) output formats are also available through command line options, see lilypond Command line options for lilypond.

### 3.4.4 Replacing the notation font

Gonville is an alternative to the Feta font used in LilyPond and can be downloaded from:

>     http://www.chiark.greenend.org.uk/~sgtatham/gonville/

Here are a few sample bars of music set in Gonville:

Here are a few sample bars of music set in LilyPond’s Feta font:

#### Installation Instructions for MacOS

Download and extract the zip file. Copy the `lilyfonts` directory to ‘`SHARE_DIR/lilypond/current`’; for more information, see Other sources of information. Move the existing `fonts` directory to `fonts_orig` and move the `lilyfonts` directory to `fonts`. Simply move `fonts_orig` back to `fonts` to revert back to Feta.

#### See also

Learning Manual: Other sources of information.

#### Known issues and warnings

Gonville cannot be used to typeset ‘Ancient Music’ notation. Please refer to the author’s website for more information on this and other specifics including licensing of Gonville.

## 3.5 MIDI output

MIDI (Musical Instrument Digital Interface) is a standard for connecting and controlling digital instruments. A MIDI file is a series of notes in a number of tracks. It is not an actual sound file; you need special software to translate between the series of notes and actual sounds.

Pieces of music can be converted to MIDI files, so you can listen to what was entered. This is convenient for checking the music; octaves that are off or accidentals that were mistyped stand out very much when listening to the MIDI output.

Standard MIDI oputput is somewhat crude; optionally, an enhanced and more realistic MIDI output is available by means of The Articulate script.

The midi output allocates a channel for each staff, and one for global settings. Therefore the midi file should not have more than 15 staves (or 14 if you do not use drums). Other staves will remain silent.

### 3.5.1 Creating MIDI files

To create a MIDI output file from a LilyPond input file, add a `\midi` block to a score, for example,

>     \score {
>       ...music...
>       \midi { }
>     }

If there is a `\midi` block in a `\score` with no `\layout` block, only MIDI output will be produced. When notation is needed too, a `\layout` block must also be present.

>     \score {
>       ...music...
>       \midi { }
>       \layout { }
>     }

Pitches, rhythms, ties, dynamics, and tempo changes are interpreted and translated correctly to the MIDI output. Dynamic marks, crescendi and decrescendi translate into MIDI volume levels. Dynamic marks translate to a fixed fraction of the available MIDI volume range. Crescendi and decrescendi make the volume vary linearly between their two extremes. The effect of dynamic markings on the MIDI output can be removed completely, see MIDI block.

The initial tempo and later tempo changes can be specified with the `\tempo` command within the music notation. These are reflected in tempo changes in the MIDI output. This command will normally result in the metronome mark being printed, but this can be suppressed, see Metronome marks. An alternative way of specifying the initial or overall MIDI tempo is described below, see MIDI block.

Due to some limitations on Windows, the default extension for MIDI files on Windows is `.mid`. Other operating systems still use the extension `.midi`. If a different extension is preferred, insert the following line at the top-level of the input file, before the start of any `\book`, `\bookpart` or `\score` blocks:

>     #(ly:set-option 'midi-extension "midi")

The line above will set the default extension for MIDI files to `.midi`.

Alternatively, this option can also be supplied on the command line:

>     lilypond … -dmidi-extension=midi lilyFile.ly

#### Instrument names

The MIDI instrument to be used is specified by setting the `Staff.midiInstrument` property to the instrument name. The name should be chosen from the list in MIDI instruments.

>     \new Staff {
>       \set Staff.midiInstrument = #"glockenspiel"
>       ...notes...
>     }

>     \new Staff \with {midiInstrument = #"cello"} {
>       ...notes...
>     }

If the selected instrument does not exactly match an instrument from the list of MIDI instruments, the Grand Piano (`"acoustic grand"`) instrument is used.

#### Selected Snippets

Changing MIDI output to one channel per voice

When outputting MIDI, the default behavior is for each staff to represent one MIDI channel, with all the voices on a staff amalgamated. This minimizes the risk of running out of MIDI channels, since there are only 16 available per track.

However, by moving the `Staff_performer` to the `Voice` context, each voice on a staff can have its own MIDI channel, as is demonstrated by the following example: despite being on the same staff, two MIDI channels are created, each with a different `midiInstrument`.

>     \score {
>       \new Staff <<
>         \new Voice \relative c''' {
>           \set midiInstrument = #"flute"
>           \voiceOne
>           \key g \major
>           \time 2/2
>           r2 g-"Flute" ~
>           g fis ~
>           fis4 g8 fis e2 ~
>           e4 d8 cis d2
>         }
>         \new Voice \relative c'' {
>           \set midiInstrument = #"clarinet"
>           \voiceTwo
>           b1-"Clarinet"
>           a2. b8 a
>           g2. fis8 e
>           fis2 r
>         }
>       >>
>       \layout { }
>       \midi {
>         \context {
>           \Staff
>           \remove "Staff_performer"
>         }
>         \context {
>           \Voice
>           \consists "Staff_performer"
>         }
>         \context {
>           \Score
>           tempoWholesPerMinute = #(ly:make-moment 72 2)
>         }
>       }
>     }

#### Known issues and warnings

Changes in the MIDI volume take place only on starting a note, so crescendi and decrescendi cannot affect the volume of a single note.

Not all midi players correctly handle tempo changes in the midi output. Players that are known to work include MS Windows Media Player and timidity.

### 3.5.2 MIDI block

A `\midi` block must appear within a score block if MIDI output is required. It is analogous to the layout block, but somewhat simpler. Often, the `\midi` block is left empty, but it can contain context rearrangements, new context definitions or code to set the values of properties. For example, the following will set the initial tempo exported to a MIDI file without causing a tempo indication to be printed:

>     \score {
>       ...music...
>       \midi {
>         \context {
>           \Score
>           tempoWholesPerMinute = #(ly:make-moment 72 4)
>         }
>       }
>     }

In this example the tempo is set to 72 quarter note beats per minute. This kind of tempo specification cannot take a dotted note length as an argument. If one is required, break the dotted note into smaller units. For example, a tempo of 90 dotted quarter notes per minute can be specified as 270 eighth notes per minute:

>     tempoWholesPerMinute = #(ly:make-moment 270 8)

Context definitions follow precisely the same syntax as those within a `\layout` block. Translation modules for sound are called performers. The contexts for MIDI output are defined in ‘`../ly/performer-init.ly`’, see Other sources of information. For example, to remove the effect of dynamics from the MIDI output, insert the following lines in the `\midi{ }` block.

>     \midi {
>       ...
>       \context {
>         \Voice
>         \remove "Dynamic_performer"
>       }
>     }

MIDI output is created only when a `\midi` block is included within a score block defined with a `\score` command.

>     \score {
>       { …notes… }
>       \midi { }
>     }

### 3.5.3 What goes into the MIDI output?

#### Supported in MIDI

The following items of notation are reflected in the MIDI output:

- Pitches
- Microtones (See Accidentals. Rendering needs a player that supports pitch bend.)
- Chords entered as chord names
- Rhythms entered as note durations, including tuplets
- Tremolos entered without ‘`:`[number]’
- Ties
- Dynamic marks
- Crescendi, decrescendi over multiple notes
- Tempo changes entered with a tempo marking
- Lyrics

Using The Articulate script, a number of items are added to the above list:

- Articulations (slurs, staccato, etc)
- Trills, turns
- Rallentando and accelerando

#### Unsupported in MIDI

The following items of notation have no effect on the MIDI output, unless you use The Articulate script:

- Rhythms entered as annotations, e.g. swing
- Tempo changes entered as annotations with no tempo marking
- Staccato and other articulations and ornamentations
- Slurs and Phrasing slurs
- Crescendi, decrescendi over a single note
- Tremolos entered with ‘`:`[number]’
- Figured bass
- Microtonal chords

### 3.5.4 Repeats in MIDI

With a few minor additions, all types of repeats can be represented in the MIDI output. This is achieved by applying the `\unfoldRepeats` music function. This function changes all repeats to unfold repeats.

>     \unfoldRepeats {
>       \repeat tremolo 8 { c'32 e' }
>       \repeat percent 2 { c''8 d'' }
>       \repeat volta 2 { c'4 d' e' f' }
>       \alternative {
>         { g' a' a' g' }
>         { f' e' d' c' }
>       }
>     }
>     \bar "|."

In scores containing multiple voices, unfolding of repeats in MIDI output will only occur correctly if each voice contains fully notated repeat indications.

When creating a score file using `\unfoldRepeats` for MIDI, it is necessary to make two `\score` blocks: one for MIDI (with unfolded repeats) and one for notation (with volta, tremolo, and percent repeats). For example,

>     \score {
>       ..music..
>       \layout { .. }
>     }
>     \score {
>       \unfoldRepeats ..music..
>       \midi { .. }
>     }

### 3.5.5 Controlling MIDI dynamics

MIDI dynamics are implemented by the Dynamic_performer which lives by default in the Voice context. It is possible to control the overall MIDI volume, the relative volume of dynamic markings and the relative volume of different instruments.

#### Dynamic marks

Dynamic marks are translated to a fixed fraction of the available MIDI volume range. The default fractions range from 0.25 for ppppp to 0.95 for fffff. The set of dynamic marks and the associated fractions can be seen in ‘`../scm/midi.scm`’, see Other sources of information. This set of fractions may be changed or extended by providing a function which takes a dynamic mark as its argument and returns the required fraction, and setting `Score.dynamicAbsoluteVolumeFunction` to this function.

For example, if a rinforzando dynamic marking, `\rfz`, is required, this will not by default have any effect on the MIDI volume, as this dynamic marking is not included in the default set. Similarly, if a new dynamic marking has been defined with `make-dynamic-script` that too will not be included in the default set. The following example shows how the MIDI volume for such dynamic markings might be added. The Scheme function sets the fraction to 0.9 if a dynamic mark of rfz is found, or calls the default function otherwise.

>     #(define (myDynamics dynamic)
>         (if (equal? dynamic "rfz")
>           0.9
>           (default-dynamic-absolute-volume dynamic)))

>     \score {
>       \new Staff {
>         \set Staff.midiInstrument = #"cello"
>         \set Score.dynamicAbsoluteVolumeFunction = #myDynamics
>         \new Voice {
>           \relative c'' {
>             a4\pp b c-\rfz
>           }
>         }
>       }
>       \layout {}
>       \midi {}
>     }

Alternatively, if the whole table of fractions needs to be redefined, it would be better to use the default-dynamic-absolute-volume procedure in ‘`../scm/midi.scm`’ and the associated table as a model. The final example in this section shows how this might be done.

#### Overall MIDI volume

The minimum and maximum overall volume of MIDI dynamic markings is controlled by setting the properties `midiMinimumVolume` and `midiMaximumVolume` at the `Score` level. These properties have an effect only on dynamic marks, so if they are to apply from the start of the score a dynamic mark must be placed there. The fraction corresponding to each dynamic mark is modified with this formula

>     midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction

In the following example the dynamic range of the overall MIDI volume is limited to the range 0.2 - 0.5.

>     \score {
>       <<
>         \new Staff {
>           \key g \major
>           \time 2/2
>           \set Staff.midiInstrument = #"flute"
>           \new Voice \relative c''' {
>             r2 g\mp g fis~
>             fis4 g8 fis e2~
>             e4 d8 cis d2
>           }
>         }
>         \new Staff {
>           \key g \major
>           \set Staff.midiInstrument = #"clarinet"
>           \new Voice \relative c'' {
>             b1\p a2. b8 a
>             g2. fis8 e
>             fis2 r
>           }
>         }
>       >>
>       \layout {}
>       \midi {
>         \context {
>           \Score
>           tempoWholesPerMinute = #(ly:make-moment 72 2)
>           midiMinimumVolume = #0.2
>           midiMaximumVolume = #0.5
>         }
>       }
>     }

#### Equalizing different instruments (i)

If the minimum and maximum MIDI volume properties are set in the `Staff` context the relative volumes of the MIDI instruments can be controlled. This gives a basic instrument equalizer, which can enhance the quality of the MIDI output remarkably.

In this example the volume of the clarinet is reduced relative to the volume of the flute. There must be a dynamic mark on the first note of each instrument for this to work correctly.

>     \score {
>       <<
>         \new Staff {
>           \key g \major
>           \time 2/2
>           \set Staff.midiInstrument = #"flute"
>           \set Staff.midiMinimumVolume = #0.7
>           \set Staff.midiMaximumVolume = #0.9
>           \new Voice \relative c''' {
>             r2 g\mp g fis~
>             fis4 g8 fis e2~
>             e4 d8 cis d2
>           }
>         }
>         \new Staff {
>           \key g \major
>           \set Staff.midiInstrument = #"clarinet"
>           \set Staff.midiMinimumVolume = #0.3
>           \set Staff.midiMaximumVolume = #0.6
>           \new Voice \relative c'' {
>             b1\p a2. b8 a
>             g2. fis8 e
>             fis2 r
>           }
>         }
>       >>
>       \layout {}
>       \midi {
>         \context {
>           \Score
>           tempoWholesPerMinute = #(ly:make-moment 72 2)
>         }
>       }
>     }

#### Equalizing different instruments (ii)

If the MIDI minimum and maximum volume properties are not set LilyPond will, by default, apply a small degree of equalization to a few instruments. The instruments and the equalization applied are shown in the table instrument-equalizer-alist in ‘`../scm/midi.scm`’.

This basic default equalizer can be replaced by setting `instrumentEqualizer` in the `Score` context to a new Scheme procedure which accepts a MIDI instrument name as its only argument and returns a pair of fractions giving the minimum and maximum volumes to be applied to that instrument. This replacement is done in the same way as shown for resetting the `dynamicAbsoluteVolumeFunction` at the start of this section. The default equalizer, default-instrument-equalizer, in ‘`../scm/midi.scm`’ shows how such a procedure might be written.

The following example sets the relative flute and clarinet volumes to the same values as the previous example.

>     #(define my-instrument-equalizer-alist '())

>     #(set! my-instrument-equalizer-alist
>       (append
>         '(
>           ("flute" . (0.7 . 0.9))
>           ("clarinet" . (0.3 . 0.6)))
>         my-instrument-equalizer-alist))

>     #(define (my-instrument-equalizer s)
>       (let ((entry (assoc s my-instrument-equalizer-alist)))
>         (if entry
>           (cdr entry))))

>     \score {
>       <<
>         \new Staff {
>           \key g \major
>           \time 2/2
>           \set Score.instrumentEqualizer = #my-instrument-equalizer
>           \set Staff.midiInstrument = #"flute"
>           \new Voice \relative c''' {
>             r2 g\mp g fis~
>             fis4 g8 fis e2~
>             e4 d8 cis d2
>           }
>         }
>         \new Staff {
>           \key g \major
>           \set Staff.midiInstrument = #"clarinet"
>           \new Voice \relative c'' {
>             b1\p a2. b8 a
>             g2. fis8 e
>             fis2 r
>           }
>         }
>       >>
>       \layout { }
>       \midi {
>         \context {
>           \Score
>           tempoWholesPerMinute = #(ly:make-moment 72 2)
>         }
>       }
>     }

### 3.5.6 Percussion in MIDI

Percussion instruments are generally notated in a `DrumStaff` context and when notated in this way they are outputted correctly to MIDI channel 10, but some pitched percussion instruments, like the xylophone, marimba, vibraphone, timpani, etc., are treated like “normal” instruments and music for these instruments should be entered in a normal `Staff` context, not a `DrumStaff` context, to obtain the correct MIDI output.

Some non-pitched percussion sounds included in the general MIDI standard, like melodic tom, taiko drum, synth drum, etc., cannot be reached via MIDI channel 10, so the notation for such instruments should also be entered in a normal `Staff` context, using suitable normal pitches.

Many percussion instruments are not included in the general MIDI standard, e.g. castanets. The easiest, although unsatisfactory, method of producing some MIDI output when writing for such instruments is to substitute the nearest sound from the standard set.

#### Known issues and warnings

Because the general MIDI standard does not contain rim shots, the sidestick is used for this purpose instead.

### 3.5.7 The Articulate script

A more realistic MIDI output is possible when using the Articulate script. It tries to take articulations (slurs, staccato, etc) into account, by replacing notes with sequential music of suitably time-scaled note plus skip. It also tries to unfold trills turns etc., and take rallentando and accelerando into account.

To use the Articulate script, you have to include it at the top of your input file,

>     \include "articulate.ly"

and in the `\score` section do

>     \unfoldRepeats \articulate <<
>     	all the rest of the score...
>     >>

After altering your input file this way, the visual output is heavily altered, but the standard `\midi` block will produce a better MIDI file.

Although not essential for the Articulate script to work, you may want to insert the `\unfoldRepeats` command as it appears in the example shown above as it enables performing abbreviatures such as trills.

#### Known issues and warnings

Articulate shortens chords and some music (esp. organ music) could sound worse.

# 4. Spacing issues

The global paper layout is determined by three factors: the page layout, the line breaks, and the spacing. These all influence each other. The choice of spacing determines how densely each system of music is set. This influences where line breaks are chosen, and thus ultimately, how many pages a piece of music takes.

Globally speaking, this procedure happens in four steps: first, flexible distances (‘springs’) are chosen, based on durations. All possible line breaking combinations are tried, and a ‘badness’ score is calculated for each. Then the height of each possible system is estimated. Finally, a page breaking and line breaking combination is chosen so that neither the horizontal nor the vertical spacing is too cramped or stretched.

Two types of blocks can contain layout settings: `\paper {…}` and `\layout {…}`. The `\paper` block contains page layout settings that are expected to be the same for all scores in a book, such as the paper height, or whether to print page numbers, etc. See Page layout. The `\layout` block contains score layout settings, such as the number of systems to use, or the space between staff-groups, etc. See Score layout.

## 4.1 Page layout

This section discusses page layout options for the `\paper` block.

### 4.1.1 The `\paper` block

The `\paper` block can appear within a `\book` block, but not within a `\score` block. Settings in a `\paper` block apply to the entire book, which may include multiple scores. Settings that can appear in a `\paper` block include:

- the `set-paper-size` scheme function,
- `\paper` variables used for customizing page layout, and
- markup definitions used for customizing the layout of headers, footers, and titles.

The `set-paper-size` function is discussed in the next section, Paper size and automatic scaling. The `\paper` variables that deal with page layout are discussed in later sections. The markup definitions that deal with headers, footers, and titles are discussed in Custom headers, footers, and titles.

Most `\paper` variables will only work in a `\paper` block. The few that will also work in a `\layout` block are listed in The `\layout` block.

Except when specified otherwise, all `\paper` variables that correspond to distances on the page are measured in millimeters, unless a different unit is specified by the user. For example, the following declaration sets `top-margin` to ten millimeters:

>     \paper {
>       top-margin = 10
>     }

To set it to `0.5` inches, use the `\in` unit suffix:

>     \paper {
>       top-margin = 0.5\in
>     }

The available unit suffixes are `\mm`, `\cm`, `\in`, and `\pt`. These units are simple values for converting from millimeters; they are defined in ‘`ly/paper-defaults-init.ly`’. For the sake of clarity, when using millimeters, the `\mm` is typically included in the code, even though it is not technically necessary.

It is also possible to define `\paper` values using Scheme. The Scheme equivalent of the above example is:

>     \paper {
>       #(define top-margin (* 0.5 in))
>     }

#### See also

Notation Reference: Paper size and automatic scaling, Custom headers, footers, and titles, The `\layout` block.

Installed Files: ‘`ly/paper-defaults-init.ly`’.

### 4.1.2 Paper size and automatic scaling

#### Setting paper size

Two functions are available for changing the paper size: `set-default-paper-size` and `set-paper-size`. `set-default-paper-size` must be placed in the toplevel scope, and `set-paper-size` must be placed in a `\paper` block:

>     #(set-default-paper-size "a4")

>     \paper {
>       #(set-paper-size "a4")
>     }

In the toplevel scope, the `set-default-paper-size` function can safely be called anywhere before the first `\paper` block. Within a `\paper` block, the safest place to call `set-paper-size` is at the top, above the list of variable declarations. The reasons for this are discussed in Automatic scaling to paper size.

`set-default-paper-size` sets the size of all pages, whereas `set-paper-size` only sets the size of the pages that the `\paper` block applies to. For example, if the `\paper` block is at the top of the file, then it will apply the paper size to all pages. If the `\paper` block is inside a `\book`, then the paper size will only apply to that book.

Common paper sizes are available, including `a4`, `letter`, `legal`, and `11x17` (also known as tabloid). Many more paper sizes are supported by default. For details, see ‘`scm/paper.scm`’, and search for the definition of `paper-alist`.

Note: The default paper size is `a4`.

Extra sizes may be added by editing the definition of `paper-alist` in the initialization file ‘`scm/paper.scm`’, however they will be overridden on a subsequent install.

If the symbol `'landscape` is supplied as an argument to `set-default-paper-size`, pages will be rotated by 90 degrees, and wider line widths will be set accordingly.

>     #(set-default-paper-size "a6" 'landscape)

#### See also

Notation Reference: Automatic scaling to paper size.

Installed Files: ‘`scm/paper.scm`’.

#### Automatic scaling to paper size

If the paper size is changed with one of the scheme functions (`set-default-paper-size` or `set-paper-size`), the values of several `\paper` variables are automatically scaled to the new size. To bypass the automatic scaling for a particular variable, set the variable after setting the paper size. Note that the automatic scaling is not triggered by setting the `paper-height` or `paper-width` variables, even though `paper-width` can influence other values (this is separate from scaling and is discussed below). The `set-default-paper-size` and `set-paper-size` functions are described in Setting paper size.

The vertical dimensions affected by automatic scaling are `top-margin` and `bottom-margin` (see Fixed vertical spacing `\paper` variables). The horizontal dimensions affected by automatic scaling are `left-margin`, `right-margin`, `inner-margin`, `outer-margin`, `binding-offset`, `indent`, and `short-indent` (see Horizontal spacing `\paper` variables).

The default values for these dimensions are set in ‘`ly/paper-defaults-init.ly`’, using internal variables named `top-margin-default`, `bottom-margin-default`, etc. These are the values that result at the default paper size `a4`. For reference, with `a4` paper the `paper-height` is `297\mm` and the `paper-width` is `210\mm`.

#### See also

Notation Reference: Fixed vertical spacing `\paper` variables, Horizontal spacing `\paper` variables.

Installed Files: ‘`ly/paper-defaults-init.ly`’, ‘`scm/paper.scm`’.

### 4.1.3 Fixed vertical spacing `\paper` variables

Note: Some `\paper` dimensions are automatically scaled to the paper size, which may lead to unexpected behavior. See Automatic scaling to paper size.

Default values (before scaling) are defined in ‘`ly/paper-defaults-init.ly`’.

`paper-height`

  The height of the page, unset by default. Note that the automatic scaling of some vertical dimensions is not affected by this.

`top-margin`

  The margin between the top of the page and the top of the printable area. If the paper size is modified, this dimension’s default value is scaled accordingly.

`bottom-margin`

  The margin between the bottom of the printable area and the bottom of the page. If the paper size is modified, this dimension’s default value is scaled accordingly.

`ragged-bottom`

  If set to true, systems will not spread vertically down the page. This does not affect the last page. This should be set to true for pieces that have only two or three systems per page, for example orchestral scores.

`ragged-last-bottom`

  If set to false, systems will spread vertically down the last page. Pieces that amply fill two pages or more should have this set to true. It also affects the last page of book parts, i.e. parts of a book created with `\bookpart` blocks.

#### See also

Notation Reference: Automatic scaling to paper size.

Installed Files: ‘`ly/paper-defaults-init.ly`’.

Snippets: Spacing.

#### Known issues and warnings

The titles (from the `\header` block) are treated as a system, so `ragged-bottom` and `ragged-last-bottom` will add space between the titles and the first system of the score.

### 4.1.4 Flexible vertical spacing `\paper` variables

In most cases, it is preferable for the vertical distances between certain items (such as margins, titles, systems, and separate scores) to be flexible, so that they stretch and compress nicely according to each situation. A number of `\paper` variables (listed below) are available to fine-tune the stretching behavior of these dimensions.

Note that the `\paper` variables discussed in this section do not control the spacing of staves within individual systems. Within-system spacing is controlled by grob properties, with settings typically entered inside a `\score` or `\layout` block, and not inside a `\paper` block. See Flexible vertical spacing within systems.

#### Structure of flexible vertical spacing alists

Each of the flexible vertical spacing `\paper` variables is an alist (association list) containing four keys:

- `basic-distance` – the vertical distance, measured in staff-spaces, between the reference points of the two items, when no collisions would result, and no stretching or compressing is in effect. The reference point of a (title or top-level) markup is its highest point, and the reference point of a system is the vertical center of the nearest `StaffSymbol` – even if a non-staff line (such as a `Lyrics` context) is in the way. Values for `basic-distance` that are less than either `padding` or `minimum-distance` are not meaningful, since the resulting distance will never be less than either `padding` or `minimum-distance`.
- `minimum-distance` – the smallest allowable vertical distance, measured in staff-spaces, between the reference points of the two items, when compressing is in effect. Values for `minimum-distance` that are less than `padding` are not meaningful, since the resulting distance will never be less than `padding.`
- `padding` – the minimum required amount of unobstructed vertical whitespace between the bounding boxes (or skylines) of the two items, measured in staff-spaces.
- `stretchability` – a unitless measure of the dimension’s relative propensity to stretch. If zero, the distance will not stretch (unless collisions would result). When positive, the significance of a particular dimension’s `stretchability` value lies only in its relation to the `stretchability` values of the other dimensions. For example, if one dimension has twice the `stretchability` of another, it will stretch twice as easily. Values should be non-negative and finite. The value `+inf.0` triggers a `programming_error` and is ignored, but `1.0e7` can be used for an almost infinitely stretchable spring. If unset, the default value is set to `basic-distance`. Note that the dimension’s propensity to compress cannot be directly set by the user and is equal to (`basic-distance` - `minimum-distance`).

If a page has a ragged bottom, the resulting distance is the largest of:

- `basic-distance`,
- `minimum-distance`, and
- `padding` plus the smallest distance necessary to eliminate collisions.

Specific methods for modifying alists are discussed in Modifying alists. The following example demonstrates the two ways these alists can be modified. The first declaration updates one key-value individually, and the second completely redefines the variable:

>     \paper {
>       system-system-spacing #'basic-distance = #8
>       score-system-spacing =
>         #'((basic-distance . 12)
>            (minimum-distance . 6)
>            (padding . 1)
>            (stretchability . 12))
>     }

#### List of flexible vertical spacing `\paper` variables

The names of these variables follow the format `upper-lower-spacing`, where `upper` and `lower` are the items to be spaced. Each distance is measured between the reference points of the two items (see the description of the alist structure above). Note that in these variable names, the term ‘`markup`’ refers to both title markups (`bookTitleMarkup` or `scoreTitleMarkup`) and top-level markups (see File structure). All distances are measured in staff-spaces.

Default settings are defined in ‘`ly/paper-defaults-init.ly`’.

`markup-system-spacing`

  the distance between a (title or top-level) markup and the system that follows it.

`score-markup-spacing`

  the distance between the last system of a score and the (title or top-level) markup that follows it.

`score-system-spacing`

  the distance between the last system of a score and the first system of the score that follows it, when no (title or top-level) markup exists between them.

`system-system-spacing`

  the distance between two systems in the same score.

`markup-markup-spacing`

  the distance between two (title or top-level) markups.

`last-bottom-spacing`

  the distance from the last system or top-level markup on a page to the bottom of the printable area (i.e. the top of the bottom margin).

`top-system-spacing`

  the distance from the top of the printable area (i.e. the bottom of the top margin) to the first system on a page, when there is no (title or top-level) markup between the two.

`top-markup-spacing`

  the distance from the top of the printable area (i.e. the bottom of the top margin) to the first (title or top-level) markup on a page, when there is no system between the two.

#### See also

Notation Reference: Flexible vertical spacing within systems.

Installed Files: ‘`ly/paper-defaults-init.ly`’.

Snippets: Spacing.

### 4.1.5 Horizontal spacing `\paper` variables

Note: Some `\paper` dimensions are automatically scaled to the paper size, which may lead to unexpected behavior. See Automatic scaling to paper size.

#### `\paper` variables for widths and margins

Default values (before scaling) that are not listed here are defined in ‘`ly/paper-defaults-init.ly`’.

`paper-width`

  The width of the page, unset by default. While `paper-width` has no effect on the automatic scaling of some horizontal dimensions, it does influence the `line-width` variable. If both `paper-width` and `line-width` are set, then `left-margin` and `right-margin` will also be updated. Also see `check-consistency`.

`line-width`

  The horizontal extent of the staff lines in unindented, non-ragged systems, equal to `(paper-width - left-margin - right-margin)` when unset. If `line-width` is set, and both `left-margin` and `right-margin` are unset, then the margins will be updated to center the systems on the page automatically. Also see `check-consistency`. This variable can also be set in a `\layout` block.

`left-margin`

  The margin between the left edge of the page and the start of the staff lines in unindented systems. If the paper size is modified, this dimension’s default value is scaled accordingly. If `left-margin` is unset, and both `line-width` and `right-margin` are set, then `left-margin` is set to `(paper-width - line-width - right-margin)`. If only `line-width` is set, then both margins are set to `((paper-width - line-width) / 2)`, and the systems are consequently centered on the page. Also see `check-consistency`.

`right-margin`

  The margin between the right edge of the page and the end of the staff lines in non-ragged systems. If the paper size is modified, this dimension’s default value is scaled accordingly. If `right-margin` is unset, and both `line-width` and `left-margin` are set, then `right-margin` is set to `(paper-width - line-width - left-margin)`. If only `line-width` is set, then both margins are set to `((paper-width - line-width) / 2)`, and the systems are consequently centered on the page. Also see `check-consistency`.

`check-consistency`

  If set to true, print a warning if `left-margin`, `line-width`, and `right-margin` do not exactly add up to `paper-width`, and replace each of these (except `paper-width`) with its default value (scaled to the paper size if necessary). If set to false, ignore any inconsistencies and allow systems to run off the edge of the page.

`ragged-right`

  If set to true, systems will not fill the line width. Instead, systems end at their natural horizontal length. Default: `#t` for scores with only one system, and `#f` for scores with two or more systems. This variable can also be set in a `\layout` block.

`ragged-last`

  If set to true, the last system in the score will not fill the line width. Instead the last system ends at its natural horizontal length. Default: `#f`. This variable can also be set in a `\layout` block.

#### See also

Notation Reference: Automatic scaling to paper size.

Installed Files: ‘`ly/paper-defaults-init.ly`’.

#### `\paper` variables for two-sided mode

Default values (before scaling) are defined in ‘`ly/paper-defaults-init.ly`’.

`two-sided`

  If set to true, use `inner-margin`, `outer-margin` and `binding-offset` to determine margins depending on whether the page number is odd or even. This overrides `left-margin` and `right-margin`.

`inner-margin`

  The margin all pages have at the inner side if they are part of a book. If the paper size is modified, this dimension’s default value is scaled accordingly. Works only with `two-sided` set to true.

`outer-margin`

  The margin all pages have at the outer side if they are part of a book. If the paper size is modified, this dimension’s default value is scaled accordingly. Works only with `two-sided` set to true.

`binding-offset`

  The amount `inner-margin` is increased to make sure nothing will be hidden by the binding. If the paper size is modified, this dimension’s default value is scaled accordingly. Works only with `two-sided` set to true.

#### See also

Notation Reference: Automatic scaling to paper size.

Installed Files: ‘`ly/paper-defaults-init.ly`’.

#### `\paper` variables for shifts and indents

Default values (before scaling) that are not listed here are defined in ‘`ly/paper-defaults-init.ly`’.

`horizontal-shift`

  The amount that all systems (including titles and system separators) are shifted to the right. Default: `0.0\mm`.

`indent`

  The level of indentation for the first system in a score. If the paper size is modified, this dimension’s default value is scaled accordingly. This variable can also be set in a `\layout` block.

`short-indent`

  The level of indentation for all systems in a score besides the first system. If the paper size is modified, this dimension’s default value is scaled accordingly. This variable can also be set in a `\layout` block.

#### See also

Notation Reference: Automatic scaling to paper size.

Installed Files: ‘`ly/paper-defaults-init.ly`’.

Snippets: Spacing.

### 4.1.6 Other `\paper` variables

#### `\paper` variables for line breaking

`max-systems-per-page`

  The maximum number of systems that will be placed on a page. This is currently supported only by the `ly:optimal-breaking` algorithm. Default: unset.

`min-systems-per-page`

  The minimum number of systems that will be placed on a page. This may cause pages to be overfilled if it is made too large. This is currently supported only by the `ly:optimal-breaking` algorithm. Default: unset.

`systems-per-page`

  The number of systems that should be placed on each page. This is currently supported only by the `ly:optimal-breaking` algorithm. Default: unset.

`system-count`

  The number of systems to be used for a score. Default: unset. This variable can also be set in a `\layout` block.

#### See also

Notation Reference: Line breaking.

#### `\paper` variables for page breaking

Default values not listed here are defined in ‘`ly/paper-defaults-init.ly`’

`blank-after-score-page-force`

  The penalty for having a blank page after the end of one score and before the next. By default, this is smaller than `blank-page-force`, so that we prefer blank pages after scores to blank pages within a score.

`blank-last-page-force`

  The penalty for ending the score on an odd-numbered page.

`blank-page-force`

  The penalty for having a blank page in the middle of a score. This is not used by `ly:optimal-breaking` since it will never consider blank pages in the middle of a score.

`page-breaking`

  The page-breaking algorithm to use. Choices are `ly:minimal-breaking`, `ly:page-turn-breaking`, and `ly:optimal-breaking`.

`page-breaking-system-system-spacing`

  Tricks the page breaker into thinking that `system-system-spacing` is set to something different than it really is. For example, if `page-breaking-system-system-spacing #'padding` is set to something substantially larger than `system-system-spacing #'padding`, then the page-breaker will put fewer systems on each page. Default: unset.

`page-count`

  The number of pages to be used for a score, unset by default.

#### See also

Notation Reference: Page breaking, Optimal page breaking, Optimal page turning, Minimal page breaking.

Installed Files: ‘`ly/paper-defaults-init.ly`’.

#### `\paper` variables for page numbering

Default values not listed here are defined in ‘`ly/paper-defaults-init.ly`’

`auto-first-page-number`

  The page breaking algorithm is affected by the first page number being odd or even. If set to true, the page breaking algorithm will decide whether to start with an odd or even number. This will result in the first page number remaining as is or being increased by one. Default: `#f`.

`first-page-number`

  The value of the page number on the first page.

`print-first-page-number`

  If set to true, a page number is printed on the first page.

`print-page-number`

  If set to false, page numbers are not printed.

#### See also

Installed Files: ‘`ly/paper-defaults-init.ly`’.

#### Known issues and warnings

Odd page numbers are always on the right. If you want the music to start on page 1 there must be a blank page on the back of the cover page so that page 1 is on the right hand side.

#### Miscellaneous `\paper` variables

`page-spacing-weight`

  The relative importance of page (vertical) spacing and line (horizontal) spacing. High values will make page spacing more important. Default: `#10`.

`print-all-headers`

  If set to true, this will print all headers for each `\score` in the output. Normally only the `piece` and `opus` header variables are printed. Default: `#f`.

`system-separator-markup`

  A markup object that is inserted between systems, often used for orchestral scores. Default: unset. The `\slashSeparator` markup, defined in ‘`ly/titling-init.ly`’, is provided as a sensible default, for example:

  >     #(set-default-paper-size "a8")

  >     \book {
  >       \paper {
  >         system-separator-markup = \slashSeparator
  >       }
  >       \header {
  >         tagline = ##f
  >       }
  >       \score {
  >         \relative c'' { c1 \break c1 \break c1 }
  >       }
  >     }

#### See also

Installed Files: ‘`ly/titling-init.ly`’.

Snippets: Spacing.

#### Known issues and warnings

The default page header puts the page number and the `instrument` field from the `\header` block on a line.

## 4.2 Score layout

This section discusses score layout options for the `\layout` block.

### 4.2.1 The `\layout` block

While the `\paper` block contains settings that relate to the page formatting of the whole document, the `\layout` block contains settings for score-specific layout. To set score layout options globally, enter them in a toplevel `\layout` block. To set layout options for an individual score, enter them in a `\layout` block inside the `\score` block, after the music. Settings that can appear in a `\layout` block include:

- the `layout-set-staff-size` scheme function,
- context modifications in `\context` blocks, and
- `\paper` variables that affect score layout.

The `layout-set-staff-size` function is discussed in the next section, Setting the staff size. Context modifications are discussed in a separate chapter; see Modifying context plug-ins and Changing context default settings. The `\paper` variables that can appear in a `\layout` block are:

- `line-width`, `ragged-right` and `ragged-last` (see `\paper` variables for widths and margins)
- `indent` and `short-indent` (see `\paper` variables for shifts and indents)
- `system-count` (see `\paper` variables for line breaking)

Here is an example `\layout` block:

>     \layout {
>       indent = 2\cm
>       \context {
>         \StaffGroup
>         \override StaffGrouper #'staff-staff-spacing #'basic-distance = #8
>       }
>       \context {
>         \Voice
>         \override TextScript #'padding = #1
>         \override Glissando #'thickness = #3
>       }
>     }

#### See also

Notation Reference: Changing context default settings.

Snippets: Spacing.

### 4.2.2 Setting the staff size

The default staff size is set to 20 points. This may be changed in two ways:

To set the staff size globally for all scores in a file (or in a `book` block, to be precise), use `set-global-staff-size`.

>     #(set-global-staff-size 14)

This sets the global default size to 14pt staff height and scales all fonts accordingly.

To set the staff size individually for each score, use

>     \score{
>       …
>       \layout {
>         #(layout-set-staff-size 15)
>       }
>     }

The Feta font provides musical symbols at eight different sizes. Each font is tuned for a different staff size: at a smaller size the font becomes heavier, to match the relatively heavier staff lines. The recommended font sizes are listed in the following table:

> font name | staff height (pt) | staff height (mm) | use
> feta11 | 11.22 | 3.9 | pocket scores
> feta13 | 12.60 | 4.4 |
> feta14 | 14.14 | 5.0 |
> feta16 | 15.87 | 5.6 |
> feta18 | 17.82 | 6.3 | song books
> feta20 | 20 | 7.0 | standard parts
> feta23 | 22.45 | 7.9 |
> feta26 | 25.2 | 8.9 |

These fonts are available in any sizes. The context property `fontSize` and the layout property `staff-space` (in StaffSymbol) can be used to tune the size for individual staves. The sizes of individual staves are relative to the global size.

#### See also

Notation Reference: Selecting notation font size.

Snippets: Spacing.

#### Known issues and warnings

`layout-set-staff-size` does not change the distance between the staff lines.

## 4.3 Breaks

### 4.3.1 Line breaking

Line breaks are normally determined automatically. They are chosen so that lines look neither cramped nor loose, and consecutive lines have similar density.

To manually force a line break at a bar line, use the `\break` command:

>     c4 c c c | \break
>     c4 c c c |

By default, a `\break` in the middle of a measure is ignored, and a warning is printed. To force a line break in the middle of a measure, add an invisible bar line with ‘`\bar ""`’:

>     c4 c c
>     \bar "" \break
>     c |
>     c4 c c c |

A `\break` occurring at a bar line is also ignored if the previous measure ends in the middle of a note, such as when a tuplet begins and ends in different measures. To allow `\break` commands to work in these situations, remove the `Forbid_line_break_engraver` from the `Voice` context. Note that manually forced line breaks have to be added in parallel with the music:

>     \new Voice \with {
>       \remove Forbid_line_break_engraver
>     } \relative c'' {
>       <<
>         { c2. \times 2/3 { c4 c c } c2. | }
>         { s1 | \break s1 | }
>       >>
>     }

Similarly, line breaks are normally forbidden when beams cross bar lines. This behavior can be changed by setting `\override Beam #'breakable = ##t`:

>     \override Beam #'breakable = ##t
>     c2. c8[ c | \break
>     c8 c] c2. |

The `\noBreak` command forbids a line break at the bar line where it is inserted.

The most basic settings influencing line spacing are `indent` and `line-width`. They are set in the `\layout` block. They control the indentation of the first line of music, and the lengths of the lines.

If `ragged-right` is set to true in the `\layout` block, then systems end at their natural horizontal length, instead of being spread horizontally to fill the whole line. This is useful for short fragments, and for checking how tight the natural spacing is.

The option `ragged-last` is similar to `ragged-right`, but affects only the last line of the piece.

>     \layout {
>       indent = 0\mm
>       line-width = 150\mm
>       ragged-last = ##t
>     }

For line breaks at regular intervals use `\break` separated by skips and repeated with `\repeat`. For example, this would cause the following 28 measures (assuming 4/4 time) to be broken every 4 measures, and only there:

>     <<
>       \repeat unfold 7 {
>         s1 \noBreak s1 \noBreak
>         s1 \noBreak s1 \break
>       }
>       { the actual music… }
>     >>

A linebreaking configuration can be saved as a ‘`.ly`’ file automatically. This allows vertical alignments to be stretched to fit pages in a second formatting run. This is fairly new and complicated. More details are available in Spacing.

#### Predefined commands

`\break`, `\noBreak`.

#### See also

Notation Reference: `\paper` variables for line breaking.

Snippets: Spacing.

Internals Reference: LineBreakEvent.

### 4.3.2 Page breaking

The default page breaking may be overridden by inserting `\pageBreak` or `\noPageBreak` commands. These commands are analogous to `\break` and `\noBreak`. They should be inserted at a bar line. These commands force and forbid a page-break from happening. Of course, the `\pageBreak` command also forces a line break.

The `\pageBreak` and `\noPageBreak` commands may also be inserted at top-level, between scores and top-level markups.

There are also analogous settings to `ragged-right` and `ragged-last` which have the same effect on vertical spacing: `ragged-bottom` and `ragged-last-bottom`. If set to `##t` the systems on all pages or just the last page respectively will not be justified vertically. See Fixed vertical spacing `\paper` variables.

Page breaks are computed by the `page-breaking` function. LilyPond provides three algorithms for computing page breaks, `ly:optimal-breaking`, `ly:page-turn-breaking` and `ly:minimal-breaking`. The default is `ly:optimal-breaking`, but the value can be changed in the `\paper` block:

>     \paper {
>       page-breaking = #ly:page-turn-breaking
>     }

When a book has many scores and pages, the page breaking problem may be difficult to solve, requiring large processing time and memory. To ease the page breaking process, `\bookpart` blocks are used to divide the book into several parts: the page breaking occurs separately on each part. Different page breaking functions may also be used in different book parts.

>     \bookpart {
>       \header {
>         subtitle = "Preface"
>       }
>       \paper {
>          %% In a part consisting mostly of text,
>          %% ly:minimal-breaking may be preferred
>          page-breaking = #ly:minimal-breaking
>       }
>       \markup { … }
>       …
>     }
>     \bookpart {
>       %% In this part, consisting of music, the default optimal
>       %% page breaking function is used.
>       \header {
>         subtitle = "First movement"
>       }
>       \score { … }
>       …
>     }

#### Predefined commands

`\pageBreak`, `\noPageBreak`.

#### See also

Notation Reference: `\paper` variables for page breaking.

Snippets: Spacing.

### 4.3.3 Optimal page breaking

The `ly:optimal-breaking` function is LilyPond’s default method of determining page breaks. It attempts to find a page breaking that minimizes cramping and stretching, both horizontally and vertically. Unlike `ly:page-turn-breaking`, it has no concept of page turns.

#### See also

Snippets: Spacing.

### 4.3.4 Optimal page turning

Often it is necessary to find a page breaking configuration so that there is a rest at the end of every second page. This way, the musician can turn the page without having to miss notes. The `ly:page-turn-breaking` function attempts to find a page breaking minimizing cramping and stretching, but with the additional restriction that it is only allowed to introduce page turns in specified places.

There are two steps to using this page breaking function. First, you must enable it in the `\paper` block, as explained in Page breaking. Then you must tell the function where you would like to allow page breaks.

There are two ways to achieve the second step. First, you can specify each potential page turn manually, by inserting `\allowPageTurn` into your input file at the appropriate places.

If this is too tedious, you can add a `Page_turn_engraver` to a Staff or Voice context. The `Page_turn_engraver` will scan the context for sections without notes (note that it does not scan for rests; it scans for the absence of notes. This is so that single-staff polyphony with rests in one of the parts does not throw off the `Page_turn_engraver`). When it finds a sufficiently long section without notes, the `Page_turn_engraver` will insert an `\allowPageTurn` at the final bar line in that section, unless there is a ‘special’ bar line (such as a double bar), in which case the `\allowPageTurn` will be inserted at the final ‘special’ bar line in the section.

The `Page_turn_engraver` reads the context property `minimumPageTurnLength` to determine how long a note-free section must be before a page turn is considered. The default value for `minimumPageTurnLength` is `#(ly:make-moment 1 1)`. If you want to disable page turns, you can set it to something very large.

>     \new Staff \with { \consists "Page_turn_engraver" }
>     {
>       a4 b c d |
>       R1 | % a page turn will be allowed here
>       a4 b c d |
>       \set Staff.minimumPageTurnLength = #(ly:make-moment 5 2)
>       R1 | % a page turn will not be allowed here
>       a4 b r2 |
>       R1*2 | % a page turn will be allowed here
>       a1
>     }

The `Page_turn_engraver` detects volta repeats. It will only allow a page turn during the repeat if there is enough time at the beginning and end of the repeat to turn the page back. The `Page_turn_engraver` can also disable page turns if the repeat is very short. If you set the context property `minimumRepeatLengthForPageTurn` then the `Page_turn_engraver` will only allow turns in repeats whose duration is longer than this value.

The page turning commands, `\pageTurn`, `\noPageTurn` and `\allowPageTurn`, may also be used at top-level, between scores and top-level markups.

#### Predefined commands

`\pageTurn`, `\noPageTurn`, `\allowPageTurn`.

#### See also

Snippets: Spacing.

#### Known issues and warnings

There should only be one `Page_turn_engraver` in a score. If there is more than one, they will interfere with each other.

### 4.3.5 Minimal page breaking

The `ly:minimal-breaking` function performs minimal computations to calculate the page breaking: it fills a page with as many systems as possible before moving to the next one. Thus, it may be preferred for scores with many pages, where the other page breaking functions could be too slow or memory demanding, or a lot of texts. It is enabled using:

>     \paper {
>       page-breaking = #ly:minimal-breaking
>     }

#### See also

Snippets: Spacing.

### 4.3.6 Explicit breaks

Lily sometimes rejects explicit `\break` and `\pageBreak` commands. There are two commands to override this behavior:

>     \override NonMusicalPaperColumn #'line-break-permission = ##f
>     \override NonMusicalPaperColumn #'page-break-permission = ##f

When `line-break-permission` is overridden to false, Lily will insert line breaks at explicit `\break` commands and nowhere else. When `page-break-permission` is overridden to false, Lily will insert page breaks at explicit `\pageBreak` commands and nowhere else.

>     \paper {
>       indent = #0
>       ragged-right = ##t
>       ragged-bottom = ##t
>     }

>     music = \relative c'' { c8 c c c }

>     \score {
>       \new Staff {
>         \repeat unfold 2 { \music } \break
>         \repeat unfold 4 { \music } \break
>         \repeat unfold 6 { \music } \break
>         \repeat unfold 8 { \music } \pageBreak
>         \repeat unfold 8 { \music } \break
>         \repeat unfold 6 { \music } \break
>         \repeat unfold 4 { \music } \break
>         \repeat unfold 2 { \music }
>       }
>       \layout {
>         \context {
>           \Score
>           \override NonMusicalPaperColumn #'line-break-permission = ##f
>           \override NonMusicalPaperColumn #'page-break-permission = ##f
>         }
>       }
>     }

#### See also

Snippets: Spacing.

### 4.3.7 Using an extra voice for breaks

Line- and page-breaking information usually appears within note entry directly.

>     music = \relative c'' { c4 c c c }

>     \score {
>       \new Staff {
>         \repeat unfold 2 { \music } \break
>         \repeat unfold 3 { \music }
>       }
>     }

This makes `\break` and `\pageBreak` commands easy to enter but mixes music entry with information that specifies how music should lay out on the page. You can keep music entry and line- and page-breaking information in two separate places by introducing an extra voice to contain the breaks. This extra voice contains only skips together with `\break`, `pageBreak` and other breaking layout information.

>     music = \relative c'' { c4 c c c }

>     \score {
>       \new Staff <<
>         \new Voice {
>           s1 * 2 \break
>           s1 * 3 \break
>           s1 * 6 \break
>           s1 * 5 \break
>         }
>         \new Voice {
>           \repeat unfold 2 { \music }
>           \repeat unfold 3 { \music }
>           \repeat unfold 6 { \music }
>           \repeat unfold 5 { \music }
>         }
>       >>
>     }

This pattern becomes especially helpful when overriding `line-break-system-details` and the other useful but long properties of `NonMusicalPaperColumnGrob`, as explained in Vertical spacing.

>     music = \relative c'' { c4 c c c }

>     \score {
>       \new Staff <<
>         \new Voice {
>           \overrideProperty "Score.NonMusicalPaperColumn"
>             #'line-break-system-details #'((Y-offset . 0))
>           s1 * 2 \break

>           \overrideProperty "Score.NonMusicalPaperColumn"
>             #'line-break-system-details #'((Y-offset . 35))
>           s1 * 3 \break

>           \overrideProperty "Score.NonMusicalPaperColumn"
>             #'line-break-system-details #'((Y-offset . 70))
>           s1 * 6 \break

>           \overrideProperty "Score.NonMusicalPaperColumn"
>             #'line-break-system-details #'((Y-offset . 105))
>           s1 * 5 \break
>         }
>         \new Voice {
>           \repeat unfold 2 { \music }
>           \repeat unfold 3 { \music }
>           \repeat unfold 6 { \music }
>           \repeat unfold 5 { \music }
>         }
>       >>
>     }

#### See also

Notation Reference: Vertical spacing.

Snippets: Spacing.

## 4.4 Vertical spacing

Vertical spacing is controlled by three things: the amount of space available (i.e., paper size and margins), the amount of space between systems, and the amount of space between staves inside a system.

### 4.4.1 Flexible vertical spacing within systems

Three separate mechanisms control the flexible vertical spacing within systems, one for each of the following categories:

- ungrouped staves,
- grouped staves (staves within a staff-group such as `ChoirStaff`, etc.), and
- non-staff lines (such as `Lyrics`, `ChordNames`, etc.).

The height of each system is determined in two steps. First, all of the staves are spaced according to the amount of space available. Then, the non-staff lines are distributed between the staves.

Note that the spacing mechanisms discussed in this section only control the vertical spacing of staves and non-staff lines within individual systems. The vertical spacing between separate systems, scores, markups, and margins is controlled by `\paper` variables, which are discussed in Flexible vertical spacing `\paper` variables.

#### Within-system spacing properties

The within-system vertical spacing mechanisms are controlled by two sets of grob properties. The first set is associated with the `VerticalAxisGroup` grob, which is created by all staves and non-staff lines. The second set is associated with the `StaffGrouper` grob, which can be created by staff-groups, but only if explicitly called. These properties are described individually at the end of this section.

The names of these properties (except for `staff-affinity`) follow the format `item1-item2-spacing`, where `item1` and `item2` are the items to be spaced. Note that `item2` is not necessarily below `item1`; for example, `nonstaff-relatedstaff-spacing` will measure upwards from the non-staff line if `staff-affinity` is `#UP`.

Each distance is measured between the reference points of the two items. The reference point for a staff is the vertical center of its `StaffSymbol` (i.e. the middle line if `line-count` is odd; the middle space if `line-count` is even). The reference points for individual non-staff lines are given in the following table:

Non-staff line | Reference point
--- | ---
`ChordNames` | baseline
`NoteNames` | baseline
`Lyrics` | baseline
`Dynamics` | vertical center
`FiguredBass` | highest point
`FretBoards` | top line

In the following image, horizontal lines indicate the positions of these reference points:

Each of the vertical spacing grob properties (except `staff-affinity`) uses the same alist structure as the `\paper` spacing variables discussed in Flexible vertical spacing `\paper` variables. Specific methods for modifying alists are discussed in Modifying alists. Grob properties should be adjusted with an `\override` inside a `\score` or `\layout` block, and not inside a `\paper` block.

The following example demonstrates the two ways these alists can be modified. The first declaration updates one key-value individually, and the second completely re-defines the property:

>     \new Staff \with {
>       \override VerticalAxisGroup #'default-staff-staff-spacing
>            #'basic-distance = #10
>     } { … }

>     \new Staff \with {
>       \override VerticalAxisGroup #'default-staff-staff-spacing =
>         #'((basic-distance . 10)
>            (minimum-distance . 9)
>            (padding . 1)
>            (stretchability . 10))
>     } { … }

To change any spacing settings globally, put them in the `\layout` block:

>     \layout {
>       \context {
>         \Staff
>         \override VerticalAxisGroup #'default-staff-staff-spacing
>              #'basic-distance = #10
>       }
>     }

Standard settings for the vertical spacing grob properties are listed in VerticalAxisGroup and StaffGrouper. Default overrides for specific types of non-staff lines are listed in the relevant context descriptions in Contexts.

#### Properties of the `VerticalAxisGroup` grob

`VerticalAxisGroup` properties are typically adjusted with an `\override` at the `Staff` level (or equivalent).

`staff-staff-spacing`

  Used to determine the distance between the current staff and the staff just below it in the same system, even if one or more non-staff lines (such as `Lyrics`) are placed between the two staves. Does not apply to the bottom staff of a system.

  Initially, the `staff-staff-spacing` of a `VerticalAxisGroup` is a Scheme function that applies the properties of the `StaffGrouper` if the staff is part of a group, or the `default-staff-staff-spacing` of the staff otherwise. This allows staves to be spaced differently when they are grouped. For uniform spacing regardless of grouping, this function may be replaced by a flexible-spacing alist, using the complete-redefinition form of override shown above.

`default-staff-staff-spacing`

  A flexible-spacing alist defining the `staff-staff-spacing` used for ungrouped staves, unless `staff-staff-spacing` has been explicitly set with an `\override`.

`staff-affinity`

  The direction of the staff to use for spacing the current non-staff line. Choices are `UP`, `DOWN`, and `CENTER`. If `CENTER`, the non-staff line will be placed equidistant between the two nearest staves on either side, unless collisions or other spacing constraints prevent this. Adjacent non-staff lines should have non-increasing `staff-affinity` from top to bottom, e.g. a non-staff line set to `UP` should not immediately follow one that is set to `DOWN`. Non-staff lines at the top of a system should use `DOWN`; those at the bottom should use `UP`. Setting `staff-affinity` for a staff causes it to be treated as a non-staff line. Setting `staff-affinity` to `#f` causes a non-staff line to be treated as a staff. Setting `staff-affinity` to `UP`, `CENTER`, or `DOWN` causes a staff to be spaced as a non-staff line.

`nonstaff-relatedstaff-spacing`

  The distance between the current non-staff line and the nearest staff in the direction of `staff-affinity`, if there are no non-staff lines between the two, and `staff-affinity` is either `UP` or `DOWN`. If `staff-affinity` is `CENTER`, then `nonstaff-relatedstaff-spacing` is used for the nearest staves on both sides, even if other non-staff lines appear between the current one and either of the staves. This means that the placement of a non-staff line depends on both the surrounding staves and the surrounding non-staff lines. Setting the `stretchability` of one of these types of spacing to a small value will make that spacing dominate. Setting the `stretchability` to a large value will make that spacing have little effect.

`nonstaff-nonstaff-spacing`

  The distance between the current non-staff line and the next non-staff line in the direction of `staff-affinity`, if both are on the same side of the related staff, and `staff-affinity` is either `UP` or `DOWN`.

`nonstaff-unrelatedstaff-spacing`

  The distance between the current non-staff line and the staff in the opposite direction from `staff-affinity`, if there are no other non-staff lines between the two, and `staff-affinity` is either `UP` or `DOWN`. This can be used, for example, to require a minimum amount of padding between a `Lyrics` line and the staff to which it does not belong.

#### Properties of the `StaffGrouper` grob

`StaffGrouper` properties are typically adjusted with an `\override` at the `StaffGroup` level (or equivalent).

`staff-staff-spacing`

  The distance between consecutive staves within the current staff-group. The `staff-staff-spacing` property of an individual staff’s `VerticalAxisGroup` grob can be overriden with different spacing settings for that staff.

`staffgroup-staff-spacing`

  The distance between the last staff of the current staff-group and the staff just below it in the same system, even if one or more non-staff lines (such as `Lyrics`) exist between the two staves. Does not apply to the bottom staff of a system. The `staff-staff-spacing` property of an individual staff’s `VerticalAxisGroup` grob can be overriden with different spacing settings for that staff.

#### See also

Notation Reference: Flexible vertical spacing `\paper` variables, Modifying alists.

Internals Reference: Contexts, VerticalAxisGroup, StaffGrouper.

Installed Files: ‘`ly/engraver-init.ly`’, ‘`scm/define-grobs.scm`’.

#### Spacing of ungrouped staves

Staves (such as `Staff`, `DrumStaff`, `TabStaff`, etc.) are contexts that can contain one or more voice contexts, but cannot contain any other staves.

The following properties affect the spacing of ungrouped staves:

- `VerticalAxisGroup` properties:
  - `default-staff-staff-spacing`
  - `staff-staff-spacing`

These grob properties are described individually above; see Within-system spacing properties.

Additional properties are involved for staves that are part of a staff-group; see Spacing of grouped staves.

The following example shows how the `default-staff-staff-spacing` property can affect the spacing of ungrouped staves. The same overrides applied to `staff-staff-spacing` would have the same effect, but would also apply in cases where the staves are combined in a group or groups.

>     \layout {
>       \context {
>         \Staff
>         \override VerticalAxisGroup #'default-staff-staff-spacing =
>           #'((basic-distance . 8)
>              (minimum-distance . 7)
>              (padding . 1))
>       }
>     }

>     <<
>       % The very low note here needs more room than 'basic-distance
>       % can provide, so the distance between this staff and the next
>       % is determined by 'padding.
>       \new Staff { b,2 r | }

>       % Here, 'basic-distance provides enough room, and there is no
>       % need to compress the space (towards 'minimum-distance) to make
>       % room for anything else on the page, so the distance between
>       % this staff and the next is determined by 'basic-distance.
>       \new Staff { \clef bass g2 r | }

>       % By setting 'padding to a negative value, staves can be made to
>       % collide.  The lowest acceptable value for 'basic-distance is 0.
>       \new Staff \with {
>         \override VerticalAxisGroup #'default-staff-staff-spacing =
>           #'((basic-distance . 3.5)
>              (padding . -10))
>       } { \clef bass g2 r | }
>       \new Staff { \clef bass g2 r | }
>     >>

#### See also

Installed Files: ‘`scm/define-grobs.scm`’.

Snippets: Spacing.

Internals Reference: VerticalAxisGroup.

#### Spacing of grouped staves

In orchestral and other large scores, it is common to place staves in groups. The space between groups is typically larger than the space between staves of the same group.

Staff-groups (such as `StaffGroup`, `ChoirStaff`, etc.) are contexts that can contain one or more staves simultaneously.

The following properties affect the spacing of staves inside staff-groups:

- `VerticalAxisGroup` properties:
  - `staff-staff-spacing`
- `StaffGrouper` properties:
  - `staff-staff-spacing`
  - `staffgroup-staff-spacing`

These grob properties are described individually above; see Within-system spacing properties.

The following example shows how properties of the `StaffGrouper` grob can affect the spacing of grouped staves:

>     \layout {
>       \context {
>         \Score
>         \override StaffGrouper #'staff-staff-spacing #'padding = #0
>         \override StaffGrouper #'staff-staff-spacing #'basic-distance = #1
>       }
>     }

>     <<
>       \new PianoStaff \with {
>         \override StaffGrouper #'staffgroup-staff-spacing #'basic-distance = #20
>       } <<
>         \new Staff { c'1 }
>         \new Staff { c'1 }
>       >>

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

#### See also

Installed Files: ‘`scm/define-grobs.scm`’.

Snippets: Spacing.

Internals Reference: VerticalAxisGroup, StaffGrouper.

#### Spacing of non-staff lines

Non-staff lines (such as `Lyrics`, `ChordNames`, etc.) are contexts whose layout objects are engraved like staves (i.e. in horizontal lines within systems). Specifically, non-staff lines are non-staff contexts that create the `VerticalAxisGroup` layout object.

The following properties affect the spacing of non-staff lines:

- `VerticalAxisGroup` properties:
  - `staff-affinity`
  - `nonstaff-relatedstaff-spacing`
  - `nonstaff-nonstaff-spacing`
  - `nonstaff-unrelatedstaff-spacing`

These grob properties are described individually above; see Within-system spacing properties.

The following example shows how the `nonstaff-nonstaff-spacing` property can affect the spacing of consecutive non-staff lines. Here, by setting the `stretchability` key to a very high value, the lyrics are able to stretch much more than usual:

>     \layout {
>       \context {
>         \Lyrics
>         \override VerticalAxisGroup
>           #'nonstaff-nonstaff-spacing #'stretchability = #1000
>       }
>     }

>     \new StaffGroup
>     <<
>       \new Staff \with {
>         \override VerticalAxisGroup #'staff-staff-spacing = #'((basic-distance . 30))
>       } { c'1 }
>       \new Lyrics \with {
>         \override VerticalAxisGroup #'staff-affinity = #UP
>       } \lyricmode { up }
>       \new Lyrics \with {
>         \override VerticalAxisGroup #'staff-affinity = #CENTER
>       } \lyricmode { center }
>       \new Lyrics \with {
>         \override VerticalAxisGroup #'staff-affinity = #DOWN
>       } \lyricmode { down }
>       \new Staff { c'1 }
>     >>

#### See also

Installed Files: ‘`ly/engraver-init.ly`’, ‘`scm/define-grobs.scm`’.

Snippets: Spacing.

Internals Reference: Contexts, VerticalAxisGroup.

### 4.4.2 Explicit staff and system positioning

One way to understand the flexible vertical spacing mechanisms explained above is as a collection of settings that control the amount of vertical padding between staves and systems.

It is possible to approach vertical spacing in a different way using `NonMusicalPaperColumn #'line-break-system-details`. While the flexible vertical spacing mechanisms specify vertical padding, `NonMusicalPaperColumn #'line-break-system-details` can specify exact vertical positions on the page.

`NonMusicalPaperColumn #'line-break-system-details` accepts an associative list of three different settings:

- `X-offset`
- `Y-offset`
- `alignment-distances`

Grob overrides, including the overrides for `NonMusicalPaperColumn` below, can occur in any of three different places in an input file:

- in the middle of note entry directly
- in a `\context` block
- in the `\with` block

When we override `NonMusicalPaperColumn`, we use the usual `\override` command in `\context` blocks and in the `\with` block. On the other hand, when we override `NonMusicalPaperColumn` in the middle of note entry, use the special `\overrideProperty` command. Here are some example `NonMusicalPaperColumn` overrides with the special `\overrideProperty` command:

>     \overrideProperty NonMusicalPaperColumn
>       #'line-break-system-details #'((X-offset . 20))

>     \overrideProperty NonMusicalPaperColumn
>       #'line-break-system-details #'((Y-offset . 40))

>     \overrideProperty NonMusicalPaperColumn
>       #'line-break-system-details #'((X-offset . 20)
>                                      (Y-offset . 40))

>     \overrideProperty NonMusicalPaperColumn
>       #'line-break-system-details #'((alignment-distances . (15)))

>     \overrideProperty NonMusicalPaperColumn
>       #'line-break-system-details #'((X-offset . 20)
>                                      (Y-offset . 40)
>                                      (alignment-distances . (15)))

To understand how each of these different settings work, we begin by looking at an example that includes no overrides at all.

>     \header { tagline = ##f }
>     \paper { left-margin = 0\mm }
>     \book {
>       \score {
>         <<
>           \new Staff <<
>             \new Voice {
>               s1*5 \break
>               s1*5 \break
>               s1*5 \break
>             }
>             \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
>           >>
>           \new Staff {
>             \repeat unfold 15 { d'4 d' d' d' }
>           }
>         >>
>       }
>     }

This score isolates line- and page-breaking information in a dedicated voice. This technique of creating a breaks voice will help keep layout separate from music entry as our example becomes more complicated. See Using an extra voice for breaks.

Explicit `\breaks` evenly divide the music into six measures per line. Vertical spacing results from LilyPond’s defaults. To set the vertical startpoint of each system explicitly, we can set the `Y-offset` pair in the `line-break-system-details` attribute of the `NonMusicalPaperColumn` grob:

>     \header { tagline = ##f }
>     \paper { left-margin = 0\mm }
>     \book {
>       \score {
>         <<
>           \new Staff <<
>             \new Voice {
>               \overrideProperty #"Score.NonMusicalPaperColumn"
>                 #'line-break-system-details #'((Y-offset . 0))
>               s1*5 \break
>               \overrideProperty #"Score.NonMusicalPaperColumn"
>                 #'line-break-system-details #'((Y-offset . 40))
>               s1*5 \break
>               \overrideProperty #"Score.NonMusicalPaperColumn"
>                 #'line-break-system-details #'((Y-offset . 80))
>               s1*5 \break
>             }
>             \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
>           >>
>           \new Staff {
>             \repeat unfold 15 { d'4 d' d' d' }
>           }
>         >>
>       }
>     }

Note that `line-break-system-details` takes an associative list of potentially many values, but that we set only one value here. Note, too, that the `Y-offset` property here determines the exact vertical position on the page at which each new system will render.

Now that we have set the vertical startpoint of each system explicitly, we can also set the vertical distances between staves within each system manually. We do this using the `alignment-distances` subproperty of `line-break-system-details`.

>     \header { tagline = ##f }
>     \paper { left-margin = 0\mm }
>     \book {
>       \score {
>         <<
>           \new Staff <<
>             \new Voice {
>               \overrideProperty #"Score.NonMusicalPaperColumn"
>                 #'line-break-system-details #'((Y-offset . 20)
>                                                (alignment-distances . (15)))
>               s1*5 \break
>               \overrideProperty #"Score.NonMusicalPaperColumn"
>                 #'line-break-system-details #'((Y-offset . 60)
>                                                (alignment-distances . (15)))
>               s1*5 \break
>               \overrideProperty #"Score.NonMusicalPaperColumn"
>                 #'line-break-system-details #'((Y-offset . 100)
>                                                (alignment-distances . (15)))
>               s1*5 \break
>             }
>             \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
>           >>
>           \new Staff {
>             \repeat unfold 15 { d'4 d' d' d' }
>           }
>         >>
>       }
>     }

Note that here we assign two different values to the `line-break-system-details` attribute of the `NonMusicalPaperColumn` grob. Though the `line-break-system-details` attribute alist accepts many additional spacing parameters (including, for example, a corresponding `X-offset` pair), we need only set the `Y-offset` and `alignment-distances` pairs to control the vertical startpoint of every system and every staff. Finally, note that `alignment-distances` specifies the vertical positioning of staves but not of staff groups.

>     \header { tagline = ##f }
>     \paper { left-margin = 0\mm }
>     \book {
>       \score {
>         <<
>           \new Staff <<
>             \new Voice {
>               \overrideProperty #"Score.NonMusicalPaperColumn"
>                 #'line-break-system-details #'((Y-offset . 0)
>                                                (alignment-distances . (30 10)))
>               s1*5 \break
>               \overrideProperty #"Score.NonMusicalPaperColumn"
>                 #'line-break-system-details #'((Y-offset . 60)
>                                                (alignment-distances . (10 10)))
>               s1*5 \break
>               \overrideProperty #"Score.NonMusicalPaperColumn"
>                 #'line-break-system-details #'((Y-offset . 100)
>                                                (alignment-distances . (10 30)))
>               s1*5 \break
>             }
>             \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
>           >>
>           \new StaffGroup <<
>             \new Staff { \repeat unfold 15 { d'4 d' d' d' } }
>             \new Staff { \repeat unfold 15 { e'4 e' e' e' } }
>           >>
>         >>
>       }
>     }

Some points to consider:

- When using `alignment-distances`, lyrics and other non-staff lines do not count as a staff.
- The units of the numbers passed to `X-offset`, `Y-offset` and `alignment-distances` are interpreted as multiples of the distance between adjacent staff lines. Positive values move staves and lyrics up, negative values move staves and lyrics down.
- Because the `NonMusicalPaperColumn #'line-break-system-details` settings given here allow the positioning of staves and systems anywhere on the page, it is possible to violate paper or margin boundaries or even to print staves or systems on top of one another. Reasonable values passed to these different settings will avoid this.

#### See also

Snippets: Spacing.

### 4.4.3 Vertical collision avoidance

Intuitively, there are some objects in musical notation that belong to the staff and there are other objects that should be placed outside the staff. Objects belonging outside the staff include things such as rehearsal marks, text and dynamic markings (from now on, these will be called outside-staff objects). LilyPond’s rule for the vertical placement of outside-staff objects is to place them as close to the staff as possible but not so close that they collide with another object.

LilyPond uses the `outside-staff-priority` property to determine whether a grob is an outside-staff object: if `outside-staff-priority` is a number, the grob is an outside-staff object. In addition, `outside-staff-priority` tells LilyPond in which order the objects should be placed.

First, LilyPond places all the objects that do not belong outside the staff. Then it sorts the outside-staff objects according to their `outside-staff-priority` (in increasing order). One by one, LilyPond takes the outside-staff objects and places them so that they do not collide with any objects that have already been placed. That is, if two outside-staff grobs are competing for the same space, the one with the lower `outside-staff-priority` will be placed closer to the staff.

>     c4_"Text"\pp
>     r2.
>     \once \override TextScript #'outside-staff-priority = #1
>     c4_"Text"\pp % this time the text will be closer to the staff
>     r2.
>     % by setting outside-staff-priority to a non-number,
>     % we disable the automatic collision avoidance
>     \once \override TextScript #'outside-staff-priority = ##f
>     \once \override DynamicLineSpanner #'outside-staff-priority = ##f
>     c4_"Text"\pp % now they will collide

The vertical padding between an outside-staff object and the previously-positioned grobs can be controlled with `outside-staff-padding`.

>     \once \override TextScript #'outside-staff-padding = #0
>     a'^"This text is placed very close to the note"
>     \once \override TextScript #'outside-staff-padding = #3
>     c^"This text is padded away from the previous text"
>     c^"This text is placed close to the previous text"

By default, outside-staff objects are placed only to avoid a horizontal collision with previously-positioned grobs. This can lead to situations in which objects are placed very close to each other horizontally. The vertical spacing between staves can also be set so that outside staff objects are interleaved. Setting `outside-staff-horizontal-padding` causes an object to be offset vertically so that such a situation doesn’t occur.

>     % the markup is too close to the following note
>     c4^"Text"
>     c4
>     c''2
>     % setting outside-staff-horizontal-padding fixes this
>     R1
>     \once \override TextScript #'outside-staff-horizontal-padding = #1
>     c,,4^"Text"
>     c4
>     c''2

#### See also

Snippets: Spacing.

## 4.5 Horizontal spacing

### 4.5.1 Horizontal spacing overview

The spacing engine translates differences in durations into stretchable distances (‘springs’) of differing lengths. Longer durations get more space, shorter durations get less. The shortest durations get a fixed amount of space (which is controlled by `shortest-duration-space` in the SpacingSpanner object). The longer the duration, the more space it gets: doubling a duration adds a fixed amount (this amount is controlled by `spacing-increment`) of space to the note.

For example, the following piece contains lots of half, quarter, and 8th notes; the eighth note is followed by 1 note head width (NHW). The quarter note is followed by 2 NHW, the half by 3 NHW, etc.

>     c2 c4. c8 c4. c8 c4. c8 c8
>     c8 c4 c4 c4

Normally, `spacing-increment` is set to 1.2 staff space, which is approximately the width of a note head, and `shortest-duration-space` is set to 2.0, meaning that the shortest note gets 2.4 staff space (2.0 times the `spacing-increment`) of horizontal space. This space is counted from the left edge of the symbol, so the shortest notes are generally followed by one NHW of space.

If one would follow the above procedure exactly, then adding a single 32nd note to a score that uses 8th and 16th notes, would widen up the entire score a lot. The shortest note is no longer a 16th, but a 32nd, thus adding 1 NHW to every note. To prevent this, the shortest duration for spacing is not the shortest note in the score, but rather the one which occurs most frequently.

The most common shortest duration is determined as follows: in every measure, the shortest duration is determined. The most common shortest duration is taken as the basis for the spacing, with the stipulation that this shortest duration should always be equal to or shorter than an 8th note. The shortest duration is printed when you run `lilypond` with the `--verbose` option.

These durations may also be customized. If you set the `common-shortest-duration` in SpacingSpanner, then this sets the base duration for spacing. The maximum duration for this base (normally an 8th), is set through `base-shortest-duration`.

Notes that are even shorter than the common shortest note are followed by a space that is proportional to their duration relative to the common shortest note. So if we were to add only a few 16th notes to the example above, they would be followed by half a NHW:

>     c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4

In the Essay on automated music engraving, it was explained that stem directions influence spacing (see Optical spacing). This is controlled with the `stem-spacing-correction` property in the NoteSpacing, object. These are generated for every Voice context. The `StaffSpacing` object (generated in Staff context) contains the same property for controlling the stem/bar line spacing. The following example shows these corrections, once with default settings, and once with exaggerated corrections:

Proportional notation is supported; see Proportional notation.

#### See also

Snippets: Spacing.

Internals Reference: SpacingSpanner, NoteSpacing, StaffSpacing, NonMusicalPaperColumn.

Essay on automated music engraving: Optical spacing.

#### Known issues and warnings

There is no convenient mechanism to manually override spacing. The following work-around may be used to insert extra space into a score, adjusting the padding value as necessary.

>      \override Score.NonMusicalPaperColumn #'padding = #10

No work-around exists for decreasing the amount of space.

### 4.5.2 New spacing area

New sections with different spacing parameters can be started with `newSpacingSection`. This is useful when there are sections with a different notions of long and short notes.

In the following example, the time signature change introduces a new section, and hence the 16ths notes are spaced wider.

>     \time 2/4
>     c4 c8 c
>     c8 c c4 c16[ c c8] c4
>     \newSpacingSection
>     \time 4/16
>     c16[ c c8]

The `\newSpacingSection` command creates a new `SpacingSpanner` object, and hence new `\override`s may be used in that location.

#### See also

Snippets: Spacing.

Internals Reference: SpacingSpanner.

### 4.5.3 Changing horizontal spacing

Horizontal spacing may be altered with the `base-shortest-duration` property. Here we compare the same music; once without altering the property, and then altered. Larger values of `ly:make-moment` will produce smaller music. Note that `ly:make-moment` constructs a duration, so `1 4` is a longer duration than `1 16`.

    \score {
      \relative c'' {
        g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
        g4 e e2 | f4 d d2 | c4 e g g | c,1 |
        d4 d d d | d4 e f2 | e4 e e e | e4 f g2 |
        g4 e e2 | f4 d d2 | c4 e g g | c,1 |
      }
    }

    \score {
      \relative c'' {
        g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
        g4 e e2 | f4 d d2 | c4 e g g | c,1 |
        d4 d d d | d4 e f2 | e4 e e e | e4 f g2 |
        g4 e e2 | f4 d d2 | c4 e g g | c,1 |
      }
      \layout {
        \context {
          \Score
          \override SpacingSpanner
            #'base-shortest-duration = #(ly:make-moment 1 16)
        }
      }
    }

#### Selected Snippets

By default, spacing in tuplets depends on various non-duration factors (such as accidentals, clef changes, etc). To disregard such symbols and force uniform equal-duration spacing, use `Score.SpacingSpanner #'uniform-stretching`. This property can only be changed at the beginning of a score,

>     \score {
>       <<
>         \new Staff {
>           \times 4/5 {
>             c8 c8 c8 c8 c8
>           }
>           c8 c8 c8 c8
>         }
>         \new Staff {
>           c8 c8 c8 c8
>           \times 4/5 {
>             c8 c8 c8 c8 c8
>           }
>         }
>       >>
>       \layout {
>         \context {
>           \Score
>           \override SpacingSpanner #'uniform-stretching = ##t
>         }
>       }
>     }

When `strict-note-spacing` is set, notes are spaced without regard for clefs, bar lines, and grace notes,

>     \override Score.SpacingSpanner #'strict-note-spacing = ##t
>     \new Staff { c8[ c \clef alto c \grace { c16[ c] } c8 c c]  c32[ c32] }

#### See also

Snippets: Spacing.

### 4.5.4 Line length

The most basic settings influencing the spacing are `indent` and `line-width`. They are set in the `\layout` block. They control the indentation of the first line of music, and the lengths of the lines.

If `ragged-right` is set to true in the `\layout` block, then systems ends at their natural horizontal length, instead of being spread horizontally to fill the whole line. This is useful for short fragments, and for checking how tight the natural spacing is. The normal default setting is false, but if the score has only one system the default value is true.

The option `ragged-last` is similar to `ragged-right`, but only affects the last line of the piece. No restrictions are put on that line. The result is similar to formatting text paragraphs. In a paragraph, the last line simply takes its natural horizontal length.

>     \layout {
>       indent = #0
>       line-width = #150
>       ragged-last = ##t
>     }

#### See also

Snippets: Spacing.

### 4.5.5 Proportional notation

LilyPond supports proportional notation, a type of horizontal spacing in which each note consumes an amount of horizontal space exactly equivalent to its rhythmic duration. This type of proportional spacing is comparable to horizontal spacing on top of graph paper. Some late 20th- and early 21st-century scores use proportional notation to clarify complex rhythmic relationships or to facilitate the placement of timelines or other graphics directly in the score.

LilyPond supports five different settings for proportional notation, which may be used together or alone:

- `proportionalNotationDuration`
- `uniform-stretching`
- `strict-note-spacing`
- `\remove Separating_line_group_engraver`
- `\override PaperColumn #'used = ##t`

In the examples that follow, we explore these five different proportional notation settings and examine how these settings interact.

We start with the following one-measure example, which uses classical spacing with ragged-right turned on.

>     \score {
>       <<
>         \new RhythmicStaff {
>           c'2
>           c'16 c'16 c'16 c'16
>           \times 4/5 {
>             c'16 c'16 c'16 c'16 c'16
>           }
>         }
>       >>
>     }

Notice that the half note which begins the measure takes up far less than half of the horizontal space of the measure. Likewise, the sixteenth notes and sixteenth-note quintuplets (or twentieth notes) which end the measure together take up far more than half the horizontal space of the measure.

In classical engraving, this spacing may be exactly what we want because we can borrow horizontal space from the half note and conserve horizontal space across the measure as a whole.

On the other hand, if we want to insert a measured timeline or other graphic above or below our score, we need proportional notation. We turn proportional notation on with the proportionalNotationDuration setting.

>     \score {
>       <<
>         \new RhythmicStaff {
>           c'2
>           c'16 c'16 c'16 c'16
>           \times 4/5 {
>             c'16 c'16 c'16 c'16 c'16
>           }
>         }
>       >>
>      \layout {
>         \context {
>           \Score
>           proportionalNotationDuration = #(ly:make-moment 1 20)
>         }
>       }
>     }

The half note at the beginning of the measure and the faster notes in the second half of the measure now occupy equal amounts of horizontal space. We could place a measured timeline or graphic above or below this example.

The `proportionalNotationDuration` setting is a context setting that lives in `Score`. Remember that context settings can appear in one of three locations within our input file – in a `\with` block, in a `\context` block, or directly in music entry preceded by the `\set` command. As with all context settings, users can pick which of the three different locations they would like to set `proportionalNotationDuration` in to.

The `proportionalNotationDuration` setting takes a single argument, which is the reference duration against that all music will be spaced. The LilyPond Scheme function `make-moment` takes two arguments – a numerator and denominator which together express some fraction of a whole note. The call `#(ly:make-moment 1 20)` therefore produces a reference duration of a twentieth note. Values such as `#(ly:make-moment 1 16)`, `#(ly:make-moment 1 8)`, and `#(ly:make-moment 3 97)` are all possible as well.

How do we select the right reference duration to pass to `proportionalNotationDuration`? Usually by a process of trial and error, beginning with a duration close to the fastest (or smallest) duration in the piece. Smaller reference durations space music loosely; larger reference durations space music tightly.

>     \score {
>       <<
>         \new RhythmicStaff {
>           c'2
>           c'16 c'16 c'16 c'16
>           \times 4/5 {
>             c'16 c'16 c'16 c'16 c'16
>           }
>         }
>       >>
>       \layout {
>         \context {
>           \Score
>           proportionalNotationDuration = #(ly:make-moment 1 8)
>         }
>       }
>     }

>     \score {
>       <<
>         \new RhythmicStaff {
>           c'2
>           c'16 c'16 c'16 c'16
>           \times 4/5 {
>             c'16 c'16 c'16 c'16 c'16
>           }
>         }
>       >>
>       \layout {
>         \context {
>           \Score
>           proportionalNotationDuration = #(ly:make-moment 1 16)
>         }
>       }
>     }

>     \score {
>       <<
>         \new RhythmicStaff {
>           c'2
>           c'16 c'16 c'16 c'16
>           \times 4/5 {
>             c'16 c'16 c'16 c'16 c'16
>           }
>         }
>       >>
>       \layout {
>         \context {
>           \Score
>           proportionalNotationDuration = #(ly:make-moment 1 32)
>         }
>       }
>     }

Note that too large a reference duration – such as the eighth note, above – spaces music too tightly and can cause note head collisions. Also that proportional notation in general takes up more horizontal space than classical spacing. Proportional spacing provides rhythmic clarity at the expense of horizontal space.

Next we examine how to optimally space overlapping tuplets.

We start by examining what happens to our original example, with classical spacing, when we add a second staff with a different type of tuplet.

>     \score {
>       <<
>         \new RhythmicStaff {
>           c'2
>           c'16 c'16 c'16 c'16
>           \times 4/5 {
>             c'16 c'16 c'16 c'16 c'16
>           }
>         }
>         \new RhythmicStaff {
>           \times 8/9 {
>             c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
>           }
>         }
>       >>
>     }

The spacing is bad because the evenly spaced notes of the bottom staff do not stretch uniformly. Classical engravings include very few complex triplets and so classical engraving rules can generate this type of result. Setting `proportionalNotationDuration` fixes this.

>     \score {
>       <<
>         \new RhythmicStaff {
>           c'2
>           c'16 c'16 c'16 c'16
>           \times 4/5 {
>             c'16 c'16 c'16 c'16 c'16
>           }
>         }
>         \new RhythmicStaff {
>           \times 8/9 {
>             c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
>           }
>         }
>       >>
>       \layout {
>         \context {
>           \Score
>           proportionalNotationDuration = #(ly:make-moment 1 20)
>         }
>       }
>     }

But if we look very carefully we can see that notes of the second half of the 9-tuplet space ever so slightly more widely than the notes of the first half of the 9-tuplet. To ensure uniform stretching, we turn on `uniform-stretching`, which is a property of `SpacingSpanner`.

>     \score {
>       <<
>         \new RhythmicStaff {
>           c'2
>           c'16 c'16 c'16 c'16
>           \times 4/5 {
>             c'16 c'16 c'16 c'16 c'16
>           }
>         }
>         \new RhythmicStaff {
>           \times 8/9 {
>             c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
>           }
>         }
>       >>
>       \layout {
>         \context {
>           \Score
>           proportionalNotationDuration = #(ly:make-moment 1 20)
>           \override SpacingSpanner #'uniform-stretching = ##t
>         }
>       }
>     }

Our two-staff example now spaces exactly, our rhythmic relationships are visually clear, and we can include a measured timeline or graphic if we want.

Note that the LilyPond’s proportional notation package expects that all proportional scores set the SpacingSpanner’s ’uniform-stretching attribute to ##t. Setting proportionalNotationDuration without also setting the SpacingSpanner’s ’uniform-stretching attribute to ##t will, for example, cause Skips to consume an incorrect amount of horizontal space.

The SpacingSpanner is an abstract grob that lives in the Score context. As with our settings of proportionalNotationDuration, overrides to the SpacingSpanner can occur in any of three different places in our input file – in the Score \with block, in a Score \context block, or in note entry directly.

There is by default only one `SpacingSpanner` per `Score`. This means that, by default, `uniform-stretching` is either turned on for the entire score or turned off for the entire score. We can, however, override this behavior and turn on different spacing features at different places in the score. We do this with the command `\newSpacingSection`. See New spacing area, for more info.

Next we examine the effects of the `Separating_line_group_engraver` and see why proportional scores frequently remove this engraver. The following example shows that there is a small amount of “prefatory” space just before the first note in each system.

>     \paper {
>       indent = #0
>     }

>     \new Staff {
>       c'1
>       \break
>       c'1
>     }

The amount of this prefatory space is the same whether after a time signature, a key signature or a clef. `Separating_line_group_engraver` is responsible for this space. Removing `Separating_line_group_engraver` reduces this space to zero.

>     \paper {
>       indent = #0
>     }

>     \new Staff \with {
>       \remove Separating_line_group_engraver
>     } {
>       c'1
>       \break
>       c'1
>     }

non-musical elements like time signatures, key signatures, clefs and accidentals are problematic in proportional notation. None of these elements has rhythmic duration. But all of these elements consume horizontal space. Different proportional scores approach these problems differently.

It may be possible to avoid spacing problems with key signatures simply by not having any. This is a valid option since most proportional scores are contemporary music. The same may be true of time signatures, especially for those scores that include a measured timeline or other graphic. But these scores are exceptional and most proportional scores include at least some time signatures. Clefs and accidentals are even more essential.

So what strategies exist for spacing non-musical elements in a proportional context? One good option is the `strict-note-spacing` property of `SpacingSpanner`. Compare the two scores below:

>     \new Staff {
>       \set Score.proportionalNotationDuration = #(ly:make-moment 1 16)
>       c''8
>       c''8
>       c''8
>       \clef alto
>       d'8
>       d'2
>     }

>     \new Staff {
>       \set Score.proportionalNotationDuration = #(ly:make-moment 1 16)
>       \override Score.SpacingSpanner #'strict-note-spacing = ##t
>       c''8
>       c''8
>       c''8
>       \clef alto
>       d'8
>       d'2
>     }

Both scores are proportional, but the spacing in the first score is too loose because of the clef change. The spacing of the second score remains strict, however, because strict-note-spacing is turned on. Turning on strict-note-spacing causes the width of time signatures, key signatures, clefs and accidentals to play no part in the spacing algorithm.

In addition to the settings given here, there are other settings that frequently appear in proportional scores. These include:

- `\override SpacingSpanner #'strict-grace-spacing = ##t`
- `tupletFullLength = ##t`
- `\override Beam #'breakable = ##t`
- `\override Glissando #'breakable = ##t`
- `\override TextSpanner #'breakable = ##t`
- `\remove Forbid_line_break_engraver in the Voice context`

These settings space grace notes strictly, extend tuplet brackets to mark both rhythmic start- and stop-points, and allow spanning elements to break across systems and pages. See the respective parts of the manual for these related settings.

#### See also

Notation Reference: New spacing area.

Snippets: Spacing.

## 4.6 Fitting music onto fewer pages

Sometimes you can end up with one or two staves on a second (or third, or fourth...) page. This is annoying, especially if you look at previous pages and it looks like there is plenty of room left on those.

When investigating layout issues, `annotate-spacing` is an invaluable tool. This command prints the values of various layout spacing variables; for more details see the following section, Displaying spacing.

### 4.6.1 Displaying spacing

To graphically display the dimensions of vertical layout variables that may be altered for page formatting, set `annotate-spacing` in the `\paper` block:

>     #(set-default-paper-size "a6" 'landscape)
>     \book {
>       \score { { c4 } }
>       \paper { annotate-spacing = ##t }
>     }

All layout dimensions are displayed in staff-spaces, regardless of the units specified in the `\paper` or `\layout` block. In the above example, `paper-height` has a value of 59.75 `staff-spaces`, and the `staff-size` is 20 points (the default value). Note that:

1 point | = (25.4/72.27) mm
1 staff-space | = (`staff-size`)/4 pts
| = (`staff-size`)/4 * (25.4/72.27) mm

In this case, one `staff-space` is approximately equal to 1.757mm. Thus the `paper-height` measurement of 59.75 `staff-spaces` is equivalent to 105 millimeters, the height of `a6` paper in landscape orientation. The pairs (a,b) are intervals, where a is the lower edge and b the upper edge of the interval.

#### See also

Notation Reference: Setting the staff size.

Snippets: Spacing.

### 4.6.2 Changing spacing

The output of `annotate-spacing` reveals vertical dimensions in great detail. For details about modifying margins and other layout variables, see Page layout.

Other than margins, there are a few other options to save space:

- Force systems to move as close together as possible (to fit as many systems as possible onto a page) while being spaced so that there is no blank space at the bottom of the page.

  >     \paper {
  >       system-system-spacing = #'((basic-distance . 0.1) (padding . 0))
  >       ragged-last-bottom = ##f
  >       ragged-bottom = ##f
  >     }

- Force the number of systems. This can help in two ways. Just setting a value, even the same value as the number of systems being typeset by default, will sometimes cause more systems to be fitted onto each page, as an estimation step is then bypassed, giving a more accurate fit to each page. Also, forcing an actual reduction in the number of systems may save a further page. For example, if the default layout has 11 systems, the following assignment will force a layout with 10 systems.

  >     \paper {
  >       system-count = #10
  >     }

- Avoid (or reduce) objects that increase the vertical size of a system. For example, volta repeats (or alternate repeats) require extra space. If these repeats are spread over two systems, they will take up more space than one system with the volta repeats and another system without. For example, dynamics that ‘stick out’ of a system can be moved closer to the staff:

  >     e4 c g\f c
  >     e4 c g-\tweak #'X-offset #-2.7 -\tweak #'Y-offset #2.5 \f c

- Alter the horizontal spacing via `SpacingSpanner`. For more details, see Changing horizontal spacing. The following example illustrates the default spacing:

  >     \score {
  >       \relative c'' {
  >         g4 e e2 |
  >         f4 d d2 |
  >         c4 d e f |
  >         g4 g g2 |
  >         g4 e e2 |
  >       }
  >     }

  The next example modifies `common-shortest-duration` from a value of `1/4` to `1/2`. The quarter note is the most common and shortest duration in this example, so by making this duration longer, a ‘squeezing’ effect occurs:

  >     \score {
  >       \relative c'' {
  >         g4 e e2 |
  >         f4 d d2 |
  >         c4 d e f |
  >         g4 g g2 |
  >         g4 e e2 |
  >       }
  >       \layout {
  >         \context {
  >           \Score
  >           \override SpacingSpanner
  >             #'common-shortest-duration = #(ly:make-moment 1 2)
  >         }
  >       }
  >     }

  The `common-shortest-duration` property cannot be modified dynamically, so it must always be placed in a `\context` block so that it applies to the whole score.

#### See also

Notation Reference: Page layout, Changing horizontal spacing.

Snippets: Spacing.

# 5. Changing defaults

The purpose of LilyPond’s design is to provide the finest quality output by default. Nevertheless, it may happen that you need to change this default layout. The layout is controlled through a large number of ‘knobs and switches’ collectively called ‘properties’. A tutorial introduction to accessing and modifying these properties can be found in the Learning Manual, see Tweaking output. This should be read first. This chapter covers similar ground, but in a style more appropriate to a reference manual.

The definitive description of the controls available for tuning can be found in a separate document: the Internals Reference. That manual lists all the variables, functions and options available in LilyPond. It is written as a HTML document, which is available on-line, and is also included with the LilyPond documentation package.

Internally, LilyPond uses Scheme (a LISP dialect) to provide infrastructure. Overriding layout decisions in effect accesses the program internals, which requires Scheme input. Scheme elements are introduced in a ‘`.ly`’ file with the hash mark `#`.1

## 5.1 Interpretation contexts

This section describes what contexts are, and how to modify them.

#### See also

Learning Manual: Contexts and engravers.

Installed Files: ‘`ly/engraver-init.ly`’, ‘`ly/performer-init.ly`’.

Snippets: Contexts and engravers.

Internals Reference: Contexts, Engravers and Performers.

### 5.1.1 Contexts explained

Contexts are arranged hierarchically:

#### Score - the master of all contexts

This is the top level notation context. No other context can contain a Score context. By default the Score context handles the administration of time signatures and makes sure that items such as clefs, time signatures, and key-signatures are aligned across staves.

A Score context is instantiated implicitly when a `\score {…}` or `\layout {…}` block is processed.

#### Top-level contexts - staff containers

StaffGroup

Groups staves while adding a bracket on the left side, grouping the staves together. The bar lines of the contained staves are connected vertically. `StaffGroup` only consists of a collection of staves, with a bracket in front and spanning bar lines.

ChoirStaff

Identical to `StaffGroup` except that the bar lines of the contained staves are not connected vertically.

GrandStaff

A group of staves, with a brace on the left side, grouping the staves together. The bar lines of the contained staves are connected vertically.

PianoStaff

Just like `GrandStaff`, but with support for instrument names to the left of each system.

#### Intermediate-level contexts - staves

Staff

Handles clefs, bar lines, keys, accidentals. It can contain `Voice` contexts.

RhythmicStaff

Like `Staff` but for printing rhythms. Pitches are ignored; the notes are printed on one line.

TabStaff

Context for generating tablature. By default lays the music expression out as a guitar tablature, printed on six lines.

DrumStaff

Handles typesetting for percussion. Can contain `DrumVoice`

VaticanaStaff

Same as `Staff`, except that it is designed for typesetting a piece in gregorian style.

MensuralStaff

Same as `Staff`, except that it is designed for typesetting a piece in mensural style.

#### Bottom-level contexts - voices

Voice-level contexts initialise certain properties and start appropriate engravers. Being bottom-level contexts, they cannot contain other contexts.

Voice

Corresponds to a voice on a staff. This context handles the conversion of dynamic signs, stems, beams, super- and sub-scripts, slurs, ties, and rests. You have to instantiate this explicitly if you require multiple voices on the same staff.

VaticanaVoice

Same as `Voice`, except that it is designed for typesetting a piece in gregorian style.

MensuralVoice

Same as `Voice`, with modifications for typesetting a piece in mensural style.

Lyrics

Corresponds to a voice with lyrics. Handles the printing of a single line of lyrics.

DrumVoice

The voice context used in a percussion staff.

FiguredBass

The context in which `BassFigure` objects are created from input entered in `\figuremode` mode.

TabVoice

The voice context used within a `TabStaff` context. Usually left to be created implicitly.

CueVoice

A voice context used to render notes of a reduced size, intended primarily for adding cue notes to a staff, see Formatting cue notes. Usually left to be created implicitly.

ChordNames

Typesets chord names.

### 5.1.2 Creating contexts

For scores with only one voice and one staff, contexts are created automatically. For more complex scores, it is necessary to create them by hand. There are three commands that do this.

- The easiest command is `\new`, and it also the quickest to type. It is prepended to a music expression, for example

  >     \new type music expression

  where type is a context name (like `Staff` or `Voice`). This command creates a new context, and starts interpreting the music expression with that.

  A practical application of `\new` is a score with many staves. Each part that should be on its own staff, is preceded with `\new Staff`.

  >     <<
  >       \new Staff { c4 c }
  >       \new Staff { d4 d }
  >     >>

  The `\new` command may also give a name to the context,

  >     \new type = id music

  However, this user specified name is only used if there is no other context already earlier with the same name.

- Like `\new`, the `\context` command also directs a music expression to a context object, but gives the context an explicit name. The syntax is

  >     \context type = id music

  This form will search for an existing context of type type called id. If that context does not exist yet, a new context with the specified name is created. This is useful if the context is referred to later on. For example, when setting lyrics the melody is in a named context

  >     \context Voice = "tenor" music

  so the texts can be properly aligned to its notes,

  >     \new Lyrics \lyricsto "tenor" lyrics

  Another possible use of named contexts is funneling two different music expressions into one context. In the following example, articulations and notes are entered separately,

  >     music = { c4 c4 }
  >     arts = { s4-. s4-> }

  They are combined by sending both to the same `Voice` context,

  >     <<
  >       \new Staff \context Voice = "A" \music
  >       \context Voice = "A" \arts
  >     >>

  With this mechanism, it is possible to define an Urtext (original edition), with the option to put several distinct articulations on the same notes.

- The third command for creating contexts is

  >     \context type music

  This is similar to `\context` with `= id`, but matches any context of type type, regardless of its given name.

  This variant is used with music expressions that can be interpreted at several levels. For example, the `\applyOutput` command (see Running a function on all layout objects). Without an explicit `\context`, it is usually applied to `Voice`

  >     \applyOutput #'context #function   % apply to Voice

  To have it interpreted at the `Score` or `Staff` level use these forms

  >     \applyOutput #'Score #function
  >     \applyOutput #'Staff #function

### 5.1.3 Keeping contexts alive

Contexts are usually terminated at the first musical moment in which they have nothing to do. So `Voice` contexts die as soon as they contain no events; `Staff` contexts die as soon as all the `Voice` contexts within them contain no events; etc. This can cause difficulties if earlier contexts which have died have to be referenced, for example, when changing staves with `\change` commands, associating lyrics with a voice with `\lyricsto` commands, or when adding further musical events to an earlier context.

There is an exception to this general rule: just one of the `Voice` contexts in a `Staff` context or in a `<<...>>` construct will always persist to the end of the enclosing `Staff` context or `<<...>>` construct, even though there may be periods when it has nothing to do. The context to persist in this way will be the first one encountered in the first enclosed `{...}` construct, ignoring any in enclosed `<<...>>` constructs.

Any context can be kept alive by ensuring it has something to do at every musical moment. `Staff` contexts are kept alive by ensuring one of their voices is kept alive. One way of doing this is to add spacer rests to a voice in parallel with the real music. These need to be added to every `Voice` context which needs to be kept alive. If several voices are to be used sporadically it is safest to keep them all alive rather than attempting to rely on the exceptions mentioned above.

In the following example, both voice A and voice B are kept alive in this way for the duration of the piece:

>     musicA = \relative c'' { d4 d d d }
>     musicB = \relative c'' { g4 g g g }
>     keepVoicesAlive = {
>       <<
>         \new Voice = "A" { s1*5 }  % Keep Voice "A" alive for 5 bars
>         \new Voice = "B" { s1*5 }  % Keep Voice "B" alive for 5 bars
>       >>
>     }

>     music = {
>       \context Voice = "A" {
>         \voiceOneStyle
>         \musicA
>       }
>       \context Voice = "B" {
>         \voiceTwoStyle
>         \musicB
>       }
>       \context Voice = "A" { \musicA }
>       \context Voice = "B" { \musicB }
>       \context Voice = "A" { \musicA }
>     }

>     \score {
>       \new Staff <<
>         \keepVoicesAlive
>         \music
>       >>
>     }

The following example shows how a sporadic melody line with lyrics might be written using this approach. In a real situation the melody and accompaniment would consist of several different sections, of course.

>     melody = \relative c'' { a4 a a a }
>     accompaniment = \relative c' { d4 d d d }
>     words = \lyricmode { These words fol -- low the mel -- o -- dy }
>     \score {
>       <<
>         \new Staff = "music" {
>           <<
>             \new Voice = "melody" {
>               \voiceOne
>               s1*4  % Keep Voice "melody" alive for 4 bars
>             }
>             {
>               \new Voice = "accompaniment" {
>                 \voiceTwo
>                 \accompaniment
>               }
>               <<
>                 \context Voice = "melody" { \melody }
>                 \context Voice = "accompaniment" { \accompaniment }
>               >>
>               \context Voice = "accompaniment" { \accompaniment }
>               <<
>                 \context Voice = "melody" { \melody }
>                 \context Voice = "accompaniment" { \accompaniment }
>               >>
>             }
>           >>
>         }
>         \new Lyrics \with { alignAboveContext = #"music" }
>         \lyricsto "melody" { \words }
>       >>
>     }

An alternative way, which may be better in many circumstances, is to keep the melody line alive by simply including spacer notes to line it up correctly with the accompaniment:

>     melody = \relative c'' {
>       s1  % skip a bar
>       a4 a a a
>       s1  % skip a bar
>       a4 a a a
>     }
>     accompaniment = \relative c' {
>       d4 d d d
>       d4 d d d
>       d4 d d d
>       d4 d d d
>     }
>     words = \lyricmode { These words fol -- low the mel -- o -- dy }

>     \score {
>       <<
>         \new Staff = "music" {
>           <<
>             \new Voice = "melody" {
>               \voiceOne
>               \melody
>             }
>             \new Voice = "accompaniment" {
>               \voiceTwo
>               \accompaniment
>             }
>           >>
>         }
>         \new Lyrics \with { alignAboveContext = #"music" }
>         \lyricsto "melody" { \words }
>       >>
>     }

### 5.1.4 Modifying context plug-ins

Notation contexts (like `Score` and `Staff`) not only store properties, they also contain plug-ins called ‘engravers’ that create notation elements. For example, the `Voice` context contains a `Note_heads_engraver` and the `Staff` context contains a `Key_signature_engraver`.

For a full a description of each plug-in, see Engravers and Performers. Every context described in Contexts lists the engravers used for that context.

It can be useful to shuffle around these plug-ins. This is done by starting a new context with `\new` or `\context`, and modifying it,

>     \new context \with {
>       \consists …
>       \consists …
>       \remove …
>       \remove …
>       etc.
>     }
>     {
>       ..music..
>     }

where the … should be the name of an engraver. Here is a simple example which removes `Time_signature_engraver` and `Clef_engraver` from a `Staff` context,

>     <<
>       \new Staff {
>         f2 g
>       }
>       \new Staff \with {
>          \remove "Time_signature_engraver"
>          \remove "Clef_engraver"
>       } {
>         f2 g2
>       }
>     >>

In the second staff there are no time signature or clef symbols. This is a rather crude method of making objects disappear since it will affect the entire staff. This method also influences the spacing, which may or may not be desirable. More sophisticated methods of blanking objects are shown in Visibility and color of objects.

The next example shows a practical application. Bar lines and time signatures are normally synchronized across the score. This is done by the `Timing_translator` and `Default_bar_line_engraver`. This plug-in keeps an administration of time signature, location within the measure, etc. By moving these engraver from `Score` to `Staff` context, we can have a score where each staff has its own time signature.

>     \score {
>       <<
>         \new Staff \with {
>           \consists "Timing_translator"
>           \consists "Default_bar_line_engraver"
>         } {
>             \time 3/4
>             c4 c c c c c
>         }
>       \new Staff \with {
>         \consists "Timing_translator"
>         \consists "Default_bar_line_engraver"
>       } {
>           \time 2/4
>           c4 c c c c c
>       }
>     >>
>     \layout {
>       \context {
>         \Score
>         \remove "Timing_translator"
>         \remove "Default_bar_line_engraver"
>         }
>       }
>     }

#### Known issues and warnings

Usually the order in which the engravers are specified does not matter, but in a few special cases the order is important, for example where one engraver writes a property and another reads it, or where one engraver creates a grob and another must process it. The order in which the engravers are specified is the order in which they are called to carry out their processing.

The following orderings are important: the `Bar_engraver` must normally be first, and the `New_fingering_engraver` must come before the `Script_column_engraver`. There may be others with ordering dependencies.

### 5.1.5 Changing context default settings

The context settings which are to be used by default in `Score`, `Staff` and `Voice` contexts may be specified in a `\layout` block, as illustrated in the following example. The `\layout` block should be placed within the `\score` block to which it is to apply, but outside any music.

Note that the `\set` command itself and the context must be omitted when the context default values are specified in this way:

>     \score {
>       \relative c'' {
>         a4^"Really small, thicker stems, no time signature" a a a
>         a a a a
>       }
>       \layout {
>         \context {
>           \Staff
>           fontSize = #-4
>           \override Stem #'thickness = #4.0
>           \remove "Time_signature_engraver"
>         }
>       }
>     }

In this example, the `\Staff` command specifies that the subsequent specifications are to be applied to all staves within this score block.

Modifications can be made to the `Score` context or all `Voice` contexts in a similar way.

#### Known issues and warnings

It is not possible to collect context changes in a variable and apply them to a `\context` definition by referring to that variable.

The `\Staff \RemoveEmptyStaves` will overwrite your current `\Staff` settings. If you wish to change the defaults for a staff which uses `\Staff \RemoveEmptyStaves`, you must do so after calling `\Staff \RemoveEmptyStaves`, ie

>     \layout {
>       \context {
>         \Staff \RemoveEmptyStaves

>         \override Stem #'thickness = #4.0
>       }
>     }

### 5.1.6 Defining new contexts

Specific contexts, like `Staff` and `Voice`, are made of simple building blocks. It is possible to create new types of contexts with different combinations of engraver plug-ins.

The next example shows how to build a different type of `Voice` context from scratch. It will be similar to `Voice`, but only prints centered slash note heads. It can be used to indicate improvisation in jazz pieces,

These settings are defined within a `\context` block inside a `\layout` block,

>     \layout {
>       \context {
>         …
>       }
>     }

In the following discussion, the example input shown should go in place of the … in the previous fragment.

First it is necessary to define a name for the new context:

>     \name ImproVoice

Since it is similar to the `Voice`, we want commands that work on (existing) `Voice`s to remain working. This is achieved by giving the new context an alias `Voice`,

>     \alias Voice

The context will print notes and instructive texts, so we need to add the engravers which provide this functionality,

>     \consists Note_heads_engraver
>     \consists Text_engraver

but we only need this on the center line,

>     \consists Pitch_squash_engraver
>     squashedPosition = #0

The Pitch_squash_engraver modifies note heads (created by Note_heads_engraver) and sets their vertical position to the value of `squashedPosition`, in this case `0`, the center line.

The notes look like a slash, and have no stem,

>     \override NoteHead #'style = #'slash
>     \override Stem #'transparent = ##t

All these plug-ins have to cooperate, and this is achieved with a special plug-in, which must be marked with the keyword `\type`. This should always be `Engraver_group`.

>     \type "Engraver_group"

Put together, we get

>     \context {
>       \name ImproVoice
>       \type "Engraver_group"
>       \consists "Note_heads_engraver"
>       \consists "Text_engraver"
>       \consists Pitch_squash_engraver
>       squashedPosition = #0
>       \override NoteHead #'style = #'slash
>       \override Stem #'transparent = ##t
>       \alias Voice
>     }

Contexts form hierarchies. We want to hang the `ImproVoice` under `Staff`, just like normal `Voice`s. Therefore, we modify the `Staff` definition with the `\accepts` command,

>     \context {
>       \Staff
>       \accepts ImproVoice
>     }

The opposite of `\accepts` is `\denies`, which is sometimes needed when reusing existing context definitions.

Putting both into a `\layout` block, like

>     \layout {
>       \context {
>         \name ImproVoice
>         …
>       }
>       \context {
>         \Staff
>         \accepts "ImproVoice"
>       }
>     }

Then the output at the start of this subsection can be entered as

>     \relative c'' {
>       a4 d8 bes8
>       \new ImproVoice {
>         c4^"ad lib" c
>         c4 c^"undress"
>         c c_"while playing :)"
>       }
>       a1
>     }

### 5.1.7 Aligning contexts

New contexts may be aligned above or below existing contexts. This could be useful in setting up a vocal staff ( Vocal ensembles) and in ossia,

Contexts like `PianoStaff` can contain other contexts nested within them. Contexts which are acceptable for nesting are defined by the “accepts” list of a context. Contexts which are not in this list are placed below the outer context in the printed score. For example, the `PianoStaff` context is defined by default to accept `Staff` and `FiguredBass` contexts within it, but not (for example) a `Lyrics` context. So in the following structure the lyrics are placed below the piano staff rather than between the two staves:

>     \new PianoStaff
>     <<
>       \new Staff { e4 d c2 }
>       \addlyrics { Three blind mice }
>       \new Staff {
>         \clef "bass"
>         { c,1 }
>       }
>     >>

The “accepts” list of a context can be modified to include additional nested contexts, so if we wanted the lyrics to appear between the two staves we could use:

>     \new PianoStaff \with { \accepts Lyrics }
>     <<
>       \new Staff { e4 d c2 }
>       \addlyrics { Three blind mice }
>       \new Staff {
>         \clef "bass"
>         { c,1 }
>       }
>     >>

The opposite of `\accepts` is `\denies`; this removes a context from the “accepts” list.

## 5.2 Explaining the Internals Reference

### 5.2.1 Navigating the program reference

Suppose we want to move the fingering indication in the fragment below:

>     c-2
>     \stemUp
>     f

If you visit the documentation on fingering instructions (in Fingering instructions), you will notice:

> See also

> Internals Reference: Fingering.

Follow the link to Fingering. At the top of the page, you will see

> Fingering objects are created by: Fingering_engraver and New_fingering_engraver.

By following related links inside the program reference, we can follow the flow of information within the program:

- Fingering: Fingering objects are created by: Fingering_engraver
- Fingering_engraver: Music types accepted: fingering-event
- fingering-event: Music event type `fingering-event` is in Music expressions named FingeringEvent

This path goes against the flow of information in the program: it starts from the output, and ends at the input event. You could also start at an input event, and read with the flow of information, eventually ending up at the output object(s).

The program reference can also be browsed like a normal document. It contains chapters on Music definitions, on Translation, and the Backend. Every chapter lists all the definitions used and all properties that may be tuned.

### 5.2.2 Layout interfaces

The HTML page that we found in the previous section describes the layout object called Fingering. Such an object is a symbol within the score. It has properties that store numbers (like thicknesses and directions), but also pointers to related objects. A layout object is also called a Grob, which is short for Graphical Object. For more details about Grobs, see grob-interface.

The page for `Fingering` lists the definitions for the `Fingering` object. For example, the page says

> `padding` (dimension, in staff space):

> `0.5`

which means that the number will be kept at a distance of at least 0.5 of the note head.

Each layout object may have several functions as a notational or typographical element. For example, the Fingering object has the following aspects

- Its size is independent of the horizontal spacing, unlike slurs or beams.
- It is a piece of text. Granted, it is usually a very short text.
- That piece of text is typeset with a font, unlike slurs or beams.
- Horizontally, the center of the symbol should be aligned to the center of the note head.
- Vertically, the symbol is placed next to the note and the staff.
- The vertical position is also coordinated with other superscript and subscript symbols.

Each of these aspects is captured in so-called interfaces, which are listed on the Fingering page at the bottom

> This object supports the following interfaces: item-interface, self-alignment-interface, side-position-interface, text-interface, text-script-interface, font-interface, finger-interface, and grob-interface.

Clicking any of the links will take you to the page of the respective object interface. Each interface has a number of properties. Some of them are not user-serviceable (‘Internal properties’), but others can be modified.

We have been talking of the `Fingering` object, but actually it does not amount to much. The initialization file (see Other sources of information) ‘`scm/define-grobs.scm`’ shows the soul of the ‘object’,

>     (Fingering
>       . ((padding . 0.5)
>          (avoid-slur . around)
>          (slur-padding . 0.2)
>          (staff-padding . 0.5)
>          (self-alignment-X . 0)
>          (self-alignment-Y . 0)
>          (script-priority . 100)
>          (stencil . ,ly:text-interface::print)
>          (direction . ,ly:script-interface::calc-direction)
>          (font-encoding . fetaText)
>          (font-size . -5) 		; don't overlap when next to heads.
>          (meta . ((class . Item)
>          (interfaces . (finger-interface
>                         font-interface
>                         text-script-interface
>                         text-interface
>                         side-position-interface
>                         self-alignment-interface
>                         item-interface))))))

As you can see, the `Fingering` object is nothing more than a bunch of variable settings, and the webpage in the Internals Reference is directly generated from this definition.

### 5.2.3 Determining the grob property

Recall that we wanted to change the position of the 2 in

>     c-2
>     \stemUp
>     f

Since the 2 is vertically positioned next to its note, we have to meddle with the interface associated with this positioning. This is done using `side-position-interface`. The page for this interface says

> `side-position-interface`

> Position a victim object (this one) next to other objects (the support). The property `direction` signifies where to put the victim object relative to the support (left or right, up or down?)

Below this description, the variable `padding` is described as

> `padding`

>   (dimension, in staff space)

>   Add this much extra space between objects that are next to each other.

By increasing the value of `padding`, we can move the fingering away from the note head. The following command inserts 3 staff spaces of white between the note and the fingering:

>     \once \override Voice.Fingering #'padding = #3

Inserting this command before the Fingering object is created, i.e., before `c2`, yields the following result:

>     \once \override Voice.Fingering #'padding = #3
>     c-2
>     \stemUp
>     f

In this case, the context for this tweak is `Voice`. This fact can also be deduced from the program reference, for the page for the Fingering_engraver plug-in says

> Fingering_engraver is part of contexts: … Voice

### 5.2.4 Naming conventions

Another thing that is needed, is an overview of the various naming conventions:

- scheme functions: lowercase-with-hyphens (incl. one-word names)
- scheme functions: ly:plus-scheme-style
- music events, music classes and music properties: as-scheme-functions
- Grob interfaces: scheme-style
- backend properties: scheme-style (but X and Y!)
- contexts (and MusicExpressions and grobs): Capitalized or CamelCase
- context properties: lowercaseFollowedByCamelCase
- engravers: Capitalized_followed_by_lowercase_and_with_underscores

Questions to be answered:

- Which of these are conventions and which are rules?
- Which are rules of the underlying language, and which are LP-specific?

## 5.3 Modifying properties

### 5.3.1 Overview of modifying properties

Each context is responsible for creating certain types of graphical objects. The settings used for printing these objects are also stored by context. By changing these settings, the appearance of objects can be altered.

There are two different kinds of properties stored in contexts: context properties and grob properties. Context properties are properties that apply to the context as a whole and control how the context itself is displayed. In contrast, grob properties apply to specific grob types that will be displayed in the context.

The `\set` and `\unset` commands are used to change values for context properties. The `\override` and `\revert` commands are used to change values for grob properties.

#### See also

Internals: Backend, All layout objects, OverrideProperty, RevertProperty, PropertySet.

#### Known issues and warnings

The back-end is not very strict in type-checking object properties. Cyclic references in Scheme values for properties can cause hangs or crashes, or both.

### 5.3.2 The `\set` command

Each context has a set of properties, variables contained in that context. Context properties are changed with the `\set` command, which has the following syntax:

>     \set context.property = #value

value is a Scheme object, which is why it must be preceded by the `#` character.

Contexts properties are usually named in `studlyCaps`. They mostly control the translation from music to notation, e.g. `localKeySignature` (for determining whether to print accidentals), or `measurePosition` (for determining when to print a bar line). Context properties can change value over time while interpreting a piece of music; `measurePosition` is an obvious example of this. Context properties are modified with `\set`.

For example, multimeasure rests will be combined into a single bar if the context property `skipBars` is set to `#t`:

>     R1*2
>     \set Score.skipBars = ##t
>     R1*2

If the context argument is left out, then the property will be set in the current bottom context (typically `ChordNames`, `Voice`, `TabVoice`, or `Lyrics`).

>     \set Score.autoBeaming = ##f
>     <<
>       {
>         e8 e e e
>         \set autoBeaming = ##t
>         e8 e e e
>       } \\ {
>         c8 c c c c8 c c c
>       }
>     >>

The change is applied ‘on-the-fly’, during the music, so that the setting only affects the second group of eighth notes.

Note that the bottom-most context does not always contain the property that you wish to change – for example, attempting to set the `skipBars` property of the default bottom context, in this case `Voice`, will have no effect, because skipBars is a property of the `Score` context.

>     R1*2
>     \set skipBars = ##t
>     R1*2

Contexts are hierarchical, so if an enclosing context was specified, for example `Staff`, then the change would also apply to all `Voice`s in the current staff.

The `\unset` command:

>     \unset context.property

is used to remove the definition of property from context. This command removes the definition only if it is set in context. Properties that have been set in enclosing contexts will not be altered by an unset in an enclosed context:

>     \set Score.autoBeaming = ##t
>     <<
>       {
>         \unset autoBeaming
>         e8 e e e
>         \unset Score.autoBeaming
>         e8 e e e
>       } \\ {
>         c8 c c c c8 c c c
>       }
>     >>

Like `\set`, the context argument does not have to be specified for a bottom context, so the two statements

>     \set Voice.autoBeaming = ##t
>     \set autoBeaming = ##t

are equivalent if the current bottom context is `Voice`.

Preceding a `\set` command by `\once` makes the setting apply to only a single time-step:

>     c4
>     \once \set fontSize = #4.7
>     c4
>     c4

A full description of all available context properties is in the internals reference, see Tunable context properties.

#### See also

Internals Reference:

Tunable context properties.

### 5.3.3 The `\override` command

There is a special type of context property: the grob description. Grob descriptions are named in `StudlyCaps` (starting with capital letters). They contain the ‘default settings’ for a particular kind of grob as an association list. See ‘`scm/define-grobs.scm`’ to see the settings for each grob description. Grob descriptions are modified with `\override`.

`\override` is actually a shorthand;

>     \override context.GrobName #'property = #value

is more or less equivalent to

>     \set context.GrobName  =
>       #(cons (cons 'property value)
>              <previous value of context.GrobName>)

The value of `context`.`GrobName` (the alist) is used to initialize the properties of individual grobs. Grobs have properties, named in Scheme style, with `dashed-words`. The values of grob properties change during the formatting process: formatting basically amounts to computing properties using callback functions.

For example, we can increase the thickness of a note stem by overriding the `thickness` property of the `Stem` object:

>     c4 c
>     \override Voice.Stem #'thickness = #3.0
>     c4 c

If no context is specified in an `\override`, the bottom context is used:

>     { \override Staff.Stem #'thickness = #3.0
>       <<
>         {
>           e4 e
>           \override Stem #'thickness = #0.5
>           e4 e
>         } \\ {
>           c4 c c c
>         }
>       >>
>     }

The effects of `\override` can be undone by `\revert`:

>     c4
>     \override Voice.Stem #'thickness = #3.0
>     c4 c
>     \revert Voice.Stem #'thickness
>     c4

The effects of `\override` and `\revert` apply to all grobs in the affected context from the current time forward:

>     {
>       <<
>         {
>           e4
>           \override Staff.Stem #'thickness = #3.0
>           e4 e e
>         } \\ {
>           c4 c c
>           \revert Staff.Stem #'thickness
>           c4
>         }
>       >>
>     }

`\once` can be used with `\override` to affect only the current time step:

>     {
>       <<
>         {
>           \override Stem #'thickness = #3.0
>           e4 e e e
>         } \\ {
>           c4
>           \once \override Stem #'thickness = #3.0
>           c4 c c
>         }
>       >>
>     }

#### See also

Internals Reference: Backend

### 5.3.4 The `\tweak` command

Changing grob properties with `\override` causes the changes to apply to all of the given grobs in the context at the moment the change applies. Sometimes, however, it is desirable to have changes apply to just one grob, rather than to all grobs in the affected context. This is accomplished with the `\tweak` command, which has the following syntax:

>     \tweak #'grob-property #value

The `\tweak` command applies to the object that immediately follows `value` in the music stream.

For an introduction to the syntax and uses of the tweak command see Tweaking methods.

When several similar items are placed at the same musical moment, the `\override` command cannot be used to modify just one of them – this is where the `\tweak` command must be used. Items which may appear more than once at the same musical moment include the following:

- note heads of notes inside a chord
- articulation signs on a single note
- ties between notes in a chord
- tuplet brackets starting at the same time

In this example, the color of one note head and the type of another note head are modified within a single chord:

>     < c
>       \tweak #'color #red
>       d
>       g
>       \tweak #'duration-log #1
>       a
>     > 4

`\tweak` can be used to modify slurs:

>     c-\tweak #'thickness #5 ( d e f)

For the `\tweak` command to work, it must remain immediately adjacent to the object to which it is to apply after the input file has been converted to a music stream. At times, LilyPond may insert additional items into the music stream during the parsing process. For example, when a note that is not explicitly part of a chord will be placed in a chord by LilyPond, so notes to be modified with `\tweak` must be placed inside a chord construct:

>     \tweak #'color #red c4
>     <\tweak #'color #red c>4

The `\tweak` command cannot be used to modify any item that does not appear explicitly in the input file. In particular it cannot be used to modify stems, beams or accidentals directly, since these are generated later by note heads, rather than by music elements in the input stream. Nor can `\tweak` be used to modify clefs or time signatures, since these become separated from any preceding `\tweak` command in the input stream by the automatic insertion of extra elements required to specify the context.

Several `\tweak` commands may be placed before a notational element – all affect it:

>     c
>     -\tweak #'style #'dashed-line
>     -\tweak #'dash-fraction #0.2
>     -\tweak #'thickness #3
>     -\tweak #'color #red
>      \glissando
>     f'

The music stream which is generated from a section of an input file, including any automatically inserted elements, may be examined, see Displaying music expressions. This may be helpful in determining what may be modified by a `\tweak` command, or in determining how to adjust the input to make a `\tweak` apply.

#### See also

Learning Manual: Tweaking methods.

Extending: Displaying music expressions.

#### Known issues and warnings

The `\tweak` command cannot be used inside a variable.

The `\tweak` commands cannot be used in `\lyricmode`.

The `\tweak` command will apply to only the first of several generated ties in a chord.

### 5.3.5 `\set` vs. `\override`

### 5.3.6 Modifying alists

Some user-configurable properties are internally represented as alists (association lists), which store pairs of keys and values. The structure of an alist is:

>     '((key1 . value1)
>       (key2 . value2)
>       (key3 . value3)
>       …)

If an alist is a grob property or `\paper` variable, its keys can be modified individually without affecting other keys.

For example, to reduce the space between adjacent staves in a staff-group, use the `staff-staff-spacing` property of the `StaffGrouper` grob. The property is an alist with four keys: `basic-distance`, `minimum-distance`, `padding`, and `stretchability`. The standard settings for this property are listed in the “Backend” section of the Internals Reference (see StaffGrouper):

>     '((basic-distance . 9)
>       (minimum-distance . 7)
>       (padding . 1)
>       (stretchability . 5))

One way to bring the staves closer together is by reducing the value of the `basic-distance` key (`9`) to match the value of `minimum-distance` (`7`). To modify a single key individually, use a nested declaration:

>     % default space between staves
>     \new PianoStaff <<
>       \new Staff { \clef treble c''1 }
>       \new Staff { \clef bass   c1   }
>     >>

>     % reduced space between staves
>     \new PianoStaff \with {
>       % this is the nested declaration
>       \override StaffGrouper #'staff-staff-spacing #'basic-distance = #7
>     } <<
>       \new Staff { \clef treble c''1 }
>       \new Staff { \clef bass   c1   }
>     >>

Using a nested declaration will update the specified key (such as `basic-distance` in the above example) without altering any other keys already set for the same property.

Now suppose we want the staves to be as close as possible without overlapping. The simplest way to do this is to set all four alist keys to zero. However, it is not necessary to enter four nested declarations, one for each key. Instead, the property can be completely re-defined with one declaration, as an alist:

>     \new PianoStaff \with {
>       \override StaffGrouper #'staff-staff-spacing =
>         #'((basic-distance . 0)
>            (minimum-distance . 0)
>            (padding . 0)
>            (stretchability . 0))
>     } <<
>       \new Staff { \clef treble c''1 }
>       \new Staff { \clef bass   c1   }
>     >>

Note that any keys not explicitly listed in the alist definition will be reset to their default-when-unset values. In the case of `staff-staff-spacing`, any unset key-values would be reset to zero (except `stretchability`, which takes the value of `basic-distance` when unset). Thus the following two declarations are equivalent:

>     \override StaffGrouper #'staff-staff-spacing =
>       #'((basic-distance . 7))

>     \override StaffGrouper #'staff-staff-spacing =
>       #'((basic-distance . 7)
>          (minimum-distance . 0)
>          (padding . 0)
>          (stretchability . 7))

One (possibly unintended) consequence of this is the removal of any standard settings that are set in an initialization file and loaded each time an input file is compiled. In the above example, the standard settings for `padding` and `minimum-distance` (defined in ‘`scm/define-grobs.scm`’) are reset to their default-when-unset values (zero for both keys). Defining a property or variable as an alist (of any size) will always reset all unset key-values to their default-when-unset values. Unless this is the intended result, it is safer to update key-values individually with a nested declaration.

Note: Nested declarations will not work for context property alists (such as `beamExceptions`, `keySignature`, `timeSignatureSettings`, etc.). These properties can only be modified by completely re-defining them as alists.

## 5.4 Useful concepts and properties

### 5.4.1 Input modes

The way in which the notation contained within an input file is interpreted is determined by the current input mode.

Chord mode

This is activated with the `\chordmode` command, and causes input to be interpreted with the syntax of chord notation, see Chord notation. Chords are rendered as notes on a staff.

Chord mode is also activated with the `\chords` command. This also creates a new `ChordNames` context and causes the following input to be interpreted with the syntax of chord notation and rendered as chord names in the `ChordNames` context, see Printing chord names.

Drum mode

This is activated with the `\drummode` command, and causes input to be interpreted with the syntax of drum notation, see Basic percussion notation.

Drum mode is also activated with the `\drums` command. This also creates a new `DrumStaff` context and causes the following input to be interpreted with the syntax of drum notation and rendered as drum symbols on a drum staff, see Basic percussion notation.

Figure mode

This is activated with the `\figuremode` command, and causes input to be interpreted with the syntax of figured bass, see Entering figured bass.

Figure mode is also activated with the `\figures` command. This also creates a new `FiguredBass` context and causes the following input to be interpreted with the figured bass syntax and rendered as figured bass symbols in the `FiguredBass` context, see Introduction to figured bass.

Fret and tab modes

There are no special input modes for entering fret and tab symbols.

To create tab diagrams, enter notes or chords in note mode and render them in a `TabStaff` context, see Default tablatures.

To create fret diagrams above a staff, you have two choices. You can either use the `FretBoards` context (see Automatic fret diagrams or you can enter them as a markup above the notes using the `\fret-diagram` command (see Fret diagram markups).

Lyrics mode

This is activated with the `\lyricmode` command, and causes input to be interpreted as lyric syllables with optional durations and associated lyric modifiers, see Vocal music.

Lyric mode is also activated with the `\addlyrics` command. This also creates a new `Lyrics` context and an implicit `\lyricsto` command which associates the following lyrics with the preceding music.

Markup mode

This is activated with the `\markup` command, and causes input to be interpreted with the syntax of markup, see Text markup commands.

Note mode

This is the default mode or it may be activated with the `\notemode` command. Input is interpreted as pitches, durations, markup, etc and typeset as musical notation on a staff.

It is not normally necessary to specify note mode explicitly, but it may be useful to do so in certain situations, for example if you are in lyric mode, chord mode or any other mode and want to insert something that only can be done with note mode syntax.

For example, to indicate dynamic markings for the verses of a choral pieces it is necessary to enter note mode to interpret the markings:

>     { c4 c4 c4 c4 }
>     \addlyrics {
>       \notemode{\set stanza = \markup{ \dynamic f 1. } }
>       To be sung loudly
>     }
>     \addlyrics {
>       \notemode{\set stanza = \markup{ \dynamic p 2. } }
>       To be sung quietly
>     }

### 5.4.2 Direction and placement

In typesetting music the direction and placement of many items is a matter of choice. For example, the stems of notes can be directed up or down; lyrics, dynamics, and other expressive marks may be placed above or below the staff; text may be aligned left, right or center; etc. Most of these choices may be left to be determined automatically by LilyPond, but in some cases it may be desirable to force a particular direction or placement.

Articulation direction indicators

By default some directions are always up or always down (e.g. dynamics or fermata), while other things can alternate between up or down based on the stem direction (like slurs or accents).

The default action may be overridden by prefixing the articulation by a direction indicator. Three direction indicators are available: `^` (meaning “up”), `_` (meaning “down”) and `-` (meaning “use default direction”). The direction indicator can usually be omitted, in which case `-` is assumed, but a direction indicator is always required before

- `\tweak` commands
- `\markup` commands
- `\tag` commands
- string markups, e.g. -"string"
- fingering instructions, e.g. `-1`
- articulation shortcuts, e.g. `-.`, `->`, `--`

Direction indicators affect only the next note:

>     c2( c)
>     c2_( c)
>     c2( c)
>     c2^( c)

The direction property

The position or direction of many layout objects is controlled by the `direction` property.

The value of the `direction` property may be set to `1`, meaning “up” or “above”, or to `-1`, meaning “down” or “below”. The symbols `UP` and `DOWN` may be used instead of `1` and `-1` respectively. The default direction may be specified by setting `direction` to `0` or `CENTER`. Alternatively, in many cases predefined commands exist to specify the direction. These are all of the form

`\xxxUp`, `xxxDown`, `xxxNeutral`

where `xxxNeutral` means “use the default direction”. See Within-staff objects.

In a few cases, arpeggio being the only common example, the value of the `direction` property specifies whether the object is to be placed to the right or left of the parent object. In this case `-1` or `LEFT` means “to the left” and `1` or `RIGHT` means “to the right”. `0` or `CENTER` means “use the default” direction, as before.

These indications affect all notes until they are cancelled.

>     c2( c)
>     \slurDown
>     c2( c)
>     c2( c)
>     \slurNeutral
>     c2( c)

### 5.4.3 Context layout order

Contexts are normally positioned in a system from top to bottom in the order in which they are encountered in the input file. When contexts are nested, the outer context will include inner nested contexts as specified in the input file, provided the inner contexts are included in the outer context’s “accepts” list. Nested contexts which are not included in the outer context’s “accepts” list will be repositioned below the outer context rather than nested within it.

Note that a context will be silently created implicitly if a command is encountered when there is no suitable context available to contain it. This can give rise to unexpected new staves or scores.

The default order in which contexts are laid out and the “accepts” list can be changed, see Aligning contexts.

#### See also

Usage Manual: An extra staff appears.

### 5.4.4 Distances and measurements

Distances in LilyPond are of two types: absolute and scaled.

Absolute distances are used for specifying margins, indents, and other page layout details, and are by default specified in millimeters. Distances may be specified in other units by following the quantity by `\mm`, `\cm`, `\in` (inches), or `\pt` (points, 1/72.27 of an inch). Page layout distances can also be specified in scalable units (see the following paragraph) by appending `\staff-space` to the quantity. Page layout is described in detail in Page layout.

Scaled distances are always specified in units of the staff-space or, rarely, the half staff-space. The staff-space is the distance between two adjacent staff lines. The default value can be changed globally by setting the global staff size, or it can be overridden locally by changing the `staff-space` property of `StaffSymbol`. Scaled distances automatically scale with any change to the either the global staff size or the `staff-space` property of `StaffSymbol`, but fonts scale automatically only with changes to the global staff size. The global staff size thus enables the overall size of a rendered score to be easily varied. For the methods of setting the global staff size see Setting the staff size.

If just a section of a score needs to be rendered to a different scale, for example an ossia section or a footnote, the global staff size cannot simply be changed as this would affect the entire score. In such cases the change in size is made by overriding both the `staff-space` property of `StaffSymbol` and the size of the fonts. A Scheme function, `magstep`, is available to convert from a font size change to the equivalent change in `staff-space`. For an explanation and an example of its use, see Length and thickness of objects.

#### See also

Learning Manual: Length and thickness of objects.

Notation Reference: Page layout, Setting the staff size.

### 5.4.5 Staff symbol properties

The vertical position of staff lines and the number of staff lines can be defined at the same time. As the following example shows, note positions are not influenced by the staff line positions.

Note: The `'line-positions` property overrides the `'line-count` property. The number of staff lines is implicitly defined by the number of elements in the list of values for `'line-positions`.

>     \new Staff \with {
>       \override StaffSymbol #'line-positions = #'(7 3 0 -4 -6 -7)
>     }
>     { a4 e' f b | d1 }

The width of a staff can be modified. The units are staff spaces. The spacing of objects inside the staff is not affected by this setting.

>     \new Staff \with {
>       \override StaffSymbol #'width = #23
>     }
>     { a4 e' f b | d1 }

### 5.4.6 Spanners

Many objects of musical notation extend over several notes or even several bars. Examples are slurs, beams, tuplet brackets, volta repeat brackets, crescendi, trills, and glissandi. Such objects are collectively called “spanners”, and have special properties to control their appearance and behaviour. Some of these properties are common to all spanners; others are restricted to a sub-set of the spanners.

All spanners support the `spanner-interface`. A few, essentially those that draw a straight line between the two objects, support in addition the `line-spanner-interface`.

#### Using the `spanner-interface`

This interface provides two properties that apply to several spanners.

The `minimum-length` property

The minimum length of the spanner is specified by the `minimum-length` property. Increasing this usually has the necessary effect of increasing the spacing of the notes between the two end points. However, this override has no effect on many spanners, as their length is determined by other considerations. A few examples where it is effective are shown below.

>     a~a
>     a
>     % increase the length of the tie
>     -\tweak #'minimum-length #5
>     ~a

>     a1
>     \compressFullBarRests
>     R1*23
>     % increase the length of the rest bar
>     \once \override MultiMeasureRest #'minimum-length = #20
>     R1*23
>     a1

>     a \< a a a \!
>     % increase the length of the hairpin
>     \override Hairpin #'minimum-length = #20
>     a \< a a a \!

This override can also be used to increase the length of slurs and phrasing slurs:

>     a( a)
>     a
>     -\tweak #'minimum-length #5
>     ( a)

>     a\( a\)
>     a
>     -\tweak #'minimum-length #5
>     \( a\)

For some layout objects, the `minimum-length` property becomes effective only if the `set-spacing-rods` procedure is called explicitly. To do this, the `springs-and-rods` property should be set to `ly:spanner::set-spacing-rods`. For example, the minimum length of a glissando has no effect unless the `springs-and-rods` property is set:

>     % default
>     e \glissando c'

>     % not effective alone
>     \once \override Glissando #'minimum-length = #20
>     e, \glissando c'

>     % effective only when both overrides are present
>     \once \override Glissando #'minimum-length = #20
>     \once \override Glissando #'springs-and-rods = #ly:spanner::set-spacing-rods
>     e, \glissando c'

The same is true of the `Beam` object:

>     % not effective alone
>     \once \override Beam #'minimum-length = #20
>     e8 e e e

>     % effective only when both overrides are present
>     \once \override Beam #'minimum-length = #20
>     \once \override Beam #'springs-and-rods = #ly:spanner::set-spacing-rods
>     e8 e e e

The `to-barline` property

The second useful property of the `spanner-interface` is `to-barline`. By default this is true, causing hairpins and other spanners which are terminated on the first note of a measure to end instead on the immediately preceding bar line. If set to false, the spanner will extend beyond the bar line and end on the note itself:

>     a \< a a a a \! a a a \break
>     \override Hairpin #'to-barline = ##f
>     a \< a a a a \! a a a

This property is not effective for all spanners. For example, setting it to `#t` has no effect on slurs or phrasing slurs or on other spanners for which terminating on the bar line would not be meaningful.

#### Using the `line-spanner-interface`

Objects which support the `line-spanner-interface` include

- `DynamicTextSpanner`
- `Glissando`
- `TextSpanner`
- `TrillSpanner`
- `VoiceFollower`

The routine responsible for drawing the stencils for these spanners is `ly:line-interface::print`. This routine determines the exact location of the two end points and draws a line between them, in the style requested. The locations of the two end points of the spanner are computed on-the-fly, but it is possible to override their Y-coordinates. The properties which need to be specified are nested two levels down within the property hierarchy, but the syntax of the `\override` command is quite simple:

>     e2 \glissando b
>     \once \override Glissando #'(bound-details left Y) = #3
>     \once \override Glissando #'(bound-details right Y) = #-2
>     e2 \glissando b

The units for the `Y` property are `staff-space`s, with the center line of the staff being the zero point. For the glissando, this is the value for `Y` at the X-coordinate corresponding to the center point of each note head, if the line is imagined to be extended to there.

If `Y` is not set, the value is computed from the vertical position of the corresponding attachment point of the spanner.

In case of a line break, the values for the end points are specified by the `left-broken` and `right-broken` sub-lists of `bound-details`. For example:

>     \override Glissando #'breakable = ##t
>     \override Glissando #'(bound-details right-broken Y) = #-3
>     c1 \glissando \break
>     f1

A number of further properties of the `left` and `right` sub-lists of the `bound-details` property may be modified in the same way as `Y`:

`Y`

  This sets the Y-coordinate of the end point, in `staff-space`s offset from the staff center line. By default, it is the center of the bound object, so a glissando points to the vertical center of the note head.

  For horizontal spanners, such as text spanners and trill spanners, it is hardcoded to 0.

`attach-dir`

  This determines where the line starts and ends in the X-direction, relative to the bound object. So, a value of `-1` (or `LEFT`) makes the line start/end at the left side of the note head it is attached to.

`X`

  This is the absolute X-coordinate of the end point. It is usually computed on the fly, and overriding it has little useful effect.

`stencil`

  Line spanners may have symbols at the beginning or end, which is contained in this sub-property. This is for internal use; it is recommended that `text` be used instead.

`text`

  This is a markup that is evaluated to yield the stencil. It is used to put cresc., tr and other text on horizontal spanners.

  >     \override TextSpanner #'(bound-details left text)
  >        = \markup { \small \bold Slower }
  >     c2\startTextSpan b c a\stopTextSpan

`stencil-align-dir-y`
`stencil-offset`

  Without setting one of these, the stencil is simply put at the end-point, centered on the line, as defined by the `X` and `Y` sub-properties. Setting either `stencil-align-dir-y` or `stencil-offset` will move the symbol at the edge vertically relative to the end point of the line:

  >     \override TextSpanner
  >       #'(bound-details left stencil-align-dir-y) = #-2
  >     \override TextSpanner
  >       #'(bound-details right stencil-align-dir-y) = #UP

  >     \override TextSpanner
  >       #'(bound-details left text) = #"ggg"
  >     \override TextSpanner
  >       #'(bound-details right text) = #"hhh"
  >     c4^\startTextSpan c c c \stopTextSpan

  Note that negative values move the text up, contrary to the effect that might be expected, as a value of `-1` or `DOWN` means align the bottom edge of the text with the spanner line. A value of `1` or `UP` aligns the top edge of the text with the spanner line.

`arrow`

  Setting this sub-property to `#t` produces an arrowhead at the end of the line.

`padding`

  This sub-property controls the space between the specified end point of the line and the actual end. Without padding, a glissando would start and end in the center of each note head.

The music function `\endSpanners` terminates the spanner which starts on the immediately following note prematurely. It is terminated after exactly one note, or at the following bar line if `to-barline` is true and a bar line occurs before the next note.

>     \endSpanners
>     c2 \startTextSpan c2 c2
>     \endSpanners
>     c2 \< c2 c2

When using `\endSpanners` it is not necessary to close \startTextSpan with \stopTextSpan, nor is it necessary to close hairpins with `\!`.

#### See also

Internals Reference: TextSpanner, Glissando, VoiceFollower, TrillSpanner, line-spanner-interface.

### 5.4.7 Visibility of objects

There are four main ways in which the visibility of layout objects can be controlled: their stencil can be removed, they can be made transparent, they can be colored white, or their `break-visibility` property can be overridden. The first three apply to all layout objects; the last to just a few – the breakable objects. The Learning Manual introduces these four techniques, see Visibility and color of objects.

There are also a few other techniques which are specific to certain layout objects. These are covered under Special considerations.

#### Removing the stencil

Every layout object has a stencil property. By default this is set to the specific function which draws that object. If this property is overridden to `#f` no function will be called and the object will not be drawn. The default action can be recovered with `\revert`.

>     a1 a
>     \override Score.BarLine #'stencil = ##f
>     a a
>     \revert Score.BarLine #'stencil
>     a a a

#### Making objects transparent

Every layout object has a transparent property which by default is set to `#f`. If set to `#t` the object still occupies space but is made invisible.

>     a4 a
>     \once \override NoteHead #'transparent = ##t
>     a a

#### Painting objects white

Every layout object has a color property which by default is set to `black`. If this is overridden to `white` the object will be indistinguishable from the white background. However, if the object crosses other objects the color of the crossing points will be determined by the order in which they are drawn, and this may leave a ghostly image of the white object, as shown here:

>     \override Staff.Clef #'color = #white
>     a1

This may be avoided by changing the order of printing the objects. All layout objects have a `layer` property which should be set to an integer. Objects with the lowest value of `layer` are drawn first, then objects with progressively higher values are drawn, so objects with higher values overwrite objects with lower values. By default most objects are assigned a `layer` value of `1`, although a few objects, including `StaffSymbol` and `BarLine`, are assigned a value of `0`. The order of printing objects with the same value of `layer` is indeterminate.

In the example above the white clef, with a default `layer` value of `1`, is drawn after the staff lines (default `layer` value `0`), so overwriting them. To change this, the `Clef` object must be given in a lower value of `layer`, say `-1`, so that it is drawn earlier:

>     \override Staff.Clef #'color = #white
>     \override Staff.Clef #'layer = #-1
>     a1

#### Using break-visibility

Most layout objects are printed only once, but some like bar lines, clefs, time signatures and key signatures, may need to be printed twice when a line break occurs – once at the end of the line and again at the start of the next line. Such objects are called breakable, and have a property, the `break-visibility` property to control their visibility at the three positions in which they may appear – at the start of a line, within a line if they are changed, and at the end of a line if a change takes place there.

For example, the time signature by default will be printed at the start of the first line, but nowhere else unless it changes, when it will be printed at the point at which the change occurs. If this change occurs at the end of a line the new time signature will be printed at the start of the next line and a cautionary time signature will be printed at the end of the previous line as well.

This behaviour is controlled by the `break-visibility` property, which is explained in Visibility and color of objects. This property takes a vector of three booleans which, in order, determine whether the object is printed at the end of, within the body of, or at the beginning of a line. Or to be more precise, before a line break, where there is no line break, or after a line break.

Alternatively, these eight combinations may be specified by pre-defined functions, defined in ‘`scm/output-lib.scm`’, where the last three columns indicate whether the layout objects will be visible in the positions shown at the head of the columns:

Function | Vector | Before | At no | After
--- | --- | --- | --- | ---
form | form | break | break | break
`all-visible` | `'#(#t #t #t)` | yes | yes | yes
`begin-of-line-visible` | `'#(#f #f #t)` | no | no | yes
`center-visible` | `'#(#f #t #f)` | no | yes | no
`end-of-line-visible` | `'#(#t #f #f)` | yes | no | no
`begin-of-line-invisible` | `'#(#t #t #f)` | yes | yes | no
`center-invisible` | `'#(#t #f #t)` | yes | no | yes
`end-of-line-invisible` | `'#(#f #t #t)` | no | yes | yes
`all-invisible` | `'#(#f #f #f)` | no | no | no

The default settings of `break-visibility` depend on the layout object. The following table shows all the layout objects of interest which are affected by `break-visibility` and the default setting of this property:

Layout object | Usual context | Default setting
--- | --- | ---
`BarLine` | `Score` | calculated
`BarNumber` | `Score` | `begin-of-line-visible`
`BreathingSign` | `Voice` | `begin-of-line-invisible`
`Clef` | `Staff` | `begin-of-line-visible`
`Custos` | `Staff` | `end-of-line-visible`
`DoublePercentRepeat` | `Voice` | `begin-of-line-invisible`
`KeySignature` | `Staff` | `begin-of-line-visible`
`OctavateEight` | `Staff` | `begin-of-line-visible`
`RehearsalMark` | `Score` | `end-of-line-invisible`
`TimeSignature` | `Staff` | `all-visible`

The example below shows the use of the vector form to control the visibility of bar lines:

>     f4 g a b
>     f4 g a b
>     % Remove bar line at the end of the current line
>     \once \override Score.BarLine #'break-visibility = #'#(#f #t #t)
>     \break
>     f4 g a b
>     f4 g a b

Although all three components of the vector used to override `break-visibility` must be present, not all of them are effective with every layout object, and some combinations may even give errors. The following limitations apply:

- Bar lines cannot be printed at start of line.
- A bar number cannot be printed at the start of the first line unless it is set to be different from 1.
- Clef – see below
- Double percent repeats are either all printed or all suppressed. Use begin-of line-invisible to print and all-invisible to suppress.
- Key signature – see below
- OctavateEight – see below

#### Special considerations

Visibility following explicit changes

The `break-visibility` property controls the visibility of key signatures and changes of clef only at the start of lines, i.e. after a break. It has no effect on the visibility of the key signature or clef following an explicit key change or an explicit clef change within or at the end of a line. In the following example the key signature following the explicit change to B-flat major is still visible, even though `all-invisible` is set.

>     \key g \major
>     f4 g a b
>     % Try to remove all key signatures
>     \override Staff.KeySignature #'break-visibility = #all-invisible
>     \key bes \major
>     f4 g a b
>     \break
>     f4 g a b
>     f4 g a b

The visibility of such explicit key signature and clef changes is controlled by the `explicitKeySignatureVisibility` and `explicitClefVisibility` properties. These are the equivalent of the `break-visibility` property and both take a vector of three booleans or the predefined functions listed above, exactly like `break-visibility`. Both are properties of the Staff context, not the layout objects themselves, and so they are set using the `\set` command. Both are set by default to `all-visible`. These properties control only the visibility of key signatures and clefs resulting from explicit changes and do not affect key signatures and clefs at the beginning of lines; `break-visibility` must still be overridden in the appropriate object to remove these.

>     \key g \major
>     f4 g a b
>     \set Staff.explicitKeySignatureVisibility = #all-invisible
>     \override Staff.KeySignature #'break-visibility = #all-invisible
>     \key bes \major
>     f4 g a b \break
>     f4 g a b
>     f4 g a b

Visibility of cautionary accidentals

To remove the cautionary accidentals printed at an explicit key change, set the Staff context property `printKeyCancellation` to `#f`:

>     \key g \major
>     f4 g a b
>     \set Staff.explicitKeySignatureVisibility = #all-invisible
>     \set Staff.printKeyCancellation = ##f
>     \override Staff.KeySignature #'break-visibility = #all-invisible
>     \key bes \major
>     f4 g a b \break
>     f4 g a b
>     f4 g a b

With these overrides only the accidentals before the notes remain to indicate the change of key.

Automatic bars

As a special case, the printing of bar lines can also be turned off by setting the `automaticBars` property in the Score context. If set to `#f`, bar lines will not be printed automatically; they must be explicitly created with a `\bar` command. Unlike the `\cadenzaOn` predefined command, measures are still counted. Bar generation will resume according to that count if this property is later set to `#t`. When set to `#f`, line breaks can occur only at explicit `\bar` commands.

Octavated clefs

The small octavation symbol on octavated clefs is produced by the `OctavateEight` layout object. Its visibility is automatically inherited from the `Clef` object, so it is not necessary to apply any required `break-visibility` overrides to the `OctavateEight` layout objects to suppress octavation symbols for invisible clefs.

For explicit clef changes, the `explicitClefVisibility` property controls both the clef symbol and any octavation symbol associated with it.

#### See also

Learning Manual: Visibility and color of objects

### 5.4.8 Line styles

Some performance indications, e.g., rallentando and accelerando and trills are written as text and are extended over many measures with lines, sometimes dotted or wavy.

These all use the same routines as the glissando for drawing the texts and the lines, and tuning their behavior is therefore also done in the same way. It is done with a spanner, and the routine responsible for drawing the spanners is `ly:line-interface::print`. This routine determines the exact location of the two span points and draws a line between them, in the style requested.

Here is an example showing the different line styles available, and how to tune them.

>     d2 \glissando d'2
>     \once \override Glissando #'style = #'dashed-line
>     d,2 \glissando d'2
>     \override Glissando #'style = #'dotted-line
>     d,2 \glissando d'2
>     \override Glissando #'style = #'zigzag
>     d,2 \glissando d'2
>     \override Glissando #'style = #'trill
>     d,2 \glissando d'2

The locations of the end-points of the spanner are computed on-the-fly for every graphic object, but it is possible to override these:

>     e2 \glissando f
>     \once \override Glissando #'(bound-details right Y) = #-2
>     e2 \glissando f

The value for `Y` is set to `-2` for the right end point. The left side may be similarly adjusted by specifying `left` instead of `right`.

If `Y` is not set, the value is computed from the vertical position of the left and right attachment points of the spanner.

Other adjustments of spanners are possible, for details, see Spanners.

### 5.4.9 Rotating objects

Both layout objects and elements of markup text can be rotated by any angle about any point, but the method of doing so differs.

#### Rotating layout objects

All layout objects which support the `grob-interface` can be rotated by setting their `rotation` property. This takes a list of three items: the angle of rotation counter-clockwise, and the x and y coordinates of the point relative to the object’s reference point about which the rotation is to be performed. The angle of rotation is specified in degrees and the coordinates in staff-spaces.

The angle of rotation and the coordinates of the rotation point must be determined by trial and error.

There are only a few situations where the rotation of layout objects is useful; the following example shows one situation where they may be:

>     g4\< e' d' f\!
>     \override Hairpin #'rotation = #'(20 -1 0)
>     g,,4\< e' d' f\!

#### Rotating markup

All markup text can be rotated to lie at any angle by prefixing it with the `\rotate` command. The command takes two arguments: the angle of rotation in degrees counter-clockwise and the text to be rotated. The extents of the text are not rotated: they take their values from the extremes of the x and y coordinates of the rotated text. In the following example the `outside-staff-priority` property for text is set to `#f` to disable the automatic collision avoidance, which would push some of the text too high.

>     \override TextScript #'outside-staff-priority = ##f
>     g4^\markup { \rotate #30 "a G" }
>     b^\markup { \rotate #30 "a B" }
>     des^\markup { \rotate #30 "a D-Flat" }
>     fis^\markup { \rotate #30 "an F-Sharp" }

## 5.5 Advanced tweaks

This section discusses various approaches to fine tuning the appearance of the printed score.

#### See also

Learning Manual: Tweaking output, Other sources of information.

Notation Reference: Explaining the Internals Reference, Modifying properties.

Installed Files: ‘`scm/define-grobs.scm`’.

Snippets: Tweaks and overrides.

Extending: Interfaces for programmers.

Internals Reference: All layout objects.

### 5.5.1 Aligning objects

Graphical objects which support the `self-alignment-interface` and/or the `side-position-interface` can be aligned to a previously placed object in a variety of ways. For a list of these objects, see self-alignment-interface and side-position-interface.

All graphical objects have a reference point, a horizontal extent and a vertical extent. The horizontal extent is a pair of numbers giving the displacements from the reference point of the left and right edges, displacements to the left being negative. The vertical extent is a pair of numbers giving the displacement from the reference point to the bottom and top edges, displacements down being negative.

An object’s position on a staff is given by the values of the `X-offset` and `Y-offset` properties. The value of `X-offset` gives the displacement from the X coordinate of the reference point of the parent object, and the value of `Y-offset` gives the displacement from the center line of the staff. The values of `X-offset` and `Y-offset` may be set directly or may be set to be calculated by procedures in order to achieve alignment with the parent object.

Note: Many objects have special positioning considerations which cause any setting of `X-offset` or `Y-offset` to be ignored or modified, even though the object supports the `self-alignment-interface`. Overriding the `X-offset` or `Y-offset` properties to a fixed value causes the respective `self-alignment` property to be disregarded.

For example, an accidental can be repositioned vertically by setting `Y-offset` but any changes to `X-offset` have no effect.

Rehearsal marks may be aligned with breakable objects such as bar lines, clef symbols, time signature symbols and key signatures. There are special properties to be found in the `break-aligned-interface` for positioning rehearsal marks on such objects.

#### See also

Using the `break-alignable-interface`, Callback functions.

#### Setting `X-offset` and `Y-offset` directly

Numerical values may be given to the `X-offset` and `Y-offset` properties of many objects. The following example shows three notes with the default fingering position and the positions with `X-offset` and `Y-offset` modified.

>     a-3
>     a
>     -\tweak #'X-offset #0
>     -\tweak #'Y-offset #0
>     -3
>     a
>     -\tweak #'X-offset #-1
>     -\tweak #'Y-offset #1
>     -3

#### Using the `side-position-interface`

An object which supports the `side-position-interface` can be placed next to its parent object so that the specified edges of the two objects touch. The object may be placed above, below, to the right or to the left of the parent. The parent cannot be specified; it is determined by the order of elements in the input stream. Most objects have the associated note head as their parent.

The values of the `side-axis` and `direction` properties determine where the object is to be placed, as follows:

`side-axis` | `direction` |
--- | --- | ---
property | property | Placement
`0` | `-1` | left
`0` | `1` | right
`1` | `-1` | below
`1` | `1` | above

When `side-axis` is `0`, `X-offset` should be set to the procedure `ly:side-position-interface::x-aligned-side`. This procedure will return the correct value of `X-offset` to place the object to the left or right side of the parent according to value of `direction`.

When `side-axis` is `1`, `Y-offset` should be set to the procedure `ly:side-position-interface::y-aligned-side`. This procedure will return the correct value of `Y-offset` to place the object to the top or bottom of the parent according to value of `direction`.

#### Using the `self-alignment-interface`

Self-aligning objects horizontally

The horizontal alignment of an object which supports the `self-alignment-interface` is controlled by the value of the `self-alignment-X` property, provided the object’s `X-offset` property is set to `ly:self-alignment-interface::x-aligned-on-self`. `self-alignment-X` may be given any real value, in units of half the total X extent of the object. Negative values move the object to the right, positive to the left. A value of `0` centers the object on the reference point of its parent, a value of `-1` aligns the left edge of the object on the reference point of its parent, and a value of `1` aligns the right edge of the object on the reference point of its parent. The symbols `LEFT`, `CENTER` and `RIGHT` may be used instead of the values `-1, 0, 1` respectively.

Normally the `\override` command would be used to modify the value of `self-alignment-X`, but the `\tweak` command can be used to separately align several annotations on a single note:

>     a'
>     -\tweak #'self-alignment-X #-1
>     ^"left-aligned"
>     -\tweak #'self-alignment-X #0
>     ^"center-aligned"
>     -\tweak #'self-alignment-X #RIGHT
>     ^"right-aligned"
>     -\tweak #'self-alignment-X #-2.5
>     ^"aligned further to the right"

Self-aligning objects vertically

Objects may be aligned vertically in an analogous way to aligning them horizontally if the `Y-offset` property is set to `ly:self-alignment-interface::y-aligned-on-self`. However, other mechanisms are often involved in vertical alignment: the value of `Y-offset` is just one variable taken into account. This may make adjusting the value of some objects tricky. The units are just half the vertical extent of the object, which is usually quite small, so quite large numbers may be required. A value of `-1` aligns the lower edge of the object with the reference point of the parent object, a value of `0` aligns the center of the object with the reference point of the parent, and a value of `1` aligns the top edge of the object with the reference point of the parent. The symbols `DOWN`, `CENTER`, `UP` may be substituted for `-1, 0, 1` respectively.

Self-aligning objects in both directions

By setting both `X-offset` and `Y-offset`, an object may be aligned in both directions simultaneously.

The following example shows how to adjust a fingering mark so that it nestles close to the note head.

>     a
>     -\tweak #'self-alignment-X #0.5  % move horizontally left
>     -\tweak #'Y-offset #ly:self-alignment-interface::y-aligned-on-self
>     -\tweak #'self-alignment-Y #-1  % move vertically up
>     -3  % third finger

#### Using the `break-alignable-interface`

Rehearsal marks and bar numbers 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`.

By default, rehearsal marks and bar numbers will be horizontally centered above the object:

>     % The rehearsal mark will be centered above the Clef
>     \override Score.RehearsalMark #'break-align-symbols = #'(clef)
>     \key a \major
>     \clef treble
>     \mark "↓"
>     e1
>     % The rehearsal mark will be centered above the Time Signature
>     \override Score.RehearsalMark #'break-align-symbols = #'(time-signature)
>     \key a \major
>     \clef treble
>     \time 3/4
>     \mark "↓"
>     e2.
>     % The rehearsal mark will be centered above the Breath Mark
>     \override Score.RehearsalMark #'break-align-symbols = #'(breathing-sign)
>     \key a \major
>     \clef treble
>     \time 4/4
>     e1
>     \breathe
>     \mark "↓"

A list of possible target alignment objects may be specified. If some of the objects are invisible at that point due to the setting of `break-visibility` or the explicit visibility settings for keys and clefs, the rehearsal mark or bar number is aligned to the first object in the list which is visible. If no objects in the list are visible the object is aligned to the bar line. If the bar line is invisible the object is aligned to the place where the bar line would be.

>     % The rehearsal mark will be centered above the Key Signature
>     \override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
>     \key a \major
>     \clef treble
>     \mark "↓"
>     e1
>     % The rehearsal mark will be centered above the Clef
>     \set Staff.explicitKeySignatureVisibility = #all-invisible
>     \override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
>     \key a \major
>     \clef bass
>     \mark "↓"
>     gis,,1
>     % The rehearsal mark will be centered above the Bar Line
>     \set Staff.explicitKeySignatureVisibility = #all-invisible
>     \set Staff.explicitClefVisibility = #all-invisible
>     \override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
>     \key a \major
>     \clef treble
>     \mark "↓"
>     e''1

The alignment of the rehearsal mark relative to the notation object can be changed, as shown in the following example. In a score with multiple staves, this setting should be done for all the staves.

>     % The RehearsalMark will be centered above the Key Signature
>     \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
>     \key a \major
>     \clef treble
>     \time 4/4
>     \mark "↓"
>     e1
>     % The RehearsalMark will be aligned with the left edge of the Key Signature
>     \once \override Score.KeySignature #'break-align-anchor-alignment = #LEFT
>     \mark "↓"
>     \key a \major
>     e1
>     % The RehearsalMark will be aligned with the right edge of the Key Signature
>     \once \override Score.KeySignature #'break-align-anchor-alignment = #RIGHT
>     \key a \major
>     \mark "↓"
>     e1

The rehearsal mark can also be offset to the right or left of the left edge by an arbitrary amount. The units are staff-spaces:

>     % The RehearsalMark will be aligned with the left edge of the Key Signature
>     % and then shifted right by 3.5 staff-spaces
>     \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
>     \once \override Score.KeySignature #'break-align-anchor = #3.5
>     \key a \major
>     \mark "↓"
>     e1
>     % The RehearsalMark will be aligned with the left edge of the Key Signature
>     % and then shifted left by 2 staff-spaces
>     \once \override Score.KeySignature #'break-align-anchor = #-2
>     \key a \major
>     \mark "↓"
>     e1

### 5.5.2 Vertical grouping of grobs

The VerticalAlignment and VerticalAxisGroup grobs work together. VerticalAxisGroup groups together different grobs like Staff, Lyrics, etc. VerticalAlignment then vertically aligns the different grobs grouped together by VerticalAxisGroup. There is usually only one VerticalAlignment per score but every Staff, Lyrics, etc. has its own VerticalAxisGroup.

### 5.5.3 Modifying stencils

All layout objects have a `stencil` property which is part of the `grob-interface`. By default, this property is usually set to a function specific to the object that is tailor-made to render the symbol which represents it in the output. For example, the standard setting for the `stencil` property of the `MultiMeasureRest` object is `ly:multi-measure-rest::print`.

The standard symbol for any object can be replaced by modifying the `stencil` property to reference a different, specially-written, procedure. This requires a high level of knowledge of the internal workings of LilyPond, but there is an easier way which can often produce adequate results.

This is to set the `stencil` property to the procedure which prints text – `ly:text-interface::print` – and to add a `text` property to the object which is set to contain the markup text which produces the required symbol. Due to the flexibility of markup, much can be achieved – see in particular Graphic notation inside markup.

The following example demonstrates this by changing the note head symbol to a cross within a circle.

>     XinO = {
>       \once \override NoteHead  #'stencil = #ly:text-interface::print
>       \once \override NoteHead #'text = \markup {
>         \combine
>           \halign #-0.7 \draw-circle #0.85 #0.2 ##f
>           \musicglyph #"noteheads.s2cross"
>       }
>     }
>     \relative c'' {
>       a a \XinO a a
>     }

Any of the glyphs in the feta Font can be supplied to the `\musicglyph` markup command – see The Feta font.

#### See also

Notation Reference: Graphic notation inside markup, Formatting text, Text markup commands, The Feta font.

### 5.5.4 Modifying shapes

#### Modifying ties and slurs

Ties, slurs and phrasing slurs are drawn as third-order Bézier curves. If the shape of the tie or slur which is calculated automatically is not optimum, the shape may be modified manually by explicitly specifying the four control points required to define a third-order Bézier curve.

Third-order or cubic Bézier curves are defined by four control points. The first and fourth control points are precisely the starting and ending points of the curve. The intermediate two control points define the shape. Animations showing how the curve is drawn can be found on the web, but the following description may be helpful. The curve starts from the first control point heading directly towards the second, gradually bending over to head towards the third and continuing to bend over to head towards the fourth, arriving there travelling directly from the third control point. The curve is entirely contained in the quadrilateral defined by the four control points.

Here is an example of a case where the tie is not optimum, and where `\tieDown` would not help.

>     <<
>       { e1 ~ e }
>     \\
>       { r4 <g c,> <g c,> <g c,> }
>     >>

One way of improving this tie is to manually modify its control points, as follows.

The coordinates of the Bézier control points are specified in units of staff-spaces. The X coordinate is relative to the reference point of the note to which the tie or slur is attached, and the Y coordinate is relative to the staff center line. The coordinates are entered as a list of four pairs of decimal numbers (reals). One approach is to estimate the coordinates of the two end points, and then guess the two intermediate points. The optimum values are then found by trial and error.

It is useful to remember that a symmetric curve requires symmetric control points, and that Bézier curves have the useful property that transformations of the curve such as translation, rotation and scaling can be achieved by applying the same transformation to the curve’s control points.

For the example above the following override gives a satisfactory tie. Note the placement – it has to be immediately before the note to which the start of the tie (or slur) is attached.

>     <<
>       {
>         \once \override Tie
>           #'control-points = #'((1 . -1) (3 . 0.6) (12.5 . 0.6) (14.5 . -1))
>          e1 ~ e1
>       }
>     \\
>       { r4 <g c,> <g c,> <g c,>4  }
>     >>

#### Known issues and warnings

It is not possible to modify shapes of ties or slurs by changing the `control-points` property if there are more than one at the same musical moment, not even by using the `\tweak` command. However, the `tie-configuration` property of `TieColumn` can be overridden to set start line and direction of ties as required.

## 5.6 Using music functions

Where tweaks need to be reused with different music expressions, it is often convenient to make the tweak part of a music function. In this section, we discuss only substitution functions, where the object is to substitute a variable into a piece of LilyPond input code. Other more complex functions are described in Music functions.

### 5.6.1 Substitution function syntax

Making a function that substitutes a variable into LilyPond code is easy. The general form of these functions is

>     function =
>     #(define-music-function
>          (parser location arg1 arg2 …)
>          (type1? type2? …)
>        #{
>          …music…
>        #})

where

`argN` | nth argument
`typeN?` | a scheme type predicate for which `argN` must return `#t`.
`…music…` | normal LilyPond input, using `$` to reference arguments (eg. ‘`$arg1`’).

The `parser` and `location` arguments are mandatory, and are used in some advanced situations as described in the ‘Extending’ manual (see Music functions). For substitution functions, just be sure to include them.

The list of type predicates is also required. Some of the most common type predicates used in music functions are:

>     boolean?
>     cheap-list?  (use instead of ‘list?’ for faster processing)
>     ly:music?
>     markup?
>     number?
>     pair?
>     string?
>     symbol?

For a list of available type predicates, see Predefined type predicates. User-defined type predicates are also allowed.

#### See also

Notation Reference: Predefined type predicates.

Extending: Music functions.

Installed Files: ‘`lily/music-scheme.cc`’, ‘`scm/c++.scm`’, ‘`scm/lily.scm`’.

### 5.6.2 Substitution function examples

This section introduces some substitution function examples. These are not intended to be exhaustive, but rather to demonstrate some of the possibilities of simple substitution functions.

In the first example, a function is defined that simplifies setting the padding of a TextScript:

>     padText =
>     #(define-music-function
>          (parser location padding)
>          (number?)
>        #{
>          \once \override TextScript #'padding = $padding
>        #})

>     \relative c''' {
>       c4^"piu mosso" b a b
>       \padText #1.8
>       c4^"piu mosso" d e f
>       \padText #2.6
>       c4^"piu mosso" fis a g
>     }

In addition to numbers, we can use music expressions such as notes for arguments to music functions:

>     custosNote =
>     #(define-music-function
>          (parser location note)
>          (ly:music?)
>        #{
>          \once \override Voice.NoteHead #'stencil =
>            #ly:text-interface::print
>          \once \override Voice.NoteHead #'text =
>            \markup \musicglyph #"custodes.mensural.u0"
>          \once \override Voice.Stem #'stencil = ##f
>          $note
>        #})

>     \relative c' { c4 d e f \custosNote g }

Substitution functions with multiple arguments can be defined:

>     tempoPadded =
>     #(define-music-function
>          (parser location padding tempotext)
>          (number? string?)
>        #{
>          \once \override Score.MetronomeMark #'padding = $padding
>          \tempo \markup { \bold $tempotext }
>        #})

>     \relative c'' {
>       \tempo \markup { "Low tempo" }
>       c4 d e f g1
>       \tempoPadded #4.0 #"High tempo"
>       g4 f e d c1
>     }

# A. Notation manual tables

## A.1 Chord name chart

The following charts shows two standard systems for printing chord names, along with the pitches they represent.

## A.2 Common chord modifiers

The following table shows chord modifiers that can be used in `\chordmode` to generate standard chord structures.

Chord type | Intervals | Modifier(s) | Example
Major | Major third, perfect fifth | `5` or nothing |
Minor | Minor third, perfect fifth | `m` or `m5` |
Augmented | Major third, augmented fifth | `aug` |
Diminished | Minor third, diminished fifth | `dim` |
Dominant seventh | Major triad, minor seventh | `7` |
Major seventh | Major triad, major seventh | `maj7` or `maj` |
Minor seventh | Minor triad, minor seventh | `m7` |
Diminished seventh | Diminished triad, diminished seventh | `dim7` |
Augmented seventh | Augmented triad, minor seventh | `aug7` |
Half-diminished seventh | Diminished triad, minor seventh | `m7.5-` |
Minor-major seventh | Minor triad, major seventh | `m7+` |
Major sixth | Major triad, sixth | `6` |
Minor sixth | Minor triad, sixth | `m6` |
Dominant ninth | Dominant seventh, major ninth | `9` |
Major ninth | Major seventh, major ninth | `maj9` |
Minor ninth | Minor seventh, major ninth | `m9` |
Dominant eleventh | Dominant ninth, perfect eleventh | `11` |
Major eleventh | Major ninth, perfect eleventh | `maj11` |
Minor eleventh | Minor ninth, perfect eleventh | `m11` |
Dominant thirteenth | Dominant ninth, major thirteenth | `13` |
Dominant thirteenth | Dominant eleventh, major thirteenth | `13.11` |
Major thirteenth | Major eleventh, major thirteenth | `maj13.11` |
Minor thirteenth | Minor eleventh, major thirteenth | `m13.11` |
Suspended second | Major second, perfect fifth | `sus2` |
Suspended fourth | Perfect fourth, perfect fifth | `sus4` |
Power chord (two-voiced) | Perfect fifth | `1.5` |
Power chord (three-voiced) | Perfect fifth, octave | `1.5.8` |

## A.3 Predefined string tunings

The chart below shows the predefined string tunings.

## A.4 Predefined fretboard diagrams

The chart below shows the predefined fretboard diagrams for guitar.

The chart below shows the predefined fretboard diagrams for ukulele.

The chart below shows the predefined fretboard diagrams for mandolin.

## A.5 MIDI instruments

The following is a list of names that can be used for the `midiInstrument` property. The order of the instruments below, starting in the left-hand column moving down, corresponds to the General MIDI Standard’s 128 Program Numbers.

>     acoustic grand            contrabass           lead 7 (fifths)
>     bright acoustic           tremolo strings      lead 8 (bass+lead)
>     electric grand            pizzicato strings    pad 1 (new age)
>     honky-tonk                orchestral harp      pad 2 (warm)
>     electric piano 1          timpani              pad 3 (polysynth)
>     electric piano 2          string ensemble 1    pad 4 (choir)
>     harpsichord               string ensemble 2    pad 5 (bowed)
>     clav                      synthstrings 1       pad 6 (metallic)
>     celesta                   synthstrings 2       pad 7 (halo)
>     glockenspiel              choir aahs           pad 8 (sweep)
>     music box                 voice oohs           fx 1 (rain)
>     vibraphone                synth voice          fx 2 (soundtrack)
>     marimba                   orchestra hit        fx 3 (crystal)
>     xylophone                 trumpet              fx 4 (atmosphere)
>     tubular bells             trombone             fx 5 (brightness)
>     dulcimer                  tuba                 fx 6 (goblins)
>     drawbar organ             muted trumpet        fx 7 (echoes)
>     percussive organ          french horn          fx 8 (sci-fi)
>     rock organ                brass section        sitar
>     church organ              synthbrass 1         banjo
>     reed organ                synthbrass 2         shamisen
>     accordion                 soprano sax          koto
>     harmonica                 alto sax             kalimba
>     concertina                tenor sax            bagpipe
>     acoustic guitar (nylon)   baritone sax         fiddle
>     acoustic guitar (steel)   oboe                 shanai
>     electric guitar (jazz)    english horn         tinkle bell
>     electric guitar (clean)   bassoon              agogo
>     electric guitar (muted)   clarinet             steel drums
>     overdriven guitar         piccolo              woodblock
>     distorted guitar          flute                taiko drum
>     guitar harmonics          recorder             melodic tom
>     acoustic bass             pan flute            synth drum
>     electric bass (finger)    blown bottle         reverse cymbal
>     electric bass (pick)      shakuhachi           guitar fret noise
>     fretless bass             whistle              breath noise
>     slap bass 1               ocarina              seashore
>     slap bass 2               lead 1 (square)      bird tweet
>     synth bass 1              lead 2 (sawtooth)    telephone ring
>     synth bass 2              lead 3 (calliope)    helicopter
>     violin                    lead 4 (chiff)       applause
>     viola                     lead 5 (charang)     gunshot
>     cello                     lead 6 (voice)

## A.6 List of colors

#### Normal colors

Usage syntax is detailed in Coloring objects.

    black       white          red         green
    blue        cyan           magenta     yellow
    grey        darkred        darkgreen   darkblue
    darkcyan    darkmagenta    darkyellow

#### X color names

X color names come several variants:

Any name that is spelled as a single word with capitalization (e.g. ‘LightSlateBlue’) can also be spelled as space separated words without capitalization (e.g. ‘light slate blue’).

The word ‘grey’ can always be spelled ‘gray’ (e.g. ‘DarkSlateGray’).

Some names can take a numerical suffix (e.g. ‘LightSalmon4’).

#### Color Names without a numerical suffix:

    snow		GhostWhite	WhiteSmoke	gainsboro	FloralWhite
    OldLace		linen		AntiqueWhite	PapayaWhip	BlanchedAlmond
    bisque		PeachPuff	NavajoWhite	moccasin	cornsilk
    ivory		LemonChiffon	seashell	honeydew	MintCream
    azure		AliceBlue	lavender	LavenderBlush	MistyRose
    white		black		DarkSlateGrey	DimGrey		SlateGrey
    LightSlateGrey	grey		LightGrey	MidnightBlue	navy
    NavyBlue	CornflowerBlue	DarkSlateBlue	SlateBlue	MediumSlateBlue
    LightSlateBlue	MediumBlue	RoyalBlue	blue		DodgerBlue
    DeepSkyBlue	SkyBlue		LightSkyBlue	SteelBlue	LightSteelBlue
    LightBlue	PowderBlue	PaleTurquoise	DarkTurquoise	MediumTurquoise
    turquoise	cyan		LightCyan	CadetBlue	MediumAquamarine
    aquamarine	DarkGreen	DarkOliveGreen	DarkSeaGreen	SeaGreen
    MediumSeaGreen	LightSeaGreen	PaleGreen	SpringGreen	LawnGreen
    green		chartreuse	MediumSpringGreen	GreenYellow	LimeGreen
    YellowGreen	ForestGreen	OliveDrab	DarkKhaki	khaki
    PaleGoldenrod	LightGoldenrodYellow	LightYellow	yellow	gold
    LightGoldenrod	goldenrod	DarkGoldenrod	RosyBrown	IndianRed
    SaddleBrown	sienna		peru		burlywood	beige
    wheat		SandyBrown	tan		chocolate	firebrick
    brown		DarkSalmon	salmon		LightSalmon	orange
    DarkOrange	coral		LightCoral	tomato		OrangeRed
    red		HotPink		DeepPink	pink		LightPink
    PaleVioletRed	maroon		MediumVioletRed	VioletRed	magenta
    violet		plum		orchid		MediumOrchid	DarkOrchid
    DarkViolet	BlueViolet	purple		MediumPurple	thistle
    DarkGrey	DarkBlue	DarkCyan	DarkMagenta	DarkRed
    LightGreen

#### Color names with a numerical suffix

In the following names the suffix N can be a number in the range 1-4:

    snowN		seashellN	AntiqueWhiteN	bisqueN		PeachPuffN
    NavajoWhiteN	LemonChiffonN	cornsilkN	ivoryN		honeydewN
    LavenderBlushN	MistyRoseN	azureN		SlateBlueN	RoyalBlueN
    blueN		DodgerBlueN	SteelBlueN	DeepSkyBlueN	SkyBlueN
    LightSkyBlueN	LightSteelBlueN	LightBlueN	LightCyanN	PaleTurquoiseN
    CadetBlueN	turquoiseN	cyanN		aquamarineN	DarkSeaGreenN
    SeaGreenN	PaleGreenN	SpringGreenN	greenN		chartreuseN
    OliveDrabN	DarkOliveGreenN	khakiN		LightGoldenrodN	LightYellowN
    yellowN		goldN		goldenrodN	DarkGoldenrodN	RosyBrownN
    IndianRedN	siennaN		burlywoodN	wheatN		tanN
    chocolateN	firebrickN	brownN		salmonN		LightSalmonN
    orangeN		DarkOrangeN	coralN		tomatoN		OrangeRedN
    redN		DeepPinkN	HotPinkN	pinkN		LightPinkN
    PaleVioletRedN	maroonN		VioletRedN	magentaN	orchidN
    plumN		MediumOrchidN	DarkOrchidN	purpleN		MediumPurpleN
    thistleN

#### Grey Scale

A grey scale can be obtained using:

>     greyN

Where N is in the range 0-100.

## A.7 The Feta font

The following symbols are available in the Emmentaler font and may be accessed directly using text markup with the name of the glyph as shown in the tables below, such as `g^\markup {\musicglyph #"scripts.segno" }` or `\markup {\musicglyph #"five"}`. For more information, see Formatting text.

### Clef glyphs

### Time Signature glyphs

### Number glyphs

### Accidental glyphs

### Default Notehead glyphs

### Special Notehead glyphs

### Shape-note Notehead glyphs

### Rest glyphs

### Flag glyphs

### Dot glyphs

### Dynamic glyphs

### Script glyphs

### Arrowhead glyphs

### Bracket-tip glyphs

### Pedal glyphs

### Accordion glyphs

### Vaticana glyphs

### Medicaea glyphs

### Hufnagel glyphs

### Mensural glyphs

### Neomensural glyphs

### Petrucci glyphs

### Solesmes glyphs

## A.8 Note head styles

The following styles may be used for note heads.

## A.9 Text markup commands

The following commands can all be used inside `\markup { }`.

### A.9.1 Font

`\abs-fontsize` size (number) arg (markup)

  Use size as the absolute font size to display arg. Adjusts `baseline-skip` and `word-space` accordingly.

  >     \markup {
  >       default text font size
  >       \hspace #2
  >       \abs-fontsize #16 { text font size 16 }
  >       \hspace #2
  >       \abs-fontsize #12 { text font size 12 }
  >     }

`\bold` arg (markup)

  Switch to bold font-series.

  >     \markup {
  >       default
  >       \hspace #2
  >       \bold
  >       bold
  >     }

`\box` arg (markup)

  Draw a box round arg. Looks at `thickness`, `box-padding` and `font-size` properties to determine line thickness and padding around the markup.

  >     \markup {
  >       \override #'(box-padding . 0.5)
  >       \box
  >       \line { V. S. }
  >     }

  Used properties:

  - `box-padding` (0.2)
  - `font-size` (0)
  - `thickness` (1)
`\caps` arg (markup)

  Copy of the `\smallCaps` command.

  >     \markup {
  >       default
  >       \hspace #2
  >       \caps {
  >         Text in small caps
  >       }
  >     }

`\dynamic` arg (markup)

  Use the dynamic font. This font only contains s, f, m, z, p, and r. When producing phrases, like ‘più f’, the normal words (like ‘più’) should be done in a different font. The recommended font for this is bold and italic.

  >     \markup {
  >       \dynamic {
  >         sfzp
  >       }
  >     }

`\finger` arg (markup)

  Set arg as small numbers.

  >     \markup {
  >       \finger {
  >         1 2 3 4 5
  >       }
  >     }

`\fontCaps` arg (markup)

  Set `font-shape` to `caps`

  Note: `\fontCaps` requires the installation and selection of fonts which support the `caps` font shape.

`\fontsize` increment (number) arg (markup)

  Add increment to the font-size. Adjusts `baseline-skip` accordingly.

  >     \markup {
  >       default
  >       \hspace #2
  >       \fontsize #-1.5
  >       smaller
  >     }

  Used properties:

  - `baseline-skip` (2)
  - `word-space` (1)
  - `font-size` (0)
`\huge` arg (markup)

  Set font size to +2.

  >     \markup {
  >       default
  >       \hspace #2
  >       \huge
  >       huge
  >     }

`\italic` arg (markup)

  Use italic `font-shape` for arg.

  >     \markup {
  >       default
  >       \hspace #2
  >       \italic
  >       italic
  >     }

`\large` arg (markup)

  Set font size to +1.

  >     \markup {
  >       default
  >       \hspace #2
  >       \large
  >       large
  >     }

`\larger` arg (markup)

  Increase the font size relative to the current setting.

  >     \markup {
  >       default
  >       \hspace #2
  >       \larger
  >       larger
  >     }

`\magnify` sz (number) arg (markup)

  Set the font magnification for its argument. In the following example, the middle A is 10% larger:

  >     A \magnify #1.1 { A } A

  Note: Magnification only works if a font name is explicitly selected. Use `\fontsize` otherwise.

  >     \markup {
  >       default
  >       \hspace #2
  >       \magnify #1.5 {
  >         50% larger
  >       }
  >     }

`\medium` arg (markup)

  Switch to medium font-series (in contrast to bold).

  >     \markup {
  >       \bold {
  >         some bold text
  >         \hspace #2
  >         \medium {
  >           medium font series
  >         }
  >         \hspace #2
  >         bold again
  >       }
  >     }

`\normal-size-sub` arg (markup)

  Set arg in subscript with a normal font size.

  >     \markup {
  >       default
  >       \normal-size-sub {
  >         subscript in standard size
  >       }
  >     }

  Used properties:

  - `baseline-skip`
`\normal-size-super` arg (markup)

  Set arg in superscript with a normal font size.

  >     \markup {
  >       default
  >       \normal-size-super {
  >         superscript in standard size
  >       }
  >     }

  Used properties:

  - `baseline-skip`
`\normal-text` arg (markup)

  Set all font related properties (except the size) to get the default normal text font, no matter what font was used earlier.

  >     \markup {
  >       \huge \bold \sans \caps {
  >         Some text with font overrides
  >         \hspace #2
  >         \normal-text {
  >           Default text, same font-size
  >         }
  >         \hspace #2
  >         More text as before
  >       }
  >     }

`\normalsize` arg (markup)

  Set font size to default.

  >     \markup {
  >       \teeny {
  >         this is very small
  >         \hspace #2
  >         \normalsize {
  >           normal size
  >         }
  >         \hspace #2
  >         teeny again
  >       }
  >     }

`\number` arg (markup)

  Set font family to `number`, which yields the font used for time signatures and fingerings. This font contains numbers and some punctuation; it has no letters.

  >     \markup {
  >       \number {
  >         0 1 2 3 4 5 6 7 8 9 . ,
  >       }
  >     }

`\roman` arg (markup)

  Set font family to `roman`.

  >     \markup {
  >       \sans \bold {
  >         sans serif, bold
  >         \hspace #2
  >         \roman {
  >           text in roman font family
  >         }
  >         \hspace #2
  >         return to sans
  >       }
  >     }

`\sans` arg (markup)

  Switch to the sans serif font family.

  >     \markup {
  >       default
  >       \hspace #2
  >       \sans {
  >         sans serif
  >       }
  >     }

`\simple` str (string)

  A simple text string; `\markup { foo }` is equivalent with `\markup { \simple #"foo" }`.

  Note: for creating standard text markup or defining new markup commands, the use of `\simple` is unnecessary.

  >     \markup {
  >       \simple #"simple"
  >       \simple #"text"
  >       \simple #"strings"
  >     }

`\small` arg (markup)

  Set font size to -1.

  >     \markup {
  >       default
  >       \hspace #2
  >       \small
  >       small
  >     }

`\smallCaps` arg (markup)

  Emit arg as small caps.

  Note: `\smallCaps` does not support accented characters.

  >     \markup {
  >       default
  >       \hspace #2
  >       \smallCaps {
  >         Text in small caps
  >       }
  >     }

`\smaller` arg (markup)

  Decrease the font size relative to the current setting.

  >     \markup {
  >       \fontsize #3.5 {
  >         some large text
  >         \hspace #2
  >         \smaller {
  >           a bit smaller
  >         }
  >         \hspace #2
  >         more large text
  >       }
  >     }

`\sub` arg (markup)

  Set arg in subscript.

  >     \markup {
  >       \concat {
  >         H
  >         \sub {
  >           2
  >         }
  >         O
  >       }
  >     }

  Used properties:

  - `baseline-skip`
  - `font-size` (0)
`\super` arg (markup)

  Set arg in superscript.

  >     \markup {
  >       E =
  >       \concat {
  >         mc
  >         \super
  >         2
  >       }
  >     }

  Used properties:

  - `baseline-skip`
  - `font-size` (0)
`\teeny` arg (markup)

  Set font size to -3.

  >     \markup {
  >       default
  >       \hspace #2
  >       \teeny
  >       teeny
  >     }

`\text` arg (markup)

  Use a text font instead of music symbol or music alphabet font.

  >     \markup {
  >       \number {
  >         1, 2,
  >         \text {
  >           three, four,
  >         }
  >         5
  >       }
  >     }

`\tiny` arg (markup)

  Set font size to -2.

  >     \markup {
  >       default
  >       \hspace #2
  >       \tiny
  >       tiny
  >     }

`\typewriter` arg (markup)

  Use `font-family` typewriter for arg.

  >     \markup {
  >       default
  >       \hspace #2
  >       \typewriter
  >       typewriter
  >     }

`\underline` arg (markup)

  Underline arg. Looks at `thickness` to determine line thickness, and `offset` to determine line y-offset.

  >     \markup \fill-line {
  >       \underline "underlined"
  >       \override #'(offset . 5)
  >       \override #'(thickness . 1)
  >       \underline "underlined"
  >       \override #'(offset . 1)
  >       \override #'(thickness . 5)
  >       \underline "underlined"
  >     }

  Used properties:

  - `offset` (2)
  - `thickness` (1)
`\upright` arg (markup)

  Set `font-shape` to `upright`. This is the opposite of `italic`.

  >     \markup {
  >       \italic {
  >         italic text
  >         \hspace #2
  >         \upright {
  >           upright text
  >         }
  >         \hspace #2
  >         italic again
  >       }
  >     }

### A.9.2 Align

`\center-align` arg (markup)

  Align `arg` to its X center.

  >     \markup {
  >       \column {
  >         one
  >         \center-align
  >         two
  >         three
  >       }
  >     }

`\center-column` args (markup list)

  Put `args` in a centered column.

  >     \markup {
  >       \center-column {
  >         one
  >         two
  >         three
  >       }
  >     }

  Used properties:

  - `baseline-skip`
`\column` args (markup list)

  Stack the markups in args vertically. The property `baseline-skip` determines the space between markups in args.

  >     \markup {
  >       \column {
  >         one
  >         two
  >         three
  >       }
  >     }

  Used properties:

  - `baseline-skip`
`\combine` arg1 (markup) arg2 (markup)

  Print two markups on top of each other.

  Note: `\combine` cannot take a list of markups enclosed in curly braces as an argument; the follow example will not compile:

  >     \combine { a list }

  >     \markup {
  >       \fontsize #5
  >       \override #'(thickness . 2)
  >       \combine
  >         \draw-line #'(0 . 4)
  >         \arrow-head #Y #DOWN ##f
  >     }

`\concat` args (markup list)

  Concatenate args in a horizontal line, without spaces in between. Strings and simple markups are concatenated on the input level, allowing ligatures. For example, `\concat { "f" \simple #"i" }` is equivalent to `"fi"`.

  >     \markup {
  >       \concat {
  >         one
  >         two
  >         three
  >       }
  >     }

`\dir-column` args (markup list)

  Make a column of args, going up or down, depending on the setting of the `direction` layout property.

  >     \markup {
  >       \override #`(direction . ,UP) {
  >         \dir-column {
  >           going up
  >         }
  >       }
  >       \hspace #1
  >       \dir-column {
  >         going down
  >       }
  >       \hspace #1
  >       \override #'(direction . 1) {
  >         \dir-column {
  >           going up
  >         }
  >       }
  >     }

  Used properties:

  - `baseline-skip`
  - `direction`
`\fill-line` args (markup list)

  Put markups in a horizontal line of width line-width. The markups are spaced or flushed to fill the entire line. If there are no arguments, return an empty stencil.

  >     \markup {
  >       \column {
  >         \fill-line {
  >           Words evenly spaced across the page
  >         }
  >         \null
  >         \fill-line {
  >           \line { Text markups }
  >           \line {
  >             \italic { evenly spaced }
  >           }
  >           \line { across the page }
  >         }
  >       }
  >     }

  Used properties:

  - `line-width` (#f)
  - `word-space` (0.6)
  - `text-direction` (1)
`\fill-with-pattern` space (number) dir (direction) pattern (markup) left (markup) right (markup)

  Put left and right in a horizontal line of width `line-width` with a line of markups pattern in between. Patterns are spaced apart by space. Patterns are aligned to the dir markup.

  >     \markup \column {
  >       "right-aligned :"
  >       \fill-with-pattern #1 #RIGHT . first right
  >       \fill-with-pattern #1 #RIGHT . second right
  >       \null
  >       "center-aligned :"
  >       \fill-with-pattern #1.5 #CENTER - left right
  >       \null
  >       "left-aligned :"
  >       \override #'(line-width . 50) \fill-with-pattern #2 #LEFT : left first
  >       \override #'(line-width . 50) \fill-with-pattern #2 #LEFT : left second
  >     }

  Used properties:

  - `line-width`
  - `word-space`
`\general-align` axis (integer) dir (number) arg (markup)

  Align arg in axis direction to the dir side.

  >     \markup {
  >       \column {
  >         one
  >         \general-align #X #LEFT
  >         two
  >         three
  >         \null
  >         one
  >         \general-align #X #CENTER
  >         two
  >         three
  >         \null
  >         \line {
  >           one
  >           \general-align #Y #UP
  >           two
  >           three
  >         }
  >         \null
  >         \line {
  >           one
  >           \general-align #Y #3.2
  >           two
  >           three
  >         }
  >       }
  >     }

`\halign` dir (number) arg (markup)

  Set horizontal alignment. If dir is `-1`, then it is left-aligned, while `+1` is right. Values in between interpolate alignment accordingly.

  >     \markup {
  >       \column {
  >         one
  >         \halign #LEFT
  >         two
  >         three
  >         \null
  >         one
  >         \halign #CENTER
  >         two
  >         three
  >         \null
  >         one
  >         \halign #RIGHT
  >         two
  >         three
  >         \null
  >         one
  >         \halign #-5
  >         two
  >         three
  >       }
  >     }

`\hcenter-in` length (number) arg (markup)

  Center arg horizontally within a box of extending length/2 to the left and right.

  >     \new StaffGroup <<
  >       \new Staff {
  >         \set Staff.instrumentName = \markup {
  >           \hcenter-in #12
  >           Oboe
  >         }
  >         c''1
  >       }
  >       \new Staff {
  >         \set Staff.instrumentName = \markup {
  >           \hcenter-in #12
  >           Bassoon
  >         }
  >         \clef tenor
  >         c'1
  >       }
  >     >>

`\hspace` amount (number)

  Create an invisible object taking up horizontal space amount.

  >     \markup {
  >       one
  >       \hspace #2
  >       two
  >       \hspace #8
  >       three
  >     }

  Used properties:

  - `word-space`
`\justify-field` symbol (symbol)

  Justify the data which has been assigned to symbol.

  >     \header {
  >       title = "My title"
  >       myText = "Lorem ipsum dolor sit amet, consectetur adipisicing
  >         elit, sed do eiusmod tempor incididunt ut labore et dolore magna
  >         aliqua.  Ut enim ad minim veniam, quis nostrud exercitation ullamco
  >         laboris nisi ut aliquip ex ea commodo consequat."
  >     }

  >     \paper {
  >       bookTitleMarkup = \markup {
  >         \column {
  >           \fill-line { \fromproperty #'header:title }
  >           \null
  >           \justify-field #'header:myText
  >         }
  >       }
  >     }

  >     \markup {
  >       \null
  >     }

`\justify` args (markup list)

  Like `\wordwrap`, but with lines stretched to justify the margins. Use `\override #'(line-width . X)` to set the line width; X is the number of staff spaces.

  >     \markup {
  >       \justify {
  >         Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed
  >         do eiusmod tempor incididunt ut labore et dolore magna aliqua.
  >         Ut enim ad minim veniam, quis nostrud exercitation ullamco
  >         laboris nisi ut aliquip ex ea commodo consequat.
  >       }
  >     }

  Used properties:

  - `text-direction` (1)
  - `word-space`
  - `line-width` (#f)
  - `baseline-skip`
`\justify-string` arg (string)

  Justify a string. Paragraphs may be separated with double newlines

  >     \markup {
  >       \override #'(line-width . 40)
  >       \justify-string #"Lorem ipsum dolor sit amet, consectetur
  >           adipisicing elit, sed do eiusmod tempor incididunt ut labore
  >           et dolore magna aliqua.

  >           Ut enim ad minim veniam, quis nostrud exercitation ullamco
  >           laboris nisi ut aliquip ex ea commodo consequat.

  >           Excepteur sint occaecat cupidatat non proident, sunt in culpa
  >           qui officia deserunt mollit anim id est laborum"
  >     }

  Used properties:

  - `text-direction` (1)
  - `word-space`
  - `line-width`
  - `baseline-skip`
`\left-align` arg (markup)

  Align arg on its left edge.

  >     \markup {
  >       \column {
  >         one
  >         \left-align
  >         two
  >         three
  >       }
  >     }

`\left-column` args (markup list)

  Put `args` in a left-aligned column.

  >     \markup {
  >       \left-column {
  >         one
  >         two
  >         three
  >       }
  >     }

  Used properties:

  - `baseline-skip`
`\line` args (markup list)

  Put args in a horizontal line. The property `word-space` determines the space between markups in args.

  >     \markup {
  >       \line {
  >         one two three
  >       }
  >     }

  Used properties:

  - `text-direction` (1)
  - `word-space`
`\lower` amount (number) arg (markup)

  Lower arg by the distance amount. A negative amount indicates raising; see also `\raise`.

  >     \markup {
  >       one
  >       \lower #3
  >       two
  >       three
  >     }

`\pad-around` amount (number) arg (markup)

  Add padding amount all around arg.

  >     \markup {
  >       \box {
  >         default
  >       }
  >       \hspace #2
  >       \box {
  >         \pad-around #0.5 {
  >           padded
  >         }
  >       }
  >     }

`\pad-markup` amount (number) arg (markup)

  Add space around a markup object.

  >     \markup {
  >       \box {
  >         default
  >       }
  >       \hspace #2
  >       \box {
  >         \pad-markup #1 {
  >           padded
  >         }
  >       }
  >     }

`\pad-to-box` x-ext (pair of numbers) y-ext (pair of numbers) arg (markup)

  Make arg take at least x-ext, y-ext space.

  >     \markup {
  >       \box {
  >         default
  >       }
  >       \hspace #4
  >       \box {
  >         \pad-to-box #'(0 . 10) #'(0 . 3) {
  >           padded
  >         }
  >       }
  >     }

`\pad-x` amount (number) arg (markup)

  Add padding amount around arg in the X direction.

  >     \markup {
  >       \box {
  >         default
  >       }
  >       \hspace #4
  >       \box {
  >         \pad-x #2 {
  >           padded
  >         }
  >       }
  >     }

`\put-adjacent` axis (integer) dir (direction) arg1 (markup) arg2 (markup)

  Put arg2 next to arg1, without moving arg1.

`\raise` amount (number) arg (markup)

  Raise arg by the distance amount. A negative amount indicates lowering, see also `\lower`.

  The argument to `\raise` is the vertical displacement amount, measured in (global) staff spaces. `\raise` and `\super` raise objects in relation to their surrounding markups.

  If the text object itself is positioned above or below the staff, then `\raise` cannot be used to move it, since the mechanism that positions it next to the staff cancels any shift made with `\raise`. For vertical positioning, use the `padding` and/or `extra-offset` properties.

  >     \markup {
  >       C
  >       \small
  >       \bold
  >       \raise #1.0
  >       9/7+
  >     }

`\right-align` arg (markup)

  Align arg on its right edge.

  >     \markup {
  >       \column {
  >         one
  >         \right-align
  >         two
  >         three
  >       }
  >     }

`\right-column` args (markup list)

  Put `args` in a right-aligned column.

  >     \markup {
  >       \right-column {
  >         one
  >         two
  >         three
  >       }
  >     }

  Used properties:

  - `baseline-skip`
`\rotate` ang (number) arg (markup)

  Rotate object with ang degrees around its center.

  >     \markup {
  >       default
  >       \hspace #2
  >       \rotate #45
  >       \line {
  >         rotated 45°
  >       }
  >     }

`\translate` offset (pair of numbers) arg (markup)

  Translate arg relative to its surroundings. offset is a pair of numbers representing the displacement in the X and Y axis.

  >     \markup {
  >       *
  >       \translate #'(2 . 3)
  >       \line { translated two spaces right, three up }
  >     }

`\translate-scaled` offset (pair of numbers) arg (markup)

  Translate arg by offset, scaling the offset by the `font-size`.

  >     \markup {
  >       \fontsize #5 {
  >         * \translate #'(2 . 3) translate
  >         \hspace #2
  >         * \translate-scaled #'(2 . 3) translate-scaled
  >       }
  >     }

  Used properties:

  - `font-size` (0)
`\vcenter` arg (markup)

  Align `arg` to its Y center.

  >     \markup {
  >       one
  >       \vcenter
  >       two
  >       three
  >     }

`\vspace` amount (number)

  Create an invisible object taking up vertical space of amount multiplied by 3.

  >     \markup {
  >         \center-column {
  >         one
  >         \vspace #2
  >         two
  >         \vspace #5
  >         three
  >       }
  >     }

`\wordwrap-field` symbol (symbol)

  Wordwrap the data which has been assigned to symbol.

  >     \header {
  >       title = "My title"
  >       myText = "Lorem ipsum dolor sit amet, consectetur adipisicing
  >         elit, sed do eiusmod tempor incididunt ut labore et dolore magna
  >         aliqua.  Ut enim ad minim veniam, quis nostrud exercitation ullamco
  >         laboris nisi ut aliquip ex ea commodo consequat."
  >     }

  >     \paper {
  >       bookTitleMarkup = \markup {
  >         \column {
  >           \fill-line { \fromproperty #'header:title }
  >           \null
  >           \wordwrap-field #'header:myText
  >         }
  >       }
  >     }

  >     \markup {
  >       \null
  >     }

`\wordwrap` args (markup list)

  Simple wordwrap. Use `\override #'(line-width . X)` to set the line width, where X is the number of staff spaces.

  >     \markup {
  >       \wordwrap {
  >         Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed
  >         do eiusmod tempor incididunt ut labore et dolore magna aliqua.
  >         Ut enim ad minim veniam, quis nostrud exercitation ullamco
  >         laboris nisi ut aliquip ex ea commodo consequat.
  >       }
  >     }

  Used properties:

  - `text-direction` (1)
  - `word-space`
  - `line-width` (#f)
  - `baseline-skip`
`\wordwrap-string` arg (string)

  Wordwrap a string. Paragraphs may be separated with double newlines.

  >     \markup {
  >       \override #'(line-width . 40)
  >       \wordwrap-string #"Lorem ipsum dolor sit amet, consectetur
  >           adipisicing elit, sed do eiusmod tempor incididunt ut labore
  >           et dolore magna aliqua.

  >           Ut enim ad minim veniam, quis nostrud exercitation ullamco
  >           laboris nisi ut aliquip ex ea commodo consequat.

  >           Excepteur sint occaecat cupidatat non proident, sunt in culpa
  >           qui officia deserunt mollit anim id est laborum"
  >     }

  Used properties:

  - `text-direction` (1)
  - `word-space`
  - `line-width`
  - `baseline-skip`

### A.9.3 Graphic

`\arrow-head` axis (integer) dir (direction) filled (boolean)

  Produce an arrow head in specified direction and axis. Use the filled head if filled is specified.

  >     \markup {
  >       \fontsize #5 {
  >         \general-align #Y #DOWN {
  >           \arrow-head #Y #UP ##t
  >           \arrow-head #Y #DOWN ##f
  >           \hspace #2
  >           \arrow-head #X #RIGHT ##f
  >           \arrow-head #X #LEFT ##f
  >         }
  >       }
  >     }

`\beam` width (number) slope (number) thickness (number)

  Create a beam with the specified parameters.

  >     \markup {
  >       \beam #5 #1 #2
  >     }

`\bracket` arg (markup)

  Draw vertical brackets around arg.

  >     \markup {
  >       \bracket {
  >         \note #"2." #UP
  >       }
  >     }

`\circle` arg (markup)

  Draw a circle around arg. Use `thickness`, `circle-padding` and `font-size` properties to determine line thickness and padding around the markup.

  >     \markup {
  >       \circle {
  >         Hi
  >       }
  >     }

  Used properties:

  - `circle-padding` (0.2)
  - `font-size` (0)
  - `thickness` (1)
`\draw-circle` radius (number) thickness (number) filled (boolean)

  A circle of radius radius and thickness thickness, optionally filled.

  >     \markup {
  >       \draw-circle #2 #0.5 ##f
  >       \hspace #2
  >       \draw-circle #2 #0 ##t
  >     }

`\draw-hline`

  Draws a line across a page, where the property `span-factor` controls what fraction of the page is taken up.

  >     \markup {
  >       \column {
  >         \draw-hline
  >         \override #'(span-factor . 1/3)
  >         \draw-hline
  >       }
  >     }

  Used properties:

  - `span-factor` (1)
  - `line-width`
  - `draw-line-markup`
`\draw-line` dest (pair of numbers)

  A simple line.

  >     \markup {
  >       \draw-line #'(4 . 4)
  >       \override #'(thickness . 5)
  >       \draw-line #'(-3 . 0)
  >     }

  Used properties:

  - `thickness` (1)
`\epsfile` axis (number) size (number) file-name (string)

  Inline an EPS image. The image is scaled along axis to size.

  >     \markup {
  >       \general-align #Y #DOWN {
  >         \epsfile #X #20 #"context-example.eps"
  >         \epsfile #Y #20 #"context-example.eps"
  >       }
  >     }

`\filled-box` xext (pair of numbers) yext (pair of numbers) blot (number)

  Draw a box with rounded corners of dimensions xext and yext. For example,

      \filled-box #'(-.3 . 1.8) #'(-.3 . 1.8) #0

  creates a box extending horizontally from -0.3 to 1.8 and vertically from -0.3 up to 1.8, with corners formed from a circle of diameter 0 (i.e., sharp corners).

  >     \markup {
  >       \filled-box #'(0 . 4) #'(0 . 4) #0
  >       \filled-box #'(0 . 2) #'(-4 . 2) #0.4
  >       \filled-box #'(1 . 8) #'(0 . 7) #0.2
  >       \with-color #white
  >       \filled-box #'(-4.5 . -2.5) #'(3.5 . 5.5) #0.7
  >     }

`\hbracket` arg (markup)

  Draw horizontal brackets around arg.

  >     \markup {
  >       \hbracket {
  >         \line {
  >           one two three
  >         }
  >       }
  >     }

`\parenthesize` arg (markup)

  Draw parentheses around arg. This is useful for parenthesizing a column containing several lines of text.

  >     \markup {
  >       \line {
  >         \parenthesize {
  >           \column {
  >             foo
  >             bar
  >           }
  >         }
  >         \override #'(angularity . 2) {
  >           \parenthesize {
  >             \column {
  >               bah
  >               baz
  >             }
  >           }
  >         }
  >       }
  >     }

  Used properties:

  - `width` (0.25)
  - `thickness` (1)
  - `size` (1)
  - `padding`
  - `angularity` (0)
`\path` thickness (number) commands (list)

  Draws a path with line thickness thickness according to the directions given in commands. commands is a list of lists where the `car` of each sublist is a drawing command and the `cdr` comprises the associated arguments for each command.

  Line-cap styles and line-join styles may be customized by overriding the `line-cap-style` and `line-join-style` properties, respectively. Available line-cap styles are `'butt`, `'round`, and `'square`. Available line-join styles are `'miter`, `'round`, and `'bevel`.

  The property `filled` specifies whether or not the path is filled with color.

  There are seven commands available to use in the list `commands`: `moveto`, `rmoveto`, `lineto`, `rlineto`, `curveto`, `rcurveto`, and `closepath`. Note that the commands that begin with r are the relative variants of the other three commands.

  The commands `moveto`, `rmoveto`, `lineto`, and `rlineto` take 2 arguments; they are the X and Y coordinates for the destination point.

  The commands `curveto` and `rcurveto` create cubic Bézier curves, and take 6 arguments; the first two are the X and Y coordinates for the first control point, the second two are the X and Y coordinates for the second control point, and the last two are the X and Y coordinates for the destination point.

  The `closepath` command takes zero arguments and closes the current subpath in the active path.

  Note that a sequence of commands must begin with a `moveto` or `rmoveto` to work with the SVG output.

  >     samplePath =
  >       #'((moveto 0 0)
  >          (lineto -1 1)
  >          (lineto 1 1)
  >          (lineto 1 -1)
  >          (curveto -5 -5 -5 5 -1 0)
  >          (closepath))

  >     \markup {
  >       \path #0.25 #samplePath
  >     }

  Used properties:

  - `filled` (#f)
  - `line-join-style` (round)
  - `line-cap-style` (round)
`\postscript` str (string)

  This inserts str directly into the output as a PostScript command string.

  >     ringsps = #"
  >       0.15 setlinewidth
  >       0.9 0.6 moveto
  >       0.4 0.6 0.5 0 361 arc
  >       stroke
  >       1.0 0.6 0.5 0 361 arc
  >       stroke
  >       "

  >     rings = \markup {
  >       \with-dimensions #'(-0.2 . 1.6) #'(0 . 1.2)
  >       \postscript #ringsps
  >     }

  >     \relative c'' {
  >       c2^\rings
  >       a2_\rings
  >     }

`\rounded-box` arg (markup)

  Draw a box with rounded corners around arg. Looks at `thickness`, `box-padding` and `font-size` properties to determine line thickness and padding around the markup; the `corner-radius` property makes it possible to define another shape for the corners (default is 1).

  >     c4^\markup {
  >       \rounded-box {
  >         Overtura
  >       }
  >     }
  >     c,8. c16 c4 r

  Used properties:

  - `box-padding` (0.5)
  - `font-size` (0)
  - `corner-radius` (1)
  - `thickness` (1)
`\scale` factor-pair (pair of numbers) arg (markup)

  Scale arg. factor-pair is a pair of numbers representing the scaling-factor in the X and Y axes. Negative values may be used to produce mirror images.

  >     \markup {
  >       \line {
  >         \scale #'(2 . 1)
  >         stretched
  >         \scale #'(1 . -1)
  >         mirrored
  >       }
  >     }

`\triangle` filled (boolean)

  A triangle, either filled or empty.

  >     \markup {
  >       \triangle ##t
  >       \hspace #2
  >       \triangle ##f
  >     }

  Used properties:

  - `baseline-skip` (2)
  - `font-size` (0)
  - `thickness` (0.1)
`\with-url` url (string) arg (markup)

  Add a link to URL url around arg. This only works in the PDF backend.

  >     \markup {
  >       \with-url #"http://lilypond.org/web/" {
  >         LilyPond ... \italic {
  >           music notation for everyone
  >         }
  >       }
  >     }

### A.9.4 Music

`\customTabClef` num-strings (integer) staff-space (number)

  Draw a tab clef sans-serif style.

`\doubleflat`

  Draw a double flat symbol.

  >     \markup {
  >       \doubleflat
  >     }

`\doublesharp`

  Draw a double sharp symbol.

  >     \markup {
  >       \doublesharp
  >     }

`\flat`

  Draw a flat symbol.

  >     \markup {
  >       \flat
  >     }

`\musicglyph` glyph-name (string)

  glyph-name is converted to a musical symbol; for example, `\musicglyph #"accidentals.natural"` selects the natural sign from the music font. See The Feta font for a complete listing of the possible glyphs.

  >     \markup {
  >       \musicglyph #"f"
  >       \musicglyph #"rests.2"
  >       \musicglyph #"clefs.G_change"
  >     }

`\natural`

  Draw a natural symbol.

  >     \markup {
  >       \natural
  >     }

`\note-by-number` log (number) dot-count (number) dir (number)

  Construct a note symbol, with stem. By using fractional values for dir, longer or shorter stems can be obtained.

  >     \markup {
  >       \note-by-number #3 #0 #DOWN
  >       \hspace #2
  >       \note-by-number #1 #2 #0.8
  >     }

  Used properties:

  - `style` (’())
  - `font-size` (0)
`\note` duration (string) dir (number)

  This produces a note with a stem pointing in dir direction, with the duration for the note head type and augmentation dots. For example, `\note #"4." #-0.75` creates a dotted quarter note, with a shortened down stem.

  >     \markup {
  >       \override #'(style . cross) {
  >         \note #"4.." #UP
  >       }
  >       \hspace #2
  >       \note #"breve" #0
  >     }

  Used properties:

  - `style` (’())
  - `font-size` (0)
`\score` score (score)

  Inline an image of music.

  >     \markup {
  >       \score {
  >         \new PianoStaff <<
  >           \new Staff \relative c' {
  >             \key f \major
  >             \time 3/4
  >             \mark \markup { Allegro }
  >             f2\p( a4)
  >             c2( a4)
  >             bes2( g'4)
  >             f8( e) e4 r
  >           }
  >           \new Staff \relative c {
  >             \clef bass
  >             \key f \major
  >             \time 3/4
  >             f8( a c a c a
  >             f c' es c es c)
  >             f,( bes d bes d bes)
  >             f( g bes g bes g)
  >           }
  >         >>
  >         \layout {
  >           indent = 0.0\cm
  >           \context {
  >             \Score
  >             \override RehearsalMark #'break-align-symbols =
  >               #'(time-signature key-signature)
  >             \override RehearsalMark #'self-alignment-X = #LEFT
  >           }
  >           \context {
  >             \Staff
  >             \override TimeSignature #'break-align-anchor-alignment = #LEFT
  >           }
  >         }
  >       }
  >     }

  Used properties:

  - `baseline-skip`
`\semiflat`

  Draw a semiflat symbol.

  >     \markup {
  >       \semiflat
  >     }

`\semisharp`

  Draw a semisharp symbol.

  >     \markup {
  >       \semisharp
  >     }

`\sesquiflat`

  Draw a 3/2 flat symbol.

  >     \markup {
  >       \sesquiflat
  >     }

`\sesquisharp`

  Draw a 3/2 sharp symbol.

  >     \markup {
  >       \sesquisharp
  >     }

`\sharp`

  Draw a sharp symbol.

  >     \markup {
  >       \sharp
  >     }

`\tied-lyric` str (string)

  Like simple-markup, but use tie characters for ‘~’ tilde symbols.

  >     \markup {
  >       \tied-lyric #"Lasciate~i monti"
  >     }

### A.9.5 Instrument Specific Markup

`\fret-diagram` definition-string (string)

  Make a (guitar) fret diagram. For example, say

  >     \markup \fret-diagram #"s:0.75;6-x;5-x;4-o;3-2;2-3;1-2;"

  for fret spacing 3/4 of staff space, D chord diagram

  Syntax rules for definition-string:

  Used properties:

  - `thickness` (0.5)
  - `fret-diagram-details`
  - `size` (1.0)
  - `align-dir` (-0.4)
`\fret-diagram-terse` definition-string (string)

  Make a fret diagram markup using terse string-based syntax.

  Here is an example

  >     \markup \fret-diagram-terse #"x;x;o;2;3;2;"

  for a D chord diagram.

  Syntax rules for definition-string:

  - Strings are terminated by semicolons; the number of semicolons is the number of strings in the diagram.
  - Mute strings are indicated by ‘`x`’.
  - Open strings are indicated by ‘`o`’.
  - A number indicates a fret indication at that fret.
  - If there are multiple fret indicators desired on a string, they should be separated by spaces.
  - Fingerings are given by following the fret number with a `-`, followed by the finger indicator, e.g. ‘`3-2`’ for playing the third fret with the second finger.
  - Where a barre indicator is desired, follow the fret (or fingering) symbol with `-(` to start a barre and `-)` to end the barre.

  Used properties:

  - `thickness` (0.5)
  - `fret-diagram-details`
  - `size` (1.0)
  - `align-dir` (-0.4)
`\fret-diagram-verbose` marking-list (pair)

  Make a fret diagram containing the symbols indicated in marking-list.

  For example,

  >     \markup \fret-diagram-verbose
  >       #'((mute 6) (mute 5) (open 4)
  >          (place-fret 3 2) (place-fret 2 3) (place-fret 1 2))

  produces a standard D chord diagram without fingering indications.

  Possible elements in marking-list:

  `(mute string-number)`

    Place a small ‘x’ at the top of string string-number.

  `(open string-number)`

    Place a small ‘o’ at the top of string string-number.

  `(barre start-string end-string fret-number)`

    Place a barre indicator (much like a tie) from string start-string to string end-string at fret fret-number.

  `(capo fret-number)`

    Place a capo indicator (a large solid bar) across the entire fretboard at fret location fret-number. Also, set fret fret-number to be the lowest fret on the fret diagram.

  `(place-fret string-number fret-number [finger-value [color-modifier]])`

    Place a fret playing indication on string string-number at fret fret-number with an optional fingering label finger-value, and an optional color modifier color-modifier. By default, the fret playing indicator is a solid dot. This can be globally changed by setting the value of the variable dot-color. Setting color-modifier to `inverted` inverts the dot color for a specific fingering. If the finger part of the `place-fret` element is present, finger-value will be displayed according to the setting of the variable finger-code. There is no limit to the number of fret indications per string.

  Used properties:

  - `thickness` (0.5)
  - `fret-diagram-details`
  - `size` (1.0)
  - `align-dir` (-0.4)
`\harp-pedal` definition-string (string)

  Make a harp pedal diagram.

  Possible elements in definition-string:

  `^`

    pedal is up

  `-`

    pedal is neutral

  `v`

    pedal is down

  `|`

    vertical divider line

  `o`

    the following pedal should be circled (indicating a change)

  The function also checks if the string has the typical form of three pedals, then the divider and then the remaining four pedals. If not it prints out a warning. However, in any case, it will also print each symbol in the order as given. This means you can place the divider (even multiple dividers) anywhere you want, but you’ll have to live with the warnings.

  The appearance of the diagram can be tweaked inter alia using the size property of the TextScript grob (`\override Voice.TextScript #'size = #0.3`) for the overall, the thickness property (`\override Voice.TextScript #'thickness = #3`) for the line thickness of the horizontal line and the divider. The remaining configuration (box sizes, offsets and spaces) is done by the harp-pedal-details list of properties (`\override Voice.TextScript #'harp-pedal-details #'box-width = #1`). It contains the following settings: `box-offset` (vertical shift of the box center for up/down pedals), `box-width`, `box-height`, `space-before-divider` (the spacing between two boxes before the divider) and `space-after-divider` (box spacing after the divider).

  >     \markup \harp-pedal #"^-v|--ov^"

  Used properties:

  - `thickness` (0.5)
  - `harp-pedal-details` (’())
  - `size` (1.2)
`\woodwind-diagram` instrument (symbol) user-draw-commands (list)

  Make a woodwind-instrument diagram. For example, say

  >     \markup \woodwind-diagram #'oboe #'((lh . (d ees)) (cc . (five3qT1q)) (rh . (gis)))

  for an oboe with the left-hand d key, left-hand ees key, and right-hand gis key depressed while the five-hole of the central column effectuates a trill between 1/4 and 3/4 closed.

  The following instruments are supported:

  To see all of the callable keys for a given instrument, include the function `(print-keys 'instrument)` in your .ly file, where instrument is the instrument whose keys you want to print.

  Certain keys allow for special configurations. The entire gamut of configurations possible is as follows:

  Additionally, these configurations can be used in trills. So, for example, `three3qTR` effectuates a trill between 3/4 full and ring depressed on the three hole. As another example, `threeRT` effectuates a trill between R and open, whereas `threeTR` effectuates a trill between open and shut. To see all of the possibilities for all of the keys of a given instrument, invoke `(print-keys-verbose 'instrument)`.

  Lastly, substituting an empty list for the pressed-key alist will result in a diagram with all of the keys drawn but none filled, for example:

  >     \markup \woodwind-diagram #'oboe #'()

  Used properties:

  - `graphical` (#t)
  - `thickness` (0.1)
  - `size` (1)

### A.9.6 Other

`\backslashed-digit` num (integer)

  A feta number, with backslash. This is for use in the context of figured bass notation.

  >     \markup {
  >       \backslashed-digit #5
  >       \hspace #2
  >       \override #'(thickness . 3)
  >       \backslashed-digit #7
  >     }

  Used properties:

  - `thickness` (1.6)
  - `font-size` (0)
`\char` num (integer)

  Produce a single character. Characters encoded in hexadecimal format require the prefix `#x`.

  >     \markup {
  >       \char #65 \char ##x00a9
  >     }

`\eyeglasses`

  Prints out eyeglasses, indicating strongly to look at the conductor.

  >     \markup { \eyeglasses }

`\footnote` mkup (markup) note (markup)

  Have footnote note act as an annotation to the markup mkup.

`\fraction` arg1 (markup) arg2 (markup)

  Make a fraction of two markups.

  >     \markup {
  >       π ≈
  >       \fraction 355 113
  >     }

  Used properties:

  - `font-size` (0)
`\fromproperty` symbol (symbol)

  Read the symbol from property settings, and produce a stencil from the markup contained within. If symbol is not defined, it returns an empty markup.

  >     \header {
  >       myTitle = "myTitle"
  >       title = \markup {
  >         from
  >         \italic
  >         \fromproperty #'header:myTitle
  >       }
  >     }
  >     \markup {
  >       \null
  >     }

`\left-brace` size (number)

  A feta brace in point size size.

  >     \markup {
  >       \left-brace #35
  >       \hspace #2
  >       \left-brace #45
  >     }

`\lookup` glyph-name (string)

  Lookup a glyph by name.

  >     \markup {
  >       \override #'(font-encoding . fetaBraces) {
  >         \lookup #"brace200"
  >         \hspace #2
  >         \rotate #180
  >         \lookup #"brace180"
  >       }
  >     }

`\markalphabet` num (integer)

  Make a markup letter for num. The letters start with A to Z and continue with double letters.

  >     \markup {
  >       \markalphabet #8
  >       \hspace #2
  >       \markalphabet #26
  >     }

`\markletter` num (integer)

  Make a markup letter for num. The letters start with A to Z (skipping letter I), and continue with double letters.

  >     \markup {
  >       \markletter #8
  >       \hspace #2
  >       \markletter #26
  >     }

`\null`

  An empty markup with extents of a single point.

  >     \markup {
  >       \null
  >     }

`\on-the-fly` procedure (symbol) arg (markup)

  Apply the procedure markup command to arg. procedure should take a single argument.

`\override` new-prop (pair) arg (markup)

  Add the argument new-prop to the property list. Properties may be any property supported by font-interface, text-interface and instrument-specific-markup-interface.

  >     \markup {
  >       \line {
  >         \column {
  >           default
  >           baseline-skip
  >         }
  >         \hspace #2
  >         \override #'(baseline-skip . 4) {
  >           \column {
  >             increased
  >             baseline-skip
  >           }
  >         }
  >       }
  >     }

`\page-link` page-number (number) arg (markup)

  Add a link to the page page-number around arg. This only works in the PDF backend.

  >     \markup {
  >       \page-link #2  { \italic { This links to page 2... } }
  >     }

`\page-ref` label (symbol) gauge (markup) default (markup)

  Reference to a page number. label is the label set on the referenced page (using the `\label` command), gauge a markup used to estimate the maximum width of the page number, and default the value to display when label is not found.

`\pattern` count (integer) axis (integer) space (number) pattern (markup)

  Prints count times a pattern markup. Patterns are spaced apart by space. Patterns are distributed on axis.

  >     \markup \column {
  >       "Horizontally repeated :"
  >       \pattern #7 #X #2 \flat
  >       \null
  >       "Vertically repeated :"
  >       \pattern #3 #Y #0.5 \flat
  >     }

`\right-brace` size (number)

  A feta brace in point size size, rotated 180 degrees.

  >     \markup {
  >       \right-brace #45
  >       \hspace #2
  >       \right-brace #35
  >     }

`\slashed-digit` num (integer)

  A feta number, with slash. This is for use in the context of figured bass notation.

  >     \markup {
  >       \slashed-digit #5
  >       \hspace #2
  >       \override #'(thickness . 3)
  >       \slashed-digit #7
  >     }

  Used properties:

  - `thickness` (1.6)
  - `font-size` (0)
`\stencil` stil (stencil)

  Use a stencil as markup.

  >     \markup {
  >       \stencil #(make-circle-stencil 2 0 #t)
  >     }

`\strut`

  Create a box of the same height as the space in the current font.

`\transparent` arg (markup)

  Make arg transparent.

  >     \markup {
  >       \transparent {
  >         invisible text
  >       }
  >     }

`\verbatim-file` name (string)

  Read the contents of file name, and include it verbatim.

  >     \markup {
  >       \verbatim-file #"simple.ly"
  >     }

`\whiteout` arg (markup)

  Provide a white background for arg.

  >     \markup {
  >       \combine
  >         \filled-box #'(-1 . 10) #'(-3 . 4) #1
  >         \whiteout whiteout
  >     }

`\with-color` color (color) arg (markup)

  Draw arg in color specified by color.

  >     \markup {
  >       \with-color #red
  >       red
  >       \hspace #2
  >       \with-color #green
  >       green
  >       \hspace #2
  >       \with-color #blue
  >       blue
  >     }

`\with-dimensions` x (pair of numbers) y (pair of numbers) arg (markup)

  Set the dimensions of arg to x and y.

`\with-link` label (symbol) arg (markup)

  Add a link to the page holding label label around arg. This only works in the PDF backend.

  >     \markup {
  >       \with-link #"label" { \italic { This links to the page containing the label... } }
  >     }

## A.10 Text markup list commands

The following commands can all be used with `\markuplines`:

`\column-lines` args (markup list)

  Like `\column`, but return a list of lines instead of a single markup. `baseline-skip` determines the space between each markup in args.

  Used properties:

  - `baseline-skip`
`\justified-lines` args (markup list)

  Like `\justify`, but return a list of lines instead of a single markup. Use `\override-lines #'(line-width . X)` to set the line width; X is the number of staff spaces.

  Used properties:

  - `text-direction` (1)
  - `word-space`
  - `line-width` (#f)
  - `baseline-skip`
`\override-lines` new-prop (pair) args (markup list)

  Like `\override`, for markup lists.

`\table-of-contents`
`\wordwrap-internal` justify (boolean) args (markup list)

  Internal markup list command used to define `\justify` and `\wordwrap`.

  Used properties:

  - `text-direction` (1)
  - `word-space`
  - `line-width` (#f)
`\wordwrap-lines` args (markup list)

  Like `\wordwrap`, but return a list of lines instead of a single markup. Use `\override-lines #'(line-width . X)` to set the line width, where X is the number of staff spaces.

  Used properties:

  - `text-direction` (1)
  - `word-space`
  - `line-width` (#f)
  - `baseline-skip`
`\wordwrap-string-internal` justify (boolean) arg (string)

  Internal markup list command used to define `\justify-string` and `\wordwrap-string`.

  Used properties:

  - `text-direction` (1)
  - `word-space`
  - `line-width`

## A.11 List of articulations

The following scripts are available in the Feta font and may be attached to notes (eg. ‘`c\accent`’).

### Articulation scripts

### Ornament scripts

### Fermata scripts

### Instrument-specific scripts

### Repeat sign scripts

### Ancient scripts

## A.12 Percussion notes

## A.13 Technical glossary

A glossary of the technical terms and concepts used internally in LilyPond. These terms may appear in the manuals, on mailing lists or in the source code.

### alist

An association list or alist for short is a Scheme pair which associates a value with a key: `(key . value)`. For example, in ‘`scm/lily.scm`’, the alist “type-p-name-alist” associates certain type predicates (e.g. `ly:music?`) with names (e.g. “music”) so that type-check failures can be reported with a console message that includes the name of the expected type predicate.

### callback

A callback is a routine, function or method whose reference is passed as an argument in a call to another routine, so allowing the called routine to invoke it. The technique enables a lower- level software layer to call a function defined in a higher layer. Callbacks are used extensively in LilyPond to permit user-level Scheme code to define how many low-level actions are performed.

### closure

In Scheme, a closure is created when a function, usually a lambda expression, is passed as a variable. The closure contains the function’s code plus references to the lexical bindings of the function’s free variables (i.e. those variables used in the expression but defined outside it). When this function is applied to different arguments later, the free variable bindings that were captured in the closure are used to obtain the values of the free variables to be used in the calculation. One useful property of closures is the retention of internal variable values between invocations, so permitting state to be maintained.

A simple closure is a closure whose expression has no free variables and hence no free variable bindings.

A simple closure is represented in LilyPond by a smob containing the expression and a method to apply the expression to a passed list of arguments.

### glyph

A glyph is a particular graphical representation of a typographic character, or a combination of two characters formating a ligature. A set of glyphs with a single style and shape comprise a font, and a set of fonts covering several styles and sizes comprise a typeface.

#### See also

Notation Reference: Fonts, Text encoding.

### grob

LilyPond objects which represent items of notation in the printed output such as note heads, stems, slurs, ties, fingering, clefs, etc are called ‘Layout objects’, often known as ‘GRaphical OBjects’, or grobs for short. They are represented by instances of the `Grob` class.

#### See also

Learning Manual: Objects and interfaces, Naming conventions of objects and properties, Properties of layout objects.

Internals Reference: grob-interface, All layout objects.

### immutable

An immutable object is one whose state cannot be modified after creation, in contrast to a mutable object, which can be modified after creation.

In LilyPond, immutable or shared properties define the default style and behavior of grobs. They are shared between many objects. In apparent contradiction to the name, they can be changed using `\override` and `\revert`.

#### See also

Notation Reference: mutable.

### interface

Actions and properties which are common to a number of grobs are grouped together in an object called a `grob-interface`, or just ‘interface’ for short.

#### See also

Learning Manual: Objects and interfaces, Naming conventions of objects and properties, Properties found in interfaces.

Notation Reference: Layout interfaces.

Internals Reference: Graphical Object Interfaces.

### lexer

A lexer is a program which converts a sequence of characters into a sequence of tokens, a process called lexical analysis. The LilyPond lexer converts the stream obtained from an input ‘`.ly`’ file into a tokenized stream more suited to the next stage of processing - parsing, for which see parser. The LilyPond lexer is built with Flex from the lexer file ‘`lily/lexer.ll`’ which contains the lexical rules. This file is part of the source code and is not included in the LilyPond binary installation.

### mutable

A mutable object is one whose state can be modified after creation, in contrast to an immutable object, whose state is fixed at the time of creation.

In LilyPond, mutable properties contain values that are specific to one grob. Typically, lists of other objects or results from computations are stored in mutable properties.

#### See also

Notation Reference: immutable.

### output-def

An instance of the `Output-def` class contains the methods and data structures associated with an output block. Instances are created for midi, layout and paper blocks.

### parser

A parser analyzes the sequence of tokens produced by a lexer to determine its grammatical structure, grouping the tokens progressively into larger groupings according to the rules of the grammar. If the sequence of tokens is valid the end product is a tree of tokens whose root is the grammar’s start symbol. If this cannot be achieved the file is invalid and an appropriate error message is produced. The syntactic groupings and the rules for constructing the groupings from their parts for the LilyPond syntax are defined in ‘`lily/parser.yy`’ and shown in Backus Normal Form (BNF) in LilyPond grammar. This file is used to build the parser during the program build by the parser generator, Bison. It is part of the source code and is not included in the LilyPond binary installation.

### parser variable

These are variables defined directly in Scheme. Their direct use by users is strongly discouraged, because their scoping semantics can be confusing.

When the value of such a variable is changed in a ‘`.ly`’ file, the change is global, and unless explicitly reverted, the new value will persist to the end of the file, affecting subsequent `\score` blocks as well as external files added with the `\include` command. This can lead to unintended consequences and in complex typesetting projects the consequent errors can be difficult to track down.

LilyPond uses the following parser variables:

- afterGraceFraction
- musicQuotes
- mode
- output-count
- output-suffix
- parseStringResult
- partCombineListener
- pitchnames
- toplevel-bookparts
- toplevel-scores
- showLastLength
- showFirstLength

### prob

PRoperty OBjects, or probs for short, are instances of the `Prob` class, a simple base class for objects which have mutable and immutable property alists and the methods to manipulate them. The `Music` and `Stream_event` classes derive from `Prob`. Instances of the `Prob` class are also created to hold the formatted content of system grobs and titling blocks during page layout.

### simple closure

See closure.

### smob

Smobs, or ScheMe OBjects, are part of the mechanism used by Guile to export C and C++ objects to Scheme code. In LilyPond, smobs are created from C++ objects through macros. There are two types of smob objects: simple smobs, intended for simple immutable objects like numbers, and complex smobs, used for objects with identities. If you have access to the LilyPond sources, more information can be found in ‘`lily/includes/smob.hh`’.

### stencil

An instance of the stencil class holds the information required to print a typographical object. It is a simple smob containing a confining box, which defines the vertical and horizontal extents of the object, and a Scheme expression which will print the object when evaluated. Stencils may be combined to form more complex stencils defined by a tree of Scheme expressions formed from the Scheme expressions of the component stencils.

The `stencil` property, which connects a grob to its stencil, is defined in the `grob-interface` interface.

#### See also

Internals Reference: grob-interface.

## A.14 All context properties

`aDueText` (markup)

  Text to print at a unisono passage.

`alignAboveContext` (string)

  Where to insert newly created context in vertical alignment.

`alignBassFigureAccidentals` (boolean)

  If true, then the accidentals are aligned in bass figure context.

`alignBelowContext` (string)

  Where to insert newly created context in vertical alignment.

`associatedVoice` (string)

  Name of the `Voice` that has the melody for this `Lyrics` line.

`autoAccidentals` (list)

  List of different ways to typeset an accidental.

  For determining when to print an accidental, several different rules are tried. The rule that gives the highest number of accidentals is used.

  Each entry in the list is either a symbol or a procedure.

  symbol

    The symbol is the name of the context in which the following rules are to be applied. For example, if context is Score then all staves share accidentals, and if context is Staff then all voices in the same staff share accidentals, but staves do not.

  procedure

    The procedure represents an accidental rule to be applied to the previously specified context.

    The procedure takes the following arguments:

    `context`

      The current context to which the rule should be applied.

    `pitch`

      The pitch of the note to be evaluated.

    `barnum`

      The current bar number.

    `measurepos`

      The current measure position.

    The procedure returns a pair of booleans. The first states whether an extra natural should be added. The second states whether an accidental should be printed. `(#t . #f)` does not make sense.

`autoBeamCheck` (procedure)

  A procedure taking three arguments, context, dir [start/stop (-1 or 1)], and test [shortest note in the beam]. A non-`#f` return value starts or stops the auto beam.

`autoBeaming` (boolean)

  If set to true then beams are generated automatically.

`autoCautionaries` (list)

  List similar to `autoAccidentals`, but it controls cautionary accidentals rather than normal ones. Both lists are tried, and the one giving the most accidentals wins. In case of draw, a normal accidental is typeset.

`automaticBars` (boolean)

  If set to false then bar lines will not be printed automatically; they must be explicitly created with a `\bar` command. Unlike the `\cadenzaOn` keyword, measures are still counted. Bar line generation will resume according to that count if this property is unset.

`barAlways` (boolean)

  If set to true a bar line is drawn after each note.

`barCheckSynchronize` (boolean)

  If true then reset `measurePosition` when finding a bar check.

`barNumberVisibility` (procedure)

  A Procedure that takes an integer and returns whether the corresponding bar number should be printed.

`baseMoment` (moment)

  Smallest unit of time that will stand on its own as a subdivided section.

`bassFigureFormatFunction` (procedure)

  A procedure that is called to produce the formatting for a `BassFigure` grob. It takes a list of `BassFigureEvent`s, a context, and the grob to format.

`bassStaffProperties` (list)

  An alist of property settings to apply for the down staff of `PianoStaff`. Used by `\autochange`.

`beamExceptions` (list)

  An alist of exceptions to autobeam rules that normally end on beats.

`beatStructure` (list)

  List of `baseMoment`s that are combined to make beats.

`chordChanges` (boolean)

  Only show changes in chords scheme?

`chordNameExceptions` (list)

  An alist of chord exceptions. Contains `(chord . markup)` entries.

`chordNameExceptionsFull` (list)

  An alist of full chord exceptions. Contains `(chord . markup)` entries.

`chordNameExceptionsPartial` (list)

  An alist of partial chord exceptions. Contains `(chord . (prefix-markup suffix-markup))` entries.

`chordNameFunction` (procedure)

  The function that converts lists of pitches to chord names.

`chordNameLowercaseMinor` (boolean)

  Downcase roots of minor chords?

`chordNameSeparator` (markup)

  The markup object used to separate parts of a chord name.

`chordNoteNamer` (procedure)

  A function that converts from a pitch object to a text markup. Used for single pitches.

`chordPrefixSpacer` (number)

  The space added between the root symbol and the prefix of a chord name.

`chordRootNamer` (procedure)

  A function that converts from a pitch object to a text markup. Used for chords.

`clefGlyph` (string)

  Name of the symbol within the music font.

`clefOctavation` (integer)

  Add this much extra octavation. Values of 7 and -7 are common.

`clefPosition` (number)

  Where should the center of the clef symbol go, measured in half staff spaces from the center of the staff.

`completionBusy` (boolean)

  Whether a completion-note head is playing.

`connectArpeggios` (boolean)

  If set, connect arpeggios across piano staff.

`countPercentRepeats` (boolean)

  If set, produce counters for percent repeats.

`createKeyOnClefChange` (boolean)

  Print a key signature whenever the clef is changed.

`createSpacing` (boolean)

  Create `StaffSpacing` objects? Should be set for staves.

`crescendoSpanner` (symbol)

  The type of spanner to be used for crescendi. Available values are ‘`hairpin`’ and ‘`text`’. If unset, a hairpin crescendo is used.

`crescendoText` (markup)

  The text to print at start of non-hairpin crescendo, i.e., ‘`cresc.`’.

`cueClefGlyph` (string)

  Name of the symbol within the music font.

`cueClefOctavation` (integer)

  Add this much extra octavation. Values of 7 and -7 are common.

`cueClefPosition` (number)

  Where should the center of the clef symbol go, measured in half staff spaces from the center of the staff.

`currentBarNumber` (integer)

  Contains the current barnumber. This property is incremented at every bar line.

`decrescendoSpanner` (symbol)

  The type of spanner to be used for decrescendi. Available values are ‘`hairpin`’ and ‘`text`’. If unset, a hairpin decrescendo is used.

`decrescendoText` (markup)

  The text to print at start of non-hairpin decrescendo, i.e., ‘`dim.`’.

`defaultBarType` (string)

  Set the default type of bar line. See `whichBar` for information on available bar types.

  This variable is read by Timing_translator at Score level.

`defaultStrings` (list)

  A list of strings to use in calculating frets for tablatures and fretboards if no strings are provided in the notes for the current moment.

`doubleRepeatType` (string)

  Set the default bar line for double repeats.

`doubleSlurs` (boolean)

  If set, two slurs are created for every slurred note, one above and one below the chord.

`drumPitchTable` (hash table)

  A table mapping percussion instruments (symbols) to pitches.

`drumStyleTable` (hash table)

  A hash table which maps drums to layout settings. Predefined values: ‘`drums-style`’, ‘`timbales-style`’, ‘`congas-style`’, ‘`bongos-style`’, and ‘`percussion-style`’.

  The layout style is a hash table, containing the drum-pitches (e.g., the symbol ‘`hihat`’) as keys, and a list `(notehead-style script vertical-position)` as values.

`explicitClefVisibility` (vector)

  ‘`break-visibility`’ function for clef changes.

`explicitCueClefVisibility` (vector)

  ‘`break-visibility`’ function for cue clef changes.

`explicitKeySignatureVisibility` (vector)

  ‘`break-visibility`’ function for explicit key changes. ‘`\override`’ of the `break-visibility` property will set the visibility for normal (i.e., at the start of the line) key signatures.

`extendersOverRests` (boolean)

  Whether to continue extenders as they cross a rest.

`extraNatural` (boolean)

  Whether to typeset an extra natural sign before accidentals changing from a non-natural to another non-natural.

`figuredBassAlterationDirection` (direction)

  Where to put alterations relative to the main figure.

`figuredBassCenterContinuations` (boolean)

  Whether to vertically center pairs of extender lines. This does not work with three or more lines.

`figuredBassFormatter` (procedure)

  A routine generating a markup for a bass figure.

`figuredBassPlusDirection` (direction)

  Where to put plus signs relative to the main figure.

`fingeringOrientations` (list)

  A list of symbols, containing ‘`left`’, ‘`right`’, ‘`up`’ and/or ‘`down`’. This list determines where fingerings are put relative to the chord being fingered.

`firstClef` (boolean)

  If true, create a new clef when starting a staff.

`followVoice` (boolean)

  If set, note heads are tracked across staff switches by a thin line.

`fontSize` (number)

  The relative size of all grobs in a context.

`forbidBreak` (boolean)

  If set to `##t`, prevent a line break at this point.

`forceClef` (boolean)

  Show clef symbol, even if it has not changed. Only active for the first clef after the property is set, not for the full staff.

`fretLabels` (list)

  A list of strings or Scheme-formatted markups containing, in the correct order, the labels to be used for lettered frets in tablature.

`glissandoMap` (list)

  A map in the form of ’((source1 . target1) (source2 . target2) (sourcen . targetn)) showing the glissandi to be drawn for note columns. The value ’() will default to ’((0 . 0) (1 . 1) (n . n)), where n is the minimal number of note-heads in the two note columns between which the glissandi occur.

`gridInterval` (moment)

  Interval for which to generate `GridPoint`s.

`handleNegativeFrets` (symbol)

  How the automatic fret calculator should handle calculated negative frets. Values include `'ignore`, to leave them out of the diagram completely, `'include`, to include them as calculated, and `'recalculate`, to ignore the specified string and find a string where they will fit with a positive fret number.

`harmonicAccidentals` (boolean)

  If set, harmonic notes in chords get accidentals.

`harmonicDots` (boolean)

  If set, harmonic notes in dotted chords get dots.

`highStringOne` (boolean)

  Whether the first string is the string with highest pitch on the instrument. This used by the automatic string selector for tablature notation.

`ignoreBarChecks` (boolean)

  Ignore bar checks.

`ignoreFiguredBassRest` (boolean)

  Don’t swallow rest events.

`ignoreMelismata` (boolean)

  Ignore melismata for this Lyrics line.

`implicitBassFigures` (list)

  A list of bass figures that are not printed as numbers, but only as extender lines.

`implicitTimeSignatureVisibility` (vector)

  break visibility for the default time signature.

`includeGraceNotes` (boolean)

  Do not ignore grace notes for Lyrics.

`instrumentCueName` (markup)

  The name to print if another instrument is to be taken.

`instrumentEqualizer` (procedure)

  A function taking a string (instrument name), and returning a `(min . max)` pair of numbers for the loudness range of the instrument.

`instrumentName` (markup)

  The name to print left of a staff. The `instrumentName` property labels the staff in the first system, and the `shortInstrumentName` property labels following lines.

`instrumentTransposition` (pitch)

  Define the transposition of the instrument. Its value is the pitch that sounds like middle C. This is used to transpose the MIDI output, and `\quote`s.

`internalBarNumber` (integer)

  Contains the current barnumber. This property is used for internal timekeeping, among others by the `Accidental_engraver`.

`keepAliveInterfaces` (list)

  A list of symbols, signifying grob interfaces that are worth keeping a staff with `remove-empty` set around for.

`keyAlterationOrder` (list)

  An alist that defines in what order alterations should be printed. The format is `(step . alter)`, where step is a number from 0 to 6 and alter from -2 (sharp) to 2 (flat).

`keySignature` (list)

  The current key signature. This is an alist containing `(step . alter)` or `((octave . step) . alter)`, where step is a number in the range 0 to 6 and alter a fraction, denoting alteration. For alterations, use symbols, e.g. `keySignature = #`((6 . ,FLAT))`.

`lyricMelismaAlignment` (direction)

  Alignment to use for a melisma syllable.

`majorSevenSymbol` (markup)

  How should the major 7th be formatted in a chord name?

`markFormatter` (procedure)

  A procedure taking as arguments the context and the rehearsal mark. It should return the formatted mark as a markup object.

`maximumFretStretch` (number)

  Don’t allocate frets further than this from specified frets.

`measureLength` (moment)

  Length of one measure in the current time signature.

`measurePosition` (moment)

  How much of the current measure have we had. This can be set manually to create incomplete measures.

`melismaBusyProperties` (list)

  A list of properties (symbols) to determine whether a melisma is playing. Setting this property will influence how lyrics are aligned to notes. For example, if set to `#'(melismaBusy beamMelismaBusy)`, only manual melismata and manual beams are considered. Possible values include `melismaBusy`, `slurMelismaBusy`, `tieMelismaBusy`, and `beamMelismaBusy`.

`metronomeMarkFormatter` (procedure)

  How to produce a metronome markup. Called with two arguments: a `TempoChangeEvent` and context.

`middleCClefPosition` (number)

  The position of the middle C, as determined only by the clef. This can be calculated by looking at `clefPosition` and `clefGlyph`.

`middleCCuePosition` (number)

  The position of the middle C, as determined only by the clef of the cue notes. This can be calculated by looking at `cueClefPosition` and `cueClefGlyph`.

`middleCOffset` (number)

  The offset of middle C from the position given by `middleCClefPosition` This is used for ottava brackets.

`middleCPosition` (number)

  The place of the middle C, measured in half staff-spaces. Usually determined by looking at `middleCClefPosition` and `middleCOffset`.

`midiChannelMapping` (symbol)

  How to map MIDI channels: per `instrument` (default), `staff` or `voice`.

`midiInstrument` (string)

  Name of the MIDI instrument to use.

`midiMaximumVolume` (number)

  Analogous to `midiMinimumVolume`.

`midiMinimumVolume` (number)

  Set the minimum loudness for MIDI. Ranges from 0 to 1.

`minimumFret` (number)

  The tablature auto string-selecting mechanism selects the highest string with a fret at least `minimumFret`.

`minimumPageTurnLength` (moment)

  Minimum length of a rest for a page turn to be allowed.

`minimumRepeatLengthForPageTurn` (moment)

  Minimum length of a repeated section for a page turn to be allowed within that section.

`noChordSymbol` (markup)

  Markup to be displayed for rests in a ChordNames context.

`noteToFretFunction` (procedure)

  Convert list of notes and list of defined strings to full list of strings and fret numbers. Parameters: The context, a list of note events, a list of tabstring events, and the fretboard grob if a fretboard is desired.

`ottavation` (markup)

  If set, the text for an ottava spanner. Changing this creates a new text spanner.

`output` (music output)

  The output produced by a score-level translator during music interpretation.

`partCombineTextsOnNote` (boolean)

  Print part-combine texts only on the next note rather than immediately on rests or skips.

`pedalSostenutoStrings` (list)

  See `pedalSustainStrings`.

`pedalSostenutoStyle` (symbol)

  See `pedalSustainStyle`.

`pedalSustainStrings` (list)

  A list of strings to print for sustain-pedal. Format is `(up updown down)`, where each of the three is the string to print when this is done with the pedal.

`pedalSustainStyle` (symbol)

  A symbol that indicates how to print sustain pedals: `text`, `bracket` or `mixed` (both).

`pedalUnaCordaStrings` (list)

  See `pedalSustainStrings`.

`pedalUnaCordaStyle` (symbol)

  See `pedalSustainStyle`.

`predefinedDiagramTable` (hash table)

  The hash table of predefined fret diagrams to use in FretBoards.

`printKeyCancellation` (boolean)

  Print restoration alterations before a key signature change.

`printOctaveNames` (boolean)

  Print octave marks for the `NoteNames` context.

`printPartCombineTexts` (boolean)

  Set ‘Solo’ and ‘A due’ texts in the part combiner?

`proportionalNotationDuration` (moment)

  Global override for shortest-playing duration. This is used for switching on proportional notation.

`rehearsalMark` (integer)

  The last rehearsal mark printed.

`repeatCommands` (list)

  This property is a list of commands of the form `(list 'volta x)`, where x is a string or `#f`. `'end-repeat` is also accepted as a command.

`repeatCountVisibility` (procedure)

  A procedure taking as arguments an integer and context, returning whether the corresponding percent repeat number should be printed when `countPercentRepeats` is set.

`restCompletionBusy` (boolean)

  Signal whether a completion-rest is active.

`restNumberThreshold` (number)

  If a multimeasure rest has more measures than this, a number is printed.

`searchForVoice` (boolean)

  Signal whether a search should be made of all contexts in the context hierarchy for a voice to provide rhythms for the lyrics.

`shapeNoteStyles` (vector)

  Vector of symbols, listing style for each note head relative to the tonic (qv.) of the scale.

`shortInstrumentName` (markup)

  See `instrumentName`.

`shortVocalName` (markup)

  Name of a vocal line, short version.

`skipBars` (boolean)

  If set to true, then skip the empty bars that are produced by multimeasure notes and rests. These bars will not appear on the printed output. If not set (the default), multimeasure notes and rests expand into their full length, printing the appropriate number of empty bars so that synchronization with other voices is preserved.

  >     {
  >       r1 r1*3 R1*3
  >       \set Score.skipBars= ##t
  >       r1*3 R1*3
  >     }

`skipTypesetting` (boolean)

  If true, no typesetting is done, speeding up the interpretation phase. Useful for debugging large scores.

`soloIIText` (markup)

  The text for the start of a solo for voice ‘two’ when part-combining.

`soloText` (markup)

  The text for the start of a solo when part-combining.

`squashedPosition` (integer)

  Vertical position of squashing for Pitch_squash_engraver.

`staffLineLayoutFunction` (procedure)

  Layout of staff lines, `traditional`, or `semitone`.

`stanza` (markup)

  Stanza ‘number’ to print before the start of a verse. Use in `Lyrics` context.

`stemLeftBeamCount` (integer)

  Specify the number of beams to draw on the left side of the next note. Overrides automatic beaming. The value is only used once, and then it is erased.

`stemRightBeamCount` (integer)

  See `stemLeftBeamCount`.

`stringNumberOrientations` (list)

  See `fingeringOrientations`.

`stringOneTopmost` (boolean)

  Whether the first string is printed on the top line of the tablature.

`stringTunings` (list)

  The tablature strings tuning. It is a list of the pitches of each string (starting with the lowest numbered one).

`strokeFingerOrientations` (list)

  See `fingeringOrientations`.

`subdivideBeams` (boolean)

  If set, multiple beams will be subdivided at `baseMoment` positions by only drawing one beam over the beat.

`suggestAccidentals` (boolean)

  If set, accidentals are typeset as cautionary suggestions over the note.

`systemStartDelimiter` (symbol)

  Which grob to make for the start of the system/staff? Set to `SystemStartBrace`, `SystemStartBracket` or `SystemStartBar`.

`systemStartDelimiterHierarchy` (pair)

  A nested list, indicating the nesting of a start delimiters.

`tablatureFormat` (procedure)

  A function formatting a tablature note head. Called with three arguments: context, string number and, fret number. It returns the text as a markup.

`tabStaffLineLayoutFunction` (procedure)

  A function determining the staff position of a tablature note head. Called with two arguments: the context and the string.

`tempoHideNote` (boolean)

  Hide the note = count in tempo marks.

`tempoWholesPerMinute` (moment)

  The tempo in whole notes per minute.

`tieWaitForNote` (boolean)

  If true, tied notes do not have to follow each other directly. This can be used for writing out arpeggios.

`timeSignatureFraction` (pair of numbers)

  A pair of numbers, signifying the time signature. For example, `#'(4 . 4)` is a 4/4 time signature.

`timeSignatureSettings` (list)

  A nested alist of settings for time signatures. Contains elements for various time signatures. The element for each time signature contains entries for `baseMoment`, `beatStructure`, and `beamExceptions`.

`timing` (boolean)

  Keep administration of measure length, position, bar number, etc.? Switch off for cadenzas.

`tonic` (pitch)

  The tonic of the current scale.

`topLevelAlignment` (boolean)

  If true, the Vertical_align_engraver will create a VerticalAlignment; otherwise, it will create a StaffGrouper

`trebleStaffProperties` (list)

  An alist of property settings to apply for the up staff of `PianoStaff`. Used by `\autochange`.

`tremoloFlags` (integer)

  The number of tremolo flags to add if no number is specified.

`tupletFullLength` (boolean)

  If set, the tuplet is printed up to the start of the next note.

`tupletFullLengthNote` (boolean)

  If set, end at the next note, otherwise end on the matter (time signatures, etc.) before the note.

`tupletSpannerDuration` (moment)

  Normally, a tuplet bracket is as wide as the `\times` expression that gave rise to it. By setting this property, you can make brackets last shorter.

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

`useBassFigureExtenders` (boolean)

  Whether to use extender lines for repeated bass figures.

`vocalName` (markup)

  Name of a vocal line.

`voltaSpannerDuration` (moment)

  This specifies the maximum duration to use for the brackets printed for `\alternative`. This can be used to shrink the length of brackets in the situation where one alternative is very large.

`whichBar` (string)

  This property is read to determine what type of bar line to create.

  Example:

  >     \set Staff.whichBar = "|:"

  This will create a start-repeat bar in this staff only. Valid values are described in bar-line-interface.

## A.15 Layout properties

`add-stem-support` (boolean)

  If set, the `Stem` object is included in this script’s support.

`after-line-breaking` (boolean)

  Dummy property, used to trigger callback for `after-line-breaking`.

`align-dir` (direction)

  Which side to align? `-1`: left side, `0`: around center of width, `1`: right side.

`allow-loose-spacing` (boolean)

  If set, column can be detached from main spacing.

`allow-span-bar` (boolean)

  If false, no inter-staff bar line will be created below this bar line.

`alteration` (number)

  Alteration numbers for accidental.

`alteration-alist` (list)

  List of `(pitch . accidental)` pairs for key signature.

`annotation` (string)

  Annotate a grob for debug purposes.

`annotation-balloon` (boolean)

  Print the balloon around an annotation.

`annotation-line` (boolean)

  Print the line from an annotation to the grob that it annotates.

`arpeggio-direction` (direction)

  If set, put an arrow on the arpeggio squiggly line.

`arrow-length` (number)

  Arrow length.

`arrow-width` (number)

  Arrow width.

`auto-knee-gap` (dimension, in staff space)

  If a gap is found between note heads where a horizontal beam fits that is larger than this number, make a kneed beam.

`average-spacing-wishes` (boolean)

  If set, the spacing wishes are averaged over staves.

`avoid-note-head` (boolean)

  If set, the stem of a chord does not pass through all note heads, but starts at the last note head.

`avoid-slur` (symbol)

  Method of handling slur collisions. Choices are `inside`, `outside`, `around`, and `ignore`. `inside` adjusts the slur if needed to keep the grob inside the slur. `outside` moves the grob vertically to the outside of the slur. `around` moves the grob vertically to the outside of the slur only if there is a collision. `ignore` does not move either. In grobs whose notational significance depends on vertical position (such as accidentals, clefs, etc.), `outside` and `around` behave like `ignore`.

`axes` (list)

  List of axis numbers. In the case of alignment grobs, this should contain only one number.

`base-shortest-duration` (moment)

  Spacing is based on the shortest notes in a piece. Normally, pieces are spaced as if notes at least as short as this are present.

`baseline-skip` (dimension, in staff space)

  Distance between base lines of multiple lines of text.

`beam-thickness` (dimension, in staff space)

  Beam thickness, measured in `staff-space` units.

`beam-width` (dimension, in staff space)

  Width of the tremolo sign.

`beamed-stem-shorten` (list)

  How much to shorten beamed stems, when their direction is forced. It is a list, since the value is different depending on the number of flags and beams.

`beaming` (pair)

  Pair of number lists. Each number list specifies which beams to make. `0` is the central beam, `1` is the next beam toward the note, etc. This information is used to determine how to connect the beaming patterns from stem to stem inside a beam.

`beamlet-default-length` (pair)

  A pair of numbers. The first number specifies the default length of a beamlet that sticks out of the left hand side of this stem; the second number specifies the default length of the beamlet to the right. The actual length of a beamlet is determined by taking either the default length or the length specified by `beamlet-max-length-proportion`, whichever is smaller.

`beamlet-max-length-proportion` (pair)

  The maximum length of a beamlet, as a proportion of the distance between two adjacent stems.

`before-line-breaking` (boolean)

  Dummy property, used to trigger a callback function.

`between-cols` (pair)

  Where to attach a loose column to.

`bound-details` (list)

  An alist of properties for determining attachments of spanners to edges.

`bound-padding` (number)

  The amount of padding to insert around spanner bounds.

`bracket-flare` (pair of numbers)

  A pair of numbers specifying how much edges of brackets should slant outward. Value `0.0` means straight edges.

`bracket-visibility` (boolean or symbol)

  This controls the visibility of the tuplet bracket. Setting it to false prevents printing of the bracket. Setting the property to `if-no-beam` makes it print only if there is no beam associated with this tuplet bracket.

`break-align-anchor` (number)

  Grobs aligned to this break-align grob will have their X-offsets shifted by this number. In bar lines, for example, this is used to position grobs relative to the (visual) center of the bar line.

`break-align-anchor-alignment` (number)

  Read by `ly:break-aligned-interface::calc-extent-aligned-anchor` for aligning an anchor to a grob’s extent.

`break-align-orders` (vector)

  Defines the order in which prefatory matter (clefs, key signatures) appears. The format is a vector of length 3, where each element is one order for end-of-line, middle of line, and start-of-line, respectively. An order is a list of symbols.

  For example, clefs are put after key signatures by setting

  >     \override Score.BreakAlignment #'break-align-orders =
  >       #(make-vector 3 '(span-bar
  >                         breathing-sign
  >                         staff-bar
  >                         key
  >                         clef
  >                         time-signature))

`break-align-symbol` (symbol)

  This key is used for aligning and spacing breakable items.

`break-align-symbols` (list)

  A list of symbols that determine which break-aligned grobs to align this to. If the grob selected by the first symbol in the list is invisible due to break-visibility, we will align to the next grob (and so on). Choices are `left-edge`, `ambitus`, `breathing-sign`, `clef`, `staff-bar`, `key-cancellation`, `key-signature`, `time-signature`, and `custos`.

`break-overshoot` (pair of numbers)

  How much does a broken spanner stick out of its bounds?

`break-visibility` (vector)

  A vector of 3 booleans, `#(end-of-line unbroken begin-of-line)`. `#t` means visible, `#f` means killed.

`breakable` (boolean)

  Allow breaks here.

`c0-position` (integer)

  An integer indicating the position of middle C.

`circled-tip` (boolean)

  Put a circle at start/end of hairpins (al/del niente).

`clip-edges` (boolean)

  Allow outward pointing beamlets at the edges of beams?

`collapse-height` (dimension, in staff space)

  Minimum height of system start delimiter. If equal or smaller, the bracket/brace/line is removed.

`collision-interfaces` (list)

  A list of interfaces for which automatic beam-collision resolution is run.

`collision-voice-only` (boolean)

  Does automatic beam collsion apply only to the voice in which the beam was created?

`color` (color)

  The color of this grob.

`common-shortest-duration` (moment)

  The most common shortest note length. This is used in spacing. Enlarging this sets the score tighter.

`concaveness` (number)

  A beam is concave if its inner stems are closer to the beam than the two outside stems. This number is a measure of the closeness of the inner stems. It is used for damping the slope of the beam.

`connect-to-neighbor` (pair)

  Pair of booleans, indicating whether this grob looks as a continued break.

`control-points` (list)

  List of offsets (number pairs) that form control points for the tie, slur, or bracket shape. For Béziers, this should list the control points of a third-order Bézier curve.

`damping` (number)

  Amount of beam slope damping.

`dash-definition` (pair)

  List of `dash-elements` defining the dash structure. Each `dash-element` has a starting t value, an ending t-value, a `dash-fraction`, and a `dash-period`.

`dash-fraction` (number)

  Size of the dashes, relative to `dash-period`. Should be between `0.0` (no line) and `1.0` (continuous line).

`dash-period` (number)

  The length of one dash together with whitespace. If negative, no line is drawn at all.

`default-direction` (direction)

  Direction determined by note head positions.

`default-staff-staff-spacing` (list)

  The settings to use for `staff-staff-spacing` when it is unset, for ungrouped staves and for grouped staves that do not have the relevant `StaffGrouper` property set (`staff-staff-spacing` or `staffgroup-staff-spacing`).

`details` (list)

  Alist of parameters for detailed grob behavior. More information on the allowed parameters for a grob can be found by looking at the top of the Internals Reference page for each interface having a `details` property.

`digit-names` (vector)

  Names for string finger digits.

`direction` (direction)

  If `side-axis` is `0` (or `#X`), then this property determines whether the object is placed `#LEFT`, `#CENTER` or `#RIGHT` with respect to the other object. Otherwise, it determines whether the object is placed `#UP`, `#CENTER` or `#DOWN`. Numerical values may also be used: `#UP`=`1`, `#DOWN`=`-1`, `#LEFT`=`-1`, `#RIGHT`=`1`, `#CENTER`=`0`.

`dot-count` (integer)

  The number of dots.

`dot-negative-kern` (number)

  The space to remove between a dot and a slash in percent repeat glyphs. Larger values bring the two elements closer together.

`dot-placement-list` (list)

  List consisting of `(description string-number fret-number finger-number)` entries used to define fret diagrams.

`duration-log` (integer)

  The 2-log of the note head duration, i.e., `0` = whole note, `1` = half note, etc.

`eccentricity` (number)

  How asymmetrical to make a slur. Positive means move the center to the right.

`edge-height` (pair)

  A pair of numbers specifying the heights of the vertical edges: `(left-height . right-height)`.

`edge-text` (pair)

  A pair specifying the texts to be set at the edges: `(left-text . right-text)`.

`expand-limit` (integer)

  Maximum number of measures expanded in church rests.

`extra-dy` (number)

  Slope glissandi this much extra.

`extra-offset` (pair of numbers)

  A pair representing an offset. This offset is added just before outputting the symbol, so the typesetting engine is completely oblivious to it. The values are measured in `staff-space` units of the staff’s `StaffSymbol`.

`extra-spacing-height` (pair of numbers)

  In the horizontal spacing problem, we increase the height of each item by this amount (by adding the ‘car’ to the bottom of the item and adding the ‘cdr’ to the top of the item). In order to make a grob infinitely high (to prevent the horizontal spacing problem from placing any other grobs above or below this grob), set this to `(-inf.0 . +inf.0)`.

`extra-spacing-width` (pair of numbers)

  In the horizontal spacing problem, we pad each item by this amount (by adding the ‘car’ on the left side of the item and adding the ‘cdr’ on the right side of the item). In order to make a grob take up no horizontal space at all, set this to `(+inf.0 . -inf.0)`.

`extra-X-extent` (pair of numbers)

  A grob is enlarged in X dimension by this much.

`extra-Y-extent` (pair of numbers)

  A grob is enlarged in Y dimension by this much.

`flag` (stencil)

  A function returning the full flag stencil for the `Stem`, which is passed to the function as the only argument. The default ly:stem::calc-stencil function uses the `flag-style` property to determine the correct glyph for the flag. By providing your own function, you can create arbitrary flags.

`flag-count` (number)

  The number of tremolo beams.

`flag-style` (symbol)

  A symbol determining what style of flag glyph is typeset on a `Stem`. Valid options include `'()` for standard flags, `'mensural` and `'no-flag`, which switches off the flag.

`font-encoding` (symbol)

  The font encoding is the broadest category for selecting a font. Currently, only lilypond’s system fonts (Emmentaler) are using this property. Available values are `fetaMusic` (Emmentaler), `fetaBraces`, `fetaText` (Emmentaler).

`font-family` (symbol)

  The font family is the broadest category for selecting text fonts. Options include: `sans`, `roman`.

`font-name` (string)

  Specifies a file name (without extension) of the font to load. This setting overrides selection using `font-family`, `font-series` and `font-shape`.

`font-series` (symbol)

  Select the series of a font. Choices include `medium`, `bold`, `bold-narrow`, etc.

`font-shape` (symbol)

  Select the shape of a font. Choices include `upright`, `italic`, `caps`.

`font-size` (number)

  The font size, compared to the ‘normal’ size. `0` is style-sheet’s normal size, `-1` is smaller, `+1` is bigger. Each step of 1 is approximately 12% larger; 6 steps are exactly a factor 2 larger. Fractional values are allowed.

`footnote-text` (markup)

  A footnote for the grob.

`force-hshift` (number)

  This specifies a manual shift for notes in collisions. The unit is the note head width of the first voice note. This is used by note-collision-interface.

`fraction` (pair of numbers)

  Numerator and denominator of a time signature object.

`french-beaming` (boolean)

  Use French beaming style for this stem. The stem stops at the innermost beams.

`fret-diagram-details` (list)

  An alist of detailed grob properties for fret diagrams. Each alist entry consists of a `(property . value)` pair. The properties which can be included in `fret-diagram-details` include the following:

  - `barre-type` – Type of barre indication used. Choices include `curved`, `straight`, and `none`. Default `curved`.
  - `capo-thickness` – Thickness of capo indicator, in multiples of fret-space. Default value 0.5.
  - `dot-color` – Color of dots. Options include `black` and `white`. Default `black`.
  - `dot-label-font-mag` – Magnification for font used to label fret dots. Default value 1.
  - `dot-position` – Location of dot in fret space. Default 0.6 for dots without labels, 0.95-`dot-radius` for dots with labels.
  - `dot-radius` – Radius of dots, in terms of fret spaces. Default value 0.425 for labeled dots, 0.25 for unlabeled dots.
  - `finger-code` – Code for the type of fingering indication used. Options include `none`, `in-dot`, and `below-string`. Default `none` for markup fret diagrams, `below-string` for `FretBoards` fret diagrams.
  - `fret-count` – The number of frets. Default 4.
  - `fret-label-custom-format` – The format string to be used label the lowest fret number, when `number-type` equals to `custom`. Default "~a".
  - `fret-label-font-mag` – The magnification of the font used to label the lowest fret number. Default 0.5.
  - `fret-label-vertical-offset` – The offset of the fret label from the center of the fret in direction parallel to strings. Default 0.
  - `label-dir` – Side to which the fret label is attached. `-1`, `#LEFT`, or `#DOWN` for left or down; `1`, `#RIGHT`, or `#UP` for right or up. Default `#RIGHT`.
  - `mute-string` – Character string to be used to indicate muted string. Default `"x"`.
  - `number-type` – Type of numbers to use in fret label. Choices include `roman-lower`, `roman-upper`, `arabic` and `custom`. In the later case, the format string is supplied by the `fret-label-custom-format` property. Default `roman-lower`.
  - `open-string` – Character string to be used to indicate open string. Default `"o"`.
  - `orientation` – Orientation of fret-diagram. Options include `normal`, `landscape`, and `opposing-landscape`. Default `normal`.
  - `string-count` – The number of strings. Default 6.
  - `string-label-font-mag` – The magnification of the font used to label fingerings at the string, rather than in the dot. Default value 0.6 for `normal` orientation, 0.5 for `landscape` and `opposing-landscape`.
  - `string-thickness-factor` – Factor for changing thickness of each string in the fret diagram. Thickness of string k is given by `thickness` * (1+`string-thickness-factor`) ^ (k-1). Default 0.
  - `top-fret-thickness` – The thickness of the top fret line, as a multiple of the standard thickness. Default value 3.
  - `xo-font-magnification` – Magnification used for mute and open string indicators. Default value 0.5.
  - `xo-padding` – Padding for open and mute indicators from top fret. Default value 0.25.
`full-length-padding` (number)

  How much padding to use at the right side of a full-length tuplet bracket.

`full-length-to-extent` (boolean)

  Run to the extent of the column for a full-length tuplet bracket.

`full-measure-extra-space` (number)

  Extra space that is allocated at the beginning of a measure with only one note. This property is read from the NonMusicalPaperColumn that begins the measure.

`full-size-change` (boolean)

  Don’t make a change clef smaller.

`gap` (dimension, in staff space)

  Size of a gap in a variable symbol.

`gap-count` (integer)

  Number of gapped beams for tremolo.

`glyph` (string)

  A string determining what ‘style’ of glyph is typeset. Valid choices depend on the function that is reading this property.

`glyph-name` (string)

  The glyph name within the font.

`glyph-name-alist` (list)

  An alist of key-string pairs.

`graphical` (boolean)

  Display in graphical (vs. text) form.

`grow-direction` (direction)

  Crescendo or decrescendo?

`hair-thickness` (number)

  Thickness of the thin line in a bar line.

`harp-pedal-details` (list)

  An alist of detailed grob properties for harp pedal diagrams. Each alist entry consists of a `(property . value)` pair. The properties which can be included in harp-pedal-details include the following:

  - `box-offset` – Vertical shift of the center of flat/sharp pedal boxes above/below the horizontal line. Default value 0.8.
  - `box-width` – Width of each pedal box. Default value 0.4.
  - `box-height` – Height of each pedal box. Default value 1.0.
  - `space-before-divider` – Space between boxes before the first divider (so that the diagram can be made symmetric). Default value 0.8.
  - `space-after-divider` – Space between boxes after the first divider. Default value 0.8.
  - `circle-thickness` – Thickness (in unit of the line-thickness) of the ellipse around circled pedals. Default value 0.5.
  - `circle-x-padding` – Padding in X direction of the ellipse around circled pedals. Default value 0.15.
  - `circle-y-padding` – Padding in Y direction of the ellipse around circled pedals. Default value 0.2.
`head-direction` (direction)

  Are the note heads left or right in a semitie?

`height` (dimension, in staff space)

  Height of an object in `staff-space` units.

`height-limit` (dimension, in staff space)

  Maximum slur height: The longer the slur, the closer it is to this height.

`hide-tied-accidental-after-break` (boolean)

  If set, an accidental that appears on a tied note after a line break will not be displayed.

`horizontal-shift` (integer)

  An integer that identifies ranking of `NoteColumn`s for horizontal shifting. This is used by note-collision-interface.

`horizontal-skylines` (pair of skylines)

  Two skylines, one to the left and one to the right of this grob.

`ignore-collision` (boolean)

  If set, don’t do note collision resolution on this `NoteColumn`.

`implicit` (boolean)

  Is this an implicit bass figure?

`inspect-index` (integer)

  If debugging is set, set beam and slur configuration to this index, and print the respective scores.

`inspect-quants` (pair of numbers)

  If debugging is set, set beam and slur quants to this position, and print the respective scores.

`keep-inside-line` (boolean)

  If set, this column cannot have objects sticking into the margin.

`kern` (dimension, in staff space)

  Amount of extra white space to add. For bar lines, this is the amount of space after a thick line.

`knee` (boolean)

  Is this beam kneed?

`knee-spacing-correction` (number)

  Factor for the optical correction amount for kneed beams. Set between `0` for no correction and `1` for full correction.

`labels` (list)

  List of labels (symbols) placed on a column.

`layer` (integer)

  An integer which determines the order of printing objects. Objects with the lowest value of layer are drawn first, then objects with progressively higher values are drawn, so objects with higher values overwrite objects with lower values. By default most objects are assigned a layer value of 1.

`ledger-line-thickness` (pair of numbers)

  The thickness of ledger lines. It is the sum of 2 numbers: The first is the factor for line thickness, and the second for staff space. Both contributions are added.

`left-bound-info` (list)

  An alist of properties for determining attachments of spanners to edges.

`left-padding` (dimension, in staff space)

  The amount of space that is put left to an object (e.g., a lyric extender).

`length` (dimension, in staff space)

  User override for the stem length of unbeamed stems.

`length-fraction` (number)

  Multiplier for lengths. Used for determining ledger lines and stem lengths.

`line-break-penalty` (number)

  Penalty for a line break at this column. This affects the choices of the line breaker; it avoids a line break at a column with a positive penalty and prefers a line break at a column with a negative penalty.

`line-break-permission` (symbol)

  Instructs the line breaker on whether to put a line break at this column. Can be `force` or `allow`.

`line-break-system-details` (list)

  An alist of properties to use if this column is the start of a system.

`line-count` (integer)

  The number of staff lines.

`line-positions` (list)

  Vertical positions of staff lines.

`line-thickness` (number)

  The thickness of the tie or slur contour.

`long-text` (markup)

  Text markup. See Formatting text.

`max-beam-connect` (integer)

  Maximum number of beams to connect to beams from this stem. Further beams are typeset as beamlets.

`max-stretch` (number)

  The maximum amount that this `VerticalAxisGroup` can be vertically stretched (for example, in order to better fill a page).

`measure-count` (integer)

  The number of measures for a multi-measure rest.

`measure-length` (moment)

  Length of a measure. Used in some spacing situations.

`merge-differently-dotted` (boolean)

  Merge note heads in collisions, even if they have a different number of dots. This is normal notation for some types of polyphonic music.

  `merge-differently-dotted` only applies to opposing stem directions (i.e., voice 1 & 2).

`merge-differently-headed` (boolean)

  Merge note heads in collisions, even if they have different note heads. The smaller of the two heads is rendered invisible. This is used in polyphonic guitar notation. The value of this setting is used by note-collision-interface.

  `merge-differently-headed` only applies to opposing stem directions (i.e., voice 1 & 2).

`minimum-distance` (dimension, in staff space)

  Minimum distance between rest and notes or beam.

`minimum-length` (dimension, in staff space)

  Try to make a spanner at least this long, normally in the horizontal direction. This requires an appropriate callback for the `springs-and-rods` property. If added to a `Tie`, this sets the minimum distance between noteheads.

`minimum-length-fraction` (number)

  Minimum length of ledger line as fraction of note head size.

`minimum-space` (dimension, in staff space)

  Minimum distance that the victim should move (after padding).

`minimum-X-extent` (pair of numbers)

  Minimum size of an object in X dimension, measured in `staff-space` units.

`minimum-Y-extent` (pair of numbers)

  Minimum size of an object in Y dimension, measured in `staff-space` units.

`neutral-direction` (direction)

  Which direction to take in the center of the staff.

`neutral-position` (number)

  Position (in half staff spaces) where to flip the direction of custos stem.

`next` (graphical (layout) object)

  Object that is next relation (e.g., the lyric syllable following an extender).

`no-alignment` (boolean)

  If set, don’t place this grob in a `VerticalAlignment`; rather, place it using its own `Y-offset` callback.

`no-ledgers` (boolean)

  If set, don’t draw ledger lines on this object.

`no-stem-extend` (boolean)

  If set, notes with ledger lines do not get stems extending to the middle staff line.

`non-break-align-symbols` (list)

  A list of symbols that determine which NON-break-aligned interfaces to align this to.

`non-default` (boolean)

  Set for manually specified clefs.

`non-musical` (boolean)

  True if the grob belongs to a `NonMusicalPaperColumn`.

`nonstaff-nonstaff-spacing` (list)

  The spacing alist controlling the distance between the current non-staff line and the next non-staff line in the direction of `staff-affinity`, if both are on the same side of the related staff, and `staff-affinity` is either `UP` or `DOWN`. See `staff-staff-spacing` for a description of the alist structure.

`nonstaff-relatedstaff-spacing` (list)

  The spacing alist controlling the distance between the current non-staff line and the nearest staff in the direction of `staff-affinity`, if there are no non-staff lines between the two, and `staff-affinity` is either `UP` or `DOWN`. If `staff-affinity` is `CENTER`, then `nonstaff-relatedstaff-spacing` is used for the nearest staves on both sides, even if other non-staff lines appear between the current one and either of the staves. See `staff-staff-spacing` for a description of the alist structure.

`nonstaff-unrelatedstaff-spacing` (list)

  The spacing alist controlling the distance between the current non-staff line and the nearest staff in the opposite direction from `staff-affinity`, if there are no other non-staff lines between the two, and `staff-affinity` is either `UP` or `DOWN`. See `staff-staff-spacing` for a description of the alist structure.

`normalized-endpoints` (pair)

  Represents left and right placement over the total spanner, where the width of the spanner is normalized between 0 and 1.

`note-names` (vector)

  Vector of strings containing names for easy-notation note heads.

`outside-staff-horizontal-padding` (number)

  By default, an outside-staff-object can be placed so that is it very close to another grob horizontally. If this property is set, the outside-staff-object is raised so that it is not so close to its neighbor.

`outside-staff-padding` (number)

  The padding to place between this grob and the staff when spacing according to `outside-staff-priority`.

`outside-staff-priority` (number)

  If set, the grob is positioned outside the staff in such a way as to avoid all collisions. In case of a potential collision, the grob with the smaller `outside-staff-priority` is closer to the staff.

`packed-spacing` (boolean)

  If set, the notes are spaced as tightly as possible.

`padding` (dimension, in staff space)

  Add this much extra space between objects that are next to each other.

`padding-pairs` (list)

  An alist mapping `(name . name)` to distances.

`page-break-penalty` (number)

  Penalty for page break at this column. This affects the choices of the page breaker; it avoids a page break at a column with a positive penalty and prefers a page break at a column with a negative penalty.

`page-break-permission` (symbol)

  Instructs the page breaker on whether to put a page break at this column. Can be `force` or `allow`.

`page-turn-penalty` (number)

  Penalty for a page turn at this column. This affects the choices of the page breaker; it avoids a page turn at a column with a positive penalty and prefers a page turn at a column with a negative penalty.

`page-turn-permission` (symbol)

  Instructs the page breaker on whether to put a page turn at this column. Can be `force` or `allow`.

`parenthesized` (boolean)

  Parenthesize this grob.

`positions` (pair of numbers)

  Pair of staff coordinates `(left . right)`, where both left and right are in `staff-space` units of the current staff. For slurs, this value selects which slur candidate to use; if extreme positions are requested, the closest one is taken.

`prefer-dotted-right` (boolean)

  For note collisions, prefer to shift dotted up-note to the right, rather than shifting just the dot.

`ratio` (number)

  Parameter for slur shape. The higher this number, the quicker the slur attains its `height-limit`.

`remove-empty` (boolean)

  If set, remove group if it contains no interesting items.

`remove-first` (boolean)

  Remove the first staff of an orchestral score?

`restore-first` (boolean)

  Print a natural before the accidental.

`rhythmic-location` (rhythmic location)

  Where (bar number, measure position) in the score.

`right-bound-info` (list)

  An alist of properties for determining attachments of spanners to edges.

`right-padding` (dimension, in staff space)

  Space to insert on the right side of an object (e.g., between note and its accidentals).

`rotation` (list)

  Number of degrees to rotate this object, and what point to rotate around. For example, `#'(45 0 0)` rotates by 45 degrees around the center of this object.

`same-direction-correction` (number)

  Optical correction amount for stems that are placed in tight configurations. This amount is used for stems with the same direction to compensate for note head to stem distance.

`script-priority` (number)

  A sorting key that determines in what order a script is within a stack of scripts.

`self-alignment-X` (number)

  Specify alignment of an object. The value `-1` means left aligned, `0` centered, and `1` right-aligned in X direction. Other numerical values may also be specified.

`self-alignment-Y` (number)

  Like `self-alignment-X` but for the Y axis.

`shorten-pair` (pair of numbers)

  The lengths to shorten a text-spanner on both sides, for example a pedal bracket. Positive values shorten the text-spanner, while negative values lengthen it.

`shortest-duration-space` (dimension, in staff space)

  Start with this much space for the shortest duration. This is expressed in `spacing-increment` as unit. See also spacing-spanner-interface.

`shortest-playing-duration` (moment)

  The duration of the shortest note playing here.

`shortest-starter-duration` (moment)

  The duration of the shortest note that starts here.

`side-axis` (number)

  If the value is `#X` (or equivalently `0`), the object is placed horizontally next to the other object. If the value is `#Y` or `1`, it is placed vertically.

`side-relative-direction` (direction)

  Multiply direction of `direction-source` with this to get the direction of this object.

`size` (number)

  Size of object, relative to standard size.

`skyline-horizontal-padding` (number)

  For determining the vertical distance between two staves, it is possible to have a configuration which would result in a tight interleaving of grobs from the top staff and the bottom staff. The larger this parameter is, the farther apart the staves are placed in such a configuration.

`skyline-vertical-padding` (number)

  The amount by which the left and right skylines of a column are padded vertically, beyond the `Y-extent`s and `extra-spacing-height`s of the constituent grobs in the column. Increase this to prevent interleaving of grobs from adjacent columns.

`slash-negative-kern` (number)

  The space to remove between slashes in percent repeat glyphs. Larger values bring the two elements closer together.

`slope` (number)

  The slope of this object.

`slur-padding` (number)

  Extra distance between slur and script.

`space-alist` (list)

  A table that specifies distances between prefatory items, like clef and time-signature. The format is an alist of spacing tuples: `(break-align-symbol type . distance)`, where type can be the symbols `minimum-space` or `extra-space`.

`space-to-barline` (boolean)

  If set, the distance between a note and the following non-musical column will be measured to the bar line instead of to the beginning of the non-musical column. If there is a clef change followed by a bar line, for example, this means that we will try to space the non-musical column as though the clef is not there.

`spacing-increment` (number)

  Add this much space for a doubled duration. Typically, the width of a note head. See also spacing-spanner-interface.

`spacing-pair` (pair)

  A pair of alignment symbols which set an object’s spacing relative to its left and right `BreakAlignment`s.

  For example, a `MultiMeasureRest` will ignore prefatory items at its bounds (i.e., clefs, key signatures and time signatures) using the following override:

  >     \override MultiMeasureRest #'spacing-pair = #'(staff-bar . staff-bar)

`springs-and-rods` (boolean)

  Dummy variable for triggering spacing routines.

`stacking-dir` (direction)

  Stack objects in which direction?

`staff-affinity` (direction)

  The direction of the staff to use for spacing the current non-staff line. Choices are `UP`, `DOWN`, and `CENTER`. If `CENTER`, the non-staff line will be placed equidistant between the two nearest staves on either side, unless collisions or other spacing constraints prevent this. Setting `staff-affinity` for a staff causes it to be treated as a non-staff line. Setting `staff-affinity` to `#f` causes a non-staff line to be treated as a staff.

`staff-padding` (dimension, in staff space)

  Maintain this much space between reference points and the staff. Its effect is to align objects of differing sizes (like the dynamics p and f) on their baselines.

`staff-position` (number)

  Vertical position, measured in half staff spaces, counted from the middle line.

`staff-space` (dimension, in staff space)

  Amount of space between staff lines, expressed in global `staff-space`.

`staff-staff-spacing` (list)

  When applied to a staff-group’s `StaffGrouper` grob, this spacing alist controls the distance between consecutive staves within the staff-group. When applied to a staff’s `VerticalAxisGroup` grob, it controls the distance between the staff and the nearest staff below it in the same system, replacing any settings inherited from the `StaffGrouper` grob of the containing staff-group, if there is one. This property remains in effect even when non-staff lines appear between staves. The alist can contain the following keys:

  - `basic-distance` – the vertical distance, measured in staff-spaces, between the reference points of the two items when no collisions would result, and no stretching or compressing is in effect.
  - `minimum-distance` – the smallest allowable vertical distance, measured in staff-spaces, between the reference points of the two items, when compressing is in effect.
  - `padding` – the minimum required amount of unobstructed vertical whitespace between the bounding boxes (or skylines) of the two items, measured in staff-spaces.
  - `stretchability` – a unitless measure of the dimension’s relative propensity to stretch. If zero, the distance will not stretch (unless collisions would result).
`staffgroup-staff-spacing` (list)

  The spacing alist controlling the distance between the last staff of the current staff-group and the staff just below it in the same system, even if one or more non-staff lines exist between the two staves. If the `staff-staff-spacing` property of the staff’s `VerticalAxisGroup` grob is set, that is used instead. See `staff-staff-spacing` for a description of the alist structure.

`stem-attachment` (pair of numbers)

  An `(x . y)` pair where the stem attaches to the notehead.

`stem-end-position` (number)

  Where does the stem end (the end is opposite to the support-head)?

`stem-spacing-correction` (number)

  Optical correction amount for stems that are placed in tight configurations. For opposite directions, this amount is the correction for two normal sized stems that overlap completely.

`stemlet-length` (number)

  How long should be a stem over a rest?

`stencil` (stencil)

  The symbol to print.

`stencils` (list)

  Multiple stencils, used as intermediate value.

`strict-grace-spacing` (boolean)

  If set, main notes are spaced normally, then grace notes are put left of the musical columns for the main notes.

`strict-note-spacing` (boolean)

  If set, unbroken columns with non-musical material (clefs, bar lines, etc.) are not spaced separately, but put before musical columns.

`stroke-style` (string)

  Set to `"grace"` to turn stroke through flag on.

`style` (symbol)

  This setting determines in what style a grob is typeset. Valid choices depend on the `stencil` callback reading this property.

`text` (markup)

  Text markup. See Formatting text.

`text-direction` (direction)

  This controls the ordering of the words. The default `RIGHT` is for roman text. Arabic or Hebrew should use `LEFT`.

`thick-thickness` (number)

  Bar line thickness, measured in `line-thickness`.

`thickness` (number)

  Line thickness, generally measured in `line-thickness`.

`thin-kern` (number)

  The space after a hair-line in a bar line.

`tie-configuration` (list)

  List of `(position . dir)` pairs, indicating the desired tie configuration, where position is the offset from the center of the staff in staff space and dir indicates the direction of the tie (`1`=>up, `-1`=>down, `0`=>center). A non-pair entry in the list causes the corresponding tie to be formatted automatically.

`to-barline` (boolean)

  If true, the spanner will stop at the bar line just before it would otherwise stop.

`toward-stem-shift` (number)

  Amount by which scripts are shifted toward the stem if their direction coincides with the stem direction. `0.0` means keep the default position (centered on the note head), `1.0` means centered on the stem. Interpolated values are possible.

`transparent` (boolean)

  This makes the grob invisible.

`uniform-stretching` (boolean)

  If set, items stretch proportionally to their durations. This looks better in complex polyphonic patterns.

`used` (boolean)

  If set, this spacing column is kept in the spacing problem.

`vertical-skylines` (pair of skylines)

  Two skylines, one above and one below this grob.

`when` (moment)

  Global time step associated with this column happen?

`whiteout` (boolean)

  If true, the grob is printed over a white background to white-out underlying material, if the grob is visible. Usually #f by default.

`width` (dimension, in staff space)

  The width of a grob measured in staff space.

`word-space` (dimension, in staff space)

  Space to insert between words in texts.

`X-extent` (pair of numbers)

  Hard coded extent in X direction.

`X-offset` (number)

  The horizontal amount that this object is moved relative to its X-parent.

`Y-extent` (pair of numbers)

  Hard coded extent in Y direction.

`Y-offset` (number)

  The vertical amount that this object is moved relative to its Y-parent.

`zigzag-length` (dimension, in staff space)

  The length of the lines of a zigzag, relative to `zigzag-width`. A value of `1` gives 60-degree zigzags.

`zigzag-width` (dimension, in staff space)

  The width of one zigzag squiggle. This number is adjusted slightly so that the glissando line can be constructed from a whole number of squiggles.

## A.16 Available music functions

`acciaccatura` - music (music)

  Create an acciaccatura from the following music expression

`addChordShape` - key-symbol (symbol) tuning (pair) shape-definition (string or pair)

  Add chord shape shape-definition to the chord-shape-table hash with the key (cons key-symbol tuning).

`addInstrumentDefinition` - name (string) lst (list)

  Create instrument name with properties list.

`addQuote` - name (string) music (music)

  Define music as a quotable music expression named name

`afterGrace` - main (music) grace (music)

  Create grace note(s) after a main music expression.

`allowPageTurn`

  Allow a page turn. May be used at toplevel (ie between scores or markups), or inside a score.

`applyContext` - proc (procedure)

  Modify context properties with Scheme procedure proc.

`applyMusic` - func (procedure) music (music)

  Apply procedure func to music.

`applyOutput` - ctx (symbol) proc (procedure)

  Apply function `proc` to every layout object in context `ctx`

`appoggiatura` - music (music)

  Create an appoggiatura from music

`assertBeamQuant` - l (pair) r (pair)

  Testing function: check whether the beam quants l and r are correct

`assertBeamSlope` - comp (procedure)

  Testing function: check whether the slope of the beam is the same as `comp`

`autochange` - music (music)

  Make voices that switch between staves automatically

`balloonGrobText` - grob-name (symbol) offset (pair of numbers) text (markup)

  Attach text to grob-name at offset offset (use like `\once`)

`balloonText` - offset (pair of numbers) text (markup)

  Attach text at offset (use like `\tweak`)

`bar` - type (string)

  Insert a bar line of type type

`barNumberCheck` - n (integer)

  Print a warning if the current bar number is not n.

`bendAfter` - delta (real number)

  Create a fall or doit of pitch interval delta.

`bookOutputName` - newfilename (string)

  Direct output for the current book block to newfilename.

`bookOutputSuffix` - newsuffix (string)

  Set the output filename suffix for the current book block to newsuffix.

`breathe`

  Insert a breath mark.

`chordGlissando` - mus1 (music) mus2 (music)

  Make a glissando between the notes of triads `mus1` and `mus2`.

`clef` - type (string)

  Set the current clef to type.

`compoundMeter` - args (pair)

  Create compound time signatures. The argument is a Scheme list of lists. Each list describes one fraction, with the last entry being the denominator, while the first entries describe the summands in the enumerator. If the time signature consists of just one fraction, the list can be given directly, i.e. not as a list containing a single list. For example, a time signature of (3+1)/8 + 2/4 would be created as `\compoundMeter #'((3 1 8) (2 4))`, and a time signature of (3+2)/8 as `\compoundMeter #'((3 2 8))` or shorter `\compoundMeter #'(3 2 8)`.

`contextStringTuning` - tuning (symbol) chord (music)

  (undocumented; fixme)

`cueClef` - type (string)

  Set the current cue clef to type.

`cueClefUnset`

  Unset the current cue clef.

`cueDuring` - what (string) dir (direction) main-music (music)

  Insert contents of quote what corresponding to main-music, in a CueVoice oriented by dir.

`cueDuringWithClef` - what (string) dir (direction) clef (string) main-music (music)

  Insert contents of quote what corresponding to main-music, in a CueVoice oriented by dir.

`deadNote` - note (music)

  Print note with a cross-shaped note head.

`defaultNoteHeads`

  Revert to the default note head style.

`displayLilyMusic` - music (music)

  Display the LilyPond input representation of music to the console.

`displayMusic` - music (music)

  Display the internal representation of music to the console.

`endSpanners` - music (music)

  Terminate the next spanner prematurely after exactly one note without the need of a specific end spanner.

`featherDurations` - factor (moment) argument (music)

  Adjust durations of music in argument by rational factor.

`footnote` - offset (pair of numbers) text (markup) footnote (markup)

  Attach text at offset with text referring to footnote (use like `\tweak`)

`footnoteGrob` - grob-name (symbol) offset (pair of numbers) text (markup) footnote (markup)

  Attach text to grob-name at offset offset, with text referring to footnote (use like `\once`)

`grace` - music (music)

  Insert music as grace notes.

`harmonicByFret` - fret (number) music (music)

  (undocumented; fixme)

`harmonicByRatio` - ratio (number) music (music)

  (undocumented; fixme)

`harmonicNote` - note (music)

  Print note with a diamond-shaped note head.

`harmonicsOn`

  Set the default note head style to a diamond-shaped style.

`instrumentSwitch` - name (string)

  Switch instrument to name, which must be predefined with `\addInstrumentDefinition`.

`inversion` - around (music) to (music) music (music)

  Invert music about around and transpose from around to to.

`keepWithTag` - tag (symbol) music (music)

  Include only elements of music that are tagged with tag.

`killCues` - music (music)

  Remove cue notes from music.

`label` - label (symbol)

  Create label as a bookmarking label.

`language` - language (string)

  Set note names for language language.

`languageRestore`

  Restore a previously-saved pitchnames alist.

`languageSaveAndChange` - language (string)

  Store the previous pitchnames alist, and set a new one.

`makeClusters` - arg (music)

  Display chords in arg as clusters.

`makeDefaultStringTunings` - default-tuning-alist (list)

  (undocumented; fixme)

`makeStringTuning` - tuning (symbol) chord (music)

  (undocumented; fixme)

`modalInversion` - around (music) to (music) scale (music) music (music)

  Invert music about around using scale and transpose from around to to.

`modalTranspose` - from (music) to (music) scale (music) music (music)

  Transpose music from pitch from to pitch to using scale.

`musicMap` - proc (procedure) mus (music)

  Apply proc to mus and all of the music it contains.

`noPageBreak`

  Forbid a page break. May be used at toplevel (i.e., between scores or markups), or inside a score.

`noPageTurn`

  Forbid a page turn. May be used at toplevel (i.e., between scores or markups), or inside a score.

`octaveCheck` - pitch-note (music)

  Octave check.

`ottava` - octave (integer)

  Set the octavation.

`overrideProperty` - name (string) property (symbol) value (any type)

  Set property to value in all grobs named name. The name argument is a string of the form `"Context.GrobName"` or `"GrobName"`.

`overrideTimeSignatureSettings` - time-signature (pair) base-moment (pair) beat-structure (list) beam-exceptions (list)

  Override `timeSignatureSettings` for time signatures of time-signature to have settings of base-moment, beat-structure, and beam-exceptions.

`pageBreak`

  Force a page break. May be used at toplevel (i.e., between scores or markups), or inside a score.

`pageTurn`

  Force a page turn between two scores or top-level markups.

`palmMute` - note (music)

  Print note with a triangle-shaped note head.

`palmMuteOn`

  Set the default note head style to a triangle-shaped style.

`parallelMusic` - voice-ids (list) music (music)

  Define parallel music sequences, separated by ’|’ (bar check signs), and assign them to the identifiers provided in voice-ids.

  voice-ids: a list of music identifiers (symbols containing only letters)

  music: a music sequence, containing BarChecks as limiting expressions.

  Example:

        \parallelMusic #'(A B C) {
          c c | d d | e e |
          d d | e e | f f |
        }
      <==>
        A = { c c | d d | }
        B = { d d | e e | }
        C = { e e | f f | }

`parenthesize` - arg (music)

  Tag arg to be parenthesized.

`partcombine` - part1 (music) part2 (music)

  Take the music in part1 and part2 and typeset so that they share a staff.

`partcombineForce` - type (symbol-or-boolean) once (boolean)

  Override the part-combiner.

`phrasingSlurDashPattern` - dash-fraction (number) dash-period (number)

  Set up a custom style of dash pattern for dash-fraction ratio of line to space repeated at dash-period interval.

`pitchedTrill` - main-note (music) secondary-note (music)

  Print a trill with main-note as the main note of the trill and print secondary-note as a stemless note head in parentheses.

`pointAndClickOff`

  Suppress generating extra code in final-format (e.g. pdf) files to point back to the lilypond source statement.

`pointAndClickOn`

  Enable generation of code in final-format (e.g. pdf) files to reference the originating lilypond source statement; this is helpful when developing a score but generates bigger final-format files.

`quoteDuring` - what (string) main-music (music)

  Indicate a section of music to be quoted. what indicates the name of the quoted voice, as specified in an `\addQuote` command. main-music is used to indicate the length of music to be quoted; usually contains spacers or multi-measure rests.

`removeWithTag` - tag (symbol) music (music)

  Remove elements of music that are tagged with tag.

`resetRelativeOctave` - reference-note (music)

  Set the octave inside a \relative section.

`retrograde` - music (music)

  Return music in reverse order.

`revertTimeSignatureSettings` - time-signature (pair)

  Revert `timeSignatureSettings` for time signatures of time-signature.

`rightHandFinger` - finger (number or string)

  Apply finger as a fingering indication.

`scaleDurations` - fraction (pair of numbers) music (music)

  Multiply the duration of events in music by fraction.

`shiftDurations` - dur (integer) dots (integer) arg (music)

  Scale arg up by a factor of 2^dur*(2-(1/2)^dots).

`slurDashPattern` - dash-fraction (number) dash-period (number)

  (undocumented; fixme)

`spacingTweaks` - parameters (list)

  Set the system stretch, by reading the ’system-stretch property of the ‘parameters’ assoc list.

`storePredefinedDiagram` - fretboard-table (hash table) chord (music) tuning (pair) diagram-definition (string or pair)

  Add predefined fret diagram defined by diagram-definition for the chord pitches chord and the stringTuning tuning.

`styledNoteHeads` - style (symbol) heads (list or symbol) music (music)

  Set heads in music to style.

`tabChordRepetition`

  Include the string information in a chord repetition.

`tag` - tag (symbol) arg (music)

  Add tag to the `tags` property of arg.

`tieDashPattern` - dash-fraction (number) dash-period (number)

  (undocumented; fixme)

`tocItem` - text (markup)

  Add a line to the table of content, using the `tocItemMarkup` paper variable markup

`transposedCueDuring` - what (string) dir (direction) pitch-note (music) main-music (music)

  Insert notes from the part what into a voice called `cue`, using the transposition defined by pitch-note. This happens simultaneously with main-music, which is usually a rest. The argument dir determines whether the cue notes should be notated as a first or second voice.

`transposition` - pitch-note (music)

  Set instrument transposition

`tweak` - sym (symbol) val (any type) arg (music)

  Add `sym . val` to the `tweaks` property of arg.

`unfoldRepeats` - music (music)

  Force any `\repeat volta`, `\repeat tremolo` or `\repeat percent` commands in music to be interpreted as `\repeat unfold`.

`withMusicProperty` - sym (symbol) val (any type) music (music)

  Set sym to val in music.

`xNote` - note (music)

  Print note with a cross-shaped note head.

`xNotesOn`

  Set the default note head style to a cross-shaped style.

## A.17 Predefined type predicates

### R5RS primary predicates

Type predicate | Description
--- | ---
`boolean?` | boolean
`char?` | character
`number?` | number
`pair?` | pair
`port?` | port
`procedure?` | procedure
`string?` | string
`symbol?` | symbol
`vector?` | vector

### R5RS secondary predicates

Type predicate | Description
--- | ---
`char-alphabetic?` | alphabetic character
`char-lower-case?` | lower-case character
`char-numeric?` | numeric character
`char-upper-case?` | upper-case character
`char-whitespace?` | whitespace character
`complex?` | complex number
`eof-object?` | end-of-file object
`even?` | even number
`exact?` | exact number
`inexact?` | inexact number
`input-port?` | input port
`integer?` | integer
`list?` | list (use `cheap-list?` for faster processing)
`negative?` | negative number
`null?` | null
`odd?` | odd number
`output-port?` | output port
`positive?` | positive number
`rational?` | rational number
`real?` | real number
`zero?` | zero

### Guile predicates

Type predicate | Description
--- | ---
`hash-table?` | hash table

### LilyPond scheme predicates

Type predicate | Description
--- | ---
`boolean-or-symbol?` | boolean or symbol
`cheap-list?` | list (use this instead of `list?` for faster processing)
`color?` | color
`grob-list?` | list of grobs
`list-or-symbol?` | list or symbol
`markup?` | markup
`markup-command-list?` | markup command list
`markup-list?` | markup list
`moment-pair?` | pair of moment objects
`number-or-grob?` | number or grob
`number-or-pair?` | number or pair
`number-or-string?` | number or string
`number-pair?` | pair of numbers
`rhythmic-location?` | rhythmic location
`scheme?` | any type
`string-or-pair?` | string or pair
`string-or-symbol?` | string or symbol

### LilyPond exported predicates

Type predicate | Description
--- | ---
`ly:box?` | box
`ly:context?` | context
`ly:dimension?` | dimension, in staff space
`ly:dir?` | direction
`ly:dispatcher?` | dispatcher
`ly:duration?` | duration
`ly:font-metric?` | font metric
`ly:grob?` | graphical (layout) object
`ly:grob-array?` | array of grobs
`ly:input-location?` | input location
`ly:item?` | item
`ly:iterator?` | iterator
`ly:lily-lexer?` | lily-lexer
`ly:lily-parser?` | lily-parser
`ly:listener?` | listener
`ly:moment?` | moment
`ly:music?` | music
`ly:music-function?` | music function
`ly:music-list?` | list of music objects
`ly:music-output?` | music output
`ly:otf-font?` | OpenType font
`ly:output-def?` | output definition
`ly:page-marker?` | page marker
`ly:pango-font?` | pango font
`ly:paper-book?` | paper book
`ly:paper-system?` | paper-system Prob
`ly:pitch?` | pitch
`ly:prob?` | property object
`ly:score?` | score
`ly:simple-closure?` | simple closure
`ly:skyline?` | skyline
`ly:skyline-pair?` | pair of skylines
`ly:source-file?` | source file
`ly:spanner?` | spanner
`ly:stencil?` | stencil
`ly:stream-event?` | stream event
`ly:translator?` | translator
`ly:translator-group?` | translator group

## A.18 Scheme functions

Function: ly:add-context-mod contextmods modification

  Adds the given context modification to the list contextmods of context modifications.

Function: ly:add-file-name-alist alist

  Add mappings for error messages from alist.

Function: ly:add-interface iface desc props

  Add a new grob interface. iface is the interface name, desc is the interface description, and props is the list of user-settable properties for the interface.

Function: ly:add-listener list disp cl

  Add the listener list to the dispatcher disp. Whenever disp hears an event of class cl, it is forwarded to list.

Function: ly:add-option sym val description

  Add a program option sym. val is the default value and description is a string description.

Function: ly:all-grob-interfaces

  Return the hash table with all grob interface descriptions.

Function: ly:all-options

  Get all option settings in an alist.

Function: ly:all-stencil-expressions

  Return all symbols recognized as stencil expressions.

Function: ly:assoc-get key alist default-value strict-checking

  Return value if key in alist, else default-value (or `#f` if not specified). If strict-checking is set to `#t` and key is not in alist, a programming_error is output.

Function: ly:axis-group-interface::add-element grob grob-element

  Set grob the parent of grob-element on all axes of grob.

Function: ly:beam-score-count

  count number of beam scores.

Function: ly:book-add-bookpart! book-smob book-part

  Add book-part to book-smob book part list.

Function: ly:book-add-score! book-smob score

  Add score to book-smob score list.

Function: ly:book-book-parts book

  Return book parts in book.

Function: ly:book-header book

  Return header in book.

Function: ly:book-paper book

  Return paper in book.

Function: ly:book-process book-smob default-paper default-layout output

  Print book. output is passed to the backend unchanged. For example, it may be a string (for file based outputs) or a socket (for network based output).

Function: ly:book-process-to-systems book-smob default-paper default-layout output

  Print book. output is passed to the backend unchanged. For example, it may be a string (for file based outputs) or a socket (for network based output).

Function: ly:book-scores book

  Return scores in book.

Function: ly:box? x

  Is x a `Box` object?

Function: ly:bp num

  num bigpoints (1/72th inch).

Function: ly:bracket a iv t p

  Make a bracket in direction a. The extent of the bracket is given by iv. The wings protrude by an amount of p, which may be negative. The thickness is given by t.

Function: ly:broadcast disp ev

  Send the stream event ev to the dispatcher disp.

Function: ly:camel-case->lisp-identifier name-sym

  Convert `FooBar_Bla` to `foo-bar-bla` style symbol.

Function: ly:chain-assoc-get key achain default-value strict-checking

  Return value for key from a list of alists achain. If no entry is found, return default-value or `#f` if default-value is not specified. With strict-checking set to `#t`, a programming_error is output in such cases.

Function: ly:cm num

  num cm.

Function: ly:command-line-code

  The Scheme code specified on command-line with ‘`-e`’.

Function: ly:command-line-options

  The Scheme options specified on command-line with ‘`-d`’.

Function: ly:command-line-verbose?

  Was `be_verbose_global` set?

Function: ly:connect-dispatchers to from

  Make the dispatcher to listen to events from from.

Function: ly:context? x

  Is x a `Context` object?

Function: ly:context-current-moment context

  Return the current moment of context.

Function: ly:context-event-source context

  Return `event-source` of context context.

Function: ly:context-events-below context

  Return a `stream-distributor` that distributes all events from context and all its subcontexts.

Function: ly:context-find context name

  Find a parent of context that has name or alias name. Return `#f` if not found.

Function: ly:context-grob-definition context name

  Return the definition of name (a symbol) within context as an alist.

Function: ly:context-id context

  Return the ID string of context, i.e., for `\context Voice = "one" …` return the string `one`.

Function: ly:context-name context

  Return the name of context, i.e., for `\context Voice = "one" …` return the symbol `Voice`.

Function: ly:context-now context

  Return `now-moment` of context context.

Function: ly:context-parent context

  Return the parent of context, `#f` if none.

Function: ly:context-property context sym def

  Return the value for property sym in context. If def is given, and property value is `'()`, return def.

Function: ly:context-property-where-defined context name

  Return the context above context where name is defined.

Function: ly:context-pushpop-property context grob eltprop val

  Do a single `\override` or `\revert` operation in context. The grob definition grob is extended with eltprop (if val is specified) or reverted (if unspecified).

Function: ly:context-set-property! context name val

  Set value of property name in context context to val.

Function: ly:context-unset-property context name

  Unset value of property name in context context.

Function: ly:default-scale

  Get the global default scale.

Function: ly:dimension? d

  Return d as a number. Used to distinguish length variables from normal numbers.

Function: ly:dir? s

  Is s a direction? Valid directions are `-1`, `0`, or `1`, where `-1` represents left or down, `1` represents right or up, and `0` represents a neutral direction.

Function: ly:dispatcher? x

  Is x a `Dispatcher` object?

Function: ly:duration? x

  Is x a `Duration` object?

Function: ly:duration<? p1 p2

  Is p1 shorter than p2?

Function: ly:duration->string dur

  Convert dur to a string.

Function: ly:duration-dot-count dur

  Extract the dot count from dur.

Function: ly:duration-factor dur

  Extract the compression factor from dur. Return it as a pair.

Function: ly:duration-length dur

  The length of the duration as a `moment`.

Function: ly:duration-log dur

  Extract the duration log from dur.

Function: ly:effective-prefix

  Return effective prefix.

Function: ly:encode-string-for-pdf str

  Encode the given string to either Latin1 (which is a subset of the PDFDocEncoding) or if that’s not possible to full UTF-16BE with Byte-Order-Mark (BOM).

Function: ly:engraver-announce-end-grob engraver grob cause

  Announce the end of a grob (i.e., the end of a spanner) originating from given engraver instance, with grob being a grob. cause should either be another grob or a music event.

Function: ly:engraver-make-grob engraver grob-name cause

  Create a grob originating from given engraver instance, with given grob-name, a symbol. cause should either be another grob or a music event.

Function: ly:error str rest

  A Scheme callable function to issue the error str. The error is formatted with `format` and rest.

Function: ly:eval-simple-closure delayed closure scm-start scm-end

  Evaluate a simple closure with the given delayed argument. If scm-start and scm-end are defined, evaluate it purely with those start and end points.

Function: ly:event-deep-copy m

  Copy m and all sub expressions of m.

Function: ly:event-property sev sym

  Get the property sym of stream event mus. If sym is undefined, return `'()`.

Function: ly:event-set-property! ev sym val

  Set property sym in event ev to val.

Function: ly:expand-environment str

  Expand `$VAR` and `${VAR}` in str.

Function: ly:export arg

  Export a Scheme object to the parser so it is treated as an identifier.

Function: ly:find-file name

  Return the absolute file name of name, or `#f` if not found.

Function: ly:font-config-add-directory dir

  Add directory dir to FontConfig.

Function: ly:font-config-add-font font

  Add font font to FontConfig.

Function: ly:font-config-display-fonts

  Dump a list of all fonts visible to FontConfig.

Function: ly:font-config-get-font-file name

  Get the file for font name.

Function: ly:font-design-size font

  Given the font metric font, return the design size, relative to the current output-scale.

Function: ly:font-file-name font

  Given the font metric font, return the corresponding file name.

Function: ly:font-get-glyph font name

  Return a stencil from font for the glyph named name. If the glyph is not available, return an empty stencil.

  Note that this command can only be used to access glyphs from fonts loaded with `ly:system-font-load`; currently, this means either the Emmentaler or Emmentaler-Brace fonts, corresponding to the font encodings `fetaMusic` and `fetaBraces`, respectively.

Function: ly:font-glyph-name-to-charcode font name

  Return the character code for glyph name in font.

  Note that this command can only be used to access glyphs from fonts loaded with `ly:system-font-load`; currently, this means either the Emmentaler or Emmentaler-Brace fonts, corresponding to the font encodings `fetaMusic` and `fetaBraces`, respectively.

Function: ly:font-glyph-name-to-index font name

  Return the index for name in font.

  Note that this command can only be used to access glyphs from fonts loaded with `ly:system-font-load`; currently, this means either the Emmentaler or Emmentaler-Brace fonts, corresponding to the font encodings `fetaMusic` and `fetaBraces`, respectively.

Function: ly:font-index-to-charcode font index

  Return the character code for index in font.

  Note that this command can only be used to access glyphs from fonts loaded with `ly:system-font-load`; currently, this means either the Emmentaler or Emmentaler-Brace fonts, corresponding to the font encodings `fetaMusic` and `fetaBraces`, respectively.

Function: ly:font-magnification font

  Given the font metric font, return the magnification, relative to the current output-scale.

Function: ly:font-metric? x

  Is x a `Font_metric` object?

Function: ly:font-name font

  Given the font metric font, return the corresponding name.

Function: ly:font-sub-fonts font

  Given the font metric font of an OpenType font, return the names of the subfonts within font.

Function: ly:format str rest

  LilyPond specific format, supporting `~a` and `~[0-9]f`. Basic support for `~s` is also provided.

Function: ly:format-output context

  Given a global context in its final state, process it and return the `Music_output` object in its final state.

Function: ly:get-all-function-documentation

  Get a hash table with all LilyPond Scheme extension functions.

Function: ly:get-all-translators

  Return a list of all translator objects that may be instantiated.

Function: ly:get-context-mods contextmod

  Returns the list of context modifications stored in contextmod.

Function: ly:get-listened-event-classes

  Return a list of all event classes that some translator listens to.

Function: ly:get-option var

  Get a global option setting.

Function: ly:gettext original

  A Scheme wrapper function for `gettext`.

Function: ly:grob? x

  Is x a `Grob` object?

Function: ly:grob-alist-chain grob global

  Get an alist chain for grob grob, with global as the global default. If unspecified, `font-defaults` from the layout block is taken.

Function: ly:grob-array? x

  Is x a `Grob_array` object?

Function: ly:grob-array->list grob-arr

  Return the elements of grob-arr as a Scheme list.

Function: ly:grob-array-length grob-arr

  Return the length of grob-arr.

Function: ly:grob-array-ref grob-arr index

  Retrieve the indexth element of grob-arr.

Function: ly:grob-basic-properties grob

  Get the immutable properties of grob.

Function: ly:grob-chain-callback grob proc sym

  Find the callback that is stored as property sym of grob grob and chain proc to the head of this, meaning that it is called using grob and the previous callback’s result.

Function: ly:grob-common-refpoint grob other axis

  Find the common refpoint of grob and other for axis.

Function: ly:grob-common-refpoint-of-array grob others axis

  Find the common refpoint of grob and others (a grob-array) for axis.

Function: ly:grob-default-font grob

  Return the default font for grob grob.

Function: ly:grob-extent grob refp axis

  Get the extent in axis direction of grob relative to the grob refp.

Function: ly:grob-interfaces grob

  Return the interfaces list of grob grob.

Function: ly:grob-layout grob

  Get `\layout` definition from grob grob.

Function: ly:grob-object grob sym

  Return the value of a pointer in grob grob of property sym. It returns `'()` (end-of-list) if sym is undefined in grob.

Function: ly:grob-original grob

  Return the unbroken original grob of grob.

Function: ly:grob-parent grob axis

  Get the parent of grob. axis is 0 for the X-axis, 1 for the Y-axis.

Function: ly:grob-pq<? a b

  Compare two grob priority queue entries. This is an internal function.

Function: ly:grob-properties grob

  Get the mutable properties of grob.

Function: ly:grob-property grob sym val

  Return the value for property sym of grob. If no value is found, return val or `'()` if val is not specified.

Function: ly:grob-property-data grob sym

  Return the value for property sym of grob, but do not process callbacks.

Function: ly:grob-relative-coordinate grob refp axis

  Get the coordinate in axis direction of grob relative to the grob refp.

Function: ly:grob-robust-relative-extent grob refp axis

  Get the extent in axis direction of grob relative to the grob refp, or `(0,0)` if empty.

Function: ly:grob-script-priority-less a b

  Compare two grobs by script priority. For internal use.

Function: ly:grob-set-nested-property! grob symlist val

  Set nested property symlist in grob grob to value val.

Function: ly:grob-set-object! grob sym val

  Set sym in grob grob to value val.

Function: ly:grob-set-parent! grob axis parent-grob

  Set parent-grob the parent of grob grob in axis axis.

Function: ly:grob-set-property! grob sym val

  Set sym in grob grob to value val.

Function: ly:grob-staff-position sg

  Return the Y-position of sg relative to the staff.

Function: ly:grob-suicide! grob

  Kill grob.

Function: ly:grob-system grob

  Return the system grob of grob.

Function: ly:grob-translate-axis! grob d a

  Translate grob on axis a over distance d.

Function: ly:gulp-file name size

  Read size characters from the file name, and return its contents in a string. If size is undefined, the entire file is read. The file is looked up using the search path.

Function: ly:hash-table-keys tab

  Return a list of keys in tab.

Function: ly:inch num

  num inches.

Function: ly:input-both-locations sip

  Return input location in sip as `(file-name first-line first-column last-line last-column)`.

Function: ly:input-file-line-char-column sip

  Return input location in sip as `(file-name line char column)`.

Function: ly:input-location? x

  Is x an `input-location`?

Function: ly:input-message sip msg rest

  Print msg as a GNU compliant error message, pointing to the location in sip. msg is interpreted similar to `format`’s argument, using rest.

Function: ly:interpret-music-expression mus ctx

  Interpret the music expression mus in the global context ctx. The context is returned in its final state.

Function: ly:interpret-stencil-expression expr func arg1 offset

  Parse expr, feed bits to func with first arg arg1 having offset offset.

Function: ly:intlog2 d

  The 2-logarithm of 1/d.

Function: ly:is-listened-event-class sym

  Is sym a listened event class?

Function: ly:item? g

  Is g an `Item` object?

Function: ly:item-break-dir it

  The break status direction of item it. `-1` means end of line, `0` unbroken, and `1` beginning of line.

Function: ly:iterator? x

  Is x a `Music_iterator` object?

Function: ly:lexer-keywords lexer

  Return a list of `(KEY . CODE)` pairs, signifying the LilyPond reserved words list.

Function: ly:lily-lexer? x

  Is x a `Lily_lexer` object?

Function: ly:lily-parser? x

  Is x a `Lily_parser` object?

Function: ly:listener? x

  Is x a `Listener` object?

Function: ly:make-book paper header scores

  Make a `\book` of paper and header (which may be `#f` as well) containing `\scores`.

Function: ly:make-book-part scores

  Make a `\bookpart` containing `\scores`.

Function: ly:make-dispatcher

  Return a newly created dispatcher.

Function: ly:make-duration length dotcount num den

  length is the negative logarithm (base 2) of the duration: 1 is a half note, 2 is a quarter note, 3 is an eighth note, etc. The number of dots after the note is given by the optional argument dotcount.

  The duration factor is optionally given by num and den.

  A duration is a musical duration, i.e., a length of time described by a power of two (whole, half, quarter, etc.) and a number of augmentation dots.

Function: ly:make-global-context output-def

  Set up a global interpretation context, using the output block output-def. The context is returned.

Function: ly:make-global-translator global

  Create a translator group and connect it to the global context global. The translator group is returned.

Function: ly:make-listener callback

  Create a listener. Any time the listener hears an object, it will call callback with that object.

  callback should take exactly one argument.

Function: ly:make-moment n d gn gd

  Create the rational number with main timing n/d, and optional grace timing gn/gd.

  A moment is a point in musical time. It consists of a pair of rationals (m, g), where m is the timing for the main notes, and g the timing for grace notes. In absence of grace notes, g is zero.

Function: ly:make-music props

  Make a C++ `Music` object and initialize it with props.

  This function is for internal use and is only called by `make-music`, which is the preferred interface for creating music objects.

Function: ly:make-music-function signature func

  Make a function to process music, to be used for the parser. func is the function, and signature describes its arguments. signature is a list containing either `ly:music?` predicates or other type predicates.

Function: ly:make-output-def

  Make an output definition.

Function: ly:make-page-label-marker label

  Return page marker with label label.

Function: ly:make-page-permission-marker symbol permission

  Return page marker with page breaking and turning permissions.

Function: ly:make-pango-description-string chain size

  Make a `PangoFontDescription` string for the property alist chain at size size.

Function: ly:make-paper-outputter port format

  Create an outputter that evaluates within `output-`format, writing to port.

Function: ly:make-pitch octave note alter

  octave is specified by an integer, zero for the octave containing middle C. note is a number indexing the global default scale, with 0 corresponding to pitch C and 6 usually corresponding to pitch B. alter is a rational number of 200-cent whole tones for alteration.

Function: ly:make-prob type init rest

  Create a `Prob` object.

Function: ly:make-scale steps

  Create a scale. The argument is a vector of rational numbers, each of which represents the number of 200 cent tones of a pitch above the tonic.

Function: ly:make-score music

  Return score with music encapsulated in it.

Function: ly:make-simple-closure expr

  Make a simple closure. expr should be form of `(func a1 a2 …)`, and will be invoked as `(func delayed-arg a1 a2 …)`.

Function: ly:make-stencil expr xext yext

  Stencils are device independent output expressions. They carry two pieces of information:

  1. A specification of how to print this object. This specification is processed by the output backends, for example ‘`scm/output-ps.scm`’.
  2. The vertical and horizontal extents of the object, given as pairs. If an extent is unspecified (or if you use `(1000 . -1000)` as its value), it is taken to be empty.

Function: ly:make-stream-event cl proplist

  Create a stream event of class cl with the given mutable property list.

Function: ly:message str rest

  A Scheme callable function to issue the message str. The message is formatted with `format` and rest.

Function: ly:minimal-breaking pb

  Break (pages and lines) the `Paper_book` object pb without looking for optimal spacing: stack as many lines on a page before moving to the next one.

Function: ly:mm num

  num mm.

Function: ly:module->alist mod

  Dump the contents of module mod as an alist.

Function: ly:module-copy dest src

  Copy all bindings from module src into dest.

Function: ly:modules-lookup modules sym def

  Look up sym in the list modules, returning the first occurence. If not found, return def or `#f` if def isn’t specified.

Function: ly:moment? x

  Is x a `Moment` object?

Function: ly:moment<? a b

  Compare two moments.

Function: ly:moment-add a b

  Add two moments.

Function: ly:moment-div a b

  Divide two moments.

Function: ly:moment-grace-denominator mom

  Extract denominator from grace timing.

Function: ly:moment-grace-numerator mom

  Extract numerator from grace timing.

Function: ly:moment-main-denominator mom

  Extract denominator from main timing.

Function: ly:moment-main-numerator mom

  Extract numerator from main timing.

Function: ly:moment-mod a b

  Modulo of two moments.

Function: ly:moment-mul a b

  Multiply two moments.

Function: ly:moment-sub a b

  Subtract two moments.

Function: ly:music? obj

  Is obj a music object?

Function: ly:music-compress m factor

  Compress music object m by moment factor.

Function: ly:music-deep-copy m

  Copy m and all sub expressions of m.

Function: ly:music-duration-compress mus fact

  Compress mus by factor fact, which is a `Moment`.

Function: ly:music-duration-length mus

  Extract the duration field from mus and return the length.

Function: ly:music-function? x

  Is x a `music-function`?

Function: ly:music-function-extract x

  Return the Scheme function inside x.

Function: ly:music-length mus

  Get the length of music expression mus and return it as a `Moment` object.

Function: ly:music-list? lst

  Is lst a list of music objects?

Function: ly:music-mutable-properties mus

  Return an alist containing the mutable properties of mus. The immutable properties are not available, since they are constant and initialized by the `make-music` function.

Function: ly:music-output? x

  Is x a `Music_output` object?

Function: ly:music-property mus sym val

  Return the value for property sym of music expression mus. If no value is found, return val or `'()` if val is not specified.

Function: ly:music-set-property! mus sym val

  Set property sym in music expression mus to val.

Function: ly:music-transpose m p

  Transpose m such that central C is mapped to p. Return m.

Function: ly:note-column-accidentals note-column

  Return the `AccidentalPlacement` grob from note-column if any, or `SCM_EOL` otherwise.

Function: ly:note-column-dot-column note-column

  Return the `DotColumn` grob from note-column if any, or `SCM_EOL` otherwise.

Function: ly:note-head::stem-attachment font-metric glyph-name

  Get attachment in font-metric for attaching a stem to notehead glyph-name.

Function: ly:number->string s

  Convert s to a string without generating many decimals.

Function: ly:optimal-breaking pb

  Optimally break (pages and lines) the `Paper_book` object pb to minimize badness in bother vertical and horizontal spacing.

Function: ly:option-usage

  Print `ly:set-option` usage.

Function: ly:otf->cff otf-file-name

  Convert the contents of an OTF file to a CFF file, returning it as a string.

Function: ly:otf-font? font

  Is font an OpenType font?

Function: ly:otf-font-glyph-info font glyph

  Given the font metric font of an OpenType font, return the information about named glyph glyph (a string).

Function: ly:otf-font-table-data font tag

  Extract a table tag from font. Return empty string for non-existent tag.

Function: ly:otf-glyph-count font

  Return the number of glyphs in font.

Function: ly:otf-glyph-list font

  Return a list of glyph names for font.

Function: ly:output-def? def

  Is def an output definition?

Function: ly:output-def-clone def

  Clone output definition def.

Function: ly:output-def-lookup def sym val

  Return the value of sym in output definition def (e.g., `\paper`). If no value is found, return val or `'()` if val is undefined.

Function: ly:output-def-parent def

  Return the parent output definition of def.

Function: ly:output-def-scope def

  Return the variable scope inside def.

Function: ly:output-def-set-variable! def sym val

  Set an output definition def variable sym to val.

Function: ly:output-description output-def

  Return the description of translators in output-def.

Function: ly:output-formats

  Formats passed to ‘`--format`’ as a list of strings, used for the output.

Function: ly:outputter-close outputter

  Close port of outputter.

Function: ly:outputter-dump-stencil outputter stencil

  Dump stencil expr onto outputter.

Function: ly:outputter-dump-string outputter str

  Dump str onto outputter.

Function: ly:outputter-module outputter

  Return output module of outputter.

Function: ly:outputter-output-scheme outputter expr

  Eval expr in module of outputter.

Function: ly:outputter-port outputter

  Return output port for outputter.

Function: ly:page-marker? x

  Is x a `Page_marker` object?

Function: ly:page-turn-breaking pb

  Optimally break (pages and lines) the `Paper_book` object pb such that page turns only happen in specified places, returning its pages.

Function: ly:pango-font? f

  Is f a pango font?

Function: ly:pango-font-physical-fonts f

  Return alist of `(ps-name file-name font-index)` lists for Pango font f.

Function: ly:paper-book? x

  Is x a `Paper_book` object?

Function: ly:paper-book-header pb

  Return the header definition (`\header`) in `Paper_book` object pb.

Function: ly:paper-book-pages pb

  Return pages in `Paper_book` object pb.

Function: ly:paper-book-paper pb

  Return the paper output definition (`\paper`) in `Paper_book` object pb.

Function: ly:paper-book-performances pb

  Return performances in `Paper_book` object pb.

Function: ly:paper-book-scopes pb

  Return scopes in `Paper_book` object pb.

Function: ly:paper-book-systems pb

  Return systems in `Paper_book` object pb.

Function: ly:paper-fonts def

  Return a list containing the fonts from output definition def (e.g., `\paper`).

Function: ly:paper-get-font def chain

  Find a font metric in output definition def satisfying the font-qualifiers in alist chain chain, and return it. (An alist chain is a list of alists, containing grob properties.)

Function: ly:paper-get-number def sym

  Return the value of variable sym in output definition def as a double.

Function: ly:paper-outputscale def

  Return the output-scale for output definition def.

Function: ly:paper-score-paper-systems paper-score

  Return vector of `paper_system` objects from paper-score.

Function: ly:paper-system? obj

  Is obj a C++ `Prob` object of type `paper-system`?

Function: ly:paper-system-minimum-distance sys1 sys2

  Measure the minimum distance between these two paper-systems, using their stored skylines if possible and falling back to their extents otherwise.

Function: ly:parse-file name

  Parse a single `.ly` file. Upon failure, throw `ly-file-failed` key.

Function: ly:parser-clear-error parser

  Clear the error flag for the parser.

Function: ly:parser-clone parser-smob

  Return a clone of parser-smob.

Function: ly:parser-define! parser-smob symbol val

  Bind symbol to val in parser-smob’s module.

Function: ly:parser-error parser msg input

  Display an error message and make the parser fail.

Function: ly:parser-has-error? parser

  Does parser have an error flag?

Function: ly:parser-include-string parser-smob ly-code

  Include the string ly-code into the input stream for parser-smob.

Function: ly:parser-lexer parser-smob

  Return the lexer for parser-smob.

Function: ly:parser-lookup parser-smob symbol

  Look up symbol in parser-smob’s module. Return `'()` if not defined.

Function: ly:parser-output-name parser

  Return the base name of the output file.

Function: ly:parser-parse-string parser-smob ly-code

  Parse the string ly-code with parser-smob. Upon failure, throw `ly-file-failed` key.

Function: ly:parser-set-note-names parser names

  Replace current note names in parser. names is an alist of symbols. This only has effect if the current mode is notes.

Function: ly:parser-set-repetition-function parser fun

  Replace the current repetition function in parser. fun is the new repetition function.

Function: ly:parser-set-repetition-symbol parser sym

  Replace the current repetition symbol in parser. sym is the new repetition symbol.

Function: ly:performance-write performance filename

  Write performance to filename.

Function: ly:pfb->pfa pfb-file-name

  Convert the contents of a Type 1 font in PFB format to PFA format.

Function: ly:pitch? x

  Is x a `Pitch` object?

Function: ly:pitch<? p1 p2

  Is p1 lexicographically smaller than p2?

Function: ly:pitch-alteration pp

  Extract the alteration from pitch pp.

Function: ly:pitch-diff pitch root

  Return pitch delta such that pitch transposed by delta equals root.

Function: ly:pitch-negate p

  Negate p.

Function: ly:pitch-notename pp

  Extract the note name from pitch pp.

Function: ly:pitch-octave pp

  Extract the octave from pitch pp.

Function: ly:pitch-quartertones pp

  Calculate the number of quarter tones of pp from middle C.

Function: ly:pitch-semitones pp

  Calculate the number of semitones of pp from middle C.

Function: ly:pitch-steps p

  Number of steps counted from middle C of the pitch p.

Function: ly:pitch-transpose p delta

  Transpose p by the amount delta, where delta is relative to middle C.

Function: ly:pointer-group-interface::add-grob grob sym grob-element

  Add grob-element to grob’s sym grob array.

Function: ly:position-on-line? sg spos

  Return whether spos is on a line of the staff associated with the grob sg (even on an extender line).

Function: ly:prob? x

  Is x a `Prob` object?

Function: ly:prob-immutable-properties prob

  Retrieve an alist of immutable properties.

Function: ly:prob-mutable-properties prob

  Retrieve an alist of mutable properties.

Function: ly:prob-property prob sym val

  Return the value for property sym of Prob object prob. If no value is found, return val or `'()` if val is not specified.

Function: ly:prob-property? obj sym

  Is boolean prop sym of sym set?

Function: ly:prob-set-property! obj sym value

  Set property sym of obj to value.

Function: ly:prob-type? obj type

  Is obj the specified prob-type?

Function: ly:programming-error str rest

  A Scheme callable function to issue the internal warning str. The message is formatted with `format` and rest.

Function: ly:progress str rest

  A Scheme callable function to print progress str. The message is formatted with `format` and rest.

Function: ly:property-lookup-stats sym

  Return hash table with a property access corresponding to sym. Choices are `prob`, `grob`, and `context`.

Function: ly:protects

  Return hash of protected objects.

Function: ly:pt num

  num printer points.

Function: ly:register-stencil-expression symbol

  Add symbol as head of a stencil expression.

Function: ly:relative-group-extent elements common axis

  Determine the extent of elements relative to common in the axis direction.

Function: ly:reset-all-fonts

  Forget all about previously loaded fonts.

Function: ly:round-filled-box xext yext blot

  Make a `Stencil` object that prints a black box of dimensions xext, yext and roundness blot.

Function: ly:round-filled-polygon points blot

  Make a `Stencil` object that prints a black polygon with corners at the points defined by points (list of coordinate pairs) and roundness blot.

Function: ly:run-translator mus output-def

  Process mus according to output-def. An interpretation context is set up, and mus is interpreted with it. The context is returned in its final state.

  Optionally, this routine takes an object-key to to uniquely identify the score block containing it.

Function: ly:score? x

  Is x a `Score` object?

Function: ly:score-add-output-def! score def

  Add an output definition def to score.

Function: ly:score-embedded-format score layout

  Run score through layout (an output definition) scaled to correct output-scale already, returning a list of layout-lines.

Function: ly:score-error? score

  Was there an error in the score?

Function: ly:score-header score

  Return score header.

Function: ly:score-music score

  Return score music.

Function: ly:score-output-defs score

  All output definitions in a score.

Function: ly:score-set-header! score module

  Set the score header.

Function: ly:set-default-scale scale

  Set the global default scale. This determines the tuning of pitches with no accidentals or key signatures. The first pitch is C. Alterations are calculated relative to this scale. The number of pitches in this scale determines the number of scale steps that make up an octave. Usually the 7-note major scale.

Function: ly:set-grob-modification-callback cb

  Specify a procedure that will be called every time LilyPond modifies a grob property. The callback will receive as arguments the grob that is being modified, the name of the C++ file in which the modification was requested, the line number in the C++ file in which the modification was requested, the name of the function in which the modification was requested, the property to be changed, and the new value for the property.

Function: ly:set-middle-C! context

  Set the `middleCPosition` variable in context based on the variables `middleCClefPosition` and middleCOffset.

Function: ly:set-option var val

  Set a program option.

Function: ly:set-property-cache-callback cb

  Specify a procedure that will be called whenever lilypond calculates a callback function and caches the result. The callback will receive as arguments the grob whose property it is, the name of the property, the name of the callback that calculated the property, and the new (cached) value of the property.

Function: ly:simple-closure? clos

  Is clos a simple closure?

Function: ly:skyline? x

  Is x a `Skyline` object?

Function: ly:skyline-pair? x

  Is x a `Skyline_pair` object?

Function: ly:slur-score-count

  count number of slur scores.

Function: ly:smob-protects

  Return LilyPond’s internal smob protection list.

Function: ly:solve-spring-rod-problem springs rods length ragged

  Solve a spring and rod problem for count objects, that are connected by count-1 springs, and an arbitrary number of rods. count is implicitly given by springs and rods. The springs argument has the format `(ideal, inverse_hook)` and rods is of the form `(idx1, idx2, distance)`.

  length is a number, ragged a boolean.

  The function returns a list containing the force (positive for stretching, negative for compressing and `#f` for non-satisfied constraints) followed by spring-count+1 positions of the objects.

Function: ly:source-file? x

  Is x a `Source_file` object?

Function: ly:spanner? g

  Is g a spanner object?

Function: ly:spanner-bound spanner dir

  Get one of the bounds of spanner. dir is `-1` for left, and `1` for right.

Function: ly:spanner-broken-into spanner

  Return broken-into list for spanner.

Function: ly:spanner-set-bound! spanner dir item

  Set grob item as bound in direction dir for spanner.

Function: ly:spawn command rest

  Simple interface to g_spawn_sync str. The error is formatted with `format` and rest.

Function: ly:staff-symbol-line-thickness grob

  Returns the `line-thickness` of the staff associated with grob.

Function: ly:staff-symbol-staff-space grob

  Returns the `staff-space` of the staff associated with grob.

Function: ly:start-environment

  Return the environment (a list of strings) that was in effect at program start.

Function: ly:stderr-redirect file-name mode

  Redirect stderr to file-name, opened with mode.

Function: ly:stencil? x

  Is x a `Stencil` object?

Function: ly:stencil-add args

  Combine stencils. Takes any number of arguments.

Function: ly:stencil-aligned-to stil axis dir

  Align stil using its own extents. dir is a number. `-1` and `1` are left and right, respectively. Other values are interpolated (so `0` means the center).

Function: ly:stencil-combine-at-edge first axis direction second padding minimum

  Construct a stencil by putting second next to first. axis can be 0 (x-axis) or 1 (y-axis). direction can be -1 (left or down) or 1 (right or up). The stencils are juxtaposed with padding as extra space. If this puts the reference points closer than minimum, they are moved by the latter amount. first and second may also be `'()` or `#f`.

Function: ly:stencil-empty? stil

  Return whether stil is empty.

Function: ly:stencil-expr stil

  Return the expression of stil.

Function: ly:stencil-extent stil axis

  Return a pair of numbers signifying the extent of stil in axis direction (`0` or `1` for x and y axis, respectively).

Function: ly:stencil-fonts s

  Analyze s, and return a list of fonts used in s.

Function: ly:stencil-in-color stc r g b

  Put stc in a different color.

Function: ly:stencil-rotate stil angle x y

  Return a stencil stil rotated angle degrees around the relative offset (x, y). E.g. an offset of (-1, 1) will rotate the stencil around the left upper corner.

Function: ly:stencil-rotate-absolute stil angle x y

  Return a stencil stil rotated angle degrees around point (x, y), given in absolute coordinates.

Function: ly:stencil-scale stil x y

  Scale stil using the horizontal and vertical scaling factors x and y.

Function: ly:stencil-translate stil offset

  Return a stil, but translated by offset (a pair of numbers).

Function: ly:stencil-translate-axis stil amount axis

  Return a copy of stil but translated by amount in axis direction.

Function: ly:stream-event? obj

  Is `obj` a `Stream_event` object?

Function: ly:string-percent-encode str

  Encode all characters in string str with hexadecimal percent escape sequences, with the following exceptions: characters `-`, `.`, `/`, and `_`; and characters in ranges `0-9`, `A-Z`, and `a-z`.

Function: ly:string-substitute a b s

  Replace string a by string b in string s.

Function: ly:success str rest

  A Scheme callable function to issue a success message str. The message is formatted with `format` and rest.

Function: ly:system-font-load name

  Load the OpenType system font ‘`name.otf`’. Fonts loaded with this command must contain three additional SFNT font tables called `LILC`, `LILF`, and `LILY`, needed for typesetting musical elements. Currently, only the Emmentaler and the Emmentaler-Brace fonts fulfill these requirements.

  Note that only `ly:font-get-glyph` and derived code (like `\lookup`) can access glyphs from the system fonts; text strings are handled exclusively via the Pango interface.

Function: ly:text-interface::interpret-markup

  Convert a text markup into a stencil. Takes three arguments, layout, props, and markup.

  layout is a `\layout` block; it may be obtained from a grob with `ly:grob-layout`. props is an alist chain, i.e. a list of alists. This is typically obtained with `(ly:grob-alist-chain grob (ly:output-def-lookup layout 'text-font-defaults))`. markup is the markup text to be processed.

Function: ly:translator? x

  Is x a `Translator` object?

Function: ly:translator-context trans

  Return the context of the translator object trans.

Function: ly:translator-description me

  Return an alist of properties of translator me.

Function: ly:translator-group? x

  Is x a `Translator_group` object?

Function: ly:translator-name trans

  Return the type name of the translator object trans. The name is a symbol.

Function: ly:transpose-key-alist l pit

  Make a new key alist of l transposed by pitch pit.

Function: ly:truncate-list! lst i

  Take at most the first i of list lst.

Function: ly:ttf->pfa ttf-file-name idx

  Convert the contents of a TrueType font file to PostScript Type 42 font, returning it as a string. The optional idx argument is useful for TrueType collections (TTC) only; it specifies the font index within the TTC. The default value of idx is 0.

Function: ly:ttf-ps-name ttf-file-name idx

  Extract the PostScript name from a TrueType font. The optional idx argument is useful for TrueType collections (TTC) only; it specifies the font index within the TTC. The default value of idx is 0.

Function: ly:unit

  Return the unit used for lengths as a string.

Function: ly:usage

  Print usage message.

Function: ly:version

  Return the current lilypond version as a list, e.g., `(1 3 127 uu1)`.

Function: ly:warning str rest

  A Scheme callable function to issue the warning str. The message is formatted with `format` and rest.

Function: ly:wide-char->utf-8 wc

  Encode the Unicode codepoint wc, an integer, as UTF-8.

# B. Cheat sheet

Syntax | Description | Example
`1 2 8 16` | durations |
`c4. c4..` | augmentation dots |
`c d e f g a b` | scale |
`fis bes` | alteration |
`\clef treble \clef bass` | clefs |
`\time 3/4 \time 4/4` | time signature |
`r4 r8` | rest |
`d ~ d` | tie |
`\key es \major` | key signature |
note`'` | raise octave |
note`,` | lower octave |
`c( d e)` | slur |
`c\( c( d) e\)` | phrasing slur |
`a8[ b]` | beam |
`<< \new Staff ... >>` | more staves |
`c-> c-.` | articulations |
`c2\mf c\sfz` | dynamics |
`a\< a a\!` | crescendo |
`a\> a a\!` | decrescendo |
`< >` | chord |
`\partial 8` | pickup / upbeat |
`\times 2/3 {f g a}` | triplets |
`\grace` | grace notes |
`\lyricmode { twinkle }` | entering lyrics | twinkle
`\new Lyrics` | printing lyrics |
`twin -- kle` | lyric hyphen |
`\chordmode { c:dim f:maj7 }` | chords |
`\context ChordNames` | printing chord names |
`<<{e f} \\ {c d}>>` | polyphony |
`s4 s8 s16` | spacer rests |

# C. LilyPond grammar

This appendix contains a description of the LilyPond grammar, as output from the parser.

    Grammar

        1 lilypond: /* empty */
        2         | lilypond toplevel_expression
        3         | lilypond assignment
        4         | lilypond error
        5         | lilypond "\invalid"

        6 toplevel_expression: lilypond_header
        7                    | book_block
        8                    | bookpart_block
        9                    | score_block
       10                    | composite_music
       11                    | full_markup
       12                    | full_markup_list
       13                    | output_def

       14 embedded_scm: SCM_TOKEN
       15             | SCM_IDENTIFIER

       16 lilypond_header_body: /* empty */
       17                     | lilypond_header_body assignment

       18 lilypond_header: "\header" '{' lilypond_header_body '}'

       19 assignment_id: STRING
       20              | LYRICS_STRING

       21 assignment: assignment_id '=' identifier_init
       22           | assignment_id property_path '=' identifier_init
       23           | embedded_scm

       24 identifier_init: score_block
       25                | book_block
       26                | bookpart_block
       27                | output_def
       28                | context_def_spec_block
       29                | music
       30                | post_event
       31                | number_expression
       32                | string
       33                | embedded_scm
       34                | full_markup
       35                | full_markup_list
       36                | DIGIT
       37                | context_modification

       38 context_def_spec_block: "\context" '{' context_def_spec_body '}'

       39 context_def_spec_body: /* empty */
       40                      | CONTEXT_DEF_IDENTIFIER
       41                      | context_def_spec_body
                                   "\grobdescriptions"
                                   embedded_scm
       42                      | context_def_spec_body context_mod
       43                      | context_def_spec_body context_modification

       44 book_block: "\book" '{' book_body '}'

       45 book_body: /* empty */
       46          | BOOK_IDENTIFIER
       47          | book_body paper_block
       48          | book_body bookpart_block
       49          | book_body score_block
       50          | book_body composite_music
       51          | book_body full_markup
       52          | book_body full_markup_list
       53          | book_body lilypond_header
       54          | book_body error

       55 bookpart_block: "\bookpart" '{' bookpart_body '}'

       56 bookpart_body: /* empty */
       57              | BOOK_IDENTIFIER
       58              | bookpart_body paper_block
       59              | bookpart_body score_block
       60              | bookpart_body composite_music
       61              | bookpart_body full_markup
       62              | bookpart_body full_markup_list
       63              | bookpart_body lilypond_header
       64              | bookpart_body error

       65 score_block: "\score" '{' score_body '}'

       66 score_body: music
       67           | SCORE_IDENTIFIER
       68           | score_body lilypond_header
       69           | score_body output_def
       70           | score_body error

       71 paper_block: output_def

       72 output_def: output_def_body '}'

       73 output_def_head: "\paper"
       74                | "\midi"
       75                | "\layout"

       76 output_def_head_with_mode_switch: output_def_head

       77 output_def_body: output_def_head_with_mode_switch '{'
       78                | output_def_head_with_mode_switch
                             '{'
                             OUTPUT_DEF_IDENTIFIER
       79                | output_def_body assignment
       80                | output_def_body context_def_spec_block
       81                | output_def_body error

       82 tempo_event: "\tempo" steno_duration '=' tempo_range
       83            | "\tempo" scalar steno_duration '=' tempo_range
       84            | "\tempo" scalar

       85 music_list: /* empty */
       86           | music_list music
       87           | music_list embedded_scm
       88           | music_list error

       89 music: simple_music
       90      | composite_music

       91 alternative_music: /* empty */
       92                  | "\alternative" '{' music_list '}'

       93 repeated_music: "\repeat"
                            simple_string
                            unsigned_number
                            music
                            alternative_music

       94 sequential_music: "\sequential" '{' music_list '}'
       95                 | '{' music_list '}'

       96 simultaneous_music: "\simultaneous" '{' music_list '}'
       97                   | "<<" music_list ">>"

       98 simple_music: event_chord
       99             | MUSIC_IDENTIFIER
      100             | music_property_def
      101             | context_change

      103 context_modification: "\with"  '{' context_mod_list '}'
      104                     | "\with" CONTEXT_MOD_IDENTIFIER
      105                     | CONTEXT_MOD_IDENTIFIER

      106 optional_context_mod: /* empty */
      107                     | context_modification

      108 context_mod_list: /* empty */
      109                 | context_mod_list context_mod
      110                 | context_mod_list CONTEXT_MOD_IDENTIFIER

      111 composite_music: prefix_composite_music
      112                | grouped_music_list

      113 grouped_music_list: simultaneous_music
      114                   | sequential_music

      115 function_scm_argument: embedded_scm
      116                      | simple_string

      117 function_arglist_music_last: EXPECT_MUSIC function_arglist music

      118 function_arglist_nonmusic_last: EXPECT_MARKUP
                                            function_arglist
                                            full_markup
      119                               | EXPECT_MARKUP
                                            function_arglist
                                            simple_string
      120                               | EXPECT_SCM
                                            function_arglist
                                            function_scm_argument

      121 function_arglist_nonmusic: EXPECT_NO_MORE_ARGS
      122                          | EXPECT_MARKUP
                                       function_arglist_nonmusic
                                       full_markup
      123                          | EXPECT_MARKUP
                                       function_arglist_nonmusic
                                       simple_string
      124                          | EXPECT_SCM
                                       function_arglist_nonmusic
                                       function_scm_argument

      125 function_arglist: EXPECT_NO_MORE_ARGS
      126                 | function_arglist_music_last
      127                 | function_arglist_nonmusic_last

      128 generic_prefix_music_scm: MUSIC_FUNCTION function_arglist

      129 optional_id: /* empty */
      130            | '=' simple_string

      131 prefix_composite_music: generic_prefix_music_scm
      132                       | "\context"
                                    simple_string
                                    optional_id
                                    optional_context_mod
                                    music
      133                       | "\new"
                                    simple_string
                                    optional_id
                                    optional_context_mod
                                    music
      134                       | "\times" fraction music
      135                       | repeated_music
      136                       | "\transpose"
                                    pitch_also_in_chords
                                    pitch_also_in_chords
                                    music
      137                       | mode_changing_head grouped_music_list
      138                       | mode_changing_head_with_context
                                    optional_context_mod
                                    grouped_music_list
      139                       | relative_music
      140                       | re_rhythmed_music

      141 mode_changing_head: "\notemode"
      142                   | "\drummode"
      143                   | "\figuremode"
      144                   | "\chordmode"
      145                   | "\lyricmode"

      146 mode_changing_head_with_context: "\drums"
      147                                | "\figures"
      148                                | "\chords"
      149                                | "\lyrics"

      150 relative_music: "\relative" absolute_pitch music
      151               | "\relative" composite_music

      153 new_lyrics: "\addlyrics"  grouped_music_list

      155 new_lyrics: "\addlyrics"  MUSIC_IDENTIFIER

      157 new_lyrics: new_lyrics "\addlyrics"  grouped_music_list

      159 new_lyrics: new_lyrics "\addlyrics"  MUSIC_IDENTIFIER

      160 re_rhythmed_music: grouped_music_list new_lyrics
      161                  | MUSIC_IDENTIFIER new_lyrics

      163 re_rhythmed_music: "\lyricsto" simple_string  music

      164 context_change: "\change" STRING '=' STRING

      165 property_path_revved: embedded_scm
      166                     | property_path_revved embedded_scm

      167 property_path: property_path_revved

      168 property_operation: STRING '=' scalar
      169                   | "\unset" simple_string
      170                   | "\override" simple_string property_path '=' scalar
      171                   | "\revert" simple_string embedded_scm

      172 context_def_mod: "\consists"
      173                | "\remove"
      174                | "\accepts"
      175                | "\defaultchild"
      176                | "\denies"
      177                | "\alias"
      178                | "\type"
      179                | "\description"
      180                | "\name"

      181 context_mod: property_operation
      182            | context_def_mod STRING
      183            | context_def_mod embedded_scm

      184 context_prop_spec: simple_string
      185                  | simple_string '.' simple_string

      186 simple_music_property_def: "\override"
                                       context_prop_spec
                                       property_path
                                       '='
                                       scalar
      187                          | "\revert" context_prop_spec embedded_scm
      188                          | "\set" context_prop_spec '=' scalar
      189                          | "\unset" context_prop_spec

      190 music_property_def: simple_music_property_def
      191                   | "\once" simple_music_property_def

      192 string: STRING
      193       | STRING_IDENTIFIER
      194       | string '+' string

      195 simple_string: STRING
      196              | LYRICS_STRING
      197              | STRING_IDENTIFIER

      198 scalar: string
      199       | LYRICS_STRING
      200       | bare_number
      201       | embedded_scm
      202       | full_markup
      203       | DIGIT

      204 event_chord: simple_chord_elements post_events
      205            | CHORD_REPETITION optional_notemode_duration post_events
      206            | MULTI_MEASURE_REST optional_notemode_duration post_events
      207            | command_element
      208            | note_chord_element

      209 note_chord_element: chord_body optional_notemode_duration post_events

      210 chord_body: "<" chord_body_elements ">"

      211 chord_body_elements: /* empty */
      212                    | chord_body_elements chord_body_element

      213 chord_body_element: pitch
                                exclamations
                                questions
                                octave_check
                                post_events
      214                   | DRUM_PITCH post_events
      215                   | music_function_chord_body

      216 music_function_identifier_musicless_prefix: MUSIC_FUNCTION

      217 music_function_chord_body: music_function_identifier_musicless_prefix
                                       EXPECT_MUSIC
                                       function_arglist_nonmusic
                                       chord_body_element
      218                          | music_function_identifier_musicless_prefix
                                       function_arglist_nonmusic

      219 music_function_event: music_function_identifier_musicless_prefix
                                  EXPECT_MUSIC
                                  function_arglist_nonmusic
                                  post_event
      220                     | music_function_identifier_musicless_prefix
                                  function_arglist_nonmusic

      221 command_element: command_event
      222                | "\skip" duration_length
      223                | "\["
      224                | "\]"
      225                | "\"
      226                | '|'
      227                | "\partial" duration_length
      228                | "\time" fraction
      229                | "\mark" scalar

      230 command_event: "\~"
      231              | "\mark" "\default"
      232              | tempo_event
      233              | "\key" "\default"
      234              | "\key" NOTENAME_PITCH SCM_IDENTIFIER

      235 post_events: /* empty */
      236            | post_events post_event

      237 post_event: direction_less_event
      238           | script_dir music_function_event
      239           | "--"
      240           | "__"
      241           | script_dir direction_reqd_event
      242           | script_dir direction_less_event
      243           | string_number_event

      244 string_number_event: E_UNSIGNED

      245 direction_less_char: '['
      246                    | ']'
      247                    | '~'
      248                    | '('
      249                    | ')'
      250                    | "\!"
      251                    | "\("
      252                    | "\)"
      253                    | "\>"
      254                    | "\<"

      255 direction_less_event: direction_less_char
      256                     | EVENT_IDENTIFIER
      257                     | tremolo_type

      258 direction_reqd_event: gen_text_def
      259                     | script_abbreviation

      260 octave_check: /* empty */
      261             | '='
      262             | '=' sub_quotes
      263             | '=' sup_quotes

      264 sup_quotes: '''
      265           | sup_quotes '''

      266 sub_quotes: ','
      267           | sub_quotes ','

      268 steno_pitch: NOTENAME_PITCH
      269            | NOTENAME_PITCH sup_quotes
      270            | NOTENAME_PITCH sub_quotes

      271 steno_tonic_pitch: TONICNAME_PITCH
      272                  | TONICNAME_PITCH sup_quotes
      273                  | TONICNAME_PITCH sub_quotes

      274 pitch: steno_pitch

      275 pitch_also_in_chords: pitch
      276                     | steno_tonic_pitch

      277 gen_text_def: full_markup
      278             | string
      279             | DIGIT

      280 script_abbreviation: '^'
      281                    | '+'
      282                    | '-'
      283                    | '|'
      284                    | ">"
      285                    | '.'
      286                    | '_'

      287 script_dir: '_'
      288           | '^'
      289           | '-'

      290 absolute_pitch: steno_pitch

      291 duration_length: multiplied_duration

      292 optional_notemode_duration: /* empty */
      293                           | multiplied_duration

      294 steno_duration: bare_unsigned dots
      295               | DURATION_IDENTIFIER dots

      296 multiplied_duration: steno_duration
      297                    | multiplied_duration '*' bare_unsigned
      298                    | multiplied_duration '*' FRACTION

      299 fraction: FRACTION
      300         | UNSIGNED '/' UNSIGNED

      301 dots: /* empty */
      302     | dots '.'

      303 tremolo_type: ':'
      304             | ':' bare_unsigned

      305 bass_number: DIGIT
      306            | UNSIGNED
      307            | STRING
      308            | full_markup

      309 figured_bass_alteration: '-'
      310                        | '+'
      311                        | '!'

      312 bass_figure: "_"
      313            | bass_number
      314            | bass_figure ']'
      315            | bass_figure figured_bass_alteration
      316            | bass_figure figured_bass_modification

      317 figured_bass_modification: "\+"
      318                          | "\!"
      319                          | '/'
      320                          | "\"

      321 br_bass_figure: bass_figure
      322               | '[' bass_figure

      323 figure_list: /* empty */
      324            | figure_list br_bass_figure

      325 figure_spec: FIGURE_OPEN figure_list FIGURE_CLOSE

      326 optional_rest: /* empty */
      327              | "\rest"

      328 simple_element: pitch
                            exclamations
                            questions
                            octave_check
                            optional_notemode_duration
                            optional_rest
      329               | DRUM_PITCH optional_notemode_duration
      330               | RESTNAME optional_notemode_duration
      331               | lyric_element optional_notemode_duration

      332 simple_chord_elements: simple_element
      333                      | new_chord
      334                      | figure_spec optional_notemode_duration

      335 lyric_element: lyric_markup
      336              | LYRICS_STRING

      337 new_chord: steno_tonic_pitch optional_notemode_duration
      338          | steno_tonic_pitch
                       optional_notemode_duration
                       chord_separator
                       chord_items

      339 chord_items: /* empty */
      340            | chord_items chord_item

      341 chord_separator: ":"
      342                | "^"
      343                | "/" steno_tonic_pitch
      344                | "/+" steno_tonic_pitch

      345 chord_item: chord_separator
      346           | step_numbers
      347           | CHORD_MODIFIER

      348 step_numbers: step_number
      349             | step_numbers '.' step_number

      350 step_number: bare_unsigned
      351            | bare_unsigned '+'
      352            | bare_unsigned "-"

      353 tempo_range: bare_unsigned
      354            | bare_unsigned '~' bare_unsigned

      355 number_expression: number_expression '+' number_term
      356                  | number_expression '-' number_term
      357                  | number_term

      358 number_term: number_factor
      359            | number_factor '*' number_factor
      360            | number_factor '/' number_factor

      361 number_factor: '-' number_factor
      362              | bare_number

      363 bare_number: UNSIGNED
      364            | REAL
      365            | NUMBER_IDENTIFIER
      366            | REAL NUMBER_IDENTIFIER
      367            | UNSIGNED NUMBER_IDENTIFIER

      368 bare_unsigned: UNSIGNED
      369              | DIGIT

      370 unsigned_number: bare_unsigned
      371                | NUMBER_IDENTIFIER

      372 exclamations: /* empty */
      373             | exclamations '!'

      374 questions: /* empty */
      375          | questions '?'

      376 lyric_markup: LYRIC_MARKUP_IDENTIFIER

      378 lyric_markup: LYRIC_MARKUP  markup_top

      379 full_markup_list: MARKUPLINES_IDENTIFIER

      381 full_markup_list: "\markuplines"  markup_list

      382 full_markup: MARKUP_IDENTIFIER

      384 full_markup: "\markup"  markup_top

      385 markup_top: markup_list
      386           | markup_head_1_list simple_markup
      387           | simple_markup

      388 markup_list: MARKUPLINES_IDENTIFIER
      389            | markup_composed_list
      390            | markup_braced_list
      391            | markup_command_list

      392 markup_composed_list: markup_head_1_list markup_braced_list

      393 markup_braced_list: '{' markup_braced_list_body '}'

      394 markup_braced_list_body: /* empty */
      395                        | markup_braced_list_body markup
      396                        | markup_braced_list_body markup_list

      397 markup_command_list: MARKUP_LIST_FUNCTION markup_command_list_arguments

      398 markup_command_basic_arguments: EXPECT_MARKUP_LIST
                                            markup_command_list_arguments
                                            markup_list
      399                               | EXPECT_SCM
                                            markup_command_list_arguments
                                            embedded_scm
      400                               | EXPECT_NO_MORE_ARGS

      401 markup_command_list_arguments: markup_command_basic_arguments
      402                              | EXPECT_MARKUP
                                           markup_command_list_arguments
                                           markup

      403 markup_head_1_item: MARKUP_FUNCTION
                                EXPECT_MARKUP
                                markup_command_list_arguments

      404 markup_head_1_list: markup_head_1_item
      405                   | markup_head_1_list markup_head_1_item

      406 simple_markup: STRING
      407              | MARKUP_IDENTIFIER
      408              | LYRIC_MARKUP_IDENTIFIER
      409              | STRING_IDENTIFIER

      411 simple_markup: "\score" 0 '{' score_body '}'
      412              | MARKUP_FUNCTION markup_command_basic_arguments

      413 markup: markup_head_1_list simple_markup
      414       | simple_markup

    Terminals, with rules where they appear

    "-" (319) 352
    "--" (340) 239
    "/" (320) 343
    "/+" (316) 344
    ":" (318) 341
    "<" (321) 210
    "<<" (323) 97
    ">" (322) 210 284
    ">>" (324) 97
    "\!" (329) 250 318
    "\" (325) 225 320
    "\(" (331) 251
    "\)" (328) 252
    "\+" (334) 317
    "\<" (333) 254
    "\>" (326) 253
    "\[" (330) 223
    "\]" (332) 224
    "\accepts" (261) 174
    "\addlyrics" (259) 153 155 157 159
    "\alias" (262) 177
    "\alternative" (263) 92
    "\book" (264) 44
    "\bookpart" (265) 55
    "\C[haracter]" (327)
    "\change" (266) 164
    "\chordmode" (267) 144
    "\chords" (268) 148
    "\consists" (269) 172
    "\context" (270) 38 132
    "\default" (271) 231 233
    "\defaultchild" (272) 175
    "\denies" (273) 176
    "\description" (274) 179
    "\drummode" (275) 142
    "\drums" (276) 146
    "\figuremode" (277) 143
    "\figures" (278) 147
    "\grobdescriptions" (279) 41
    "\header" (280) 18
    "\invalid" (281) 5
    "\key" (282) 233 234
    "\layout" (283) 75
    "\lyricmode" (284) 145
    "\lyrics" (285) 149
    "\lyricsto" (286) 163
    "\mark" (287) 229 231
    "\markup" (288) 384
    "\markuplines" (289) 381
    "\midi" (290) 74
    "\name" (291) 180
    "\new" (315) 133
    "\notemode" (292) 141
    "\octave" (293)
    "\once" (294) 191
    "\override" (295) 170 186
    "\paper" (296) 73
    "\partial" (297) 227
    "\relative" (298) 150 151
    "\remove" (299) 173
    "\repeat" (300) 93
    "\rest" (301) 327
    "\revert" (302) 171 187
    "\score" (303) 65 411
    "\sequential" (304) 94
    "\set" (305) 188
    "\simultaneous" (306) 96
    "\skip" (307) 222
    "\tempo" (308) 82 83 84
    "\time" (314) 228
    "\times" (309) 134
    "\transpose" (310) 136
    "\type" (311) 178
    "\unset" (312) 169 189
    "\with" (313) 103 104
    "\~" (335) 230
    "^" (317) 342
    "_" (339) 312
    "__" (336) 240
    $end (0) 0
    '!' (33) 311 373
    ''' (39) 264 265
    '(' (40) 248
    ')' (41) 249
    '*' (42) 297 298 359
    '+' (43) 194 281 310 351 355
    ',' (44) 266 267
    '-' (45) 282 289 309 356 361
    '.' (46) 185 285 302 349
    '/' (47) 300 319 360
    ':' (58) 303 304
    '=' (61) 21 22 82 83 130 164 168 170 186 188 261 262 263
    '?' (63) 375
    '[' (91) 245 322
    ']' (93) 246 314
    '^' (94) 280 288
    '_' (95) 286 287
    '{' (123) 18 38 44 55 65 77 78 92 94 95 96 103 393 411
    '|' (124) 226 283
    '}' (125) 18 38 44 55 65 72 92 94 95 96 103 393 411
    '~' (126) 247 354
    BOOK_IDENTIFIER (352) 46 57
    CHORD_MODIFIER (354) 347
    CHORD_REPETITION (355) 205
    CHORDMODIFIER_PITCH (353)
    CHORDMODIFIERS (341)
    CONTEXT_DEF_IDENTIFIER (356) 40
    CONTEXT_MOD_IDENTIFIER (357) 104 105 110
    DIGIT (344) 36 203 279 305 369
    DRUM_PITCH (358) 214 329
    DURATION_IDENTIFIER (359) 295
    E_UNSIGNED (345) 244
    error (256) 4 54 64 70 81 88
    EVENT_IDENTIFIER (360) 256
    EXPECT_MARKUP (347) 118 119 122 123 402 403
    EXPECT_MARKUP_LIST (350) 398
    EXPECT_MUSIC (348) 117 217 219
    EXPECT_NO_MORE_ARGS (351) 121 125 400
    EXPECT_SCM (349) 120 124 399
    FIGURE_CLOSE (337) 325
    FIGURE_OPEN (338) 325
    FRACTION (361) 298 299
    LYRIC_MARKUP (342) 378
    LYRIC_MARKUP_IDENTIFIER (363) 376 408
    LYRICS_STRING (362) 20 196 199 336
    MARKUP_FUNCTION (364) 403 412
    MARKUP_IDENTIFIER (366) 382 407
    MARKUP_LIST_FUNCTION (365) 397
    MARKUPLINES_IDENTIFIER (367) 379 388
    MULTI_MEASURE_REST (343) 206
    MUSIC_FUNCTION (368) 128 216
    MUSIC_IDENTIFIER (369) 99 155 159 161
    NOTENAME_PITCH (370) 234 268 269 270
    NUMBER_IDENTIFIER (371) 365 366 367 371
    OUTPUT_DEF_IDENTIFIER (372) 78
    PREC_BOT (260)
    PREC_TOP (258)
    REAL (373) 364 366
    RESTNAME (374) 330
    SCM_IDENTIFIER (375) 15 234
    SCM_TOKEN (376) 14
    SCORE_IDENTIFIER (377) 67
    STRING (378) 19 164 168 182 192 195 307 406
    STRING_IDENTIFIER (379) 193 197 409
    TONICNAME_PITCH (380) 271 272 273
    UNARY_MINUS (381)
    UNSIGNED (346) 300 306 363 367 368

    Nonterminals, with rules where they appear

    absolute_pitch (240)
        on left: 290, on right: 150
    alternative_music (173)
        on left: 91 92, on right: 93
    assignment (155)
        on left: 21 22 23, on right: 3 17 79
    assignment_id (154)
        on left: 19 20, on right: 21 22
    bare_number (269)
        on left: 363 364 365 366 367, on right: 200 362
    bass_number (248)
        on left: 305 306 307 308, on right: 313
    book_block (159)
        on left: 44, on right: 7 25
    bookpart_block (161)
        on left: 55, on right: 8 26 48
    br_bass_figure (252)
        on left: 321 322, on right: 324
    chord_body (216)
        on left: 210, on right: 209
    chord_body_element (218)
        on left: 213 214 215, on right: 212 217
    chord_body_elements (217)
        on left: 211 212, on right: 210 212
    chord_item (262)
        on left: 345 346 347, on right: 340
    chord_items (260)
        on left: 339 340, on right: 338 340
    chord_separator (261)
        on left: 341 342 343 344, on right: 338 345
    command_event (223)
        on left: 230 231 232 233 234, on right: 221
    composite_music (182)
        on left: 111 112, on right: 10 50 60 90 151
    context_change (202)
        on left: 164, on right: 101
    context_def_spec_block (157)
        on left: 38, on right: 28 80
    context_mod (207)
        on left: 181 182 183, on right: 42 109
    context_mod_list (181)
        on left: 108 109 110, on right: 103 109 110
    context_modification (178)
        on left: 103 104 105, on right: 37 43 107
    context_prop_spec (208)
        on left: 184 185, on right: 186 187 188 189
    direction_less_event (228)
        on left: 255 256 257, on right: 237 242
    direction_reqd_event (229)
        on left: 258 259, on right: 241
    dots (246)
        on left: 301 302, on right: 294 295 302
    duration_length (241)
        on left: 291, on right: 222 227
    event_chord (214)
        on left: 204 205 206 207 208, on right: 98
    exclamations (272)
        on left: 372 373, on right: 213 328 373
    figure_list (253)
        on left: 323 324, on right: 324 325
    figure_spec (254)
        on left: 325, on right: 334
    figured_bass_alteration (249)
        on left: 309 310 311, on right: 315
    figured_bass_modification (251)
        on left: 317 318 319 320, on right: 316
    fraction (245)
        on left: 299 300, on right: 134 228
    full_markup_list (276)
        on left: 379 381, on right: 12 35 52 62
    function_arglist_music_last (185)
        on left: 117, on right: 126
    function_arglist_nonmusic_last (186)
        on left: 118 119 120, on right: 127
    function_scm_argument (184)
        on left: 115 116, on right: 120 124
    gen_text_def (237)
        on left: 277 278 279, on right: 258
    generic_prefix_music_scm (189)
        on left: 128, on right: 131
    lilypond (149)
        on left: 1 2 3 4 5, on right: 0 2 3 4 5
    lilypond_header (153)
        on left: 18, on right: 6 53 63 68
    lilypond_header_body (152)
        on left: 16 17, on right: 17 18
    lyric_element (258)
        on left: 335 336, on right: 331
    lyric_markup (274)
        on left: 376 378, on right: 335
    markup (292)
        on left: 413 414, on right: 395 402
    markup_braced_list (283)
        on left: 393, on right: 390 392
    markup_braced_list_body (284)
        on left: 394 395 396, on right: 393 395 396
    markup_command_list (285)
        on left: 397, on right: 391
    markup_composed_list (282)
        on left: 392, on right: 389
    markup_head_1_item (288)
        on left: 403, on right: 404 405
    markup_head_1_list (289)
        on left: 404 405, on right: 386 392 405 413
    markup_list (281)
        on left: 388 389 390 391, on right: 381 385 396 398
    markup_top (280)
        on left: 385 386 387, on right: 378 384
    mode_changing_head (192)
        on left: 141 142 143 144 145, on right: 137
    multiplied_duration (244)
        on left: 296 297 298, on right: 291 293 297 298
    music_function_chord_body (220)
        on left: 217 218, on right: 215
    music_function_event (221)
        on left: 219 220, on right: 238
    music_list (171)
        on left: 85 86 87 88, on right: 86 87 88 92 94 95 96 97
    music_property_def (210)
        on left: 190 191, on right: 100
    new_chord (259)
        on left: 337 338, on right: 333
    new_lyrics (195)
        on left: 153 155 157 159, on right: 157 159 160 161
    note_chord_element (215)
        on left: 209, on right: 208
    number_expression (266)
        on left: 355 356 357, on right: 31 355 356
    number_factor (268)
        on left: 361 362, on right: 358 359 360 361
    number_term (267)
        on left: 358 359 360, on right: 355 356 357
    octave_check (230)
        on left: 260 261 262 263, on right: 213 328
    optional_context_mod (180)
        on left: 106 107, on right: 132 133 138
    optional_id (190)
        on left: 129 130, on right: 132 133
    optional_rest (255)
        on left: 326 327, on right: 328
    output_def (166)
        on left: 72, on right: 13 27 69 71
    output_def_body (169)
        on left: 77 78 79 80 81, on right: 72 79 80 81
    output_def_head (167)
        on left: 73 74 75, on right: 76
    output_def_head_with_mode_switch (168)
        on left: 76, on right: 77 78
    paper_block (165)
        on left: 71, on right: 47 58
    pitch (235)
        on left: 274, on right: 213 275 328
    pitch_also_in_chords (236)
        on left: 275 276, on right: 136
    post_events (224)
        on left: 235 236, on right: 204 205 206 209 213 214 236
    property_operation (205)
        on left: 168 169 170 171, on right: 181
    property_path (204)
        on left: 167, on right: 22 170 186
    property_path_revved (203)
        on left: 165 166, on right: 166 167
    questions (273)
        on left: 374 375, on right: 213 328 375
    re_rhythmed_music (200)
        on left: 160 161 163, on right: 140
    relative_music (194)
        on left: 150 151, on right: 139
    repeated_music (174)
        on left: 93, on right: 135
    score_block (163)
        on left: 65, on right: 9 24 49 59
    score_body (164)
        on left: 66 67 68 69 70, on right: 65 68 69 70 411
    script_dir (239)
        on left: 287 288 289, on right: 238 241 242
    sequential_music (175)
        on left: 94 95, on right: 114
    simple_chord_elements (257)
        on left: 332 333 334, on right: 204
    simple_element (256)
        on left: 328 329 330 331, on right: 332
    simple_music (177)
        on left: 98 99 100 101, on right: 89
    simultaneous_music (176)
        on left: 96 97, on right: 113
    steno_duration (243)
        on left: 294 295, on right: 82 83 296
    steno_pitch (233)
        on left: 268 269 270, on right: 274 290
    step_number (264)
        on left: 350 351 352, on right: 348 349
    step_numbers (263)
        on left: 348 349, on right: 346 349
    string (211)
        on left: 192 193 194, on right: 32 194 198 278
    string_number_event (226)
        on left: 244, on right: 243
    sub_quotes (232)
        on left: 266 267, on right: 262 267 270 273
    sup_quotes (231)
        on left: 264 265, on right: 263 265 269 272
    tempo_event (170)
        on left: 82 83 84, on right: 232
    tempo_range (265)
        on left: 353 354, on right: 82 83
    toplevel_expression (150)
        on left: 6 7 8 9 10 11 12 13, on right: 2
    tremolo_type (247)
        on left: 303 304, on right: 257
    unsigned_number (271)
        on left: 370 371, on right: 93

# D. GNU Free Documentation License

Version 1.3, 3 November 2008

    Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
    http://fsf.org/

    Everyone is permitted to copy and distribute verbatim copies
    of this license document, but changing it is not allowed.

1. PREAMBLE

   The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

   This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

   We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

2. APPLICABILITY AND DEFINITIONS

   This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.

   A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

   A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

   The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.

   The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

   A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.

   Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.

   The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.

   The “publisher” means any person or entity that distributes copies of the Document to the public.

   A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.

   The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.

3. VERBATIM COPYING

   You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

   You may also lend copies, under the same conditions stated above, and you may publicly display copies.

4. COPYING IN QUANTITY

   If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

   If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

   If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

   It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

5. MODIFICATIONS

   You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

   1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
   2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.
   3. State on the Title page the name of the publisher of the Modified Version, as the publisher.
   4. Preserve all the copyright notices of the Document.
   5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
   6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
   7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document’s license notice.
   8. Include an unaltered copy of this License.
   9. Preserve the section Entitled “History”, Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled “History” in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
   10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the “History” section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
   11. For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
   12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
   13. Delete any section Entitled “Endorsements”. Such a section may not be included in the Modified Version.
   14. Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title with any Invariant Section.
   15. Preserve any Warranty Disclaimers.

   If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles.

   You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

   You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

   The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

6. COMBINING DOCUMENTS

   You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.

   The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

   In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.”

7. COLLECTIONS OF DOCUMENTS

   You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

   You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

8. AGGREGATION WITH INDEPENDENT WORKS

   A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.

   If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.

9. TRANSLATION

   Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.

   If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.

10. TERMINATION

    You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License.

    However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.

    Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.

    Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it.

11. FUTURE REVISIONS OF THIS LICENSE

    The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

    Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Document.

12. RELICENSING

    “Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A “Massive Multiauthor Collaboration” (or “MMC”) contained in the site means any set of copyrightable works thus published on the MMC site.

    “CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization.

    “Incorporate” means to publish or republish a Document, in whole or in part, as part of another Document.

    An MMC is “eligible for relicensing” if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008.

    The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing.

## ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

      Copyright (C)  year  your name.
      Permission is granted to copy, distribute and/or modify this document
      under the terms of the GNU Free Documentation License, Version 1.3
      or any later version published by the Free Software Foundation;
      with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
      Texts.  A copy of the license is included in the section entitled ``GNU
      Free Documentation License''.

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with…Texts.” line with this:

        with the Invariant Sections being list their titles, with
        the Front-Cover Texts being list, and with the Back-Cover Texts
        being list.

If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.

# E. LilyPond command index

This index lists all the LilyPond commands and keywords with links to those sections of the manual which describe or discuss their use. Each link is in two parts. The first part points to the exact location in the manual where the command or keyword appears; the second part points to the start of the section of the manual in which the command or keyword appears.

Jump to: | ! ' , - . / : < = > ? [ \ ] ^ _ | ~ A B C D E F G H I J K L M N O P Q R S T U V W X

| Index Entry | Section
! |  |
| `!` | Accidentals
' |  |
| `'` | Absolute octave entry
, |  |
| `,` | Absolute octave entry
- |  |
| `-` | Articulations and ornamentations
. |  |
| `.` | Durations
/ |  |
| `/` | Extended and altered chords
| `/+` | Extended and altered chords
: |  |
| `:` | Tremolo repeats
< |  |
| `<` | Chorded notes
| `<...>` | Chorded notes
= |  |
| `=` | Octave checks
> |  |
| `>` | Chorded notes
? |  |
| `?` | Accidentals
[ |  |
| `[` | Manual beams
\ |  |
| `\!` | Dynamics
| `\(` | Phrasing slurs
| `\)` | Phrasing slurs
| `\<` | Dynamics
| `\>` | Dynamics
| `\abs-fontsize` | A.9.1 Font
| `\accent` | Articulations and ornamentations
| `\accepts` | 5.1.6 Defining new contexts
| `\accepts` | 5.1.6 Defining new contexts
| `\accepts` | 5.1.7 Aligning contexts
| `\addChordShape` | Predefined fret diagrams
| `\addInstrumentDefinition` | Instrument names
| `\addlyrics` | Aligning lyrics to a melody
| `\addlyrics` | Automatic syllable durations
| `\addlyrics` | Using `\addlyrics`
| `\addQuote` | Quoting other voices
| `\aeolian` | Key signature
| `\afterGrace` | Grace notes
| `\aikenHeads` | Shape note heads
| `\aikenHeadsMinor` | Shape note heads
| `\alias` | 5.1.6 Defining new contexts
| `\allowPageTurn` | Predefined commands
| `\alternative` | 1.4.1 Long repeats
| `\arpeggio` | Arpeggio
| `\arpeggioArrowDown` | Arpeggio
| `\arpeggioArrowUp` | Arpeggio
| `\arpeggioBracket` | Arpeggio
| `\arpeggioNormal` | Arpeggio
| `\arpeggioParenthesis` | Arpeggio
| `\arpeggioParenthesisDashed` | Arpeggio
| `\arrow-head` | Graphic notation inside markup
| `\arrow-head` | A.9.3 Graphic
| `\ascendens` | Gregorian square neume ligatures
| `\ascendens` | Predefined commands
| `\auctum` | Gregorian square neume ligatures
| `\auctum` | Predefined commands
| `\augmentum` | Predefined commands
| `\autoBeamOff` | Automatic beams
| `\autoBeamOn` | Automatic beams
| `\autochange` | Changing staff automatically
| `\backslashed-digit` | A.9.6 Other
| `\balloonGrobText` | Balloon help
| `\balloonLengthOff` | Balloon help
| `\balloonLengthOn` | Balloon help
| `\balloonText` | Balloon help
| `\bar` | Bar lines
| `\bar` | Selected Snippets
| `\barNumberCheck` | Bar and bar number checks
| `\beam` | A.9.3 Graphic
| `\bendAfter` | Falls and doits
| `\bold` | Selecting font and font size
| `\bold` | A.9.1 Font
| `\book` | 3.1.2 Multiple scores in a book
| `\book` | 3.1.2 Multiple scores in a book
| `\book` | 3.1.5 File structure
| `\bookOutputName` | 3.1.4 Output file names
| `\bookOutputSuffix` | 3.1.4 Output file names
| `\bookpart` | 3.1.2 Multiple scores in a book
| `\bookpart` | 3.1.5 File structure
| `\bookpart` | 4.3.2 Page breaking
| `\box` | Graphic notation inside markup
| `\box` | A.9.1 Font
| `\bracket` | New dynamic marks
| `\bracket` | Graphic notation inside markup
| `\bracket` | A.9.3 Graphic
| `\break` | Predefined commands
| `\breathe` | Breath marks
| `\breve` | Durations
| `\breve` | Rests
| `\cadenzaOff` | Unmetered music
| `\cadenzaOn` | Unmetered music
| `\caesura` | Predefined commands
| `\caps` | A.9.1 Font
| `\cavum` | Gregorian square neume ligatures
| `\cavum` | Predefined commands
| `\center-align` | Text alignment
| `\center-align` | A.9.2 Align
| `\center-column` | Text alignment
| `\center-column` | A.9.2 Align
| `\change` | Changing staff manually
| `\char` | A.9.6 Other
| `\chordGlissando` | Default tablatures
| `\chordmode` | See also
| `\chordmode` | See also
| `\chordmode` | Predefined fret diagrams
| `\circle` | Graphic notation inside markup
| `\circle` | A.9.3 Graphic
| `\clef` | Clef
| `\cm` | 5.4.4 Distances and measurements
| `\coda` | Articulations and ornamentations
| `\column` | Text alignment
| `\column` | A.9.2 Align
| `\column-lines` | A.10 Text markup list commands
| `\combine` | Graphic notation inside markup
| `\combine` | A.9.2 Align
| `\compressFullBarRests` | Full measure rests
| `\compressFullBarRests` | Full measure rests
| `\concat` | A.9.2 Align
| `\consists` | 5.1.6 Defining new contexts
| `\context` | 5.1.2 Creating contexts
| `\contextStringTunings` | Custom tablatures
| `\cr` | Dynamics
| `\cresc` | Dynamics
| `\crescHairpin` | Dynamics
| `\crescTextCresc` | Dynamics
| `\cueDuring` | Formatting cue notes
| `\customTabClef` | A.9.4 Music
| `\decr` | Dynamics
| `\decresc` | Dynamics
| `\defaultTimeSignature` | Time signature
| `\deminutum` | Gregorian square neume ligatures
| `\deminutum` | Predefined commands
| `\denies` | 5.1.6 Defining new contexts
| `\denies` | 5.1.6 Defining new contexts
| `\denies` | 5.1.7 Aligning contexts
| `\descendens` | Gregorian square neume ligatures
| `\descendens` | Predefined commands
| `\dim` | Dynamics
| `\dimHairpin` | Dynamics
| `\dimTextDecr` | Dynamics
| `\dimTextDecresc` | Dynamics
| `\dimTextDim` | Dynamics
| `\dir-column` | A.9.2 Align
| `\displayLilyMusic` | 3.3.4 Displaying LilyPond notation
| `\divisioMaior` | Predefined commands
| `\divisioMaxima` | Predefined commands
| `\divisioMinima` | Predefined commands
| `\dorian` | Key signature
| `\dotsDown` | Durations
| `\dotsNeutral` | Durations
| `\dotsUp` | Durations
| `\doubleflat` | A.9.4 Music
| `\doublesharp` | A.9.4 Music
| `\downbow` | Articulations and ornamentations
| `\downbow` | Bowing indications
| `\downmordent` | Articulations and ornamentations
| `\downprall` | Articulations and ornamentations
| `\draw-circle` | Graphic notation inside markup
| `\draw-circle` | A.9.3 Graphic
| `\draw-hline` | A.9.3 Graphic
| `\draw-line` | Graphic notation inside markup
| `\draw-line` | A.9.3 Graphic
| `\drummode` | Instantiating new staves
| `\dynamic` | New dynamic marks
| `\dynamic` | A.9.1 Font
| `\dynamicDown` | Dynamics
| `\dynamicNeutral` | Dynamics
| `\dynamicUp` | Dynamics
| `\easyHeadsOff` | Easy notation note heads
| `\easyHeadsOn` | Easy notation note heads
| `\epsfile` | Graphic notation inside markup
| `\epsfile` | A.9.3 Graphic
| `\espressivo` | Articulations and ornamentations
| `\espressivo` | Dynamics
| `\expandFullBarRests` | Full measure rests
| `\expandFullBarRests` | Full measure rests
| `\eyeglasses` | A.9.6 Other
| `\f` | Dynamics
| `\featherDurations` | Feathered beams
| `\fermata` | Articulations and ornamentations
| `\fermataMarkup` | Full measure rests
| `\fermataMarkup` | Full measure rests
| `\fermataMarkup` | Articulations and ornamentations
| `\ff` | Dynamics
| `\fff` | Dynamics
| `\ffff` | Dynamics
| `\fffff` | Dynamics
| `\fill-line` | Text alignment
| `\fill-line` | A.9.2 Align
| `\fill-with-pattern` | A.9.2 Align
| `\filled-box` | Graphic notation inside markup
| `\filled-box` | A.9.3 Graphic
| `\finalis` | Predefined commands
| `\finger` | Fingering instructions
| `\finger` | A.9.1 Font
| `\flageolet` | Articulations and ornamentations
| `\flat` | A.9.4 Music
| `\flexa` | Predefined commands
| `\fontCaps` | A.9.1 Font
| `\fontsize` | Selecting font and font size
| `\fontsize` | A.9.1 Font
| `\footnote` | A.9.6 Other
| `\fp` | Dynamics
| `\fraction` | A.9.6 Other
| `\frenchChords` | Predefined commands
| `\fret-diagram` | Fret diagram markups
| `\fret-diagram` | A.9.5 Instrument Specific Markup
| `\fret-diagram-terse` | Fret diagram markups
| `\fret-diagram-terse` | A.9.5 Instrument Specific Markup
| `\fret-diagram-verbose` | Fret diagram markups
| `\fret-diagram-verbose` | A.9.5 Instrument Specific Markup
| `\fromproperty` | A.9.6 Other
| `\funkHeads` | Shape note heads
| `\funkHeadsMinor` | Shape note heads
| `\general-align` | Text alignment
| `\general-align` | A.9.2 Align
| `\germanChords` | Predefined commands
| `\glissando` | Glissando
| `\grace` | Grace notes
| `\halfopen` | Articulations and ornamentations
| `\halign` | Text alignment
| `\halign` | A.9.2 Align
| `\harmonic` | Harmonics
| `\harmonic` | Default tablatures
| `\harmonicByFret` | Default tablatures
| `\harmonicByRatio` | Default tablatures
| `\harmonicsOff` | Harmonics
| `\harmonicsOn` | Harmonics
| `\harp-pedal` | A.9.5 Instrument Specific Markup
| `\hbracket` | Graphic notation inside markup
| `\hbracket` | A.9.3 Graphic
| `\hcenter-in` | A.9.2 Align
| `\header` | 3.1.5 File structure
| `\hideKeySignature` | Bagpipe definitions
| `\hideNotes` | Hidden notes
| `\hideSplitTiedTabNotes` | Default tablatures
| `\hideStaffSwitch` | Staff-change lines
| `\hspace` | A.9.2 Align
| `\huge` | Selecting notation font size
| `\huge` | Selecting font and font size
| `\huge` | A.9.1 Font
| `\improvisationOff` | Improvisation
| `\improvisationOff` | Showing melody rhythms
| `\improvisationOn` | Improvisation
| `\improvisationOn` | Showing melody rhythms
| `\in` | 5.4.4 Distances and measurements
| `\inclinatum` | Gregorian square neume ligatures
| `\inclinatum` | Predefined commands
| `\include` | 3.3.1 Including LilyPond files
| `\instrumentSwitch` | Instrument names
| `\inversion` | Inversion
| `\ionian` | Key signature
| `\italianChords` | Predefined commands
| `\italic` | Selecting font and font size
| `\italic` | A.9.1 Font
| `\justified-lines` | Multi-page markup
| `\justified-lines` | A.10 Text markup list commands
| `\justify` | Text alignment
| `\justify` | A.9.2 Align
| `\justify-field` | A.9.2 Align
| `\justify-string` | A.9.2 Align
| `\keepWithTag` | Using tags
| `\key` | Key signature
| `\key` | Shape note heads
| `\killCues` | Formatting cue notes
| `\label` | Predefined commands
| `\laissezVibrer` | Ties
| `\large` | Selecting notation font size
| `\large` | Selecting font and font size
| `\large` | A.9.1 Font
| `\larger` | Selecting font and font size
| `\larger` | Selecting font and font size
| `\larger` | A.9.1 Font
| `\layout` | 3.1.5 File structure
| `\layout` | 4.2.1 The `\layout` block
| `\left-align` | Text alignment
| `\left-align` | A.9.2 Align
| `\left-brace` | A.9.6 Other
| `\left-column` | A.9.2 Align
| `\lheel` | Articulations and ornamentations
| `\line` | A.9.2 Align
| `\linea` | Gregorian square neume ligatures
| `\linea` | Predefined commands
| `\lineprall` | Articulations and ornamentations
| `\locrian` | Key signature
| `\longa` | Durations
| `\longa` | Rests
| `\longfermata` | Articulations and ornamentations
| `\lookup` | A.9.6 Other
| `\lower` | Text alignment
| `\lower` | A.9.2 Align
| `\ltoe` | Articulations and ornamentations
| `\lydian` | Key signature
| `\lyricmode` | Entering lyrics
| `\lyricmode` | Aligning lyrics to a melody
| `\lyricsto` | Aligning lyrics to a melody
| `\lyricsto` | Automatic syllable durations
| `\lyricsto` | Using `\lyricsto`
| `\magnify` | Selecting font and font size
| `\magnify` | A.9.1 Font
| `\major` | Key signature
| `\makeClusters` | Clusters
| `\makeStringTuning` | Custom tablatures
| `\marcato` | Articulations and ornamentations
| `\mark` | Rehearsal marks
| `\mark` | Text marks
| `\markalphabet` | A.9.6 Other
| `\markletter` | A.9.6 Other
| `\markup` | Text marks
| `\markup` | Separate text
| `\markup` | Separate text
| `\markup` | Text markup introduction
| `\markuplines` | Separate text
| `\markuplines` | Multi-page markup
| `\markuplines` | See also
| `\maxima` | Durations
| `\maxima` | Rests
| `\medium` | A.9.1 Font
| `\melisma` | Multiple notes to one syllable
| `\melismaEnd` | Multiple notes to one syllable
| `\mergeDifferentlyDottedOff` | Collision resolution
| `\mergeDifferentlyDottedOn` | Collision resolution
| `\mergeDifferentlyHeadedOff` | Collision resolution
| `\mergeDifferentlyHeadedOn` | Collision resolution
| `\mf` | Dynamics
| `\midi` | 3.1.5 File structure
| `\minor` | Key signature
| `\mixolydian` | Key signature
| `\mm` | 5.4.4 Distances and measurements
| `\modalInversion` | Modal inversion
| `\modalTranspose` | Modal transposition
| `\mordent` | Articulations and ornamentations
| `\mp` | Dynamics
| `\musicglyph` | Rehearsal marks
| `\musicglyph` | A.9.4 Music
| `\name` | 5.1.6 Defining new contexts
| `\natural` | A.9.4 Music
| `\new` | 5.1.2 Creating contexts
| `\noBeam` | Manual beams
| `\noBreak` | Predefined commands
| `\noPageBreak` | Predefined commands
| `\noPageTurn` | Predefined commands
| `\normal-size-sub` | A.9.1 Font
| `\normal-size-super` | A.9.1 Font
| `\normal-text` | A.9.1 Font
| `\normalsize` | Selecting notation font size
| `\normalsize` | Selecting font and font size
| `\normalsize` | A.9.1 Font
| `\note` | A.9.4 Music
| `\note-by-number` | A.9.4 Music
| `\null` | Text alignment
| `\null` | A.9.6 Other
| `\number` | A.9.1 Font
| `\numericTimeSignature` | Time signature
| `\octaveCheck` | Octave checks
| `\on-the-fly` | A.9.6 Other
| `\once` | 5.3.3 The `\override` command
| `\oneVoice` | Single-staff polyphony
| `\open` | Articulations and ornamentations
| `\open` | Bowing indications
| `\oriscus` | Gregorian square neume ligatures
| `\oriscus` | Predefined commands
| `\ottava` | Ottava brackets
| `\override` | See also
| `\override` | A.9.6 Other
| `\override in \lyricmode` | Entering lyrics
| `\override-lines` | A.10 Text markup list commands
| `\overrideTimeSignatureSettings` | Time signature
| `\p` | Dynamics
| `\pad-around` | Graphic notation inside markup
| `\pad-around` | A.9.2 Align
| `\pad-markup` | Graphic notation inside markup
| `\pad-markup` | A.9.2 Align
| `\pad-to-box` | Graphic notation inside markup
| `\pad-to-box` | A.9.2 Align
| `\pad-x` | Graphic notation inside markup
| `\pad-x` | A.9.2 Align
| `\page-link` | A.9.6 Other
| `\page-ref` | Predefined commands
| `\page-ref` | A.9.6 Other
| `\pageBreak` | Predefined commands
| `\pageTurn` | Predefined commands
| `\paper` | 3.1.5 File structure
| `\paper` | 4.1.2 Paper size and automatic scaling
| `\parallelMusic` | Writing music in parallel
| `\parenthesize` | Parentheses
| `\parenthesize` | A.9.3 Graphic
| `\partcombine` | Automatic part combining
| `\partial` | Upbeats
| `\partial` | 1.4.1 Long repeats
| `\partial` | Normal repeats
| `\path` | A.9.3 Graphic
| `\pattern` | A.9.6 Other
| `\pes` | Predefined commands
| `\phrasingSlurDashed` | Phrasing slurs
| `\phrasingSlurDashPattern` | Phrasing slurs
| `\phrasingSlurDotted` | Phrasing slurs
| `\phrasingSlurDown` | Phrasing slurs
| `\phrasingSlurHalfDashed` | Phrasing slurs
| `\phrasingSlurHalfSolid` | Phrasing slurs
| `\phrasingSlurNeutral` | Phrasing slurs
| `\phrasingSlurSolid` | Phrasing slurs
| `\phrasingSlurUp` | Phrasing slurs
| `\phrygian` | Key signature
| `\pitchedTrill` | Trills
| `\portato` | Articulations and ornamentations
| `\postscript` | Graphic notation inside markup
| `\postscript` | A.9.3 Graphic
| `\powerChords` | Indicating power chords
| `\pp` | Dynamics
| `\ppp` | Dynamics
| `\pppp` | Dynamics
| `\ppppp` | Dynamics
| `\prall` | Articulations and ornamentations
| `\pralldown` | Articulations and ornamentations
| `\prallmordent` | Articulations and ornamentations
| `\prallprall` | Articulations and ornamentations
| `\prallup` | Articulations and ornamentations
| `\predefinedFretboardsOff` | Automatic fret diagrams
| `\predefinedFretboardsOn` | Automatic fret diagrams
| `\pt` | 5.4.4 Distances and measurements
| `\put-adjacent` | A.9.2 Align
| `\quilisma` | Gregorian square neume ligatures
| `\quilisma` | Predefined commands
| `\quoteDuring` | Quoting other voices
| `\quoteDuring` | Formatting cue notes
| `\raise` | Text alignment
| `\raise` | A.9.2 Align
| `\relative` | Relative octave entry
| `\relative` | See also
| `\relative` | See also
| `\relative` | Changing staff automatically
| `\RemoveEmptyStaves` | Hiding staves
| `\RemoveEmptyStaves` | Hiding staves
| `\removeWithTag` | Using tags
| `\repeat` | 1.4.1 Long repeats
| `\repeat percent` | Percent repeats
| `\repeat tremolo` | Tremolo repeats
| `\repeatTie` | Ties
| `\repeatTie` | Normal repeats
| `\repeatTie` | Repeats with alternative endings
| `\rest` | Rests
| `\retrograde` | Retrograde
| `\reverseturn` | Articulations and ornamentations
| `\revert` | 5.3.3 The `\override` command
| `\revertTimeSignatureSettings` | Time signature
| `\rfz` | Dynamics
| `\rheel` | Articulations and ornamentations
| `\right-align` | Text alignment
| `\right-align` | A.9.2 Align
| `\right-brace` | A.9.6 Other
| `\right-column` | A.9.2 Align
| `\rightHandFinger` | Right-hand fingerings
| `\roman` | A.9.1 Font
| `\rotate` | A.9.2 Align
| `\rounded-box` | Graphic notation inside markup
| `\rounded-box` | A.9.3 Graphic
| `\rtoe` | Articulations and ornamentations
| `\sacredHarpHeads` | Shape note heads
| `\sacredHarpHeadsMinor` | Shape note heads
| `\sans` | A.9.1 Font
| `\scale` | A.9.3 Graphic
| `\scaleDurations` | Scaling durations
| `\scaleDurations` | Polymetric notation
| `\score` | 3.1.1 Structure of a score
| `\score` | 3.1.5 File structure
| `\score` | A.9.4 Music
| `\segno` | Articulations and ornamentations
| `\semiflat` | A.9.4 Music
| `\semiGermanChords` | Predefined commands
| `\semisharp` | A.9.4 Music
| `\sesquiflat` | A.9.4 Music
| `\sesquisharp` | A.9.4 Music
| `\set` | Setting automatic beam behavior
| `\set` | 5.3.2 The `\set` command
| `\sf` | Dynamics
| `\sff` | Dynamics
| `\sfz` | Dynamics
| `\sharp` | A.9.4 Music
| `\shiftOff` | Collision resolution
| `\shiftOn` | Collision resolution
| `\shiftOnn` | Collision resolution
| `\shiftOnnn` | Collision resolution
| `\shortfermata` | Articulations and ornamentations
| `\showKeySignature` | Bagpipe definitions
| `\showStaffSwitch` | Staff-change lines
| `\signumcongruentiae` | Articulations and ornamentations
| `\simple` | A.9.1 Font
| `\skip` | Invisible rests
| `\skip` | Repeats with alternative endings
| `\slashed-digit` | A.9.6 Other
| `\slurDashed` | Slurs
| `\slurDashPattern` | Slurs
| `\slurDotted` | Slurs
| `\slurDown` | Slurs
| `\slurHalfDashed` | Slurs
| `\slurHalfSolid` | Slurs
| `\slurNeutral` | Slurs
| `\slurSolid` | Slurs
| `\slurUp` | Slurs
| `\small` | Selecting notation font size
| `\small` | Selecting font and font size
| `\small` | A.9.1 Font
| `\smallCaps` | A.9.1 Font
| `\smaller` | Selecting font and font size
| `\smaller` | Selecting font and font size
| `\smaller` | A.9.1 Font
| `\snappizzicato` | Articulations and ornamentations
| `\sostenutoOff` | Piano pedals
| `\sostenutoOn` | Piano pedals
| `\southernHarmonyHeads` | Shape note heads
| `\southernHarmonyHeadsMinor` | Shape note heads
| `\sp` | Dynamics
| `\spp` | Dynamics
| `\staccatissimo` | Articulations and ornamentations
| `\staccato` | Articulations and ornamentations
| `\startGroup` | Analysis brackets
| `\startStaff` | Staff symbol
| `\startStaff` | Ossia staves
| `\startTrillSpan` | Trills
| `\stemDown` | Stems
| `\stemNeutral` | Stems
| `\stemUp` | Stems
| `\stencil` | A.9.6 Other
| `\stopGroup` | Analysis brackets
| `\stopped` | Articulations and ornamentations
| `\stopStaff` | Staff symbol
| `\stopStaff` | Ossia staves
| `\stopStaff` | Hiding staves
| `\stopTrillSpan` | Trills
| `\storePredefinedDiagram` | Predefined fret diagrams
| `\stropha` | Gregorian square neume ligatures
| `\stropha` | Predefined commands
| `\strut` | A.9.6 Other
| `\sub` | Selecting font and font size
| `\sub` | A.9.1 Font
| `\super` | Selecting font and font size
| `\super` | A.9.1 Font
| `\sustainOff` | Piano pedals
| `\sustainOn` | Piano pedals
| `\tabChordRepetition` | Default tablatures
| `\tabFullNotation` | Default tablatures
| `\table-of-contents` | Predefined commands
| `\table-of-contents` | A.10 Text markup list commands
| `\tag` | Using tags
| `\taor` | Bagpipe definitions
| `\teeny` | Selecting notation font size
| `\teeny` | Selecting font and font size
| `\teeny` | A.9.1 Font
| `\tempo` | Metronome marks
| `\tenuto` | Articulations and ornamentations
| `\text` | A.9.1 Font
| `\textLengthOff` | Full measure rests
| `\textLengthOff` | Text scripts
| `\textLengthOn` | Full measure rests
| `\textLengthOn` | Text scripts
| `\textSpannerDown` | Text spanners
| `\textSpannerNeutral` | Text spanners
| `\textSpannerUp` | Text spanners
| `\thumb` | Articulations and ornamentations
| `\thumb` | Fingering instructions
| `\tied-lyric` | A.9.4 Music
| `\tieDashed` | Ties
| `\tieDotted` | Ties
| `\tieDown` | Ties
| `\tieNeutral` | Ties
| `\tieSolid` | Ties
| `\tieUp` | Ties
| `\time` | Time signature
| `\time` | Setting automatic beam behavior
| `\times` | Tuplets
| `\times` | Polymetric notation
| `\tiny` | Selecting notation font size
| `\tiny` | Selecting font and font size
| `\tiny` | A.9.1 Font
| `\tocItem` | Predefined commands
| `\translate` | Text alignment
| `\translate` | A.9.2 Align
| `\translate-scaled` | Text alignment
| `\translate-scaled` | A.9.2 Align
| `\transparent` | A.9.6 Other
| `\transpose` | See also
| `\transpose` | Transpose
| `\transpose` | See also
| `\transposedCueDuring` | Formatting cue notes
| `\transposition` | Instrument transpositions
| `\transposition` | Quoting other voices
| `\treCorde` | Piano pedals
| `\triangle` | Graphic notation inside markup
| `\triangle` | A.9.3 Graphic
| `\trill` | Articulations and ornamentations
| `\trill` | Trills
| `\tupletDown` | Tuplets
| `\tupletNeutral` | Tuplets
| `\tupletUp` | Tuplets
| `\turn` | Articulations and ornamentations
| `\tweak` | 5.3.4 The `\tweak` command
| `\type` | 5.1.6 Defining new contexts
| `\typewriter` | A.9.1 Font
| `\unaCorda` | Piano pedals
| `\underline` | Selecting font and font size
| `\underline` | A.9.1 Font
| `\unfoldRepeats` | 3.5.4 Repeats in MIDI
| `\unHideNotes` | Hidden notes
| `\unset` | 5.3.2 The `\set` command
| `\upbow` | Articulations and ornamentations
| `\upbow` | Bowing indications
| `\upmordent` | Articulations and ornamentations
| `\upprall` | Articulations and ornamentations
| `\upright` | A.9.1 Font
| `\varcoda` | Articulations and ornamentations
| `\vcenter` | A.9.2 Align
| `\verbatim-file` | A.9.6 Other
| `\verylongfermata` | Articulations and ornamentations
| `\virga` | Gregorian square neume ligatures
| `\virga` | Predefined commands
| `\virgula` | Predefined commands
| `\voiceFourStyle` | Voice styles
| `\voiceNeutralStyle` | Voice styles
| `\voiceOne` | Single-staff polyphony
| `\voiceOne ... \voiceFour` | Single-staff polyphony
| `\voiceOneStyle` | Voice styles
| `\voiceThreeStyle` | Voice styles
| `\voiceTwoStyle` | Voice styles
| `\vspace` | A.9.2 Align
| `\walkerHeads` | Shape note heads
| `\walkerHeadsMinor` | Shape note heads
| `\whiteout` | A.9.6 Other
| `\with` | 5.1.4 Modifying context plug-ins
| `\with-color` | Coloring objects
| `\with-color` | A.9.6 Other
| `\with-dimensions` | A.9.6 Other
| `\with-link` | A.9.6 Other
| `\with-url` | A.9.3 Graphic
| `\woodwind-diagram` | A.9.5 Instrument Specific Markup
| `\wordwrap` | Text alignment
| `\wordwrap` | A.9.2 Align
| `\wordwrap-field` | A.9.2 Align
| `\wordwrap-internal` | A.10 Text markup list commands
| `\wordwrap-lines` | Multi-page markup
| `\wordwrap-lines` | A.10 Text markup list commands
| `\wordwrap-string` | A.9.2 Align
| `\wordwrap-string-internal` | A.10 Text markup list commands
] |  |
| `]` | Manual beams
^ |  |
| `^` | Extended and altered chords
_ |  |
| `_` | Multiple syllables to one note
| `|` | Bar and bar number checks
| `|` | Bar and bar number checks
~ |  |
| `~` | Ties
A |  |
| `accepts` | 5.1.6 Defining new contexts
| `addChordShape` | Predefined fret diagrams
| `addInstrumentDefinition` | Instrument names
| `addQuote` | Quoting other voices
| `aeolian` | Key signature
| `afterGrace` | Grace notes
| `aikenHeads` | Shape note heads
| `aikenHeadsMinor` | Shape note heads
| `alias` | 5.1.6 Defining new contexts
| `alignAboveContext` | 5.1.7 Aligning contexts
| `alignBelowContext` | 5.1.7 Aligning contexts
| `annotate-spacing` | 4.6.1 Displaying spacing
| `arpeggio` | Arpeggio
| `arpeggioArrowDown` | Arpeggio
| `arpeggioArrowUp` | Arpeggio
| `arpeggioBracket` | Arpeggio
| `arpeggioNormal` | Arpeggio
| `arpeggioParenthesis` | Arpeggio
| `arpeggioParenthesisDashed` | Arpeggio
| `arrow-head` | Graphic notation inside markup
| `aug` | Common chords
| `auto-first-page-number` | `\paper` variables for page numbering
| `autoBeaming` | Setting automatic beam behavior
| `autoBeamOff` | Automatic beams
| `autoBeamOn` | Automatic beams
| `autochange` | Changing staff automatically
B |  |
| `balloonGrobText` | Balloon help
| `balloonLengthOff` | Balloon help
| `balloonLengthOn` | Balloon help
| `balloonText` | Balloon help
| `Balloon_engraver` | Balloon help
| `banjo-c-tuning` | Banjo tablatures
| `banjo-modal-tuning` | Banjo tablatures
| `banjo-open-d-tuning` | Banjo tablatures
| `banjo-open-dm-tuning` | Banjo tablatures
| `bar` | Bar lines
| `bar` | Selected Snippets
| `barCheckSynchronize` | Bar and bar number checks
| `BarNumber` | Bar numbers
| `barNumberCheck` | Bar and bar number checks
| `barNumberVisibility` | Bar numbers
| `bartype` | Selected Snippets
| `base-shortest-duration` | 4.5.1 Horizontal spacing overview
| `baseMoment` | Setting automatic beam behavior
| `beamExceptions` | Setting automatic beam behavior
| `beatStructure` | Setting automatic beam behavior
| `bendAfter` | Falls and doits
| `binding-offset` | `\paper` variables for two-sided mode
| `blank-after-score-page-force` | `\paper` variables for page breaking
| `blank-last-page-force` | `\paper` variables for page breaking
| `blank-page-force` | `\paper` variables for page breaking
| `bold` | Selecting font and font size
| `bottom-margin` | 4.1.3 Fixed vertical spacing `\paper` variables
| `box` | Graphic notation inside markup
| `bracket` | New dynamic marks
| `bracket` | Graphic notation inside markup
| `bracket` | Piano pedals
| `breakable` | Predefined commands
| `breathe` | Breath marks
| `breve` | Durations
| `breve` | Rests
C |  |
| `cadenzaOff` | Unmetered music
| `cadenzaOn` | Unmetered music
| `center-align` | Text alignment
| `center-column` | Text alignment
| `change` | Changing staff manually
| `check-consistency` | `\paper` variables for widths and margins
| `chordChanges` | Selected Snippets
| `chordmode` | See also
| `chordmode` | See also
| `chordmode` | Predefined fret diagrams
| `chordNameExceptions` | Customizing chord names
| `chordNameLowercaseMinor` | Customizing chord names
| `ChordNames` | Predefined fret diagrams
| `chordNameSeparator` | Customizing chord names
| `chordNoteNamer` | Customizing chord names
| `chordPrefixSpacer` | Customizing chord names
| `chordRootNamer` | Customizing chord names
| `chords` | Printing chord names
| `circle` | Graphic notation inside markup
| `clef` | Clef
| `color` | Coloring objects
| `column` | Text alignment
| `combine` | Graphic notation inside markup
| `common-shortest-duration` | 4.5.1 Horizontal spacing overview
| `Completion_heads_engraver` | Automatic note splitting
| `Completion_rest_engraver` | Automatic note splitting
| `compressFullBarRests` | Full measure rests
| `compressFullBarRests` | Full measure rests
| `consists` | 5.1.6 Defining new contexts
| `contextStringTunings` | Custom tablatures
| `controlpitch` | Octave checks
| `cr` | Dynamics
| `cresc` | Dynamics
| `crescHairpin` | Dynamics
| `crescTextCresc` | Dynamics
| `cross` | Special note heads
| `cross-staff` | Cross-staff stems
| `cueDuring` | Formatting cue notes
| `currentBarNumber` | Bar numbers
| `currentBarNumber` | Time administration
D |  |
| `decr` | Dynamics
| `decresc` | Dynamics
| `default` | Automatic accidentals
| `default` | Automatic accidentals
| `default-staff-staff-spacing` | Within-system spacing properties
| `defaultBarType` | Selected Snippets
| `defaultTimeSignature` | Time signature
| `denies` | 5.1.6 Defining new contexts
| `dim` | Dynamics
| `dim` | Common chords
| `dimHairpin` | Dynamics
| `dimTextDecr` | Dynamics
| `dimTextDecresc` | Dynamics
| `dimTextDim` | Dynamics
| `dodecaphonic` | Automatic accidentals
| `dorian` | Key signature
| `dotsDown` | Durations
| `dotsNeutral` | Durations
| `dotsUp` | Durations
| `draw-circle` | Graphic notation inside markup
| `draw-line` | Graphic notation inside markup
| `drummode` | Instantiating new staves
| `DrumStaff` | Instantiating new staves
| `dynamic` | New dynamic marks
| `dynamicDown` | Dynamics
| `DynamicLineSpanner` | Dynamics
| `dynamicNeutral` | Dynamics
| `dynamicUp` | Dynamics
E |  |
| `easyHeadsOff` | Easy notation note heads
| `easyHeadsOn` | Easy notation note heads
| `epsfile` | Graphic notation inside markup
| `espressivo` | Dynamics
| `expandFullBarRests` | Full measure rests
| `expandFullBarRests` | Full measure rests
| `extra-offset` | Within-system spacing properties
F |  |
| `f` | Dynamics
| `featherDurations` | Feathered beams
| `fermataMarkup` | Full measure rests
| `fermataMarkup` | Full measure rests
| `ff` | Dynamics
| `fff` | Dynamics
| `ffff` | Dynamics
| `fffff` | Dynamics
| `fill-line` | Text alignment
| `filled-box` | Graphic notation inside markup
| `finger` | Fingering instructions
| `first-page-number` | `\paper` variables for page numbering
| `flag-style` | Cross-staff stems
| `followVoice` | Staff-change lines
| `font-interface` | Selecting notation font size
| `font-interface` | Fonts explained
| `font-size` | Selecting notation font size
| `font-size` | Selecting notation font size
| `fontsize` | Selecting font and font size
| `fontSize` | Selecting notation font size
| `forget` | Automatic accidentals
| `four-string-banjo` | Banjo tablatures
| `fp` | Dynamics
| `fret-diagram` | Fret diagram markups
| `fret-diagram-interface` | Fret diagram markups
| `fret-diagram-terse` | Fret diagram markups
| `fret-diagram-verbose` | Fret diagram markups
| `FretBoards` | Predefined fret diagrams
| `funkHeads` | Shape note heads
| `funkHeadsMinor` | Shape note heads
G |  |
| `general-align` | Text alignment
| `glissando` | Glissando
| `grace` | Grace notes
| `GregorianTranscriptionStaff` | Instantiating new staves
| `gridInterval` | Grid lines
| `Grid_line_span_engraver` | Grid lines
| `Grid_point_engraver` | Grid lines
| `grow-direction` | Feathered beams
H |  |
| `halign` | Text alignment
| `hbracket` | Graphic notation inside markup
| `hideKeySignature` | Bagpipe definitions
| `hideNotes` | Hidden notes
| `hideStaffSwitch` | Staff-change lines
| `horizontal-shift` | `\paper` variables for shifts and indents
| `Horizontal_bracket_engraver` | Analysis brackets
| `huge` | Selecting notation font size
| `huge` | Selecting font and font size
I |  |
| `improvisationOff` | Improvisation
| `improvisationOff` | Showing melody rhythms
| `improvisationOn` | Improvisation
| `improvisationOn` | Showing melody rhythms
| `indent` | Instrument names
| `indent` | `\paper` variables for shifts and indents
| `indent` | 4.5.4 Line length
| `inner-margin` | `\paper` variables for two-sided mode
| `instrumentSwitch` | Instrument names
| `ionian` | Key signature
| `italic` | Selecting font and font size
J |  |
| `justified-lines` | Multi-page markup
| `justify` | Text alignment
K |  |
| `key` | Key signature
| `key` | Shape note heads
| `killCues` | Formatting cue notes
L |  |
| `laissezVibrer` | Ties
| `large` | Selecting notation font size
| `large` | Selecting font and font size
| `larger` | Selecting font and font size
| `larger` | Selecting font and font size
| `last-bottom-spacing` | List of flexible vertical spacing `\paper` variables
| `layout file` | 4.2.2 Setting the staff size
| `left-align` | Text alignment
| `left-margin` | `\paper` variables for widths and margins
| `length` | Cross-staff stems
| `line-width` | `\paper` variables for widths and margins
| `line-width` | 4.5.4 Line length
| `locrian` | Key signature
| `longa` | Durations
| `longa` | Rests
| `lower` | Text alignment
| `ly:minimal-breaking` | 4.3.5 Minimal page breaking
| `ly:optimal-breaking` | 4.3.3 Optimal page breaking
| `ly:page-turn-breaking` | 4.3.4 Optimal page turning
| `lydian` | Key signature
M |  |
| `m` | Common chords
| `magnify` | Selecting font and font size
| `magstep` | Selecting notation font size
| `magstep` | 5.4.4 Distances and measurements
| `maj` | Common chords
| `major` | Key signature
| `major seven symbols` | Predefined commands
| `majorSevenSymbol` | Customizing chord names
| `make-dynamic-script` | New dynamic marks
| `make-pango-font-tree` | Entire document fonts
| `makeClusters` | Clusters
| `makeStringTuning` | Custom tablatures
| `mark` | Rehearsal marks
| `mark` | Text marks
| `markup` | Text marks
| `markup` | Separate text
| `markup` | Separate text
| `markup` | Text markup introduction
| `markup-markup-spacing` | List of flexible vertical spacing `\paper` variables
| `markup-system-spacing` | List of flexible vertical spacing `\paper` variables
| `markuplines` | Separate text
| `markuplines` | Multi-page markup
| `markuplines` | See also
| `max-systems-per-page` | `\paper` variables for line breaking
| `maxima` | Durations
| `maxima` | Rests
| `measureLength` | Setting automatic beam behavior
| `measureLength` | Time administration
| `measurePosition` | Upbeats
| `measurePosition` | Time administration
| `MensuralStaff` | Instantiating new staves
| `mergeDifferentlyDottedOff` | Collision resolution
| `mergeDifferentlyDottedOn` | Collision resolution
| `mergeDifferentlyHeadedOff` | Collision resolution
| `mergeDifferentlyHeadedOn` | Collision resolution
| `mf` | Dynamics
| `min-systems-per-page` | `\paper` variables for line breaking
| `minimum-Y-extent` | Within-system spacing properties
| `minimumFret` | Default tablatures
| `minimumFret` | Automatic fret diagrams
| `minimumPageTurnLength` | 4.3.4 Optimal page turning
| `minimumRepeatLengthForPageTurn` | 4.3.4 Optimal page turning
| `minor` | Key signature
| `mixed` | Piano pedals
| `mixolydian` | Key signature
| `modalInversion` | Modal inversion
| `modalTranspose` | Modal transposition
| `modern` | Automatic accidentals
| `modern-cautionary` | Automatic accidentals
| `modern-voice` | Automatic accidentals
| `modern-voice-cautionary` | Automatic accidentals
| `mp` | Dynamics
| `MultiMeasureRestText` | Full measure rests
| `musicglyph` | Rehearsal marks
N |  |
| `name` | 5.1.6 Defining new contexts
| `neo-modern` | Automatic accidentals
| `neo-modern-cautionary` | Automatic accidentals
| `neo-modern-voice` | Automatic accidentals
| `neo-modern-voice-cautionary` | Automatic accidentals
| `no-reset` | Automatic accidentals
| `noBeam` | Manual beams
| `nonstaff-nonstaff-spacing` | Within-system spacing properties
| `nonstaff-relatedstaff-spacing` | Within-system spacing properties
| `nonstaff-unrelatedstaff-spacing` | Within-system spacing properties
| `normalsize` | Selecting notation font size
| `normalsize` | Selecting font and font size
| `Note_heads_engraver` | Automatic note splitting
| `null` | Text alignment
| `numericTimeSignature` | Time signature
O |  |
| `octaveCheck` | Octave checks
| `oneVoice` | Single-staff polyphony
| `ottava` | Ottava brackets
| `outer-margin` | `\paper` variables for two-sided mode
| `outside-staff-horizontal-padding` | 4.4.3 Vertical collision avoidance
| `outside-staff-padding` | 4.4.3 Vertical collision avoidance
| `outside-staff-priority` | 4.4.3 Vertical collision avoidance
P |  |
| `p` | Dynamics
| `pad-around` | Graphic notation inside markup
| `pad-markup` | Graphic notation inside markup
| `pad-to-box` | Graphic notation inside markup
| `pad-x` | Graphic notation inside markup
| `page-breaking` | `\paper` variables for page breaking
| `page-breaking-system-system-spacing` | `\paper` variables for page breaking
| `page-count` | `\paper` variables for page breaking
| `page-spacing-weight` | Miscellaneous `\paper` variables
| `paper-height` | 4.1.3 Fixed vertical spacing `\paper` variables
| `paper-width` | `\paper` variables for widths and margins
| `parallelMusic` | Writing music in parallel
| `parenthesize` | Parentheses
| `partcombine` | Automatic part combining
| `partial` | Upbeats
| `pedalSustainStyle` | Piano pedals
| `percent` | Percent repeats
| `phrasingSlurDashed` | Phrasing slurs
| `phrasingSlurDashPattern` | Phrasing slurs
| `phrasingSlurDotted` | Phrasing slurs
| `phrasingSlurDown` | Phrasing slurs
| `phrasingSlurHalfDashed` | Phrasing slurs
| `phrasingSlurHalfSolid` | Phrasing slurs
| `phrasingSlurNeutral` | Phrasing slurs
| `phrasingSlurSolid` | Phrasing slurs
| `phrasingSlurUp` | Phrasing slurs
| `phrygian` | Key signature
| `piano` | Automatic accidentals
| `piano-cautionary` | Automatic accidentals
| `PianoStaff` | References for keyboards
| `PianoStaff` | Changing staff automatically
| `pipeSymbol` | Bar and bar number checks
| `pitchedTrill` | Trills
| `Pitch_squash_engraver` | Showing melody rhythms
| `postscript` | Graphic notation inside markup
| `powerChords` | Indicating power chords
| `pp` | Dynamics
| `ppp` | Dynamics
| `pppp` | Dynamics
| `ppppp` | Dynamics
| `predefinedFretboardsOff` | Automatic fret diagrams
| `predefinedFretboardsOn` | Automatic fret diagrams
| `print-all-headers` | Miscellaneous `\paper` variables
| `print-first-page-number` | `\paper` variables for page numbering
| `print-page-number` | `\paper` variables for page numbering
Q |  |
| `quotedCueEventTypes` | Selected Snippets
| `quotedEventTypes` | Selected Snippets
| `quoteDuring` | Quoting other voices
| `quoteDuring` | Formatting cue notes
R |  |
| `r` | Rests
| `R` | Full measure rests
| `ragged-bottom` | 4.1.3 Fixed vertical spacing `\paper` variables
| `ragged-last` | `\paper` variables for widths and margins
| `ragged-last` | 4.5.4 Line length
| `ragged-last-bottom` | 4.1.3 Fixed vertical spacing `\paper` variables
| `ragged-right` | `\paper` variables for widths and margins
| `ragged-right` | 4.5.4 Line length
| `raise` | Text alignment
| `relative` | Relative octave entry
| `relative` | See also
| `relative` | See also
| `relative` | Changing staff automatically
| `repeatCommands` | Manual repeat marks
| `repeatTie` | Ties
| `rest` | Rests
| `retrograde` | Retrograde
| `rfz` | Dynamics
| `rgb-color` | Coloring objects
| `RhythmicStaff` | Instantiating new staves
| `right-align` | Text alignment
| `right-margin` | `\paper` variables for widths and margins
| `rightHandFinger` | Right-hand fingerings
| `rounded-box` | Graphic notation inside markup
S |  |
| `s` | Invisible rests
| `sacredHarpHeads` | Shape note heads
| `sacredHarpHeadsMinor` | Shape note heads
| `scaleDurations` | Scaling durations
| `scaleDurations` | Polymetric notation
| `score-markup-spacing` | List of flexible vertical spacing `\paper` variables
| `score-system-spacing` | List of flexible vertical spacing `\paper` variables
| `self-alignment-X` | Within-system spacing properties
| `set` | Setting automatic beam behavior
| `set-accidental-style` | Automatic accidentals
| `set-octavation` | Ottava brackets
| `sf` | Dynamics
| `sff` | Dynamics
| `sfz` | Dynamics
| `shiftOff` | Collision resolution
| `shiftOn` | Collision resolution
| `shiftOnn` | Collision resolution
| `shiftOnnn` | Collision resolution
| `short-indent` | Instrument names
| `short-indent` | `\paper` variables for shifts and indents
| `show-available-fonts` | Single entry fonts
| `showFirstLength` | 3.4.2 Skipping corrected music
| `showKeySignature` | Bagpipe definitions
| `showLastLength` | 3.4.2 Skipping corrected music
| `showStaffSwitch` | Staff-change lines
| `skip` | Invisible rests
| `skipTypesetting` | 3.4.2 Skipping corrected music
| `slurDashed` | Slurs
| `slurDashPattern` | Slurs
| `slurDotted` | Slurs
| `slurDown` | Slurs
| `slurHalfDashed` | Slurs
| `slurHalfSolid` | Slurs
| `slurNeutral` | Slurs
| `slurSolid` | Slurs
| `slurUp` | Slurs
| `small` | Selecting notation font size
| `small` | Selecting font and font size
| `smaller` | Selecting font and font size
| `smaller` | Selecting font and font size
| `sostenutoOff` | Piano pedals
| `sostenutoOn` | Piano pedals
| `southernHarmonyHeads` | Shape note heads
| `southernHarmonyHeadsMinor` | Shape note heads
| `sp` | Dynamics
| `spacing` | 4.5.1 Horizontal spacing overview
| `spp` | Dynamics
| `staff-affinity` | Within-system spacing properties
| `staff-staff-spacing` | Within-system spacing properties
| `Staff.midiInstrument` | Instrument names
| `staffgroup-staff-spacing` | Within-system spacing properties
| `Staff_symbol_engraver` | Hiding staves
| `start-repeat` | Manual repeat marks
| `startGroup` | Analysis brackets
| `startStaff` | Staff symbol
| `startStaff` | Ossia staves
| `startTrillSpan` | Trills
| `Stem` | Cross-staff stems
| `stem-spacing-correction` | 4.5.1 Horizontal spacing overview
| `stemDown` | Stems
| `stemLeftBeamCount` | Manual beams
| `stemNeutral` | Stems
| `stemRightBeamCount` | Manual beams
| `stemUp` | Stems
| `stopGroup` | Analysis brackets
| `stopStaff` | Staff symbol
| `stopStaff` | Ossia staves
| `stopStaff` | Hiding staves
| `stopTrillSpan` | Trills
| `storePredefinedDiagram` | Predefined fret diagrams
| `StringTunings` | Custom tablatures
| `stringTunings` | Predefined fret diagrams
| `sub` | Selecting font and font size
| `suggestAccidentals` | Annotational accidentals (musica ficta)
| `super` | Selecting font and font size
| `sus` | Extended and altered chords
| `sustainOff` | Piano pedals
| `sustainOn` | Piano pedals
| `system-count` | `\paper` variables for line breaking
| `system-separator-markup` | Miscellaneous `\paper` variables
| `system-system-spacing` | List of flexible vertical spacing `\paper` variables
| `systems-per-page` | `\paper` variables for line breaking
T |  |
| `TabStaff` | Instantiating new staves
| `TabStaff` | Default tablatures
| `TabVoice` | Default tablatures
| `taor` | Bagpipe definitions
| `teaching` | Automatic accidentals
| `teeny` | Selecting notation font size
| `teeny` | Selecting font and font size
| `tempo` | Metronome marks
| `text` | Piano pedals
| `textLengthOff` | Full measure rests
| `textLengthOff` | Text scripts
| `textLengthOn` | Full measure rests
| `textLengthOn` | Text scripts
| `textSpannerDown` | Text spanners
| `textSpannerNeutral` | Text spanners
| `textSpannerUp` | Text spanners
| `thumb` | Fingering instructions
| `tieDashed` | Ties
| `tieDotted` | Ties
| `tieDown` | Ties
| `tieNeutral` | Ties
| `tieSolid` | Ties
| `tieUp` | Ties
| `time` | Time signature
| `time` | Setting automatic beam behavior
| `times` | Tuplets
| `times` | Polymetric notation
| `timeSignatureFraction` | Polymetric notation
| `tiny` | Selecting notation font size
| `tiny` | Selecting font and font size
| `top-margin` | 4.1.3 Fixed vertical spacing `\paper` variables
| `top-markup-spacing` | List of flexible vertical spacing `\paper` variables
| `top-system-spacing` | List of flexible vertical spacing `\paper` variables
| `translate` | Text alignment
| `translate-scaled` | Text alignment
| `transpose` | See also
| `transpose` | Transpose
| `transpose` | See also
| `transposedCueDuring` | Formatting cue notes
| `transposition` | Instrument transpositions
| `transposition` | Quoting other voices
| `treCorde` | Piano pedals
| `tremolo` | Tremolo repeats
| `tremoloFlags` | Tremolo repeats
| `triangle` | Graphic notation inside markup
| `trill` | Trills
| `tupletDown` | Tuplets
| `tupletNeutral` | Tuplets
| `TupletNumber` | Selected Snippets
| `tupletNumberFormatFunction` | Selected Snippets
| `tupletSpannerDuration` | Selected Snippets
| `tupletUp` | Tuplets
| `two-sided` | `\paper` variables for two-sided mode
| `type` | 5.1.6 Defining new contexts
U |  |
| `unaCorda` | Piano pedals
| `underline` | Selecting font and font size
| `unfold` | Written-out repeats
| `unHideNotes` | Hidden notes
V |  |
| `VaticanaStaff` | Instantiating new staves
| `VerticalAxisGroup` | Within-system spacing properties
| `voice` | Automatic accidentals
| `Voice` | Single-staff polyphony
| `voice` | Automatic accidentals
| `voiceOne` | Single-staff polyphony
W |  |
| `walkerHeads` | Shape note heads
| `walkerHeadsMinor` | Shape note heads
| `whichBar` | Selected Snippets
| `with-color` | Coloring objects
| `wordwrap` | Text alignment
| `wordwrap-lines` | Multi-page markup
X |  |
| `X-offset` | Within-system spacing properties
| `x11-color` | Coloring objects
| `x11-color` | See also

Jump to: | ! ' , - . / : < = > ? [ \ ] ^ _ | ~ A B C D E F G H I J K L M N O P Q R S T U V W X

# F. LilyPond index

In addition to all the LilyPond commands and keywords, this index lists musical terms and words which relate to each of them, with links to those sections of the manual which describe or discuss that topic. Each link is in two parts. The first part points to the exact location in the manual where the topic appears; the second part points to the start of the section of the manual where that topic is discussed.

Jump to: | ! ' , - . / 1 8 : < = > ? [ \ ] ^ _ | ~ A B C D E F G H I J K L M N O P Q R S T U V W X

| Index Entry | Section
! |  |
| `!` | Accidentals
' |  |
| `'` | Absolute octave entry
, |  |
| `,` | Absolute octave entry
- |  |
| `-` | Articulations and ornamentations
. |  |
| `.` | Durations
/ |  |
| `/` | Extended and altered chords
| `/+` | Extended and altered chords
1 |  |
| 15ma | Ottava brackets
8 |  |
| 8va | Ottava brackets
| 8ve | Ottava brackets
: |  |
| `:` | Tremolo repeats
< |  |
| `<` | Chorded notes
| `<...>` | Chorded notes
= |  |
| `=` | Octave checks
> |  |
| `>` | Chorded notes
? |  |
| `?` | Accidentals
[ |  |
| `[` | Manual beams
\ |  |
| `\!` | Dynamics
| `\(` | Phrasing slurs
| `\)` | Phrasing slurs
| `\<` | Dynamics
| `\>` | Dynamics
| `\abs-fontsize` | A.9.1 Font
| `\accent` | Articulations and ornamentations
| `\accepts` | 5.1.6 Defining new contexts
| `\accepts` | 5.1.6 Defining new contexts
| `\accepts` | 5.1.7 Aligning contexts
| `\addChordShape` | Predefined fret diagrams
| `\addInstrumentDefinition` | Instrument names
| `\addlyrics` | Aligning lyrics to a melody
| `\addlyrics` | Automatic syllable durations
| `\addlyrics` | Using `\addlyrics`
| `\addQuote` | Quoting other voices
| `\aeolian` | Key signature
| `\afterGrace` | Grace notes
| `\aikenHeads` | Shape note heads
| `\aikenHeadsMinor` | Shape note heads
| `\alias` | 5.1.6 Defining new contexts
| `\allowPageTurn` | Predefined commands
| `\alternative` | 1.4.1 Long repeats
| `\arpeggio` | Arpeggio
| `\arpeggioArrowDown` | Arpeggio
| `\arpeggioArrowUp` | Arpeggio
| `\arpeggioBracket` | Arpeggio
| `\arpeggioNormal` | Arpeggio
| `\arpeggioParenthesis` | Arpeggio
| `\arpeggioParenthesisDashed` | Arpeggio
| `\arrow-head` | Graphic notation inside markup
| `\arrow-head` | A.9.3 Graphic
| `\ascendens` | Gregorian square neume ligatures
| `\ascendens` | Predefined commands
| `\auctum` | Gregorian square neume ligatures
| `\auctum` | Predefined commands
| `\augmentum` | Predefined commands
| `\autoBeamOff` | Automatic beams
| `\autoBeamOn` | Automatic beams
| `\autochange` | Changing staff automatically
| `\backslashed-digit` | A.9.6 Other
| `\balloonGrobText` | Balloon help
| `\balloonLengthOff` | Balloon help
| `\balloonLengthOn` | Balloon help
| `\balloonText` | Balloon help
| `\bar` | Bar lines
| `\bar` | Selected Snippets
| `\barNumberCheck` | Bar and bar number checks
| `\beam` | A.9.3 Graphic
| `\bendAfter` | Falls and doits
| `\bold` | Selecting font and font size
| `\bold` | A.9.1 Font
| `\book` | 3.1.2 Multiple scores in a book
| `\book` | 3.1.2 Multiple scores in a book
| `\book` | 3.1.5 File structure
| `\bookOutputName` | 3.1.4 Output file names
| `\bookOutputSuffix` | 3.1.4 Output file names
| `\bookpart` | 3.1.2 Multiple scores in a book
| `\bookpart` | 3.1.5 File structure
| `\bookpart` | 4.3.2 Page breaking
| `\box` | Graphic notation inside markup
| `\box` | A.9.1 Font
| `\bracket` | New dynamic marks
| `\bracket` | Graphic notation inside markup
| `\bracket` | A.9.3 Graphic
| `\break` | Predefined commands
| `\breathe` | Breath marks
| `\breve` | Durations
| `\breve` | Rests
| `\cadenzaOff` | Unmetered music
| `\cadenzaOn` | Unmetered music
| `\caesura` | Predefined commands
| `\caps` | A.9.1 Font
| `\cavum` | Gregorian square neume ligatures
| `\cavum` | Predefined commands
| `\center-align` | Text alignment
| `\center-align` | A.9.2 Align
| `\center-column` | Text alignment
| `\center-column` | A.9.2 Align
| `\change` | Changing staff manually
| `\char` | A.9.6 Other
| `\chordGlissando` | Default tablatures
| `\chordmode` | See also
| `\chordmode` | See also
| `\chordmode` | Predefined fret diagrams
| `\circle` | Graphic notation inside markup
| `\circle` | A.9.3 Graphic
| `\clef` | Clef
| `\cm` | 5.4.4 Distances and measurements
| `\coda` | Articulations and ornamentations
| `\column` | Text alignment
| `\column` | A.9.2 Align
| `\column-lines` | A.10 Text markup list commands
| `\combine` | Graphic notation inside markup
| `\combine` | A.9.2 Align
| `\compressFullBarRests` | Full measure rests
| `\compressFullBarRests` | Full measure rests
| `\concat` | A.9.2 Align
| `\consists` | 5.1.6 Defining new contexts
| `\context` | 5.1.2 Creating contexts
| `\contextStringTunings` | Custom tablatures
| `\cr` | Dynamics
| `\cresc` | Dynamics
| `\crescHairpin` | Dynamics
| `\crescTextCresc` | Dynamics
| `\cueDuring` | Formatting cue notes
| `\customTabClef` | A.9.4 Music
| `\decr` | Dynamics
| `\decresc` | Dynamics
| `\defaultTimeSignature` | Time signature
| `\deminutum` | Gregorian square neume ligatures
| `\deminutum` | Predefined commands
| `\denies` | 5.1.6 Defining new contexts
| `\denies` | 5.1.6 Defining new contexts
| `\denies` | 5.1.7 Aligning contexts
| `\descendens` | Gregorian square neume ligatures
| `\descendens` | Predefined commands
| `\dim` | Dynamics
| `\dimHairpin` | Dynamics
| `\dimTextDecr` | Dynamics
| `\dimTextDecresc` | Dynamics
| `\dimTextDim` | Dynamics
| `\dir-column` | A.9.2 Align
| `\displayLilyMusic` | 3.3.4 Displaying LilyPond notation
| `\divisioMaior` | Predefined commands
| `\divisioMaxima` | Predefined commands
| `\divisioMinima` | Predefined commands
| `\dorian` | Key signature
| `\dotsDown` | Durations
| `\dotsNeutral` | Durations
| `\dotsUp` | Durations
| `\doubleflat` | A.9.4 Music
| `\doublesharp` | A.9.4 Music
| `\downbow` | Articulations and ornamentations
| `\downbow` | Bowing indications
| `\downmordent` | Articulations and ornamentations
| `\downprall` | Articulations and ornamentations
| `\draw-circle` | Graphic notation inside markup
| `\draw-circle` | A.9.3 Graphic
| `\draw-hline` | A.9.3 Graphic
| `\draw-line` | Graphic notation inside markup
| `\draw-line` | A.9.3 Graphic
| `\drummode` | Instantiating new staves
| `\dynamic` | New dynamic marks
| `\dynamic` | A.9.1 Font
| `\dynamicDown` | Dynamics
| `\dynamicNeutral` | Dynamics
| `\dynamicUp` | Dynamics
| `\easyHeadsOff` | Easy notation note heads
| `\easyHeadsOn` | Easy notation note heads
| `\epsfile` | Graphic notation inside markup
| `\epsfile` | A.9.3 Graphic
| `\espressivo` | Articulations and ornamentations
| `\espressivo` | Dynamics
| `\expandFullBarRests` | Full measure rests
| `\expandFullBarRests` | Full measure rests
| `\eyeglasses` | A.9.6 Other
| `\f` | Dynamics
| `\featherDurations` | Feathered beams
| `\fermata` | Articulations and ornamentations
| `\fermataMarkup` | Full measure rests
| `\fermataMarkup` | Full measure rests
| `\fermataMarkup` | Articulations and ornamentations
| `\ff` | Dynamics
| `\fff` | Dynamics
| `\ffff` | Dynamics
| `\fffff` | Dynamics
| `\fill-line` | Text alignment
| `\fill-line` | A.9.2 Align
| `\fill-with-pattern` | A.9.2 Align
| `\filled-box` | Graphic notation inside markup
| `\filled-box` | A.9.3 Graphic
| `\finalis` | Predefined commands
| `\finger` | Fingering instructions
| `\finger` | A.9.1 Font
| `\flageolet` | Articulations and ornamentations
| `\flat` | A.9.4 Music
| `\flexa` | Predefined commands
| `\fontCaps` | A.9.1 Font
| `\fontsize` | Selecting font and font size
| `\fontsize` | A.9.1 Font
| `\footnote` | A.9.6 Other
| `\fp` | Dynamics
| `\fraction` | A.9.6 Other
| `\frenchChords` | Predefined commands
| `\fret-diagram` | Fret diagram markups
| `\fret-diagram` | A.9.5 Instrument Specific Markup
| `\fret-diagram-terse` | Fret diagram markups
| `\fret-diagram-terse` | A.9.5 Instrument Specific Markup
| `\fret-diagram-verbose` | Fret diagram markups
| `\fret-diagram-verbose` | A.9.5 Instrument Specific Markup
| `\fromproperty` | A.9.6 Other
| `\funkHeads` | Shape note heads
| `\funkHeadsMinor` | Shape note heads
| `\general-align` | Text alignment
| `\general-align` | A.9.2 Align
| `\germanChords` | Predefined commands
| `\glissando` | Glissando
| `\grace` | Grace notes
| `\halfopen` | Articulations and ornamentations
| `\halign` | Text alignment
| `\halign` | A.9.2 Align
| `\harmonic` | Harmonics
| `\harmonic` | Default tablatures
| `\harmonicByFret` | Default tablatures
| `\harmonicByRatio` | Default tablatures
| `\harmonicsOff` | Harmonics
| `\harmonicsOn` | Harmonics
| `\harp-pedal` | A.9.5 Instrument Specific Markup
| `\hbracket` | Graphic notation inside markup
| `\hbracket` | A.9.3 Graphic
| `\hcenter-in` | A.9.2 Align
| `\header` | 3.1.5 File structure
| `\hideKeySignature` | Bagpipe definitions
| `\hideNotes` | Hidden notes
| `\hideSplitTiedTabNotes` | Default tablatures
| `\hideStaffSwitch` | Staff-change lines
| `\hspace` | A.9.2 Align
| `\huge` | Selecting notation font size
| `\huge` | Selecting font and font size
| `\huge` | A.9.1 Font
| `\improvisationOff` | Improvisation
| `\improvisationOff` | Showing melody rhythms
| `\improvisationOn` | Improvisation
| `\improvisationOn` | Showing melody rhythms
| `\in` | 5.4.4 Distances and measurements
| `\inclinatum` | Gregorian square neume ligatures
| `\inclinatum` | Predefined commands
| `\include` | 3.3.1 Including LilyPond files
| `\instrumentSwitch` | Instrument names
| `\inversion` | Inversion
| `\ionian` | Key signature
| `\italianChords` | Predefined commands
| `\italic` | Selecting font and font size
| `\italic` | A.9.1 Font
| `\justified-lines` | Multi-page markup
| `\justified-lines` | A.10 Text markup list commands
| `\justify` | Text alignment
| `\justify` | A.9.2 Align
| `\justify-field` | A.9.2 Align
| `\justify-string` | A.9.2 Align
| `\keepWithTag` | Using tags
| `\key` | Key signature
| `\key` | Shape note heads
| `\killCues` | Formatting cue notes
| `\label` | Predefined commands
| `\laissezVibrer` | Ties
| `\large` | Selecting notation font size
| `\large` | Selecting font and font size
| `\large` | A.9.1 Font
| `\larger` | Selecting font and font size
| `\larger` | Selecting font and font size
| `\larger` | A.9.1 Font
| `\layout` | 3.1.5 File structure
| `\layout` | 4.2.1 The `\layout` block
| `\left-align` | Text alignment
| `\left-align` | A.9.2 Align
| `\left-brace` | A.9.6 Other
| `\left-column` | A.9.2 Align
| `\lheel` | Articulations and ornamentations
| `\line` | A.9.2 Align
| `\linea` | Gregorian square neume ligatures
| `\linea` | Predefined commands
| `\lineprall` | Articulations and ornamentations
| `\locrian` | Key signature
| `\longa` | Durations
| `\longa` | Rests
| `\longfermata` | Articulations and ornamentations
| `\lookup` | A.9.6 Other
| `\lower` | Text alignment
| `\lower` | A.9.2 Align
| `\ltoe` | Articulations and ornamentations
| `\lydian` | Key signature
| `\lyricmode` | Entering lyrics
| `\lyricmode` | Aligning lyrics to a melody
| `\lyricsto` | Aligning lyrics to a melody
| `\lyricsto` | Automatic syllable durations
| `\lyricsto` | Using `\lyricsto`
| `\magnify` | Selecting font and font size
| `\magnify` | A.9.1 Font
| `\major` | Key signature
| `\makeClusters` | Clusters
| `\makeStringTuning` | Custom tablatures
| `\marcato` | Articulations and ornamentations
| `\mark` | Rehearsal marks
| `\mark` | Text marks
| `\markalphabet` | A.9.6 Other
| `\markletter` | A.9.6 Other
| `\markup` | Text marks
| `\markup` | Separate text
| `\markup` | Separate text
| `\markup` | Text markup introduction
| `\markuplines` | Separate text
| `\markuplines` | Multi-page markup
| `\markuplines` | See also
| `\maxima` | Durations
| `\maxima` | Rests
| `\medium` | A.9.1 Font
| `\melisma` | Multiple notes to one syllable
| `\melismaEnd` | Multiple notes to one syllable
| `\mergeDifferentlyDottedOff` | Collision resolution
| `\mergeDifferentlyDottedOn` | Collision resolution
| `\mergeDifferentlyHeadedOff` | Collision resolution
| `\mergeDifferentlyHeadedOn` | Collision resolution
| `\mf` | Dynamics
| `\midi` | 3.1.5 File structure
| `\minor` | Key signature
| `\mixolydian` | Key signature
| `\mm` | 5.4.4 Distances and measurements
| `\modalInversion` | Modal inversion
| `\modalTranspose` | Modal transposition
| `\mordent` | Articulations and ornamentations
| `\mp` | Dynamics
| `\musicglyph` | Rehearsal marks
| `\musicglyph` | A.9.4 Music
| `\name` | 5.1.6 Defining new contexts
| `\natural` | A.9.4 Music
| `\new` | 5.1.2 Creating contexts
| `\noBeam` | Manual beams
| `\noBreak` | Predefined commands
| `\noPageBreak` | Predefined commands
| `\noPageTurn` | Predefined commands
| `\normal-size-sub` | A.9.1 Font
| `\normal-size-super` | A.9.1 Font
| `\normal-text` | A.9.1 Font
| `\normalsize` | Selecting notation font size
| `\normalsize` | Selecting font and font size
| `\normalsize` | A.9.1 Font
| `\note` | A.9.4 Music
| `\note-by-number` | A.9.4 Music
| `\null` | Text alignment
| `\null` | A.9.6 Other
| `\number` | A.9.1 Font
| `\numericTimeSignature` | Time signature
| `\octaveCheck` | Octave checks
| `\on-the-fly` | A.9.6 Other
| `\once` | 5.3.3 The `\override` command
| `\oneVoice` | Single-staff polyphony
| `\open` | Articulations and ornamentations
| `\open` | Bowing indications
| `\oriscus` | Gregorian square neume ligatures
| `\oriscus` | Predefined commands
| `\ottava` | Ottava brackets
| `\override` | See also
| `\override` | A.9.6 Other
| `\override in \lyricmode` | Entering lyrics
| `\override-lines` | A.10 Text markup list commands
| `\overrideTimeSignatureSettings` | Time signature
| `\p` | Dynamics
| `\pad-around` | Graphic notation inside markup
| `\pad-around` | A.9.2 Align
| `\pad-markup` | Graphic notation inside markup
| `\pad-markup` | A.9.2 Align
| `\pad-to-box` | Graphic notation inside markup
| `\pad-to-box` | A.9.2 Align
| `\pad-x` | Graphic notation inside markup
| `\pad-x` | A.9.2 Align
| `\page-link` | A.9.6 Other
| `\page-ref` | Predefined commands
| `\page-ref` | A.9.6 Other
| `\pageBreak` | Predefined commands
| `\pageTurn` | Predefined commands
| `\paper` | 3.1.5 File structure
| `\paper` | 4.1.2 Paper size and automatic scaling
| `\parallelMusic` | Writing music in parallel
| `\parenthesize` | Parentheses
| `\parenthesize` | A.9.3 Graphic
| `\partcombine` | Automatic part combining
| `\partial` | Upbeats
| `\partial` | 1.4.1 Long repeats
| `\partial` | Normal repeats
| `\path` | A.9.3 Graphic
| `\pattern` | A.9.6 Other
| `\pes` | Predefined commands
| `\phrasingSlurDashed` | Phrasing slurs
| `\phrasingSlurDashPattern` | Phrasing slurs
| `\phrasingSlurDotted` | Phrasing slurs
| `\phrasingSlurDown` | Phrasing slurs
| `\phrasingSlurHalfDashed` | Phrasing slurs
| `\phrasingSlurHalfSolid` | Phrasing slurs
| `\phrasingSlurNeutral` | Phrasing slurs
| `\phrasingSlurSolid` | Phrasing slurs
| `\phrasingSlurUp` | Phrasing slurs
| `\phrygian` | Key signature
| `\pitchedTrill` | Trills
| `\portato` | Articulations and ornamentations
| `\postscript` | Graphic notation inside markup
| `\postscript` | A.9.3 Graphic
| `\powerChords` | Indicating power chords
| `\pp` | Dynamics
| `\ppp` | Dynamics
| `\pppp` | Dynamics
| `\ppppp` | Dynamics
| `\prall` | Articulations and ornamentations
| `\pralldown` | Articulations and ornamentations
| `\prallmordent` | Articulations and ornamentations
| `\prallprall` | Articulations and ornamentations
| `\prallup` | Articulations and ornamentations
| `\predefinedFretboardsOff` | Automatic fret diagrams
| `\predefinedFretboardsOn` | Automatic fret diagrams
| `\pt` | 5.4.4 Distances and measurements
| `\put-adjacent` | A.9.2 Align
| `\quilisma` | Gregorian square neume ligatures
| `\quilisma` | Predefined commands
| `\quoteDuring` | Quoting other voices
| `\quoteDuring` | Formatting cue notes
| `\raise` | Text alignment
| `\raise` | A.9.2 Align
| `\relative` | Relative octave entry
| `\relative` | See also
| `\relative` | See also
| `\relative` | Changing staff automatically
| `\RemoveEmptyStaves` | Hiding staves
| `\RemoveEmptyStaves` | Hiding staves
| `\removeWithTag` | Using tags
| `\repeat` | 1.4.1 Long repeats
| `\repeat percent` | Percent repeats
| `\repeat tremolo` | Tremolo repeats
| `\repeatTie` | Ties
| `\repeatTie` | Normal repeats
| `\repeatTie` | Repeats with alternative endings
| `\rest` | Rests
| `\retrograde` | Retrograde
| `\reverseturn` | Articulations and ornamentations
| `\revert` | 5.3.3 The `\override` command
| `\revertTimeSignatureSettings` | Time signature
| `\rfz` | Dynamics
| `\rheel` | Articulations and ornamentations
| `\right-align` | Text alignment
| `\right-align` | A.9.2 Align
| `\right-brace` | A.9.6 Other
| `\right-column` | A.9.2 Align
| `\rightHandFinger` | Right-hand fingerings
| `\roman` | A.9.1 Font
| `\rotate` | A.9.2 Align
| `\rounded-box` | Graphic notation inside markup
| `\rounded-box` | A.9.3 Graphic
| `\rtoe` | Articulations and ornamentations
| `\sacredHarpHeads` | Shape note heads
| `\sacredHarpHeadsMinor` | Shape note heads
| `\sans` | A.9.1 Font
| `\scale` | A.9.3 Graphic
| `\scaleDurations` | Scaling durations
| `\scaleDurations` | Polymetric notation
| `\score` | 3.1.1 Structure of a score
| `\score` | 3.1.5 File structure
| `\score` | A.9.4 Music
| `\segno` | Articulations and ornamentations
| `\semiflat` | A.9.4 Music
| `\semiGermanChords` | Predefined commands
| `\semisharp` | A.9.4 Music
| `\sesquiflat` | A.9.4 Music
| `\sesquisharp` | A.9.4 Music
| `\set` | Setting automatic beam behavior
| `\set` | 5.3.2 The `\set` command
| `\sf` | Dynamics
| `\sff` | Dynamics
| `\sfz` | Dynamics
| `\sharp` | A.9.4 Music
| `\shiftOff` | Collision resolution
| `\shiftOn` | Collision resolution
| `\shiftOnn` | Collision resolution
| `\shiftOnnn` | Collision resolution
| `\shortfermata` | Articulations and ornamentations
| `\showKeySignature` | Bagpipe definitions
| `\showStaffSwitch` | Staff-change lines
| `\signumcongruentiae` | Articulations and ornamentations
| `\simple` | A.9.1 Font
| `\skip` | Invisible rests
| `\skip` | Repeats with alternative endings
| `\slashed-digit` | A.9.6 Other
| `\slurDashed` | Slurs
| `\slurDashPattern` | Slurs
| `\slurDotted` | Slurs
| `\slurDown` | Slurs
| `\slurHalfDashed` | Slurs
| `\slurHalfSolid` | Slurs
| `\slurNeutral` | Slurs
| `\slurSolid` | Slurs
| `\slurUp` | Slurs
| `\small` | Selecting notation font size
| `\small` | Selecting font and font size
| `\small` | A.9.1 Font
| `\smallCaps` | A.9.1 Font
| `\smaller` | Selecting font and font size
| `\smaller` | Selecting font and font size
| `\smaller` | A.9.1 Font
| `\snappizzicato` | Articulations and ornamentations
| `\sostenutoOff` | Piano pedals
| `\sostenutoOn` | Piano pedals
| `\southernHarmonyHeads` | Shape note heads
| `\southernHarmonyHeadsMinor` | Shape note heads
| `\sp` | Dynamics
| `\spp` | Dynamics
| `\staccatissimo` | Articulations and ornamentations
| `\staccato` | Articulations and ornamentations
| `\startGroup` | Analysis brackets
| `\startStaff` | Staff symbol
| `\startStaff` | Ossia staves
| `\startTrillSpan` | Trills
| `\stemDown` | Stems
| `\stemNeutral` | Stems
| `\stemUp` | Stems
| `\stencil` | A.9.6 Other
| `\stopGroup` | Analysis brackets
| `\stopped` | Articulations and ornamentations
| `\stopStaff` | Staff symbol
| `\stopStaff` | Ossia staves
| `\stopStaff` | Hiding staves
| `\stopTrillSpan` | Trills
| `\storePredefinedDiagram` | Predefined fret diagrams
| `\stropha` | Gregorian square neume ligatures
| `\stropha` | Predefined commands
| `\strut` | A.9.6 Other
| `\sub` | Selecting font and font size
| `\sub` | A.9.1 Font
| `\super` | Selecting font and font size
| `\super` | A.9.1 Font
| `\sustainOff` | Piano pedals
| `\sustainOn` | Piano pedals
| `\tabChordRepetition` | Default tablatures
| `\tabFullNotation` | Default tablatures
| `\table-of-contents` | Predefined commands
| `\table-of-contents` | A.10 Text markup list commands
| `\tag` | Using tags
| `\taor` | Bagpipe definitions
| `\teeny` | Selecting notation font size
| `\teeny` | Selecting font and font size
| `\teeny` | A.9.1 Font
| `\tempo` | Metronome marks
| `\tenuto` | Articulations and ornamentations
| `\text` | A.9.1 Font
| `\textLengthOff` | Full measure rests
| `\textLengthOff` | Text scripts
| `\textLengthOn` | Full measure rests
| `\textLengthOn` | Text scripts
| `\textSpannerDown` | Text spanners
| `\textSpannerNeutral` | Text spanners
| `\textSpannerUp` | Text spanners
| `\thumb` | Articulations and ornamentations
| `\thumb` | Fingering instructions
| `\tied-lyric` | A.9.4 Music
| `\tieDashed` | Ties
| `\tieDotted` | Ties
| `\tieDown` | Ties
| `\tieNeutral` | Ties
| `\tieSolid` | Ties
| `\tieUp` | Ties
| `\time` | Time signature
| `\time` | Setting automatic beam behavior
| `\times` | Tuplets
| `\times` | Polymetric notation
| `\tiny` | Selecting notation font size
| `\tiny` | Selecting font and font size
| `\tiny` | A.9.1 Font
| `\tocItem` | Predefined commands
| `\translate` | Text alignment
| `\translate` | A.9.2 Align
| `\translate-scaled` | Text alignment
| `\translate-scaled` | A.9.2 Align
| `\transparent` | A.9.6 Other
| `\transpose` | See also
| `\transpose` | Transpose
| `\transpose` | See also
| `\transposedCueDuring` | Formatting cue notes
| `\transposition` | Instrument transpositions
| `\transposition` | Quoting other voices
| `\treCorde` | Piano pedals
| `\triangle` | Graphic notation inside markup
| `\triangle` | A.9.3 Graphic
| `\trill` | Articulations and ornamentations
| `\trill` | Trills
| `\tupletDown` | Tuplets
| `\tupletNeutral` | Tuplets
| `\tupletUp` | Tuplets
| `\turn` | Articulations and ornamentations
| `\tweak` | 5.3.4 The `\tweak` command
| `\type` | 5.1.6 Defining new contexts
| `\typewriter` | A.9.1 Font
| `\unaCorda` | Piano pedals
| `\underline` | Selecting font and font size
| `\underline` | A.9.1 Font
| `\unfoldRepeats` | 3.5.4 Repeats in MIDI
| `\unHideNotes` | Hidden notes
| `\unset` | 5.3.2 The `\set` command
| `\upbow` | Articulations and ornamentations
| `\upbow` | Bowing indications
| `\upmordent` | Articulations and ornamentations
| `\upprall` | Articulations and ornamentations
| `\upright` | A.9.1 Font
| `\varcoda` | Articulations and ornamentations
| `\vcenter` | A.9.2 Align
| `\verbatim-file` | A.9.6 Other
| `\verylongfermata` | Articulations and ornamentations
| `\virga` | Gregorian square neume ligatures
| `\virga` | Predefined commands
| `\virgula` | Predefined commands
| `\voiceFourStyle` | Voice styles
| `\voiceNeutralStyle` | Voice styles
| `\voiceOne` | Single-staff polyphony
| `\voiceOne ... \voiceFour` | Single-staff polyphony
| `\voiceOneStyle` | Voice styles
| `\voiceThreeStyle` | Voice styles
| `\voiceTwoStyle` | Voice styles
| `\vspace` | A.9.2 Align
| `\walkerHeads` | Shape note heads
| `\walkerHeadsMinor` | Shape note heads
| `\whiteout` | A.9.6 Other
| `\with` | 5.1.4 Modifying context plug-ins
| `\with-color` | Coloring objects
| `\with-color` | A.9.6 Other
| `\with-dimensions` | A.9.6 Other
| `\with-link` | A.9.6 Other
| `\with-url` | A.9.3 Graphic
| `\woodwind-diagram` | A.9.5 Instrument Specific Markup
| `\wordwrap` | Text alignment
| `\wordwrap` | A.9.2 Align
| `\wordwrap-field` | A.9.2 Align
| `\wordwrap-internal` | A.10 Text markup list commands
| `\wordwrap-lines` | Multi-page markup
| `\wordwrap-lines` | A.10 Text markup list commands
| `\wordwrap-string` | A.9.2 Align
| `\wordwrap-string-internal` | A.10 Text markup list commands
] |  |
| `]` | Manual beams
^ |  |
| `^` | Extended and altered chords
_ |  |
| `_` | Multiple syllables to one note
| `|` | Bar and bar number checks
| `|` | Bar and bar number checks
~ |  |
| `~` | Ties
A |  |
| `a due` | See also
| a due part | Automatic part combining
| absolute | Absolute octave entry
| absolute dynamics | Dynamics
| absolute octave entry | Absolute octave entry
| absolute octave specification | Absolute octave entry
| accelerando in MIDI | Supported in MIDI
| `accent` | See also
| accent | A.11 List of articulations
| accentus | A.11 List of articulations
| `accepts` | 5.1.6 Defining new contexts
| `acciaccatura` | A.16 Available music functions
| acciaccatura, multi-note | Known issues and warnings
| `Accidental` | See also
| `accidental` | See also
| `Accidental` | See also
| `accidental` | See also
| accidental on tied note | Accidentals
| accidental style | Automatic accidentals
| accidental style, cautionary, modern voice | Automatic accidentals
| accidental style, default | Automatic accidentals
| accidental style, default | Automatic accidentals
| accidental style, forget | Automatic accidentals
| accidental style, modern | Automatic accidentals
| accidental style, modern | Automatic accidentals
| accidental style, modern voice cautionary | Automatic accidentals
| accidental style, modern-cautionary | Automatic accidentals
| accidental style, neo-modern | Automatic accidentals
| accidental style, neo-modern-cautionary | Automatic accidentals
| accidental style, neo-modern-voice | Automatic accidentals
| accidental style, neo-modern-voice-cautionary | Automatic accidentals
| accidental style, no reset | Automatic accidentals
| accidental style, piano | Automatic accidentals
| accidental style, piano cautionary | Automatic accidentals
| accidental style, teaching | Automatic accidentals
| accidental style, voice | Automatic accidentals
| accidental style, voice, modern cautionary | Automatic accidentals
| accidental, cautionary | Accidentals
| Accidental, musica ficta | Annotational accidentals (musica ficta)
| accidental, parenthesized | Accidentals
| accidental, quarter-tone | See also
| accidental, reminder | Accidentals
| `accidental-interface` | See also
| `accidental-suggestion-interface` | See also
| `AccidentalCautionary` | See also
| `AccidentalPlacement` | See also
| accidentals | Automatic accidentals
| accidentals | Mensural accidentals and key signatures
| accidentals | Gregorian accidentals and key signatures
| `Accidentals and key signatures` | Accidentals
| `Accidentals and key signatures` | See also
| `Accidentals and key signatures` | Key signature
| `Accidentals and key signatures` | See also
| `Accidentals and key signatures` | See also
| accidentals and simultaneous notes | See also
| accidentals in chords | See also
| accidentals, automatic | Automatic accidentals
| accidentals, modern | Automatic accidentals
| accidentals, modern cautionary style | Automatic accidentals
| accidentals, modern style | Automatic accidentals
| accidentals, multivoice | Automatic accidentals
| accidentals, piano | Automatic accidentals
| accidentals, piano cautionary | Automatic accidentals
| `AccidentalSuggestion` | See also
| `AccidentalSuggestion` | See also
| `Accidental_engraver` | See also
| `Accidental_engraver` | See also
| `Accidental_engraver` | See also
| accordion | 2.2.3 Accordion
| accordion discant symbols | Discant symbols
| accordion shift symbols | Discant symbols
| accordion shifts | Discant symbols
| `addChordShape` | Predefined fret diagrams
| `addChordShape` | A.16 Available music functions
| adding a white background to text | A.9.6 Other
| `Adding and removing engravers` | See also
| adding custom fret diagrams | Predefined fret diagrams
| `addInstrumentDefinition` | Instrument names
| `addInstrumentDefinition` | A.16 Available music functions
| additions, in chords | Extended and altered chords
| `addQuote` | Quoting other voices
| `addQuote` | A.16 Available music functions
| adjusting staff symbol | Staff symbol
| adjusting staff symbol | 5.4.5 Staff symbol properties
| `aeolian` | Key signature
| `afterGrace` | Grace notes
| `afterGrace` | A.16 Available music functions
| afterGraceFraction | parser variable
| Aiken shape note heads | Shape note heads
| `aikenHeads` | Shape note heads
| `aikenHeadsMinor` | Shape note heads
| `al niente` | See also
| `alias` | 5.1.6 Defining new contexts
| align to objects | Using the `break-alignable-interface`
| `alignAboveContext` | 5.1.7 Aligning contexts
| `alignBelowContext` | 5.1.7 Aligning contexts
| `Aligning lyrics to a melody` | See also
| `Aligning lyrics to a melody` | See also
| aligning markup text | Text alignment
| aligning markups | Text alignment
| aligning text | Text alignment
| aligning to cadenza | Aligning to cadenzas
| alignment, text, commands | Text alignment
| alist | alist
| `All layout objects` | See also
| `All layout objects` | See also
| `All layout objects` | See also
| `allowPageTurn` | A.16 Available music functions
| altered chords | Extended and altered chords
| alternate ending in written-out repeats | Written-out repeats
| alternate endings | 1.4.1 Long repeats
| alternative endings and lyrics | Repeats with alternative endings
| alternative endings with ties | Normal repeats
| alternative melody, switching to | Switching to an alternative melody
| alto clef | Clef
| Amazing Grace bagpipe example | Bagpipe example
| `Ambitus` | See also
| `ambitus` | See also
| `ambitus` | See also
| `ambitus-interface` | See also
| `AmbitusAccidental` | See also
| `AmbitusLine` | See also
| `AmbitusNoteHead` | See also
| `Ambitus_engraver` | See also
| amount of staff lines | Staff symbol
| `An extra staff appears` | Normal repeats
| `An extra staff appears` | Written-out repeats
| `An extra staff appears` | See also
| anacrucis in a repeat | Normal repeats
| `anacrusis` | See also
| analysis, musicological | Analysis brackets
| ancient clef | Clef
| angled hairpins | Rotating layout objects
| `annotate-spacing` | 4.6.1 Displaying spacing
| anthems | 2.1.5 Choral
| `applyContext` | A.16 Available music functions
| `applyMusic` | A.16 Available music functions
| `applyOutput` | A.16 Available music functions
| `appoggiatura` | A.16 Available music functions
| Arabic key signatures | Arabic key signatures
| Arabic music | References for Arabic music
| Arabic music example | Arabic music example
| Arabic music template | Arabic music example
| Arabic note names | Arabic note names
| Arabic semi-flat symbol | Arabic note names
| Arabic time signatures | Arabic time signatures
| `arpeggio` | Arpeggio
| `Arpeggio` | See also
| arpeggio symbols, special | Arpeggio
| arpeggio, cross-staff parenthesis-style | Known issues and warnings
| arpeggio, parenthesis-style, cross-staff | Known issues and warnings
| `arpeggioArrowDown` | Arpeggio
| `arpeggioArrowUp` | Arpeggio
| `arpeggioBracket` | Arpeggio
| `arpeggioNormal` | Arpeggio
| `arpeggioParenthesis` | Arpeggio
| `arpeggioParenthesisDashed` | Arpeggio
| `arrow-head` | Graphic notation inside markup
| Articlulate scripts | Supported in MIDI
| `Articulation and dynamics` | See also
| articulation-event | Selected Snippets
| articulations | Articulations and ornamentations
| articulations | Gregorian articulation signs
| articulations in MIDI | Supported in MIDI
| artificial harmonics | Harmonics
| `assertBeamQuant` | A.16 Available music functions
| `assertBeamSlope` | A.16 Available music functions
| `associatedVoice` | Aligning lyrics to a melody
| associatedVoice | Automatic syllable durations
| associatedVoice | Switching to an alternative melody
| association list | alist
| `aug` | Common chords
| `auto-first-page-number` | `\paper` variables for page numbering
| `autoBeaming` | Setting automatic beam behavior
| autobeaming properties for time signatures | Time signature
| `autoBeamOff` | Automatic beams
| `autoBeamOn` | Automatic beams
| `autochange` | Changing staff automatically
| `autochange` | A.16 Available music functions
| autochange and relative music | Changing staff automatically
| `AutoChangeMusic` | See also
| automatic accidentals | Automatic accidentals
| automatic chord diagrams | Automatic fret diagrams
| automatic fret diagrams | Automatic fret diagrams
| automatic part combining | Automatic part combining
| automatic staff changes | Changing staff automatically
| automaticBars | Special considerations
| `Auto_beam_engraver` | See also
| `Auto_beam_engraver` | See also
| available fonts, listing | Single entry fonts
B |  |
| `Backend` | 5.2.1 Navigating the program reference
| `Backend` | See also
| `Backend` | See also
| backslashed digits | A.9.6 Other
| bagpipe | Bagpipe definitions
| bagpipe example | Bagpipe example
| balloon | Balloon help
| balloon help | Balloon help
| `balloon-interface` | See also
| `balloonGrobText` | Balloon help
| `balloonGrobText` | A.16 Available music functions
| `balloonLengthOff` | Balloon help
| `balloonLengthOn` | Balloon help
| `balloonText` | Balloon help
| `balloonText` | A.16 Available music functions
| `BalloonTextItem` | See also
| `Balloon_engraver` | Balloon help
| banjo tablature | 2.4 Fretted string instruments
| banjo tablatures | Banjo tablatures
| banjo tunings | Banjo tablatures
| `banjo-c-tuning` | Banjo tablatures
| `banjo-modal-tuning` | Banjo tablatures
| `banjo-open-d-tuning` | Banjo tablatures
| `banjo-open-dm-tuning` | Banjo tablatures
| `bar` | Bar lines
| `bar` | Selected Snippets
| `bar` | A.16 Available music functions
| bar check | Bar and bar number checks
| bar lines | Bar lines
| bar lines, closing | Bar lines
| bar lines, default, changing | Bar lines
| bar lines, double | Bar lines
| bar lines, invisible | Bar lines
| bar lines, manual | Bar lines
| bar lines, suppressing | Special considerations
| bar lines, symbols on | Text marks
| bar lines, turning off | Unmetered music
| bar number | Time administration
| bar number alignment | Selected Snippets
| bar number check | Bar and bar number checks
| bar number collision | See also
| bar number, format | Selected Snippets
| bar numbering, turning off | Unmetered music
| bar numbers | Bar numbers
| bar numbers, regular spacing | Bar numbers
| `bar-line-interface` | A.14 All context properties
| `barCheckSynchronize` | Bar and bar number checks
| baritone clef | Clef
| `BarLine` | See also
| `BarNumber` | Bar numbers
| `BarNumber` | Known issues and warnings
| `barNumberCheck` | Bar and bar number checks
| `barNumberCheck` | A.16 Available music functions
| `barNumberVisibility` | Bar numbers
| barre indications | Fret diagram markups
| `bartype` | Selected Snippets
| Bartók pizzicato | Snap (Bartók) pizzicato
| `Bar_engraver` | See also
| `Bar_number_engraver` | See also
| `base-shortest-duration` | 4.5.1 Horizontal spacing overview
| `baseMoment` | Setting automatic beam behavior
| bass clef | Clef
| bass note, for chords | Extended and altered chords
| Bass, figured | Introduction to figured bass
| Bass, thorough | Introduction to figured bass
| `BassFigure` | See also
| `BassFigure` | See also
| `BassFigureAlignment` | See also
| `BassFigureAlignment` | See also
| `BassFigureBracket` | See also
| `BassFigureBracket` | See also
| `BassFigureContinuation` | See also
| `BassFigureContinuation` | See also
| `BassFigureLine` | See also
| `BassFigureLine` | See also
| Basso continuo | Introduction to figured bass
| `bayati` | See also
| `Beam` | See also
| `Beam` | See also
| `Beam` | See also
| `Beam` | See also
| `Beam` | See also
| beam, endings in a score | Selected Snippets
| beam, endings with multiple voices | Selected Snippets
| `beam-interface` | See also
| `beam-interface` | See also
| `beam-interface` | See also
| `BeamEvent` | See also
| `BeamEvent` | See also
| `beamExceptions` | Setting automatic beam behavior
| `BeamForbidEvent` | See also
| `BeamForbidEvent` | See also
| beaming, time signature default properties | Time signature
| beams, cross-staff | Changing staff manually
| beams, customizing rules | Automatic beams
| beams, feathered | Feathered beams
| beams, in cadenzas | Unmetered music
| beams, in unmetered music | Unmetered music
| beams, line breaks | Predefined commands
| beams, manual | Automatic beams
| beams, manual | Manual beams
| beams, subdividing | Selected Snippets
| beams, with knee gap | Predefined commands
| beams, with lyrics | Setting automatic beam behavior
| beams, with melismata | Automatic beams
| beams, with polymetric meters | Polymetric notation
| beams, \partcombine with \autoBeamOff | Selected Snippets
| `Beam_engraver` | See also
| `Beam_engraver` | See also
| beats per minute | Metronome marks
| beats, grouping | Selected Snippets
| `beatStructure` | Setting automatic beam behavior
| beginners’ music | Easy notation note heads
| `bendAfter` | Falls and doits
| `bendAfter` | A.16 Available music functions
| binding gutter | `\paper` variables for two-sided mode
| `binding-offset` | `\paper` variables for two-sided mode
| bisbiglando | References for harps
| Bison | parser
| `blank-after-score-page-force` | `\paper` variables for page breaking
| `blank-last-page-force` | `\paper` variables for page breaking
| `blank-page-force` | `\paper` variables for page breaking
| BNF | parser
| `bold` | Selecting font and font size
| `bookOutputName` | A.16 Available music functions
| `bookOutputSuffix` | A.16 Available music functions
| `bottom-margin` | 4.1.3 Fixed vertical spacing `\paper` variables
| bowing indications | Bowing indications
| `box` | Graphic notation inside markup
| `brace` | See also
| brace, vertical | Grouping staves
| braces, nesting of | Nested staff groups
| braces, various sizes | Fonts explained
| `bracket` | New dynamic marks
| `bracket` | Graphic notation inside markup
| `bracket` | Piano pedals
| bracket, horizontal | Analysis brackets
| bracket, phrasing | Analysis brackets
| bracket, vertical | Grouping staves
| bracket, volta | Manual repeat marks
| brackets | Analysis brackets
| brackets, angle | Chorded notes
| brackets, nesting of | Nested staff groups
| break-align-symbols | Using the `break-alignable-interface`
| break-visibility | Using break-visibility
| `breakable` | Predefined commands
| breakbefore | Default layout of book and score title blocks
| breaking lines | 4.3.1 Line breaking
| breaking pages | 4.5.4 Line length
| breaks in unmetered music | See also
| breath marks | Breath marks
| `breathe` | Breath marks
| `breathe` | A.16 Available music functions
| `BreathingEvent` | See also
| `BreathingSign` | See also
| `BreathingSign` | See also
| `Breathing_sign_engraver` | See also
| `breve` | Durations
| `breve` | Rests
| breve rest | Rests
| broken chord | Arpeggio
| Bézier control points | Modifying ties and slurs
| Bézier curves | Modifying ties and slurs
C |  |
| C clef | Clef
| `cadenza` | See also
| `cadenza` | See also
| cadenza line breaks | See also
| cadenza page breaks | See also
| cadenza, aligning to | Aligning to cadenzas
| cadenza, with beams | Unmetered music
| `cadenzaOff` | Unmetered music
| `cadenzaOn` | Unmetered music
| `caesura` | See also
| `caesura` | See also
| callback | callback
| `Callback functions` | See also
| capo | Fret diagram markups
| cautionary accidental | Accidentals
| cautionary accidental style, piano | Automatic accidentals
| cautionary accidentals, piano | Automatic accidentals
| `center-align` | Text alignment
| `center-column` | Text alignment
| centered dynamics in piano music | References for keyboards
| centering a column of text | A.9.2 Align
| centering text on the page | Text alignment
| `change` | Changing staff manually
| changing direction of text columns | A.9.2 Align
| changing fonts | Selecting font and font size
| changing instrument names | Instrument names
| changing properties | 5.3.2 The `\set` command
| changing staff automatically | Changing staff automatically
| changing staff manually | Changing staff manually
| chants | 2.1.7 Chants psalms and hymns
| character names | Character names
| `check-consistency` | `\paper` variables for widths and margins
| choir staff | Grouping staves
| `ChoirStaff` | See also
| `ChoirStaff` | See also
| `ChoirStaff` | See also
| choral tenor clef | Clef
| `chord` | See also
| `chord` | See also
| `chord` | See also
| chord chords | 2.7.1 Chord mode
| chord diagrams | Fret diagram markups
| chord diagrams | Predefined fret diagrams
| chord diagrams, automatic | Automatic fret diagrams
| chord glissandi | Default tablatures
| chord inversions | Extended and altered chords
| chord mode | Chord mode overview
| chord names | Chord mode overview
| chord names | Printing chord names
| Chord names in MIDI | Supported in MIDI
| chord names with fret diagrams | Predefined fret diagrams
| chord quality | Common chords
| chord shapes for fretted instruments | Predefined fret diagrams
| chord steps, altering | Extended and altered chords
| chord, broken | Arpeggio
| chord, modifying one note in | 5.3.4 The `\tweak` command
| `chordChanges` | Selected Snippets
| `chordGlissando` | A.16 Available music functions
| `chordmode` | See also
| `chordmode` | See also
| `chordmode` | Predefined fret diagrams
| `ChordName` | See also
| `chordNameExceptions` | Customizing chord names
| `chordNameLowercaseMinor` | Customizing chord names
| `ChordNames` | Predefined fret diagrams
| `ChordNames` | See also
| `chordNameSeparator` | Customizing chord names
| `chordNoteNamer` | Customizing chord names
| `chordPrefixSpacer` | Customizing chord names
| `chordRootNamer` | Customizing chord names
| `chords` | Printing chord names
| chords | Printing chord names
| chords and relative octave entry | Relative octave entry
| chords and ties | Ties
| chords, accidentals in | See also
| chords, cross-staff | Cross-staff stems
| chords, fingering | Fingering instructions
| chords, jazz | Customizing chord names
| chords, power | Indicating power chords
| chords, relative pitch | Chorded notes
| chords, splitting across staves with \autochange | Known issues and warnings
| chords, suppressing repeated | Selected Snippets
| `Chord_name_engraver` | See also
| Christian Harmony note heads | Shape note heads
| `church mode` | See also
| church modes | Key signature
| church rest | Selected Snippets
| `circle` | Graphic notation inside markup
| circling text | A.9.3 Graphic
| circulus | A.11 List of articulations
| `Clef` | See also
| `clef` | Clef
| `clef` | A.16 Available music functions
| clef, alto | Clef
| clef, ancient | Clef
| clef, baritone | Clef
| clef, bass | Clef
| clef, C | Clef
| clef, F | Clef
| clef, french | Clef
| clef, G | Clef
| clef, mezzosoprano | Clef
| clef, moderntab | Custom tablatures
| clef, percussion | Basic percussion notation
| clef, soprano | Clef
| clef, subbass | Clef
| clef, tab | Custom tablatures
| clef, tenor | Clef
| clef, transposing | Clef
| clef, treble | Clef
| clef, varbaritone | Clef
| clef, violin | Clef
| clef, visibility following explicit change | Special considerations
| `clef-interface` | See also
| clefs | Mensural clefs
| clefs | Gregorian clefs
| clefs, visibility of octavation | Special considerations
| `Clef_engraver` | See also
| closing bar lines | Bar lines
| closure | closure
| `cluster` | See also
| `ClusterSpanner` | See also
| `ClusterSpannerBeacon` | See also
| `Cluster_spanner_engraver` | See also
| coda | Rehearsal marks
| coda | Articulations and ornamentations
| coda | A.11 List of articulations
| coda on bar line | Text marks
| collision, bar number | See also
| collisions | Collision resolution
| collisions, cross-staff voices | Changing staff manually
| `color` | Coloring objects
| color in chords | See also
| color, rgb | Coloring objects
| colored notes | Coloring objects
| colored notes in chords | See also
| colored objects | Coloring objects
| coloring notes | Coloring objects
| coloring objects | Coloring objects
| coloring objects | Painting objects white
| coloring text | A.9.6 Other
| coloring voices | Voice styles
| colors | Coloring objects
| Colors, list of | Normal colors
| `column` | Text alignment
| columns, text | Text alignment
| `combine` | Graphic notation inside markup
| `Combining notes into chords` | See also
| combining parts | Automatic part combining
| comma intervals | References for Turkish classical music
| `Command line options for` | 3.4.3 Alternative output formats
| `Common Practice Period` | See also
| `Common Practice Period` | See also
| `common-shortest-duration` | 4.5.1 Horizontal spacing overview
| `Completion_heads_engraver` | Automatic note splitting
| `Completion_rest_engraver` | Automatic note splitting
| compound time signatures | Selected Snippets
| `compoundMeter` | A.16 Available music functions
| `compressFullBarRests` | Full measure rests
| `compressFullBarRests` | Full measure rests
| compressing music | Scaling durations
| concatenating text | A.9.2 Align
| `concert pitch` | See also
| condensing rests | Known issues and warnings
| `consists` | 5.1.6 Defining new contexts
| Context, creating | 5.1.2 Creating contexts
| `ContextChange` | See also
| `Contexts` | Within-system spacing properties
| `Contexts` | See also
| `Contexts` | See also
| `Contexts` | See also
| `Contexts` | 5.1.4 Modifying context plug-ins
| `Contexts and engravers` | Single-staff polyphony
| `Contexts and engravers` | See also
| contexts, defining new | 5.1.6 Defining new contexts
| contexts, keeping alive | 5.1.3 Keeping contexts alive
| contexts, layout order | 5.4.3 Context layout order
| contexts, lifetime | 5.1.3 Keeping contexts alive
| contexts, nested | 5.1.7 Aligning contexts
| `contextStringTuning` | A.16 Available music functions
| `contextStringTunings` | Custom tablatures
| control pitch | Octave checks
| control points, tweaking | Known issues and warnings
| controlling general text alignment | A.9.2 Align
| `controlpitch` | Octave checks
| copyright sign | 3.3.3 Text encoding
| `cr` | Dynamics
| creating contexts | 5.1.2 Creating contexts
| creating empty text objects | A.9.6 Other
| creating horizontal spaces in text | A.9.2 Align
| creating text fractions | A.9.6 Other
| creating vertical spaces in text | A.9.2 Align
| creating vertical spaces in text | A.9.6 Other
| `cresc` | Dynamics
| `crescendo` | See also
| `crescHairpin` | Dynamics
| `crescTextCresc` | Dynamics
| `cross` | Special note heads
| cross note heads | Special note heads
| cross staff chords | Cross-staff stems
| cross staff line | Staff-change lines
| cross staff notes | Cross-staff stems
| cross staff stems | Cross-staff stems
| `cross-staff` | Cross-staff stems
| cross-staff beams | Changing staff manually
| cross-staff chords | Cross-staff stems
| cross-staff collisions | Changing staff manually
| cross-staff line | Staff-change lines
| cross-staff notes | Changing staff manually
| cross-staff notes | Cross-staff stems
| cross-staff parenthesis-style arpeggio | Known issues and warnings
| cross-staff stems | Cross-staff stems
| cross-staff tremolo | See also
| cue notes | Quoting other voices
| cue notes | Formatting cue notes
| cue notes, formatting | Formatting cue notes
| cue notes, removing | Formatting cue notes
| `cue-notes` | See also
| `cueClef` | A.16 Available music functions
| `cueClefUnset` | A.16 Available music functions
| `cueDuring` | Formatting cue notes
| `cueDuring` | A.16 Available music functions
| `cueDuringWithClef` | A.16 Available music functions
| cues | Formatting cue notes
| cues, formatting | Formatting cue notes
| cues, musical | Musical cues
| `CueVoice` | See also
| `CueVoice` | See also
| `currentBarNumber` | Bar numbers
| `currentBarNumber` | Time administration
| custodes | Custodes
| custom fret diagrams | Fret diagram markups
| custom fret diagrams, adding | Predefined fret diagrams
| custom rehearsal mark | Rehearsal marks
| custom string tunings | Custom tablatures
| customized fret diagram | Fret diagram markups
| customizing chord names | Customizing chord names
| `custos` | See also
| `Custos` | See also
| `custos` | See also
D |  |
| D.S. al Fine | Rehearsal marks
| dampened notes on fretted instruments | Indicating harmonics and dampened notes
| dashed phrasing slur | Phrasing slurs
| dashed slur | Slurs
| dashed ties | Ties
| `deadNote` | A.16 Available music functions
| decorating text | Graphic notation inside markup
| `decr` | Dynamics
| `decresc` | Dynamics
| `decrescendo` | See also
| `default` | Automatic accidentals
| `default` | Automatic accidentals
| default accidental style | Automatic accidentals
| default accidental style | Automatic accidentals
| default bar lines, changing | Bar lines
| default note duration | Durations
| default note names | Accidentals
| `default-staff-staff-spacing` | Within-system spacing properties
| `defaultBarType` | Selected Snippets
| `defaultNoteHeads` | A.16 Available music functions
| `defaultTimeSignature` | Time signature
| `Default_bar_line_engraver` | See also
| `denies` | 5.1.6 Defining new contexts
| diagram, fret, customized | Fret diagram markups
| diagrams, chord for fretted instruments | Fret diagram markups
| diagrams, fret | Fret diagram markups
| diagrams, fret, transposing | Predefined fret diagrams
| diamond note heads | Special note heads
| diamond-shaped note heads | Harmonics
| `dim` | Dynamics
| `dim` | Common chords
| `dimHairpin` | Dynamics
| diminuendo | Dynamics
| `dimTextDecr` | Dynamics
| `dimTextDecresc` | Dynamics
| `dimTextDim` | Dynamics
| discant symbols, accordion | Discant symbols
| `Displaying music expressions` | 5.3.4 The `\tweak` command
| `Displaying music expressions` | See also
| `displayLilyMusic` | A.16 Available music functions
| `displayMusic` | A.16 Available music functions
| distance between staves | 4.4.1 Flexible vertical spacing within systems
| distances, absolute | 5.4.4 Distances and measurements
| distances, scaled | 5.4.4 Distances and measurements
| divided lyrics | Divisi lyrics
| `divisio` | See also
| divisiones | Divisiones
| `dodecaphonic` | Automatic accidentals
| dodecaphonic accidental style | Automatic accidentals
| dodecaphonic style, neo-modern | Automatic accidentals
| `doit` | See also
| doits | Falls and doits
| `dorian` | Key signature
| `DotColumn` | See also
| `Dots` | See also
| `dotsDown` | Durations
| `dotsNeutral` | Durations
| `dotsUp` | Durations
| dotted notes | Durations
| dotted phrasing slurs | Phrasing slurs
| dotted slur | Slurs
| dotted ties | Ties
| double bar lines | Bar lines
| `double flat` | See also
| `double sharp` | See also
| double time signatures | Polymetric notation
| double-dotted notes | Durations
| `DoublePercentEvent` | See also
| `DoublePercentRepeat` | See also
| `DoublePercentRepeatCounter` | See also
| `DoubleRepeatSlash` | See also
| `Double_percent_repeat_engraver` | See also
| down bow indication | Bowing indications
| downbow | Articulations and ornamentations
| downbow | A.11 List of articulations
| downmordent | A.11 List of articulations
| downprall | A.11 List of articulations
| `draw-circle` | Graphic notation inside markup
| `draw-line` | Graphic notation inside markup
| drawing a line across a page | A.9.3 Graphic
| drawing beams within text | A.9.3 Graphic
| drawing boxes with rounded corners | A.9.3 Graphic
| drawing boxes with rounded corners around text | A.9.3 Graphic
| drawing circles within text | A.9.3 Graphic
| drawing graphic objects | Graphic notation inside markup
| drawing lines within text | A.9.3 Graphic
| drawing paths | A.9.3 Graphic
| drawing solid boxes within text | A.9.3 Graphic
| drawing staff symbol | Staff symbol
| drawing staff symbol | 5.4.5 Staff symbol properties
| drawing triangles within text | A.9.3 Graphic
| drum staff | Instantiating new staves
| `drummode` | Instantiating new staves
| drums | Basic percussion notation
| drums | Percussion staves
| `DrumStaff` | Instantiating new staves
| `DrumStaff` | See also
| `DrumVoice` | See also
| `Duration names notes and rests` | See also
| duration, default | Durations
| durations, of notes | Durations
| durations, scaling | Scaling durations
| `dynamic` | New dynamic marks
| dynamic marks, multiple on one note | Dynamics
| dynamic marks, new | New dynamic marks
| dynamic-event | Selected Snippets
| `dynamicDown` | Dynamics
| `DynamicLineSpanner` | Dynamics
| `DynamicLineSpanner` | See also
| `dynamicNeutral` | Dynamics
| `Dynamics` | See also
| dynamics | Dynamics
| dynamics, absolute | Dynamics
| dynamics, centered in keyboard music | References for keyboards
| dynamics, editorial | New dynamic marks
| dynamics, parenthesis | New dynamic marks
| dynamics, vertical positioning | Dynamics
| `DynamicText` | See also
| `dynamicUp` | Dynamics
E |  |
| easy notation | Easy notation note heads
| easy play note heads | Easy notation note heads
| `easyHeadsOff` | Easy notation note heads
| `easyHeadsOn` | Easy notation note heads
| editorial dynamics | New dynamic marks
| embedded graphics | Graphic notation inside markup
| embedding graphic objects | Graphic notation inside markup
| empty staves | Hiding staves
| encapsulated postscript output | 3.4.3 Alternative output formats
| enclosing text in a box with rounded corners | A.9.3 Graphic
| enclosing text within a box | A.9.1 Font
| end repeat | Manual repeat marks
| `endSpanners` | A.16 Available music functions
| `Engravers and Performers` | See also
| `Engravers and Performers` | 5.1.4 Modifying context plug-ins
| `Engravers explained` | See also
| engravers, including in contexts | 5.1.6 Defining new contexts
| entering lyrics | Entering lyrics
| `Episema` | See also
| `EpisemaEvent` | See also
| `Episema_engraver` | See also
| EPS output | 3.4.3 Alternative output formats
| `epsfile` | Graphic notation inside markup
| `espressivo` | Dynamics
| espressivo | A.11 List of articulations
| espressivo articulation | Dynamics
| exceptions, chord names. | Selected Snippets
| `expandFullBarRests` | Full measure rests
| `expandFullBarRests` | Full measure rests
| expanding music | Scaling durations
| explicitClefVisibility | Special considerations
| explicitKeySignatureVisibility | Special considerations
| `Explicitly instantiating voices` | Single-staff polyphony
| `Explicitly instantiating voices` | See also
| expressions, markup | Text markup introduction
| extended chords | Extended and altered chords
| extender | Extenders and hyphens
| `extra-offset` | Within-system spacing properties
F |  |
| `f` | Dynamics
| F clef | Clef
| `fall` | See also
| falls | Falls and doits
| `featherDurations` | Feathered beams
| `featherDurations` | A.16 Available music functions
| feathered beams | Feathered beams
| fermata | Rehearsal marks
| fermata | Articulations and ornamentations
| fermata | A.11 List of articulations
| fermata on bar line | Text marks
| fermata on multi-measure rest | Full measure rests
| `fermataMarkup` | Full measure rests
| `fermataMarkup` | Full measure rests
| Feta font | A.7 The Feta font
| `ff` | Dynamics
| `fff` | Dynamics
| `ffff` | Dynamics
| `fffff` | Dynamics
| `fifth` | See also
| `figured bass` | See also
| Figured bass | Introduction to figured bass
| `figured bass` | See also
| figured bass alignment | Predefined commands
| figured bass extender lines | Predefined commands
| `FiguredBass` | See also
| `FiguredBass` | See also
| `FiguredBass` | See also
| `fill-line` | Text alignment
| `filled-box` | Graphic notation inside markup
| finalis | Divisiones
| finding available fonts | Single entry fonts
| `finger` | Fingering instructions
| finger change | Fingering instructions
| `finger-interface` | 5.2.2 Layout interfaces
| `Fingering` | See also
| fingering | Fingering instructions
| `Fingering` | See also
| `Fingering` | 5.2.1 Navigating the program reference
| `Fingering` | 5.2.1 Navigating the program reference
| `Fingering` | 5.2.1 Navigating the program reference
| `Fingering` | 5.2.1 Navigating the program reference
| `Fingering` | 5.2.2 Layout interfaces
| `Fingering` | 5.2.2 Layout interfaces
| fingering chords | Fingering instructions
| fingering instructions for chords | Fingering instructions
| fingering vs. string numbers | String number indications
| `fingering-event` | See also
| `fingering-event` | 5.2.1 Navigating the program reference
| `fingering-event` | 5.2.1 Navigating the program reference
| `FingeringEvent` | See also
| `FingeringEvent` | 5.2.1 Navigating the program reference
| fingerings and multi-measure rests | See also
| fingerings, adding to fret diagrams | Automatic fret diagrams
| fingerings, right hand for fretted instruments | Right-hand fingerings
| `Fingering_engraver` | See also
| `Fingering_engraver` | 5.2.1 Navigating the program reference
| `Fingering_engraver` | 5.2.1 Navigating the program reference
| `Fingering_engraver` | 5.2.1 Navigating the program reference
| `Fingering_engraver` | 5.2.3 Determining the grob property
| `first-page-number` | `\paper` variables for page numbering
| `Fixing overlapping` | Changing staff manually
| `Fixing overlapping notation` | Changing staff manually
| `Fixing overlapping notation` | See also
| `flag` | See also
| `flag` | See also
| `flag-style` | Cross-staff stems
| flageolet | Articulations and ornamentations
| flageolet | A.11 List of articulations
| flags | Mensural flags
| `flat` | See also
| flat, double | Accidentals
| Flex | lexer
| follow voice | Staff-change lines
| `followVoice` | Staff-change lines
| font | glyph
| font families | Selecting font and font size
| font families, setting | Entire document fonts
| font size | Selecting font and font size
| font size (notation) | Selecting notation font size
| font size (notation) scaling | Selecting notation font size
| font size (notation), standard | Selecting notation font size
| font size, setting | 4.2.2 Setting the staff size
| font switching | Selecting font and font size
| Font, Feta | A.7 The Feta font
| `font-interface` | Selecting notation font size
| `font-interface` | Fonts explained
| `font-interface` | A.9.6 Other
| `font-size` | Selecting notation font size
| `font-size` | Selecting notation font size
| fonts, changing for entire document | Entire document fonts
| fonts, explained | Fonts explained
| fonts, finding available | Single entry fonts
| fonts, non-text in markup | Fonts explained
| `fontSize` | Selecting notation font size
| `fontsize` | Selecting font and font size
| foot marks | Articulations and ornamentations
| `footnote` | A.16 Available music functions
| `footnoteGrob` | A.16 Available music functions
| `Forbid_line_break_engraver` | See also
| `forget` | Automatic accidentals
| forget accidental style | Automatic accidentals
| format, rehearsal mark | Rehearsal marks
| formatting in lyrics | Entering lyrics
| `Formatting text` | A.15 Layout properties
| `Formatting text` | A.15 Layout properties
| formatting text spanners | Text spanners
| four bar music. | 4.3.1 Line breaking
| `Four-part SATB vocal score` | References for choral
| `Four-part SATB vocal score` | See also
| `four-string-banjo` | Banjo tablatures
| `fp` | Dynamics
| fragments | Formatting cue notes
| fragments, quoting | Quoting other voices
| framing text | Graphic notation inside markup
| french clef | Clef
| `Frenched score` | See also
| `Frenched staff` | See also
| `Frenched staff` | See also
| `Frenched staves` | See also
| fret | Default tablatures
| fret diagram, customized | Fret diagram markups
| fret diagrams | Fret diagram markups
| fret diagrams | Predefined fret diagrams
| fret diagrams with chord names | Predefined fret diagrams
| fret diagrams, adding custom | Predefined fret diagrams
| fret diagrams, adding fingerings | Automatic fret diagrams
| fret diagrams, automatic | Automatic fret diagrams
| fret diagrams, custom | Fret diagram markups
| fret diagrams, mandolin | Predefined fret diagrams
| fret diagrams, transposing | Predefined fret diagrams
| fret diagrams, ukulele | Predefined fret diagrams
| `fret-diagram` | Fret diagram markups
| fret-diagram markup | Fret diagram markups
| `fret-diagram-interface` | Fret diagram markups
| `fret-diagram-interface` | See also
| `fret-diagram-interface` | Predefined fret diagrams
| `fret-diagram-interface` | See also
| `fret-diagram-interface` | Automatic fret diagrams
| `fret-diagram-interface` | See also
| `fret-diagram-terse` | Fret diagram markups
| fret-diagram-terse markup | Fret diagram markups
| `fret-diagram-verbose` | Fret diagram markups
| fret-diagram-verbose markup | Fret diagram markups
| `FretBoards` | Predefined fret diagrams
| fretted instruments, chord shapes | Predefined fret diagrams
| fretted instruments, dampened notes | Indicating harmonics and dampened notes
| fretted instruments, harmonics | Indicating harmonics and dampened notes
| fretted instruments, indicating position and barring | Indicating position and barring
| fretted instruments, predefined string tunings | Custom tablatures
| fretted instruments, right hand fingerings | Right-hand fingerings
| full-measure rests | Full measure rests
| Funk shape note heads | Shape note heads
| `funkHeads` | Shape note heads
| `funkHeadsMinor` | Shape note heads
G |  |
| G clef | Clef
| `general-align` | Text alignment
| ghost notes | Parentheses
| `glissando` | Glissando
| `Glissando` | See also
| `Glissando` | See also
| global variable | parser variable
| glyph | glyph
| glyphs, music | Rehearsal marks
| `grace` | Grace notes
| `grace` | A.16 Available music functions
| `grace notes` | See also
| grace notes | Bagpipe definitions
| grace notes and lyrics | Adding syllables to grace notes
| grace notes within tuplet brackets | See also
| grace notes, changing layout settings | Grace notes
| grace notes, following | Grace notes
| grace notes, tweaking | Grace notes
| grace-note synchronization | Known issues and warnings
| `GraceMusic` | See also
| `Grace_beam_engraver` | See also
| `Grace_engraver` | See also
| `Grace_spacing_engraver` | See also
| grammar for LilyPond | parser
| `grand staff` | See also
| `GrandStaff` | See also
| `GrandStaff` | See also
| graphic notation | Graphic notation inside markup
| graphic objects, drawing | Graphic notation inside markup
| graphic objects, embedding | Graphic notation inside markup
| graphical object interfaces | interface
| `Graphical Object Interfaces` | See also
| graphical objects | grob
| graphics, embedding | Graphic notation inside markup
| graphics, embedding | Graphic notation inside markup
| Gregorian square neumes ligatures | Gregorian square neume ligatures
| Gregorian transcription staff | Instantiating new staves
| `GregorianTranscriptionStaff` | Instantiating new staves
| grid lines | Grid lines
| `grid-line-interface` | See also
| `grid-point-interface` | See also
| `gridInterval` | Grid lines
| `GridLine` | See also
| `GridPoint` | See also
| `Grid_line_span_engraver` | Grid lines
| `Grid_point_engraver` | Grid lines
| grob | 5.2.2 Layout interfaces
| grob | grob
| grob properties | See also
| `grob-interface` | 5.2.2 Layout interfaces
| `grob-interface` | 5.2.2 Layout interfaces
| `grob-interface` | See also
| `grob-interface` | See also
| grobs, overwriting | Painting objects white
| grobs, visibility of | 5.4.7 Visibility of objects
| grouping beats | Selected Snippets
| `grow-direction` | Feathered beams
| guitar chord charts | Showing melody rhythms
| guitar note heads | Special note heads
| guitar strumming rhythms, showing | Showing melody rhythms
| guitar tablature | 2.4 Fretted string instruments
| gutter | `\paper` variables for two-sided mode
H |  |
| `Hairpin` | See also
| `hairpin` | See also
| hairpins, angled | Rotating layout objects
| halfopen | A.11 List of articulations
| `halign` | Text alignment
| harmonic indications in tablature notation | Default tablatures
| harmonic note heads | Special note heads
| Harmonica Sacra note heads | Shape note heads
| `harmonicByFret` | A.16 Available music functions
| `harmonicByRatio` | A.16 Available music functions
| `harmonicNote` | A.16 Available music functions
| `harmonics` | See also
| harmonics on fretted instruments | Indicating harmonics and dampened notes
| harmonics, artificial | Harmonics
| harmonics, natural | Harmonics
| `harmonicsOn` | A.16 Available music functions
| harp pedal diagrams | Harp pedals
| harp pedals | Harp pedals
| harps | References for harps
| `hbracket` | Graphic notation inside markup
| help, balloon | Balloon help
| hidden notes | Hidden notes
| `hideKeySignature` | Bagpipe definitions
| `hideNotes` | Hidden notes
| `hideStaffSwitch` | Staff-change lines
| hiding ancient staves | Hiding staves
| hiding of staves | Hiding staves
| hiding rhythmic staves | Hiding staves
| horizontal bracket | Analysis brackets
| horizontal spacing | 4.5 Horizontal spacing
| horizontal text alignment | Text alignment
| `horizontal-bracket-interface` | See also
| `horizontal-shift` | `\paper` variables for shifts and indents
| `HorizontalBracket` | See also
| horizontally centering text | A.9.2 Align
| `Horizontal_bracket_engraver` | Analysis brackets
| `How LilyPond input files work` | See also
| `How LilyPond input files work` | See also
| hufnagel | 2.9 Ancient notation
| hufnagel | 2.9.1 Overview of the supported styles
| `huge` | Selecting notation font size
| `huge` | Selecting font and font size
| hymns | 2.1.7 Chants psalms and hymns
| hyphens | Extenders and hyphens
I |  |
| `I'm hearing Voices` | See also
| `I'm hearing Voices` | Percussion staves
| ictus | A.11 List of articulations
| images, embedding | Graphic notation inside markup
| immutable objects | immutable
| immutable properties | immutable
| importing stencils into text | A.9.6 Other
| improvisation | Improvisation
| `improvisationOff` | Improvisation
| `improvisationOff` | Showing melody rhythms
| `improvisationOn` | Improvisation
| `improvisationOn` | Showing melody rhythms
| include-settings | Using global settings
| including files | 3.3.1 Including LilyPond files
| `indent` | Instrument names
| `indent` | `\paper` variables for shifts and indents
| `indent` | 4.5.4 Line length
| indicating No Chord in ChordNames | Printing chord names
| indicating position and barring for fretted instruments | Indicating position and barring
| inlining an Encapsulated PostScript image | A.9.3 Graphic
| `inner-margin` | `\paper` variables for two-sided mode
| inserting music into text | A.9.4 Music
| inserting PostScript directly into text | A.9.3 Graphic
| inserting URL links into text | A.9.3 Graphic
| instrument names | Instrument names
| instrument names | Instrument names
| instrument names, adding to other contexts | Instrument names
| instrument names, centering | Instrument names
| instrument names, changing | Instrument names
| instrument names, short | Instrument names
| instrument switch | Instrument names
| `instrument-specific-markup-interface` | See also
| `instrument-specific-markup-interface` | A.9.6 Other
| `InstrumentName` | See also
| instruments, transposing | Transpose
| `InstrumentSwitch` | See also
| `instrumentSwitch` | Instrument names
| `instrumentSwitch` | A.16 Available music functions
| interface | interface
| interface, layout | 5.2.2 Layout interfaces
| `Interfaces for programmers` | See also
| interleaved music | Writing music in parallel
| Internals Reference | 5. Changing defaults
| `interval` | See also
| `inversion` | A.16 Available music functions
| inversion, modal | Modal inversion
| invisible notes | Hidden notes
| invisible rest | Invisible rests
| invisible stem | Stems
| `Invoking lilypond` | 3.4.1 Extracting fragments of music
| `ionian` | Key signature
| `iraq` | See also
| `italic` | Selecting font and font size
| `item-interface` | 5.2.2 Layout interfaces
J |  |
| jazz chords | Customizing chord names
| justified text | Text alignment
| `justified-lines` | Multi-page markup
| `justify` | Text alignment
| justifying lines of text | A.10 Text markup list commands
| justifying text | A.9.2 Align
K |  |
| keep tagged music | Using tags
| `keepWithTag` | A.16 Available music functions
| `key` | Key signature
| `key` | Shape note heads
| `key signature` | See also
| `key signature` | See also
| key signature | Mensural accidentals and key signatures
| key signature | Gregorian accidentals and key signatures
| key signature, visibility following explicit change | Special considerations
| `key-cancellation-interface` | See also
| `key-signature-interface` | See also
| keyboard instrument staves | References for keyboards
| keyboard music, centering dynamics | References for keyboards
| `KeyCancellation` | See also
| `KeyChangeEvent` | See also
| keyed instrument staves | References for keyboards
| `KeySignature` | See also
| `KeySignature` | See also
| `KeySignature` | See also
| `KeySignature` | See also
| `Key_engraver` | See also
| `Key_performer` | See also
| `killCues` | Formatting cue notes
| `killCues` | A.16 Available music functions
| kirchenpausen | Selected Snippets
| knee gap, with beams | Predefined commands
| `kurd` | See also
L |  |
| `label` | A.16 Available music functions
| `laissez vibrer` | See also
| `laissezVibrer` | Ties
| `LaissezVibrerTie` | See also
| `LaissezVibrerTieColumn` | See also
| landscape | Setting paper size
| `language` | A.16 Available music functions
| language, note names in other | Note names in other languages
| language, pitch names in other | Note names in other languages
| `languageRestore` | A.16 Available music functions
| `languageSaveAndChange` | A.16 Available music functions
| `large` | Selecting notation font size
| `large` | Selecting font and font size
| `larger` | Selecting font and font size
| `larger` | Selecting font and font size
| `last-bottom-spacing` | List of flexible vertical spacing `\paper` variables
| layers | Painting objects white
| `layout file` | 4.2.2 Setting the staff size
| layout interface | 5.2.2 Layout interfaces
| layout objects | grob
| `ledger line` | See also
| ledger lines, setting | Staff symbol
| `ledger-line-spanner-interface` | See also
| `LedgerLineSpanner` | See also
| `Ledger_line_engraver` | See also
| left aligning text | A.9.2 Align
| `left-align` | Text alignment
| `left-margin` | `\paper` variables for widths and margins
| `length` | Cross-staff stems
| `Length and thickness of objects` | See also
| `Length and thickness of objects` | 5.4.4 Distances and measurements
| `Length and thickness of objects` | See also
| length of notes | Durations
| lexer | lexer
| lheel | A.11 List of articulations
| `ligature` | See also
| `ligature` | See also
| `ligature` | See also
| `ligature` | See also
| `ligature` | See also
| Ligatures | Ligatures
| ligatures in text | A.9.2 Align
| `line` | See also
| line breaks | Bar lines
| line breaks | 4.3.1 Line breaking
| line breaks in cadenzas | See also
| line breaks in unmetered music | See also
| line breaks, beams | Predefined commands
| line, cross-staff | Staff-change lines
| line, staff-change | Staff-change lines
| line, staff-change follower | Staff-change lines
| `line-spanner-interface` | See also
| `line-width` | `\paper` variables for widths and margins
| `line-width` | 4.5.4 Line length
| `LineBreakEvent` | See also
| lineprall | A.11 List of articulations
| lines, grid | Grid lines
| lines, vertical between staves | Grid lines
| List of colors | Normal colors
| listing available fonts | Single entry fonts
| `Literature list` | Customizing chord names
| `Literature list` | See also
| `locrian` | Key signature
| `longa` | Durations
| `longa` | Rests
| longa rest | Rests
| longfermata | A.11 List of articulations
| `lower` | Text alignment
| lowering text | A.9.2 Align
| ltoe | A.11 List of articulations
| `ly:add-context-mod` | A.18 Scheme functions
| `ly:add-file-name-alist` | A.18 Scheme functions
| `ly:add-interface` | A.18 Scheme functions
| `ly:add-listener` | A.18 Scheme functions
| `ly:add-option` | A.18 Scheme functions
| `ly:all-grob-interfaces` | A.18 Scheme functions
| `ly:all-options` | A.18 Scheme functions
| `ly:all-stencil-expressions` | A.18 Scheme functions
| `ly:assoc-get` | A.18 Scheme functions
| `ly:axis-group-interface::add-element` | A.18 Scheme functions
| `ly:beam-score-count` | A.18 Scheme functions
| `ly:book-add-bookpart!` | A.18 Scheme functions
| `ly:book-add-score!` | A.18 Scheme functions
| `ly:book-book-parts` | A.18 Scheme functions
| `ly:book-header` | A.18 Scheme functions
| `ly:book-paper` | A.18 Scheme functions
| `ly:book-process` | A.18 Scheme functions
| `ly:book-process-to-systems` | A.18 Scheme functions
| `ly:book-scores` | A.18 Scheme functions
| `ly:box?` | A.18 Scheme functions
| `ly:bp` | A.18 Scheme functions
| `ly:bracket` | A.18 Scheme functions
| `ly:broadcast` | A.18 Scheme functions
| `ly:camel-case->lisp-identifier` | A.18 Scheme functions
| `ly:chain-assoc-get` | A.18 Scheme functions
| `ly:cm` | A.18 Scheme functions
| `ly:command-line-code` | A.18 Scheme functions
| `ly:command-line-options` | A.18 Scheme functions
| `ly:command-line-verbose?` | A.18 Scheme functions
| `ly:connect-dispatchers` | A.18 Scheme functions
| `ly:context-current-moment` | A.18 Scheme functions
| `ly:context-event-source` | A.18 Scheme functions
| `ly:context-events-below` | A.18 Scheme functions
| `ly:context-find` | A.18 Scheme functions
| `ly:context-grob-definition` | A.18 Scheme functions
| `ly:context-id` | A.18 Scheme functions
| `ly:context-name` | A.18 Scheme functions
| `ly:context-now` | A.18 Scheme functions
| `ly:context-parent` | A.18 Scheme functions
| `ly:context-property` | A.18 Scheme functions
| `ly:context-property-where-defined` | A.18 Scheme functions
| `ly:context-pushpop-property` | A.18 Scheme functions
| `ly:context-set-property!` | A.18 Scheme functions
| `ly:context-unset-property` | A.18 Scheme functions
| `ly:context?` | A.18 Scheme functions
| `ly:default-scale` | A.18 Scheme functions
| `ly:dimension?` | A.18 Scheme functions
| `ly:dir?` | A.18 Scheme functions
| `ly:dispatcher?` | A.18 Scheme functions
| `ly:duration->string` | A.18 Scheme functions
| `ly:duration-dot-count` | A.18 Scheme functions
| `ly:duration-factor` | A.18 Scheme functions
| `ly:duration-length` | A.18 Scheme functions
| `ly:duration-log` | A.18 Scheme functions
| `ly:duration<?` | A.18 Scheme functions
| `ly:duration?` | A.18 Scheme functions
| `ly:effective-prefix` | A.18 Scheme functions
| `ly:encode-string-for-pdf` | A.18 Scheme functions
| `ly:engraver-announce-end-grob` | A.18 Scheme functions
| `ly:engraver-make-grob` | A.18 Scheme functions
| `ly:error` | A.18 Scheme functions
| `ly:eval-simple-closure` | A.18 Scheme functions
| `ly:event-deep-copy` | A.18 Scheme functions
| `ly:event-property` | A.18 Scheme functions
| `ly:event-set-property!` | A.18 Scheme functions
| `ly:expand-environment` | A.18 Scheme functions
| `ly:export` | A.18 Scheme functions
| `ly:find-file` | A.18 Scheme functions
| `ly:font-config-add-directory` | A.18 Scheme functions
| `ly:font-config-add-font` | A.18 Scheme functions
| `ly:font-config-display-fonts` | A.18 Scheme functions
| `ly:font-config-get-font-file` | A.18 Scheme functions
| `ly:font-design-size` | A.18 Scheme functions
| `ly:font-file-name` | A.18 Scheme functions
| `ly:font-get-glyph` | A.18 Scheme functions
| `ly:font-glyph-name-to-charcode` | A.18 Scheme functions
| `ly:font-glyph-name-to-index` | A.18 Scheme functions
| `ly:font-index-to-charcode` | A.18 Scheme functions
| `ly:font-magnification` | A.18 Scheme functions
| `ly:font-metric?` | A.18 Scheme functions
| `ly:font-name` | A.18 Scheme functions
| `ly:font-sub-fonts` | A.18 Scheme functions
| `ly:format` | A.18 Scheme functions
| `ly:format-output` | A.18 Scheme functions
| `ly:get-all-function-documentation` | A.18 Scheme functions
| `ly:get-all-translators` | A.18 Scheme functions
| `ly:get-context-mods` | A.18 Scheme functions
| `ly:get-listened-event-classes` | A.18 Scheme functions
| `ly:get-option` | A.18 Scheme functions
| `ly:gettext` | A.18 Scheme functions
| `ly:grob-alist-chain` | A.18 Scheme functions
| `ly:grob-array->list` | A.18 Scheme functions
| `ly:grob-array-length` | A.18 Scheme functions
| `ly:grob-array-ref` | A.18 Scheme functions
| `ly:grob-array?` | A.18 Scheme functions
| `ly:grob-basic-properties` | A.18 Scheme functions
| `ly:grob-chain-callback` | A.18 Scheme functions
| `ly:grob-common-refpoint` | A.18 Scheme functions
| `ly:grob-common-refpoint-of-array` | A.18 Scheme functions
| `ly:grob-default-font` | A.18 Scheme functions
| `ly:grob-extent` | A.18 Scheme functions
| `ly:grob-interfaces` | A.18 Scheme functions
| `ly:grob-layout` | A.18 Scheme functions
| `ly:grob-object` | A.18 Scheme functions
| `ly:grob-original` | A.18 Scheme functions
| `ly:grob-parent` | A.18 Scheme functions
| `ly:grob-pq<?` | A.18 Scheme functions
| `ly:grob-properties` | A.18 Scheme functions
| `ly:grob-property` | A.18 Scheme functions
| `ly:grob-property-data` | A.18 Scheme functions
| `ly:grob-relative-coordinate` | A.18 Scheme functions
| `ly:grob-robust-relative-extent` | A.18 Scheme functions
| `ly:grob-script-priority-less` | A.18 Scheme functions
| `ly:grob-set-nested-property!` | A.18 Scheme functions
| `ly:grob-set-object!` | A.18 Scheme functions
| `ly:grob-set-parent!` | A.18 Scheme functions
| `ly:grob-set-property!` | A.18 Scheme functions
| `ly:grob-staff-position` | A.18 Scheme functions
| `ly:grob-suicide!` | A.18 Scheme functions
| `ly:grob-system` | A.18 Scheme functions
| `ly:grob-translate-axis!` | A.18 Scheme functions
| `ly:grob?` | A.18 Scheme functions
| `ly:gulp-file` | A.18 Scheme functions
| `ly:hash-table-keys` | A.18 Scheme functions
| `ly:inch` | A.18 Scheme functions
| `ly:input-both-locations` | A.18 Scheme functions
| `ly:input-file-line-char-column` | A.18 Scheme functions
| `ly:input-location?` | A.18 Scheme functions
| `ly:input-message` | A.18 Scheme functions
| `ly:interpret-music-expression` | A.18 Scheme functions
| `ly:interpret-stencil-expression` | A.18 Scheme functions
| `ly:intlog2` | A.18 Scheme functions
| `ly:is-listened-event-class` | A.18 Scheme functions
| `ly:item-break-dir` | A.18 Scheme functions
| `ly:item?` | A.18 Scheme functions
| `ly:iterator?` | A.18 Scheme functions
| `ly:lexer-keywords` | A.18 Scheme functions
| `ly:lily-lexer?` | A.18 Scheme functions
| `ly:lily-parser?` | A.18 Scheme functions
| `ly:listener?` | A.18 Scheme functions
| `ly:make-book` | A.18 Scheme functions
| `ly:make-book-part` | A.18 Scheme functions
| `ly:make-dispatcher` | A.18 Scheme functions
| `ly:make-duration` | A.18 Scheme functions
| `ly:make-global-context` | A.18 Scheme functions
| `ly:make-global-translator` | A.18 Scheme functions
| `ly:make-listener` | A.18 Scheme functions
| `ly:make-moment` | A.18 Scheme functions
| `ly:make-music` | A.18 Scheme functions
| `ly:make-music-function` | A.18 Scheme functions
| `ly:make-output-def` | A.18 Scheme functions
| `ly:make-page-label-marker` | A.18 Scheme functions
| `ly:make-page-permission-marker` | A.18 Scheme functions
| `ly:make-pango-description-string` | A.18 Scheme functions
| `ly:make-paper-outputter` | A.18 Scheme functions
| `ly:make-pitch` | A.18 Scheme functions
| `ly:make-prob` | A.18 Scheme functions
| `ly:make-scale` | A.18 Scheme functions
| `ly:make-score` | A.18 Scheme functions
| `ly:make-simple-closure` | A.18 Scheme functions
| `ly:make-stencil` | A.18 Scheme functions
| `ly:make-stream-event` | A.18 Scheme functions
| `ly:message` | A.18 Scheme functions
| `ly:minimal-breaking` | 4.3.5 Minimal page breaking
| `ly:minimal-breaking` | A.18 Scheme functions
| `ly:mm` | A.18 Scheme functions
| `ly:module->alist` | A.18 Scheme functions
| `ly:module-copy` | A.18 Scheme functions
| `ly:modules-lookup` | A.18 Scheme functions
| `ly:moment-add` | A.18 Scheme functions
| `ly:moment-div` | A.18 Scheme functions
| `ly:moment-grace-denominator` | A.18 Scheme functions
| `ly:moment-grace-numerator` | A.18 Scheme functions
| `ly:moment-main-denominator` | A.18 Scheme functions
| `ly:moment-main-numerator` | A.18 Scheme functions
| `ly:moment-mod` | A.18 Scheme functions
| `ly:moment-mul` | A.18 Scheme functions
| `ly:moment-sub` | A.18 Scheme functions
| `ly:moment<?` | A.18 Scheme functions
| `ly:moment?` | A.18 Scheme functions
| `ly:music-compress` | A.18 Scheme functions
| `ly:music-deep-copy` | A.18 Scheme functions
| `ly:music-duration-compress` | A.18 Scheme functions
| `ly:music-duration-length` | A.18 Scheme functions
| `ly:music-function-extract` | A.18 Scheme functions
| `ly:music-function?` | A.18 Scheme functions
| `ly:music-length` | A.18 Scheme functions
| `ly:music-list?` | A.18 Scheme functions
| `ly:music-mutable-properties` | A.18 Scheme functions
| `ly:music-output?` | A.18 Scheme functions
| `ly:music-property` | A.18 Scheme functions
| `ly:music-set-property!` | A.18 Scheme functions
| `ly:music-transpose` | A.18 Scheme functions
| `ly:music?` | A.18 Scheme functions
| `ly:note-column-accidentals` | A.18 Scheme functions
| `ly:note-column-dot-column` | A.18 Scheme functions
| `ly:note-head::stem-attachment` | A.18 Scheme functions
| `ly:number->string` | A.18 Scheme functions
| `ly:optimal-breaking` | 4.3.3 Optimal page breaking
| `ly:optimal-breaking` | A.18 Scheme functions
| `ly:option-usage` | A.18 Scheme functions
| `ly:otf->cff` | A.18 Scheme functions
| `ly:otf-font-glyph-info` | A.18 Scheme functions
| `ly:otf-font-table-data` | A.18 Scheme functions
| `ly:otf-font?` | A.18 Scheme functions
| `ly:otf-glyph-count` | A.18 Scheme functions
| `ly:otf-glyph-list` | A.18 Scheme functions
| `ly:output-def-clone` | A.18 Scheme functions
| `ly:output-def-lookup` | A.18 Scheme functions
| `ly:output-def-parent` | A.18 Scheme functions
| `ly:output-def-scope` | A.18 Scheme functions
| `ly:output-def-set-variable!` | A.18 Scheme functions
| `ly:output-def?` | A.18 Scheme functions
| `ly:output-description` | A.18 Scheme functions
| `ly:output-formats` | A.18 Scheme functions
| `ly:outputter-close` | A.18 Scheme functions
| `ly:outputter-dump-stencil` | A.18 Scheme functions
| `ly:outputter-dump-string` | A.18 Scheme functions
| `ly:outputter-module` | A.18 Scheme functions
| `ly:outputter-output-scheme` | A.18 Scheme functions
| `ly:outputter-port` | A.18 Scheme functions
| `ly:page-marker?` | A.18 Scheme functions
| `ly:page-turn-breaking` | 4.3.4 Optimal page turning
| `ly:page-turn-breaking` | A.18 Scheme functions
| `ly:pango-font-physical-fonts` | A.18 Scheme functions
| `ly:pango-font?` | A.18 Scheme functions
| `ly:paper-book-header` | A.18 Scheme functions
| `ly:paper-book-pages` | A.18 Scheme functions
| `ly:paper-book-paper` | A.18 Scheme functions
| `ly:paper-book-performances` | A.18 Scheme functions
| `ly:paper-book-scopes` | A.18 Scheme functions
| `ly:paper-book-systems` | A.18 Scheme functions
| `ly:paper-book?` | A.18 Scheme functions
| `ly:paper-fonts` | A.18 Scheme functions
| `ly:paper-get-font` | A.18 Scheme functions
| `ly:paper-get-number` | A.18 Scheme functions
| `ly:paper-outputscale` | A.18 Scheme functions
| `ly:paper-score-paper-systems` | A.18 Scheme functions
| `ly:paper-system-minimum-distance` | A.18 Scheme functions
| `ly:paper-system?` | A.18 Scheme functions
| `ly:parse-file` | A.18 Scheme functions
| `ly:parser-clear-error` | A.18 Scheme functions
| `ly:parser-clone` | A.18 Scheme functions
| `ly:parser-define!` | A.18 Scheme functions
| `ly:parser-error` | A.18 Scheme functions
| `ly:parser-has-error?` | A.18 Scheme functions
| `ly:parser-include-string` | A.18 Scheme functions
| `ly:parser-lexer` | A.18 Scheme functions
| `ly:parser-lookup` | A.18 Scheme functions
| `ly:parser-output-name` | A.18 Scheme functions
| `ly:parser-parse-string` | A.18 Scheme functions
| `ly:parser-set-note-names` | A.18 Scheme functions
| `ly:parser-set-repetition-function` | A.18 Scheme functions
| `ly:parser-set-repetition-symbol` | A.18 Scheme functions
| `ly:performance-write` | A.18 Scheme functions
| `ly:pfb->pfa` | A.18 Scheme functions
| `ly:pitch-alteration` | A.18 Scheme functions
| `ly:pitch-diff` | A.18 Scheme functions
| `ly:pitch-negate` | A.18 Scheme functions
| `ly:pitch-notename` | A.18 Scheme functions
| `ly:pitch-octave` | A.18 Scheme functions
| `ly:pitch-quartertones` | A.18 Scheme functions
| `ly:pitch-semitones` | A.18 Scheme functions
| `ly:pitch-steps` | A.18 Scheme functions
| `ly:pitch-transpose` | A.18 Scheme functions
| `ly:pitch<?` | A.18 Scheme functions
| `ly:pitch?` | A.18 Scheme functions
| `ly:pointer-group-interface::add-grob` | A.18 Scheme functions
| `ly:position-on-line?` | A.18 Scheme functions
| `ly:prob-immutable-properties` | A.18 Scheme functions
| `ly:prob-mutable-properties` | A.18 Scheme functions
| `ly:prob-property` | A.18 Scheme functions
| `ly:prob-property?` | A.18 Scheme functions
| `ly:prob-set-property!` | A.18 Scheme functions
| `ly:prob-type?` | A.18 Scheme functions
| `ly:prob?` | A.18 Scheme functions
| `ly:programming-error` | A.18 Scheme functions
| `ly:progress` | A.18 Scheme functions
| `ly:property-lookup-stats` | A.18 Scheme functions
| `ly:protects` | A.18 Scheme functions
| `ly:pt` | A.18 Scheme functions
| `ly:register-stencil-expression` | A.18 Scheme functions
| `ly:relative-group-extent` | A.18 Scheme functions
| `ly:reset-all-fonts` | A.18 Scheme functions
| `ly:round-filled-box` | A.18 Scheme functions
| `ly:round-filled-polygon` | A.18 Scheme functions
| `ly:run-translator` | A.18 Scheme functions
| `ly:score-add-output-def!` | A.18 Scheme functions
| `ly:score-embedded-format` | A.18 Scheme functions
| `ly:score-error?` | A.18 Scheme functions
| `ly:score-header` | A.18 Scheme functions
| `ly:score-music` | A.18 Scheme functions
| `ly:score-output-defs` | A.18 Scheme functions
| `ly:score-set-header!` | A.18 Scheme functions
| `ly:score?` | A.18 Scheme functions
| `ly:set-default-scale` | A.18 Scheme functions
| `ly:set-grob-modification-callback` | A.18 Scheme functions
| `ly:set-middle-C!` | A.18 Scheme functions
| `ly:set-option` | A.18 Scheme functions
| `ly:set-property-cache-callback` | A.18 Scheme functions
| `ly:simple-closure?` | A.18 Scheme functions
| `ly:skyline-pair?` | A.18 Scheme functions
| `ly:skyline?` | A.18 Scheme functions
| `ly:slur-score-count` | A.18 Scheme functions
| `ly:smob-protects` | A.18 Scheme functions
| `ly:solve-spring-rod-problem` | A.18 Scheme functions
| `ly:source-file?` | A.18 Scheme functions
| `ly:spanner-bound` | A.18 Scheme functions
| `ly:spanner-broken-into` | A.18 Scheme functions
| `ly:spanner-set-bound!` | A.18 Scheme functions
| `ly:spanner?` | A.18 Scheme functions
| `ly:spawn` | A.18 Scheme functions
| `ly:staff-symbol-line-thickness` | A.18 Scheme functions
| `ly:staff-symbol-staff-space` | A.18 Scheme functions
| `ly:start-environment` | A.18 Scheme functions
| `ly:stderr-redirect` | A.18 Scheme functions
| `ly:stencil-add` | A.18 Scheme functions
| `ly:stencil-aligned-to` | A.18 Scheme functions
| `ly:stencil-combine-at-edge` | A.18 Scheme functions
| `ly:stencil-empty?` | A.18 Scheme functions
| `ly:stencil-expr` | A.18 Scheme functions
| `ly:stencil-extent` | A.18 Scheme functions
| `ly:stencil-fonts` | A.18 Scheme functions
| `ly:stencil-in-color` | A.18 Scheme functions
| `ly:stencil-rotate` | A.18 Scheme functions
| `ly:stencil-rotate-absolute` | A.18 Scheme functions
| `ly:stencil-scale` | A.18 Scheme functions
| `ly:stencil-translate` | A.18 Scheme functions
| `ly:stencil-translate-axis` | A.18 Scheme functions
| `ly:stencil?` | A.18 Scheme functions
| `ly:stream-event?` | A.18 Scheme functions
| `ly:string-percent-encode` | A.18 Scheme functions
| `ly:string-substitute` | A.18 Scheme functions
| `ly:success` | A.18 Scheme functions
| `ly:system-font-load` | A.18 Scheme functions
| `ly:text-interface::interpret-markup` | A.18 Scheme functions
| `ly:translator-context` | A.18 Scheme functions
| `ly:translator-description` | A.18 Scheme functions
| `ly:translator-group?` | A.18 Scheme functions
| `ly:translator-name` | A.18 Scheme functions
| `ly:translator?` | A.18 Scheme functions
| `ly:transpose-key-alist` | A.18 Scheme functions
| `ly:truncate-list!` | A.18 Scheme functions
| `ly:ttf->pfa` | A.18 Scheme functions
| `ly:ttf-ps-name` | A.18 Scheme functions
| `ly:unit` | A.18 Scheme functions
| `ly:usage` | A.18 Scheme functions
| `ly:version` | A.18 Scheme functions
| `ly:warning` | A.18 Scheme functions
| `ly:wide-char->utf-8` | A.18 Scheme functions
| `lydian` | Key signature
| `LyricCombineMusic` | See also
| `LyricCombineMusic` | See also
| `LyricExtender` | See also
| `LyricHyphen` | See also
| `Lyrics` | See also
| `Lyrics` | See also
| `Lyrics` | See also
| `Lyrics` | See also
| `Lyrics` | See also
| `Lyrics` | A.14 All context properties
| `Lyrics` | A.14 All context properties
| lyrics and melodies | Automatic syllable durations
| lyrics and tied notes | Repeats with alternative endings
| lyrics assigned to one voice | Single-staff polyphony
| lyrics on grace notes | Adding syllables to grace notes
| lyrics punctuation | Entering lyrics
| lyrics, aligning to a melody | Aligning lyrics to a melody
| lyrics, aligning with sporadic melody | 5.1.3 Keeping contexts alive
| lyrics, divided | Divisi lyrics
| lyrics, entering | Entering lyrics
| lyrics, formatting | Entering lyrics
| Lyrics, increasing space between | Placing syllables horizontally
| lyrics, keeping inside margin | See also
| lyrics, positioning | Placing lyrics vertically
| lyrics, repeating | Lyrics and repeats
| lyrics, repeats with alternative endings | Repeats with alternative endings
| lyrics, skip | Invisible rests
| lyrics, skipping notes | Repeats with alternative endings
| lyrics, using variables | Working with lyrics and variables
| lyrics, with beams | Setting automatic beam behavior
| `LyricText` | See also
| `LyricText` | See also
| `LyricText` | See also
M |  |
| `m` | Common chords
| `magnify` | Selecting font and font size
| magnifying text | A.9.1 Font
| `magstep` | Selecting notation font size
| `magstep` | 5.4.4 Distances and measurements
| `maj` | Common chords
| `major` | Key signature
| `major seven symbols` | Predefined commands
| `majorSevenSymbol` | Customizing chord names
| `makam` | See also
| makam | Turkish note names
| `makamlar` | See also
| `makamlar` | See also
| `make-dynamic-script` | New dynamic marks
| `make-pango-font-tree` | Entire document fonts
| `makeClusters` | Clusters
| `makeClusters` | A.16 Available music functions
| `makeDefaultStringTunings` | A.16 Available music functions
| `makeStringTuning` | Custom tablatures
| `makeStringTuning` | A.16 Available music functions
| manual bar lines | Bar lines
| manual beams | Automatic beams
| manual beams | Manual beams
| manual beams, direction shorthand for | Manual beams
| manual beams, grace notes | Manual beams
| manual measure lines | Bar lines
| manual rehearsal mark | Rehearsal marks
| manual repeat mark | Manual repeat marks
| manual staff changes | Changing staff manually
| `Manuals` | LilyPond — Notation Reference
| `Manuals` | LilyPond — Notation Reference
| `maqam` | See also
| maqams | References for Arabic music
| marcato | Articulations and ornamentations
| marcato | A.11 List of articulations
| margin, text running over | See also
| `mark` | Rehearsal marks
| `mark` | Text marks
| mark, phrasing | Phrasing slurs
| mark, rehearsal | Rehearsal marks
| mark, rehearsal, format | Rehearsal marks
| mark, rehearsal, manual | Rehearsal marks
| mark, rehearsal, style | Rehearsal marks
| `MarkEvent` | See also
| `MarkEvent` | See also
| marks, text | Text marks
| `markup` | Text marks
| `markup` | Separate text
| `markup` | Separate text
| `markup` | Text markup introduction
| `Markup construction in Scheme` | New dynamic marks
| `Markup construction in Scheme` | See also
| `Markup construction in Scheme` | See also
| markup expressions | Text markup introduction
| markup mode, quoted text | Text markup introduction
| markup mode, special characters | Text markup introduction
| markup on multi-measure rest | Full measure rests
| markup syntax | Text markup introduction
| markup text | Text markup introduction
| markup text alignment commands | Text alignment
| markup text padding | Graphic notation inside markup
| markup text, aligning | Text alignment
| markup text, decorating | Graphic notation inside markup
| markup text, framing | Graphic notation inside markup
| markup text, justified | Text alignment
| markup text, multi-page | Multi-page markup
| markup text, wordwrapped | Text alignment
| markup, centering on the page | Text alignment
| markup, multi-line | Text alignment
| markup, multi-page | Multi-page markup
| markup, music notation inside | Music notation inside markup
| markup, score inside | Music notation inside markup
| `markup-markup-spacing` | List of flexible vertical spacing `\paper` variables
| `markup-system-spacing` | List of flexible vertical spacing `\paper` variables
| `markuplines` | Separate text
| `markuplines` | Multi-page markup
| `markuplines` | See also
| markups, aligning | Text alignment
| `Mark_engraver` | See also
| `Mark_engraver` | See also
| `max-systems-per-page` | `\paper` variables for line breaking
| `maxima` | Durations
| `maxima` | Rests
| maxima rest | Rests
| measure check | Bar and bar number checks
| measure groupings | Selected Snippets
| measure lines | Bar lines
| measure lines, invisible | Bar lines
| measure lines, manual | Bar lines
| measure number | Time administration
| measure number and repeats | Known issues and warnings
| measure number check | Bar and bar number checks
| measure number, format | Selected Snippets
| measure numbers | Bar numbers
| measure repeats | Percent repeats
| measure sub-grouping | Selected Snippets
| measure, change length | Upbeats
| measure, partial | Upbeats
| `measureLength` | Setting automatic beam behavior
| `measureLength` | Time administration
| `measurePosition` | Upbeats
| `measurePosition` | Time administration
| Medicaea, Editio | 2.9 Ancient notation
| Medicaea, Editio | 2.9.1 Overview of the supported styles
| medium intervals | References for Arabic music
| `melisma` | Multiple notes to one syllable
| `melisma` | See also
| melismata | Multiple notes to one syllable
| melismata, with beams | Automatic beams
| melody rhythms, showing | Showing melody rhythms
| mensural | 2.9 Ancient notation
| mensural | 2.9.1 Overview of the supported styles
| Mensural ligatures | White mensural ligatures
| mensural music, transcription of | Selected Snippets
| `mensural notation` | See also
| `mensural notation` | See also
| `mensural notation` | See also
| `mensural notation` | See also
| `mensural notation` | See also
| `mensural notation` | See also
| `mensural notation` | See also
| `mensural notation` | See also
| `mensural notation` | See also
| `mensural notation` | See also
| `MensuralStaff` | Instantiating new staves
| MensuralStaffContext | Mensural contexts
| MensuralVoiceContext | Mensural contexts
| mensuration sign | Mensural time signatures
| mensurstriche layout | Selected Snippets
| `mergeDifferentlyDottedOff` | Collision resolution
| `mergeDifferentlyDottedOn` | Collision resolution
| `mergeDifferentlyHeadedOff` | Collision resolution
| `mergeDifferentlyHeadedOn` | Collision resolution
| merging notes | Collision resolution
| merging text | A.9.2 Align
| `meter` | See also
| meter style | Time signature
| meter, polymetric | Polymetric notation
| `metronome` | See also
| `metronome mark` | See also
| metronome marking with text | Metronome marks
| `MetronomeMark` | See also
| `metronomic indication` | See also
| mezzosoprano clef | Clef
| `mf` | Dynamics
| microtones | Note names in other languages
| Microtones in MIDI | Supported in MIDI
| MIDI | Instrument transpositions
| MIDI | 3.5 MIDI output
| MIDI block | 3.5.2 MIDI block
| MIDI context definitions | 3.5.2 MIDI block
| MIDI transposition | Instrument transpositions
| MIDI, articulations | Supported in MIDI
| MIDI, chord names | Supported in MIDI
| MIDI, microtones | Supported in MIDI
| MIDI, Pitches | Supported in MIDI
| MIDI, quarter tones | Supported in MIDI
| MIDI, Rhythms | Supported in MIDI
| `min-systems-per-page` | `\paper` variables for line breaking
| `minimum-Y-extent` | Within-system spacing properties
| `minimumFret` | Default tablatures
| `minimumFret` | Automatic fret diagrams
| `minimumPageTurnLength` | 4.3.4 Optimal page turning
| `minimumRepeatLengthForPageTurn` | 4.3.4 Optimal page turning
| `minor` | Key signature
| mirroring markup | A.9.3 Graphic
| `mixed` | Piano pedals
| `mixolydian` | Key signature
| modal inversion | Modal inversion
| modal transformations | Modal transformations
| modal transposition | Modal transposition
| `modalInversion` | Modal inversion
| `modalInversion` | A.16 Available music functions
| `modalTranspose` | Modal transposition
| `modalTranspose` | A.16 Available music functions
| mode | parser variable
| `modern` | Automatic accidentals
| modern accidental style | Automatic accidentals
| modern accidental style | Automatic accidentals
| modern accidental style | Automatic accidentals
| modern accidentals | Automatic accidentals
| modern cautionary accidental style | Automatic accidentals
| modern style accidentals | Automatic accidentals
| modern style accidentals | Automatic accidentals
| modern style cautionary accidentals | Automatic accidentals
| `modern-cautionary` | Automatic accidentals
| modern-cautionary accidental style | Automatic accidentals
| `modern-voice` | Automatic accidentals
| `modern-voice-cautionary` | Automatic accidentals
| moderntab clef | Custom tablatures
| modes | Key signature
| modifiers, in chords. | Common chords
| mordent | Articulations and ornamentations
| mordent | A.11 List of articulations
| mordent, down | Articulations and ornamentations
| mordent, up | Articulations and ornamentations
| movements, multiple | 3.1.2 Multiple scores in a book
| `Moving objects` | Text alignment
| `Moving objects` | See also
| `mp` | Dynamics
| multi-line markup | Text alignment
| multi-line text | Text alignment
| `multi-measure rest` | See also
| multi-measure rest with markup | Full measure rests
| multi-measure rest, attaching fermata | Full measure rests
| multi-measure rest, attaching text | Full measure rests
| multi-measure rest, contracting | Full measure rests
| multi-measure rest, expanding | Full measure rests
| multi-measure rest, script | Full measure rests
| multi-measure rests | Full measure rests
| multi-measure rests and fingerings | See also
| multi-measure rests, positioning | Selected Snippets
| multi-note acciaccatura | Known issues and warnings
| multi-page markup | Multi-page markup
| `MultiMeasureRest` | See also
| `MultiMeasureRestNumber` | See also
| `MultiMeasureRestText` | Full measure rests
| multiple dynamic marks on one note | Dynamics
| `Multiple notes at once` | See also
| multiple phrasing slurs | Phrasing slurs
| multiple slurs | Slurs
| multiple voices | Collision resolution
| multivoice accidentals | Automatic accidentals
| `Music classes` | See also
| `Music definitions` | 5.2.1 Navigating the program reference
| `Music expressions explained` | See also
| `Music functions` | 5.6 Using music functions
| `Music functions` | 5.6.1 Substitution function syntax
| `Music functions` | See also
| music glyphs | Rehearsal marks
| music inside markup | Music notation inside markup
| music, beginners’ | Easy notation note heads
| music, unmetered | Time administration
| Musica ficta | Annotational accidentals (musica ficta)
| musical cues | Musical cues
| `musicglyph` | Rehearsal marks
| `musicMap` | A.16 Available music functions
| musicological analysis | Analysis brackets
| musicQuotes | parser variable
| mutable objects | mutable
| mutable properties | mutable
N |  |
| N.C. symbol | Printing chord names
| `name` | 5.1.6 Defining new contexts
| name of singer | Adding singers’ names to stanzas
| names, character | Character names
| `Naming conventions of objects and properties` | See also
| `Naming conventions of objects and properties` | See also
| natural harmonics | Harmonics
| natural pitch | Accidentals
| natural sign | Accidentals
| `neo-modern` | Automatic accidentals
| neo-modern accidental style | Automatic accidentals
| `neo-modern-cautionary` | Automatic accidentals
| neo-modern-cautionary accidental style | Automatic accidentals
| `neo-modern-voice` | Automatic accidentals
| neo-modern-voice accidental style | Automatic accidentals
| `neo-modern-voice-cautionary` | Automatic accidentals
| neo-modern-voice-cautionary accidental style | Automatic accidentals
| neomensural | 2.9.1 Overview of the supported styles
| nested contexts | 5.1.7 Aligning contexts
| nested repeat | Known issues and warnings
| nested staff brackets | Nested staff groups
| `Nesting music expressions` | Ossia staves
| `Nesting music expressions` | See also
| nesting of staves | Nested staff groups
| new contexts | 5.1.2 Creating contexts
| new dynamic marks | New dynamic marks
| `New markup list command definition` | See also
| new staff | Instantiating new staves
| `New_fingering_engraver` | See also
| `New_fingering_engraver` | 5.2.1 Navigating the program reference
| niente, al | Selected Snippets
| no chord symbol | Printing chord names
| no reset accidental style | Automatic accidentals
| `no-reset` | Automatic accidentals
| `noBeam` | Manual beams
| non-ASCII characters | 3.3.3 Text encoding
| non-empty texts | Text scripts
| non-musical symbols | Graphic notation inside markup
| non-text fonts in markup | Fonts explained
| `NonMusicalPaperColumn` | See also
| `nonstaff-nonstaff-spacing` | Within-system spacing properties
| `nonstaff-relatedstaff-spacing` | Within-system spacing properties
| `nonstaff-unrelatedstaff-spacing` | Within-system spacing properties
| `noPageBreak` | A.16 Available music functions
| `noPageTurn` | A.16 Available music functions
| normal repeat | 1.4.1 Long repeats
| `normalsize` | Selecting notation font size
| `normalsize` | Selecting font and font size
| notation font size | Selecting notation font size
| notation inside markup | Music notation inside markup
| notation, explaining | Balloon help
| notation, graphic | Graphic notation inside markup
| note cluster | Clusters
| note collisions | Collision resolution
| note duration, default | Durations
| note durations | Durations
| note grouping bracket | Analysis brackets
| `note head` | See also
| note head styles | Special note heads
| note head styles | A.8 Note head styles
| note heads | Selecting notation font size
| note heads, Aiken | Shape note heads
| note heads, ancient | Mensural note heads
| note heads, Christian Harmony | Shape note heads
| note heads, cross | Special note heads
| note heads, diamond | Special note heads
| note heads, diamond-shaped | Harmonics
| note heads, easy notation | Easy notation note heads
| note heads, easy play | Easy notation note heads
| note heads, Funk | Shape note heads
| note heads, guitar | Special note heads
| note heads, harmonic | Special note heads
| note heads, Harmonica Sacra | Shape note heads
| note heads, improvisation | Improvisation
| note heads, parlato | Special note heads
| note heads, practice | Easy notation note heads
| note heads, sacred harp | Shape note heads
| note heads, shape | Shape note heads
| note heads, slashed | Improvisation
| note heads, Southern Harmony | Shape note heads
| note heads, special | Special note heads
| note heads, Walker | Shape note heads
| note lengths | Durations
| note names, default | Accidentals
| note names, Dutch | Accidentals
| note names, other languages | Note names in other languages
| `note value` | See also
| `note-collision-interface` | A.15 Layout properties
| `note-collision-interface` | A.15 Layout properties
| `note-collision-interface` | A.15 Layout properties
| `note-event` | See also
| `note-event` | See also
| `note-event` | See also
| `note-head-interface` | See also
| `note-head-interface` | See also
| `note-head-interface` | See also
| `NoteCollision` | See also
| `NoteColumn` | See also
| `NoteHead` | See also
| `NoteHead` | See also
| `NoteHead` | See also
| notes within text by log and dot-count | A.9.4 Music
| notes within text by string | A.9.4 Music
| notes, colored | Coloring objects
| notes, colored in chords | See also
| notes, cross-staff | Changing staff manually
| notes, cross-staff | Cross-staff stems
| notes, dotted | Durations
| notes, double-dotted | Durations
| notes, ghost | Parentheses
| notes, hidden | Hidden notes
| notes, invisible | Hidden notes
| notes, parenthesized | Parentheses
| notes, smaller | Formatting cue notes
| notes, splitting | Automatic note splitting
| notes, transparent | Hidden notes
| notes, transposition of | Transpose
| `NoteSpacing` | See also
| `NoteSpacing` | 4.5.1 Horizontal spacing overview
| `NoteSpacing` | See also
| `Note_heads_engraver` | Automatic note splitting
| `Note_heads_engraver` | See also
| `Note_heads_engraver` | See also
| `Note_heads_engraver` | See also
| `Note_heads_engraver` | 5.1.6 Defining new contexts
| `Note_head_line_engraver` | See also
| `Note_spacing_engraver` | See also
| `null` | Text alignment
| number of staff lines | Staff symbol
| numbers, bar | Bar numbers
| numbers, measure | Bar numbers
| `numericTimeSignature` | Time signature
O |  |
| `Objects and interfaces` | See also
| `Objects and interfaces` | See also
| objects, colored | Coloring objects
| objects, coloring | Painting objects white
| objects, overwriting | Painting objects white
| objects, rotating | Rotating layout objects
| objects, visibility of | 5.4.7 Visibility of objects
| octavated clefs, visibility of | Special considerations
| `OctavateEight` | See also
| `octavation` | See also
| octave changing mark | Absolute octave entry
| octave check | Octave checks
| octave correction | Octave checks
| octave entry, absolute | Absolute octave entry
| octave entry, relative | Relative octave entry
| octave specification, absolute | Absolute octave entry
| octave specification, relative | Relative octave entry
| octave transposition | Clef
| `octaveCheck` | Octave checks
| `octaveCheck` | A.16 Available music functions
| `On the un-nestedness of brackets and ties` | See also
| `On the un-nestedness of brackets and ties` | See also
| `oneVoice` | Single-staff polyphony
| open | Articulations and ornamentations
| open | A.11 List of articulations
| open string indication | Bowing indications
| operation, inversion | Inversion
| operation, modal inversion | Modal inversion
| operation, retrograde | Retrograde
| operation, transposition | Modal transposition
| operations, modal | Modal transformations
| `Optical spacing` | 4.5.1 Horizontal spacing overview
| `Optical spacing` | See also
| oratorio | 2.1.5 Choral
| orchestral strings | 2.3 Unfretted string instruments
| organ pedal marks | Articulations and ornamentations
| `Organizing` | Using variables
| `Organizing pieces with variables` | See also
| `Organizing pieces with variables` | See also
| `Organizing pieces with variables` | See also
| orientation | Setting paper size
| ornamentation | Articulations and ornamentations
| ornaments | Grace notes
| ornaments | Articulations and ornamentations
| `ossia` | See also
| ossia | Hiding staves
| ossia | 5.1.7 Aligning contexts
| `Other sources of information` | See also
| `Other sources of information` | Extending notation and tuning systems
| `Other sources of information` | See also
| `Other sources of information` | 3.3.1 Including LilyPond files
| `Other sources of information` | 3.3.1 Including LilyPond files
| `Other sources of information` | See also
| `Other sources of information` | Installation Instructions for MacOS
| `Other sources of information` | See also
| `Other sources of information` | 3.5.2 MIDI block
| `Other sources of information` | Dynamic marks
| `Other sources of information` | 5.2.2 Layout interfaces
| `Other sources of information` | See also
| `Other uses for tweaks` | References for keyboards
| `Other uses for tweaks` | See also
| `ottava` | Ottava brackets
| `ottava` | A.16 Available music functions
| `ottava-bracket-interface` | See also
| `OttavaBracket` | See also
| `Ottava_spanner_engraver` | See also
| Ottoman music | References for Turkish classical music
| `outer-margin` | `\paper` variables for two-sided mode
| output-count | parser variable
| output-def | output-def
| output-suffix | parser variable
| `outside-staff-horizontal-padding` | 4.4.3 Vertical collision avoidance
| `outside-staff-padding` | 4.4.3 Vertical collision avoidance
| `outside-staff-priority` | 4.4.3 Vertical collision avoidance
| `overrideProperty` | A.16 Available music functions
| `OverrideProperty` | See also
| overrides in lyric mode | Entering lyrics
| overrides, reverting | 5.3.3 The `\override` command
| `overrideTimeSignatureSettings` | A.16 Available music functions
| overriding for only one moment | 5.3.3 The `\override` command
| overriding properties within text markup | A.9.6 Other
| overwriting objects | Painting objects white
P |  |
| `p` | Dynamics
| `pad-around` | Graphic notation inside markup
| `pad-markup` | Graphic notation inside markup
| `pad-to-box` | Graphic notation inside markup
| `pad-x` | Graphic notation inside markup
| padding | 5.2.3 Determining the grob property
| padding around text | Graphic notation inside markup
| padding text | A.9.2 Align
| padding text horizontally | A.9.2 Align
| page breaks | 4.5.4 Line length
| page breaks in cadenzas | See also
| page breaks in unmetered music | See also
| page layout | 4.5.4 Line length
| page numbers, auto-numbering | `\paper` variables for page numbering
| page numbers, specify the first | `\paper` variables for page numbering
| page numbers, suppress | `\paper` variables for page numbering
| page size | 4.1.2 Paper size and automatic scaling
| `page-breaking` | `\paper` variables for page breaking
| `page-breaking-system-system-spacing` | `\paper` variables for page breaking
| `page-count` | `\paper` variables for page breaking
| `page-spacing-weight` | Miscellaneous `\paper` variables
| `pageBreak` | A.16 Available music functions
| `pageTurn` | A.16 Available music functions
| `palmMute` | A.16 Available music functions
| `palmMuteOn` | A.16 Available music functions
| Pango | Fonts explained
| paper size | 4.1.2 Paper size and automatic scaling
| `paper-height` | 4.1.3 Fixed vertical spacing `\paper` variables
| `paper-width` | `\paper` variables for widths and margins
| parallel music | Writing music in parallel
| `parallelMusic` | Writing music in parallel
| `parallelMusic` | A.16 Available music functions
| parentheses | Parentheses
| `parentheses-interface` | See also
| `ParenthesesItem` | See also
| `Parenthesis_engraver` | See also
| `parenthesize` | Parentheses
| `parenthesize` | A.16 Available music functions
| parenthesized accidental | Accidentals
| parlato | Spoken music
| parlato note heads | Special note heads
| parser | parser
| parser variable | parser variable
| parseStringResult | parser variable
| `part` | See also
| part combiner | Automatic part combining
| part songs | 2.1.5 Choral
| `partcombine` | Automatic part combining
| `partcombine` | A.16 Available music functions
| `partcombineForce` | A.16 Available music functions
| partCombineListener | parser variable
| `PartCombineMusic` | See also
| `partial` | Upbeats
| partial measure | Upbeats
| paths, drawing | A.9.3 Graphic
| pause mark | Breath marks
| pedal diagrams, harp | Harp pedals
| pedal indication styles | Piano pedals
| pedal indication, bracket | Piano pedals
| pedal indication, mixed | Piano pedals
| pedal indication, text | Piano pedals
| pedal marks, organ | Articulations and ornamentations
| pedal sustain style | Piano pedals
| pedal, sostenuto | Piano pedals
| pedal, sustain | Piano pedals
| pedals, harp | Harp pedals
| pedals, piano | Piano pedals
| `pedalSustainStyle` | Piano pedals
| `percent` | Percent repeats
| `percent repeat` | See also
| percent repeats | Percent repeats
| `PercentRepeat` | See also
| `PercentRepeatCounter` | See also
| `PercentRepeatedMusic` | See also
| `Percent_repeat_engraver` | See also
| percussion | Basic percussion notation
| percussion | Percussion staves
| percussion clef | Basic percussion notation
| percussion staff | Instantiating new staves
| Petrucci | 2.9 Ancient notation
| Petrucci | 2.9.1 Overview of the supported styles
| phrasing bracket | Analysis brackets
| phrasing marks | Phrasing slurs
| phrasing slur | Slurs
| phrasing slur, dashed | Phrasing slurs
| phrasing slur, defining dash patterns | Phrasing slurs
| phrasing slur, dotted | Phrasing slurs
| phrasing slur, half solid and half dashed | Phrasing slurs
| phrasing slur, multiple | Phrasing slurs
| phrasing slur, simultaneous | Phrasing slurs
| phrasing slurs | Phrasing slurs
| phrasing, in lyrics | Multiple notes to one syllable
| `PhrasingSlur` | See also
| `phrasingSlurDashed` | Phrasing slurs
| `phrasingSlurDashPattern` | Phrasing slurs
| `phrasingSlurDashPattern` | A.16 Available music functions
| `phrasingSlurDotted` | Phrasing slurs
| `phrasingSlurDown` | Phrasing slurs
| `phrasingSlurHalfDashed` | Phrasing slurs
| `phrasingSlurHalfSolid` | Phrasing slurs
| `phrasingSlurNeutral` | Phrasing slurs
| `phrasingSlurSolid` | Phrasing slurs
| `phrasingSlurUp` | Phrasing slurs
| `phrygian` | Key signature
| `piano` | Automatic accidentals
| piano accidental style | Automatic accidentals
| piano accidentals | Automatic accidentals
| piano cautionary accidental style | Automatic accidentals
| piano cautionary accidentals | Automatic accidentals
| piano music, centering dynamics | References for keyboards
| piano pedals | Piano pedals
| piano staff | Grouping staves
| piano staves | References for keyboards
| `piano-cautionary` | Automatic accidentals
| `PianoPedalBracket` | See also
| `PianoStaff` | References for keyboards
| `PianoStaff` | Changing staff automatically
| `PianoStaff` | See also
| `PianoStaff` | See also
| `PianoStaff` | See also
| `PianoStaff` | See also
| `Piano_pedal_engraver` | See also
| pickup in a repeat | Normal repeats
| pickup measure | Upbeats
| `pipeSymbol` | Bar and bar number checks
| `Pitch names` | See also
| pitch names | Absolute octave entry
| `Pitch names` | See also
| `Pitch names` | See also
| `Pitch names` | See also
| `Pitch names` | See also
| pitch names, other languages | Note names in other languages
| pitch range | Ambitus
| pitched trill with accidental | Trills
| pitched trills | Trills
| `pitchedTrill` | Trills
| `pitchedTrill` | A.16 Available music functions
| pitches | Absolute octave entry
| Pitches in MIDI | Supported in MIDI
| pitches, transposition of | Transpose
| pitchnames | parser variable
| `Pitch_squash_engraver` | Showing melody rhythms
| `Pitch_squash_engraver` | See also
| `Pitch_squash_engraver` | 5.1.6 Defining new contexts
| `Pitch_squash_engraver` | A.14 All context properties
| pizzicato, Bartók | Snap (Bartók) pizzicato
| pizzicato, snap | Snap (Bartók) pizzicato
| placement of lyrics | Placing lyrics vertically
| `Placement of objects` | Articulations and ornamentations
| `Placement of objects` | See also
| `Placement of objects` | Text scripts
| `Placement of objects` | See also
| placing horizontal brackets around text | A.9.3 Graphic
| placing parentheses around text | A.9.3 Graphic
| placing vertical brackets around text | A.9.3 Graphic
| `pointAndClickOff` | A.16 Available music functions
| `pointAndClickOn` | A.16 Available music functions
| `polymetric` | See also
| `polymetric` | See also
| polymetric meters, with beams | Polymetric notation
| polymetric scores | 5.1.4 Modifying context plug-ins
| polymetric signatures | Polymetric notation
| `polymetric time signature` | See also
| polyphonic music | Collision resolution
| `polyphony` | See also
| polyphony, single-staff | Single-staff polyphony
| `portato` | See also
| portato | A.11 List of articulations
| positioning multi-measure rests | Selected Snippets
| `postscript` | Graphic notation inside markup
| `power chord` | See also
| power chords | Indicating power chords
| `powerChords` | Indicating power chords
| `pp` | Dynamics
| `ppp` | Dynamics
| `pppp` | Dynamics
| `ppppp` | Dynamics
| practice note heads | Easy notation note heads
| prall | Articulations and ornamentations
| prall | A.11 List of articulations
| prall, down | Articulations and ornamentations
| prall, up | Articulations and ornamentations
| pralldown | A.11 List of articulations
| prallmordent | Articulations and ornamentations
| prallmordent | A.11 List of articulations
| prallprall | Articulations and ornamentations
| prallprall | A.11 List of articulations
| prallup | A.11 List of articulations
| predefined string tunings for fretted instruments | Custom tablatures
| `predefinedFretboardsOff` | Automatic fret diagrams
| `predefinedFretboardsOn` | Automatic fret diagrams
| prima volta | 1.4.1 Long repeats
| `print-all-headers` | Miscellaneous `\paper` variables
| `print-first-page-number` | `\paper` variables for page numbering
| `print-page-number` | `\paper` variables for page numbering
| printing chord names | Printing chord names
| printing order | Painting objects white
| printing reserved characters | Text markup introduction
| printing special characters | Text markup introduction
| prob | prob
| properties | 5.3.2 The `\set` command
| `Properties found in interfaces` | See also
| `Properties of layout objects` | See also
| properties, grob | See also
| property object | prob
| `PropertySet` | See also
| psalms | 2.1.7 Chants psalms and hymns
| punctuation in lyrics | Entering lyrics
| putting space around text | A.9.2 Align
Q |  |
| `quarter tone` | See also
| quarter tones | Accidentals
| Quarter tones in MIDI | Supported in MIDI
| quarter-tone accidental | See also
| quote, voices | Quoting other voices
| quoted text | Text scripts
| quoted text in markup mode | Text markup introduction
| `quotedCueEventTypes` | Selected Snippets
| `quotedEventTypes` | Selected Snippets
| `quoteDuring` | Quoting other voices
| `quoteDuring` | Formatting cue notes
| `quoteDuring` | A.16 Available music functions
| `QuoteMusic` | See also
| quotes in lyrics | Entering lyrics
| quotes, in lyrics | Multiple syllables to one note
| quoting other voices | Formatting cue notes
R |  |
| `R` | Full measure rests
| `r` | Rests
| `ragged-bottom` | 4.1.3 Fixed vertical spacing `\paper` variables
| `ragged-last` | `\paper` variables for widths and margins
| `ragged-last` | 4.5.4 Line length
| `ragged-last-bottom` | 4.1.3 Fixed vertical spacing `\paper` variables
| `ragged-right` | `\paper` variables for widths and margins
| `ragged-right` | 4.5.4 Line length
| railroad tracks | Selected Snippets
| `raise` | Text alignment
| raising text | A.9.2 Align
| rallentando in MIDI | Supported in MIDI
| range of pitches | Ambitus
| `rast` | See also
| Ratisbona, Editio | 2.9.1 Overview of the supported styles
| `Real music example` | Collision resolution
| `Real music example` | See also
| `Real music example` | References for keyboards
| `Real music example` | See also
| referencing page labels in text | A.9.6 Other
| referencing page numbers in text | A.9.6 Other
| referencing page numbers in text | A.9.6 Other
| regular line breaks | 4.3.1 Line breaking
| rehearsal mark format | Rehearsal marks
| rehearsal mark style | Rehearsal marks
| rehearsal mark, manual | Rehearsal marks
| rehearsal marks | Rehearsal marks
| `RehearsalMark` | See also
| `RehearsalMark` | See also
| `relative` | Relative octave entry
| `relative` | See also
| `relative` | See also
| `relative` | Changing staff automatically
| relative music and autochange | Changing staff automatically
| relative octave entry | Relative octave entry
| relative octave entry and chords | Relative octave entry
| relative octave entry and transposition | See also
| relative octave specification | Relative octave entry
| relative pitch, chords | Chorded notes
| `RelativeOctaveCheck` | See also
| `RelativeOctaveMusic` | See also
| religious music | 2.1.7 Chants psalms and hymns
| reminder accidental | Accidentals
| removals, in chords | Extended and altered chords
| remove tagged music | Using tags
| `removeWithTag` | A.16 Available music functions
| removing cue notes | Formatting cue notes
| removing cues | Formatting cue notes
| renaissance music | Selected Snippets
| `repeat` | See also
| repeat and measure number | Known issues and warnings
| repeat and slur | Known issues and warnings
| repeat bars | Bar lines
| repeat number, changing | Manual repeat marks
| repeat timing information | Known issues and warnings
| repeat volta, changing | Manual repeat marks
| repeat with alternate endings | 1.4.1 Long repeats
| repeat with anacrucis | Normal repeats
| repeat with pickup | Normal repeats
| repeat with upbeat | Normal repeats
| repeat, ambiguous | Known issues and warnings
| repeat, end | Manual repeat marks
| repeat, manual | Manual repeat marks
| repeat, measure | Percent repeats
| repeat, nested | Known issues and warnings
| repeat, normal | 1.4.1 Long repeats
| repeat, percent | Percent repeats
| repeat, short | Percent repeats
| repeat, start | Manual repeat marks
| repeat, tremolo | Tremolo repeats
| repeat, unfold | Written-out repeats
| `repeatCommands` | Manual repeat marks
| `RepeatedMusic` | See also
| `RepeatedMusic` | See also
| `RepeatedMusic` | See also
| repeating lyrics with alternative endings | Repeats with alternative endings
| repeating ties | Ties
| repeats | Bar lines
| repeats and lyrics | Lyrics and repeats
| repeats in MIDI | 3.5.4 Repeats in MIDI
| repeats with ties | Normal repeats
| repeats, written-out | Written-out repeats
| `RepeatSlash` | See also
| `RepeatSlashEvent` | See also
| `repeatTie` | Ties
| repetitious music | Written-out repeats
| reserved characters, printing | Text markup introduction
| `resetRelativeOctave` | A.16 Available music functions
| resizing of staves | Ossia staves
| `rest` | Rests
| `Rest` | See also
| rest, church | Selected Snippets
| rest, collisions of | Known issues and warnings
| rest, condensing ordinary | Known issues and warnings
| rest, entering durations | Rests
| rest, full-measure | Full measure rests
| rest, invisible | Invisible rests
| rest, multi-measure | Rests
| rest, multi-measure | Full measure rests
| rest, specifying vertical position | Rests
| rest, whole for a full measure | Full measure rests
| rest, whole-measure | Rests
| rest-event | Selected Snippets
| `RestCollision` | See also
| restoring default properties for time signatures | Time signature
| rests, ancient | Mensural rests
| rests, splitting | Automatic note splitting
| `Rest_engraver` | See also
| `retrograde` | Retrograde
| `retrograde` | A.16 Available music functions
| retrograde transformation | Retrograde
| reverseturn | Articulations and ornamentations
| reverseturn | A.11 List of articulations
| reverting overrides | 5.3.3 The `\override` command
| `RevertProperty` | See also
| `revertTimeSignatureSettings` | A.16 Available music functions
| `rfz` | Dynamics
| rgb color | Coloring objects
| `rgb-color` | Coloring objects
| rheel | A.11 List of articulations
| rhythmic staff | Instantiating new staves
| `RhythmicStaff` | Instantiating new staves
| `RhythmicStaff` | See also
| `RhythmicStaff` | See also
| Rhythms in MIDI | Supported in MIDI
| rhythms, showing melody | Showing melody rhythms
| right aligning text | A.9.2 Align
| right hand fingerings for fretted instruments | Right-hand fingerings
| `right-align` | Text alignment
| `right-margin` | `\paper` variables for widths and margins
| `rightHandFinger` | Right-hand fingerings
| `rightHandFinger` | A.16 Available music functions
| root of chord | Common chords
| rotating objects | Rotating layout objects
| rotating text | A.9.2 Align
| `rounded-box` | Graphic notation inside markup
| rtoe | A.11 List of articulations
| `Running a function on all layout objects` | 5.1.2 Creating contexts
S |  |
| `s` | Invisible rests
| sacred harp note heads | Shape note heads
| `sacredHarpHeads` | Shape note heads
| `sacredHarpHeadsMinor` | Shape note heads
| SATB | 2.1.5 Choral
| scalable vector graphics output | 3.4.3 Alternative output formats
| `scaleDurations` | Scaling durations
| `scaleDurations` | Polymetric notation
| `scaleDurations` | A.16 Available music functions
| scaling durations | Scaling durations
| scaling markup | A.9.3 Graphic
| scaling text | A.9.2 Align
| Scheme object | smob
| `Scheme tutorial` | 5. Changing defaults
| Scheme variable | parser variable
| `scordatura` | See also
| `Score` | See also
| `Score` | A.14 All context properties
| `Score` | A.14 All context properties
| score inside markup | Music notation inside markup
| `Score is a (single) compound musical expression` | See also
| `score-markup-spacing` | List of flexible vertical spacing `\paper` variables
| `score-system-spacing` | List of flexible vertical spacing `\paper` variables
| `Scores and parts` | 3.3.1 Including LilyPond files
| `Scores and parts` | See also
| Scottish highland bagpipe | Bagpipe definitions
| `Script` | Articulations and ornamentations
| `Script` | See also
| `Script` | See also
| script on multi-measure rest | Full measure rests
| `ScriptEvent` | See also
| scripts | Articulations and ornamentations
| `Script_engraver` | See also
| seconda volta | 1.4.1 Long repeats
| segno | Bar lines
| segno | Rehearsal marks
| segno | Articulations and ornamentations
| segno | A.11 List of articulations
| segno on bar line | Text marks
| selecting font size (notation) | Selecting notation font size
| `self-alignment-interface` | 5.2.2 Layout interfaces
| `self-alignment-interface` | 5.5.1 Aligning objects
| `self-alignment-X` | Within-system spacing properties
| `semai` | See also
| Semai form | Arabic time signatures
| semi-flat | Note names in other languages
| Semi-flat symbol appearance | Arabic note names
| semi-flats | Accidentals
| semi-sharp | Note names in other languages
| semi-sharps | Accidentals
| semicirculus | A.11 List of articulations
| separate text | Separate text
| sesqui-flat | Note names in other languages
| sesqui-sharp | Note names in other languages
| `set` | Setting automatic beam behavior
| `set-accidental-style` | Automatic accidentals
| `set-octavation` | Ottava brackets
| setting extent of text objects | A.9.6 Other
| setting horizontal text alignment | A.9.2 Align
| setting of ledger lines | Staff symbol
| `Setting simple songs` | References for vocal music
| `Setting simple songs` | See also
| setting subscript in standard font size | A.9.1 Font
| setting superscript in standard font size | A.9.1 Font
| seventh chords | Common chords
| `sf` | Dynamics
| `sff` | Dynamics
| `sfz` | Dynamics
| shape notes | Shape note heads
| shared properties | immutable
| `sharp` | See also
| sharp, double | Accidentals
| shift note | Collision resolution
| shift rest, automatic | Collision resolution
| `shiftDurations` | A.16 Available music functions
| shifting voices | Collision resolution
| `shiftOff` | Collision resolution
| `shiftOn` | Collision resolution
| `shiftOnn` | Collision resolution
| `shiftOnnn` | Collision resolution
| `short-indent` | Instrument names
| `short-indent` | `\paper` variables for shifts and indents
| shortfermata | A.11 List of articulations
| `show-available-fonts` | Single entry fonts
| `showFirstLength` | 3.4.2 Skipping corrected music
| `showKeySignature` | Bagpipe definitions
| `showLastLength` | 3.4.2 Skipping corrected music
| `showStaffSwitch` | Staff-change lines
| `side-position-interface` | 5.2.2 Layout interfaces
| `side-position-interface` | 5.5.1 Aligning objects
| signatures, polymetric | Polymetric notation
| signumcongruentiae | A.11 List of articulations
| `sikah` | See also
| `simile` | See also
| simple closure | closure
| simple text strings | A.9.1 Font
| simple text strings with tie characters | A.9.4 Music
| simultaneous notes and accidentals | See also
| simultaneous phrasing slurs | Phrasing slurs
| simultaneous slurs | Slurs
| singer name | Adding singers’ names to stanzas
| single-staff polyphony | Single-staff polyphony
| `Size of objects` | See also
| `skip` | Invisible rests
| `SkipMusic` | See also
| skipping notes in lyrics | Repeats with alternative endings
| `skipTypesetting` | 3.4.2 Skipping corrected music
| slashed digits | A.9.6 Other
| slashed note heads | Improvisation
| `Slash_repeat_engraver` | See also
| slides in tablature notation | Default tablatures
| `slur` | See also
| `Slur` | See also
| `Slur` | See also
| slur and repeat | Known issues and warnings
| slur style | Slurs
| slur, dashed | Slurs
| slur, dashed phrasing | Phrasing slurs
| slur, defining dash patterns | Slurs
| slur, defining dash patterns for phrasing | Phrasing slurs
| slur, dotted | Slurs
| slur, dotted phrasing | Phrasing slurs
| slur, half dashed and half solid | Slurs
| slur, half solid and half dashed phrasing | Phrasing slurs
| slur, multiple phrasing | Phrasing slurs
| slur, phrasing | Slurs
| slur, phrasing | Phrasing slurs
| slur, phrasing, defining dash patterns | Phrasing slurs
| slur, simultaneous phrasing | Phrasing slurs
| slur, solid | Slurs
| `slurDashed` | Slurs
| `slurDashPattern` | Slurs
| `slurDashPattern` | A.16 Available music functions
| `slurDotted` | Slurs
| `slurDown` | Slurs
| `slurHalfDashed` | Slurs
| `slurHalfSolid` | Slurs
| `slurNeutral` | Slurs
| slurs | Slurs
| slurs, above notes | Slurs
| slurs, below notes | Slurs
| slurs, manual placement | Slurs
| slurs, modifying | Modifying ties and slurs
| slurs, multiple | Slurs
| slurs, simultaneous | Slurs
| `slurSolid` | Slurs
| `slurUp` | Slurs
| `small` | Selecting notation font size
| `small` | Selecting font and font size
| `smaller` | Selecting font and font size
| `smaller` | Selecting font and font size
| smaller notes | Formatting cue notes
| smob | smob
| snap pizzicato | Snap (Bartók) pizzicato
| snappizzicato | A.11 List of articulations
| Solesmes | 2.9.1 Overview of the supported styles
| solid slur | Slurs
| solo part | Automatic part combining
| `Songs` | See also
| `Songs` | See also
| soprano clef | Clef
| sos. | Piano pedals
| sostenuto pedal | Piano pedals
| `SostenutoEvent` | See also
| `sostenutoOff` | Piano pedals
| `sostenutoOn` | Piano pedals
| `SostenutoPedal` | See also
| `SostenutoPedalLineSpanner` | See also
| Sound | 3.5 MIDI output
| Southern Harmony note heads | Shape note heads
| `southernHarmonyHeads` | Shape note heads
| `southernHarmonyHeadsMinor` | Shape note heads
| `sp` | Dynamics
| space between staves | 4.4.1 Flexible vertical spacing within systems
| space inside systems | 4.4.1 Flexible vertical spacing within systems
| spacer note | Invisible rests
| spacer rest | Invisible rests
| spaces in lyrics | Entering lyrics
| spaces, in lyrics | Multiple syllables to one note
| `spacing` | 4.5.1 Horizontal spacing overview
| Spacing lyrics | Placing syllables horizontally
| spacing of ledger lines | Staff symbol
| spacing, display of layout | 4.6.1 Displaying spacing
| spacing, horizontal | 4.5 Horizontal spacing
| spacing, vertical | 4.4 Vertical spacing
| `spacing-spanner-interface` | A.15 Layout properties
| `spacing-spanner-interface` | A.15 Layout properties
| `SpacingSpanner` | 4.5.1 Horizontal spacing overview
| `SpacingSpanner` | 4.5.1 Horizontal spacing overview
| `SpacingSpanner` | See also
| `SpacingSpanner` | See also
| `spacingTweaks` | A.16 Available music functions
| `SpanBar` | See also
| special arpeggio symbols | Arpeggio
| special characters in markup mode | Text markup introduction
| special note heads | Special note heads
| splitting notes | Automatic note splitting
| splitting rests | Automatic note splitting
| `spp` | Dynamics
| Sprechgesang | Spoken music
| Square neumes ligatures | Gregorian square neume ligatures
| staccatissimo | Articulations and ornamentations
| staccatissimo | A.11 List of articulations
| `staccato` | See also
| staccato | A.11 List of articulations
| stacking text in a column | A.9.2 Align
| `staff` | See also
| `Staff` | See also
| `Staff` | See also
| `staff` | See also
| `Staff` | See also
| `staff` | See also
| `Staff` | See also
| `Staff` | See also
| `Staff` | See also
| `Staff` | See also
| `Staff` | See also
| `Staff` | 4.5.1 Horizontal spacing overview
| `Staff` | A.14 All context properties
| staff change line | Staff-change lines
| staff changes, automatic | Changing staff automatically
| staff changes, manual | Changing staff manually
| staff distance | 4.4.1 Flexible vertical spacing within systems
| staff group | Grouping staves
| staff initiation | Instantiating new staves
| staff instantiation | Instantiating new staves
| staff line, thickness of | Staff symbol
| staff lines, amount of | Staff symbol
| staff lines, number of | Staff symbol
| staff size, setting | 4.2.2 Setting the staff size
| staff switching | Staff-change lines
| staff symbol, drawing | Staff symbol
| staff symbol, setting of | Staff symbol
| staff symbol, setting of | 5.4.5 Staff symbol properties
| staff, choir | Grouping staves
| staff, drum | Instantiating new staves
| staff, empty | Hiding staves
| staff, Frenched | Ossia staves
| staff, grand | Grouping staves
| staff, hiding | Hiding staves
| staff, multiple | Grouping staves
| staff, nested | Nested staff groups
| staff, new | Instantiating new staves
| staff, percussion | Instantiating new staves
| staff, piano | Grouping staves
| staff, resizing of | Ossia staves
| staff, single | Instantiating new staves
| staff, starting | Staff symbol
| staff, stopping | Staff symbol
| `staff-affinity` | Within-system spacing properties
| staff-change line | Staff-change lines
| `staff-staff-spacing` | Within-system spacing properties
| `staff-symbol-interface` | Staff symbol
| `staff-symbol-interface` | See also
| `Staff.midiInstrument` | Instrument names
| `StaffGroup` | Known issues and warnings
| `StaffGroup` | See also
| `StaffGroup` | See also
| `staffgroup-staff-spacing` | Within-system spacing properties
| `StaffGrouper` | See also
| `StaffGrouper` | Within-system spacing properties
| `StaffGrouper` | See also
| `StaffGrouper` | See also
| `StaffGrouper` | 5.3.6 Modifying alists
| `StaffSpacing` | See also
| `StaffSymbol` | See also
| `StaffSymbol` | See also
| `StaffSymbol` | See also
| `StaffSymbol` | 4.2.2 Setting the staff size
| `Staff_symbol_engraver` | Hiding staves
| standalone text | Separate text
| standard font size (notation) | Selecting notation font size
| stanza number | Adding stanza numbers
| `StanzaNumber` | See also
| start of system | Grouping staves
| start repeat | Manual repeat marks
| start staff lines | Staff symbol
| `start-repeat` | Manual repeat marks
| `startGroup` | Analysis brackets
| starting a staff | Staff symbol
| `startStaff` | Staff symbol
| `startStaff` | Ossia staves
| `startTrillSpan` | Trills
| `staves` | See also
| staves, keyboard instruments | References for keyboards
| staves, keyed instruments | References for keyboards
| staves, multiple | Grouping staves
| staves, nested | Nested staff groups
| staves, piano | References for keyboards
| stem | Stems
| `Stem` | Cross-staff stems
| `Stem` | See also
| stem, direction | Stems
| stem, down | Stems
| stem, invisible | Stems
| stem, neutral | Stems
| stem, up | Stems
| stem, with slash | Grace notes
| `stem-interface` | See also
| `stem-spacing-correction` | 4.5.1 Horizontal spacing overview
| `stemDown` | Stems
| `stemLeftBeamCount` | Manual beams
| `stemNeutral` | Stems
| `stemRightBeamCount` | Manual beams
| stems, cross-staff | Cross-staff stems
| `stemUp` | Stems
| `Stem_engraver` | See also
| `Stem_engraver` | See also
| stencil | stencil
| stencil, removing | Removing the stencil
| stop staff lines | Staff symbol
| `stopGroup` | Analysis brackets
| stopped | Articulations and ornamentations
| stopped | A.11 List of articulations
| stopping a staff | Staff symbol
| `stopStaff` | Staff symbol
| `stopStaff` | Ossia staves
| `stopStaff` | Hiding staves
| `stopTrillSpan` | Trills
| `storePredefinedDiagram` | Predefined fret diagrams
| `storePredefinedDiagram` | A.16 Available music functions
| string numbers | String number indications
| `String quartet` | References for unfretted strings
| `String quartet` | See also
| string vs. fingering numbers | String number indications
| string, indicating open | Bowing indications
| `StringNumber` | See also
| strings, orchestral | 2.3 Unfretted string instruments
| strings, writing for | 2.3 Unfretted string instruments
| `StringTunings` | Custom tablatures
| `stringTunings` | Predefined fret diagrams
| `StrokeFinger` | See also
| strumming rhythms, showing | Showing melody rhythms
| `Style sheets` | Using global settings
| `Style sheets` | See also
| style, rehearsal mark | Rehearsal marks
| style, slur | Slurs
| `styledNoteHeads` | A.16 Available music functions
| styles, note heads | Special note heads
| styles, voice | Voice styles
| `sub` | Selecting font and font size
| subbass clef | Clef
| subscript | Selecting font and font size
| subscript text | A.9.1 Font
| `suggestAccidentals` | Annotational accidentals (musica ficta)
| `super` | Selecting font and font size
| superscript | Selecting font and font size
| superscript text | A.9.1 Font
| `sus` | Extended and altered chords
| sustain pedal | Piano pedals
| sustain pedal style | Piano pedals
| `SustainEvent` | See also
| `sustainOff` | Piano pedals
| `sustainOn` | Piano pedals
| `SustainPedal` | See also
| `SustainPedalLineSpanner` | See also
| SVG output | 3.4.3 Alternative output formats
| switching fonts | Selecting font and font size
| switching instruments | Instrument names
| syllable durations, automatic | Automatic syllable durations
| symbols, non-musical | Graphic notation inside markup
| syntax, markup | Text markup introduction
| system | Grouping staves
| system separator mark | Separating systems
| system start delimiters | Grouping staves
| system start delimiters, nested | Nested staff groups
| `system-count` | `\paper` variables for line breaking
| `system-separator-markup` | Miscellaneous `\paper` variables
| `system-system-spacing` | List of flexible vertical spacing `\paper` variables
| `systems-per-page` | `\paper` variables for line breaking
| `SystemStartBar` | See also
| `SystemStartBar` | See also
| `SystemStartBrace` | See also
| `SystemStartBrace` | See also
| `SystemStartBracket` | See also
| `SystemStartBracket` | See also
| `SystemStartSquare` | See also
| `SystemStartSquare` | See also
T |  |
| tab clef | Custom tablatures
| `tabChordRepetition` | A.16 Available music functions
| tablature | Instantiating new staves
| tablature | 2.4 Fretted string instruments
| tablature and harmonic indications | Default tablatures
| tablature and slides | Default tablatures
| tablature, banjo | 2.4 Fretted string instruments
| tablature, banjo | Custom tablatures
| tablature, banjo | Banjo tablatures
| tablature, bass | Custom tablatures
| tablature, bass guitar | Custom tablatures
| tablature, cello | Custom tablatures
| tablature, custom string tunings | Custom tablatures
| tablature, double bass | Custom tablatures
| tablature, guitar | 2.4 Fretted string instruments
| tablature, guitar | Custom tablatures
| tablature, mandolin | Custom tablatures
| tablature, predefined string tunings | Custom tablatures
| tablature, ukulele | Custom tablatures
| tablature, viola | Custom tablatures
| tablature, violin | Custom tablatures
| tablatures, basic | Default tablatures
| tablatures, custom | Custom tablatures
| tablatures, default | Default tablatures
| `TabNoteHead` | See also
| tabstaff | Instantiating new staves
| `TabStaff` | Instantiating new staves
| `TabStaff` | Default tablatures
| `TabVoice` | Default tablatures
| `Tab_note_heads_engraver` | See also
| `tag` | A.16 Available music functions
| `taor` | Bagpipe definitions
| `taqasim` | See also
| `teaching` | Automatic accidentals
| teaching accidental style | Automatic accidentals
| `teeny` | Selecting notation font size
| `teeny` | Selecting font and font size
| Template Arabic music | Arabic music example
| `tempo` | Metronome marks
| `tempo indication` | See also
| tempo marks within tuplet brackets | Known issues and warnings
| tenor clef | Clef
| tenor clef, choral | Clef
| `tenuto` | See also
| tenuto | A.11 List of articulations
| `text` | Piano pedals
| text alignment commands | Text alignment
| text columns, left-aligned | A.9.2 Align
| text columns, right-aligned | A.9.2 Align
| text in columns | Text alignment
| text in volta bracket | Manual repeat marks
| text items, non-empty | Text scripts
| text marks | Text marks
| text markup | Text markup introduction
| text on bar line | Text marks
| text on multi-measure rest | Full measure rests
| text outside margin | See also
| text padding | Graphic notation inside markup
| Text scripts | Text scripts
| text size | Selecting font and font size
| text spanners | Text spanners
| text spanners, formatting | Text spanners
| text spread over multiple pages | Multi-page markup
| text, aligning | Text alignment
| text, centering on the page | Text alignment
| text, decorating | Graphic notation inside markup
| text, framing | Graphic notation inside markup
| text, horizontal alignment | Text alignment
| text, justified | Text alignment
| text, keeping inside margin | See also
| text, multi-line | Text alignment
| Text, other languages | 1.8.1 Writing text
| text, separate | Separate text
| text, standalone | Separate text
| text, top-level | Separate text
| text, vertical alignment | Text alignment
| text, wordwrapped | Text alignment
| `text-interface` | 5.2.2 Layout interfaces
| `text-interface` | A.9.6 Other
| `text-script-interface` | 5.2.2 Layout interfaces
| `textLengthOff` | Full measure rests
| `textLengthOff` | Text scripts
| `textLengthOn` | Full measure rests
| `textLengthOn` | Text scripts
| `TextScript` | See also
| `TextScript` | See also
| `TextScript` | See also
| `TextScript` | See also
| `TextScript` | See also
| `TextScript` | See also
| `TextScript` | See also
| `TextScript` | See also
| `TextScript` | See also
| `TextSpanner` | See also
| `TextSpanner` | See also
| `textSpannerDown` | Text spanners
| `textSpannerNeutral` | Text spanners
| `textSpannerUp` | Text spanners
| `The Feta font` | A.9.4 Music
| thickness of staff lines | Staff symbol
| Thorough bass | Introduction to figured bass
| `thumb` | Fingering instructions
| thumb marking | Articulations and ornamentations
| thumb-script | Fingering instructions
| `Tie` | See also
| `tie` | See also
| `tie` | See also
| `TieColumn` | See also
| tied note, accidental | Accidentals
| `tieDashed` | Ties
| `tieDashPattern` | A.16 Available music functions
| `tieDotted` | Ties
| `tieDown` | Ties
| `tieNeutral` | Ties
| ties and chords | Ties
| ties and volta brackets | Ties
| ties in alternative endings | Normal repeats
| ties in repeats | Normal repeats
| ties, appearance | Ties
| ties, dashed | Ties
| ties, dotted | Ties
| ties, in lyrics | Multiple syllables to one note
| ties, laissez vibrer | Ties
| ties, modifying | Modifying ties and slurs
| ties, placement | Ties
| ties, repeating | Ties
| `tieSolid` | Ties
| `tieUp` | Ties
| `time` | Time signature
| `time` | Setting automatic beam behavior
| time administration | Time administration
| `time signature` | See also
| time signature default settings | Time signature
| time signature properties, restoring default values | Time signature
| time signature style | Time signature
| time signature, compound | Selected Snippets
| time signature, visibility of | Time signature
| time signatures | Mensural time signatures
| time signatures, double | Polymetric notation
| Time signatures, multiple | 5.1.4 Modifying context plug-ins
| time signatures, polymetric | Polymetric notation
| `times` | Tuplets
| `times` | Polymetric notation
| `TimeScaledMusic` | See also
| `TimeSignature` | See also
| `TimeSignature` | See also
| `timeSignatureFraction` | Polymetric notation
| timing (within the score) | Time administration
| timing information and repeats | Known issues and warnings
| `Timing_translator` | See also
| `Timing_translator` | See also
| `Timing_translator` | See also
| `Timing_translator` | See also
| `Timing_translator` | See also
| `Timing_translator` | A.14 All context properties
| `tiny` | Selecting notation font size
| `tiny` | Selecting font and font size
| `tocItem` | A.16 Available music functions
| `Top` | LilyPond — Notation Reference
| `Top` | LilyPond — Notation Reference
| `Top` | 5. Changing defaults
| top-level text | Separate text
| `top-margin` | 4.1.3 Fixed vertical spacing `\paper` variables
| `top-markup-spacing` | List of flexible vertical spacing `\paper` variables
| `top-system-spacing` | List of flexible vertical spacing `\paper` variables
| toplevel-bookparts | parser variable
| toplevel-scores | parser variable
| transcription of mensural music | Selected Snippets
| transformation, retrograde | Retrograde
| transformations, modal | Modal transformations
| `translate` | Text alignment
| `translate-scaled` | Text alignment
| translating text | A.9.2 Align
| translating text | A.9.2 Align
| `Translation` | 5.2.1 Navigating the program reference
| transparent notes | Hidden notes
| transparent, making objects | Making objects transparent
| `transpose` | See also
| `transpose` | Transpose
| `transpose` | See also
| `transposedCueDuring` | Formatting cue notes
| `transposedCueDuring` | A.16 Available music functions
| `TransposedMusic` | See also
| transposing | Transpose
| transposing clef | Clef
| transposing fret diagrams | Predefined fret diagrams
| `transposing instrument` | See also
| `transposing instrument` | See also
| transposing instruments | Transpose
| `transposition` | Instrument transpositions
| `transposition` | Quoting other voices
| `transposition` | A.16 Available music functions
| transposition and relative octave entry | See also
| transposition of notes | Transpose
| transposition of pitches | Transpose
| transposition, instrument | Instrument transpositions
| transposition, MIDI | Instrument transpositions
| transposition, modal | Modal transposition
| tre corde | Piano pedals
| treble clef | Clef
| `treCorde` | Piano pedals
| `tremolo` | Tremolo repeats
| tremolo beams | Tremolo repeats
| tremolo marks | Tremolo repeats
| tremolo, cross-staff | See also
| `tremoloFlags` | Tremolo repeats
| triads | Common chords
| `triangle` | Graphic notation inside markup
| `trill` | Trills
| trill | A.11 List of articulations
| trill with accidental | Trills
| trills | Trills
| trills in MIDI | Supported in MIDI
| trills, pitched | Trills
| `TrillSpanner` | See also
| `TrillSpanner` | See also
| `triplet` | See also
| triplet formatting | Selected Snippets
| triplets | Tuplets
| `Tunable context properties` | Multiple notes to one syllable
| `Tunable context properties` | See also
| `Tunable context properties` | 5.3.2 The `\set` command
| `Tunable context properties` | See also
| tuning, non-Western | Extending notation and tuning systems
| tunings, banjo | Banjo tablatures
| `tuplet` | See also
| tuplet bracket placement | Tuplets
| tuplet formatting | Selected Snippets
| Tuplet number changes | Selected Snippets
| `TupletBracket` | See also
| `tupletDown` | Tuplets
| `tupletNeutral` | Tuplets
| `TupletNumber` | Selected Snippets
| `tupletNumberFormatFunction` | Selected Snippets
| tuplets | Tuplets
| `tupletSpannerDuration` | Selected Snippets
| `tupletUp` | Tuplets
| Turkish music | References for Turkish classical music
| Turkish note names | Turkish note names
| turn | Articulations and ornamentations
| turn | A.11 List of articulations
| turns in MIDI | Supported in MIDI
| `tweak` | A.16 Available music functions
| tweaking | 5.3.4 The `\tweak` command
| tweaking control points | Known issues and warnings
| tweaking grace notes | Grace notes
| `Tweaking methods` | See also
| `Tweaking methods` | 5.3.4 The `\tweak` command
| `Tweaking methods` | See also
| `Tweaking output` | 5. Changing defaults
| `Tweaking output` | See also
| tweaks in a variable | Known issues and warnings
| tweaks in lyrics | Known issues and warnings
| `two-sided` | `\paper` variables for two-sided mode
| `type` | 5.1.6 Defining new contexts
| typeface | glyph
| typeset text | Text markup introduction
U |  |
| U.C. | Piano pedals
| ukulele | Fret diagram markups
| una corda | Piano pedals
| `unaCorda` | Piano pedals
| `UnaCordaEvent` | See also
| `UnaCordaPedal` | See also
| `UnaCordaPedalLineSpanner` | See also
| `unbreakable-spanner-interface` | See also
| `underline` | Selecting font and font size
| underlining text | A.9.1 Font
| `unfold` | Written-out repeats
| unfold music | Written-out repeats
| unfold music with alternate endings | Written-out repeats
| unfold repeat | Written-out repeats
| unfold repeat with alternate endings | Written-out repeats
| `UnfoldedRepeatedMusic` | See also
| `UnfoldedRepeatedMusic` | See also
| `unfoldRepeats` | A.16 Available music functions
| `unHideNotes` | Hidden notes
| Unicode | 3.3.3 Text encoding
| unmetered music | Unmetered music
| unmetered music | Time administration
| unmetered music, line breaks | See also
| unmetered music, page breaks | See also
| unmetered music, with beams | Unmetered music
| up bow indication | Bowing indications
| upbeat | Upbeats
| upbeat in a repeat | Normal repeats
| upbow | Articulations and ornamentations
| upbow | A.11 List of articulations
| upmordent | A.11 List of articulations
| upprall | A.11 List of articulations
| UTF-8 | 3.3.3 Text encoding
V |  |
| varbaritone clef | Clef
| varcoda | Articulations and ornamentations
| varcoda | A.11 List of articulations
| variables | 3.1.5 File structure
| variables, use of | Using variables
| Vaticana, Editio | 2.9 Ancient notation
| Vaticana, Editio | 2.9.1 Overview of the supported styles
| `VaticanaStaff` | Instantiating new staves
| VaticanaStaffContext | Gregorian chant contexts
| VaticanaVoiceContext | Gregorian chant contexts
| vertical lines between staves | Grid lines
| vertical positioning of dynamics | Dynamics
| vertical spacing | 4.4 Vertical spacing
| vertical spacing | 4.5.4 Line length
| vertical text alignment | Text alignment
| `VerticalAxisGroup` | Within-system spacing properties
| `VerticalAxisGroup` | See also
| `VerticalAxisGroup` | Within-system spacing properties
| `VerticalAxisGroup` | See also
| `VerticalAxisGroup` | See also
| `VerticalAxisGroup` | See also
| `VerticalAxisGroup` | See also
| vertically centering text | A.9.2 Align
| verylongfermata | A.11 List of articulations
| violin clef | Clef
| `Visibility and color of objects` | See also
| `Visibility and color of objects` | See also
| `Visibility and color of objects` | See also
| `Visibility and color of objects` | See also
| `Visibility and color of objects` | 5.1.4 Modifying context plug-ins
| `Visibility and color of objects` | 5.4.7 Visibility of objects
| `Visibility and color of objects` | Using break-visibility
| `Visibility and color of objects` | See also
| visibility of objects | 5.4.7 Visibility of objects
| visibility of octavated clefs | Special considerations
| `Vocal ensembles` | Placing lyrics vertically
| `Vocal ensembles` | See also
| `Vocal ensembles` | References for choral
| `Vocal ensembles` | See also
| `Vocal ensembles` | See also
| `Vocal ensembles` | Pointing a psalm
| `Vocal ensembles` | See also
| `Vocal ensembles` | 5.1.7 Aligning contexts
| `voice` | Automatic accidentals
| `Voice` | Single-staff polyphony
| `Voice` | See also
| `voice` | Automatic accidentals
| `Voice` | See also
| `Voice` | Known issues and warnings
| `Voice` | See also
| `Voice` | See also
| `Voice` | See also
| `Voice` | 4.5.1 Horizontal spacing overview
| `Voice` | 5.2.3 Determining the grob property
| voice accidental style | Automatic accidentals
| voice styles | Voice styles
| voice, following | Staff-change lines
| `VoiceFollower` | See also
| `VoiceFollower` | See also
| `voiceOne` | Single-staff polyphony
| `Voices contain music` | Known issues and warnings
| `Voices contain music` | See also
| `Voices contain music` | See also
| voices, divided | Divided voices
| voices, multiple | Collision resolution
| voices, multiple | Collision resolution
| voices, quoting | Quoting other voices
| voices, \partcombine with \autoBeamOff | Selected Snippets
| `volta` | See also
| volta bracket | Manual repeat marks
| volta bracket with text | Manual repeat marks
| volta brackets and ties | Ties
| volta, prima | 1.4.1 Long repeats
| volta, seconda | 1.4.1 Long repeats
| `VoltaBracket` | See also
| `VoltaBracket` | See also
| `VoltaRepeatedMusic` | See also
| `VoltaRepeatedMusic` | See also
| `Volta_engraver` | See also
W |  |
| Walker shape note heads | Shape note heads
| `walkerHeads` | Shape note heads
| `walkerHeadsMinor` | Shape note heads
| `whichBar` | Selected Snippets
| White mensural ligatures | White mensural ligatures
| whitespace | 3.1.5 File structure
| whole rest for a full measure | Full measure rests
| wind instruments | References for wind instruments
| `with-color` | Coloring objects
| `Within-staff objects` | 5.4.2 Direction and placement
| `withMusicProperty` | A.16 Available music functions
| `wordwrap` | Text alignment
| `wordwrap-lines` | Multi-page markup
| wordwrapped text | Text alignment
| `Working on input files` | See also
| writing music in parallel | Writing music in parallel
| written-out repeats | Written-out repeats
X |  |
| `X-offset` | Within-system spacing properties
| x11 color | Coloring objects
| x11 color | See also
| `x11-color` | Coloring objects
| `x11-color` | See also
| `xNote` | A.16 Available music functions
| `xNotesOn` | A.16 Available music functions

Jump to: | ! ' , - . / 1 8 : < = > ? [ \ ] ^ _ | ~ A B C D E F G H I J K L M N O P Q R S T U V W X

# Footnotes

[1] Scheme tutorial, contains a short tutorial on entering numbers, lists, strings, and symbols in Scheme.

# Table of Contents

# About This Document

This document was generated by Graham Percival on June 12, 2011 using texi2html 1.82.

The buttons in the navigation panels have the following meaning:

Button | Name | Go to | From 1.2.3 go to
--- | --- | --- | ---
[] |  |  |
[ << ] | FastBack | Beginning of this chapter or previous chapter | 1
[] |  |  |
[Top] | Top | Cover (top) of document |
[Contents] | Contents | Table of contents |
[Index] | Index | Index |
[ ? ] | About | About (help) |
[] |  |  |
[ >> ] | FastForward | Next chapter | 2
[] |  |  |
[] |  |  |
[ < ] | Back | Previous section in reading order | 1.2.2
[] |  |  |
[ Up ] | Up | Up section | 1.2
[] |  |  |
[ > ] | Forward | Next section in reading order | 1.2.4

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

- 1. Section One
  - 1.1 Subsection One-One
    - ...
  - 1.2 Subsection One-Two
    - 1.2.1 Subsubsection One-Two-One
    - 1.2.2 Subsubsection One-Two-Two
    - 1.2.3 Subsubsection One-Two-Three <== Current Position
    - 1.2.4 Subsubsection One-Two-Four
  - 1.3 Subsection One-Three
    - ...
  - 1.4 Subsection One-Four

Other languages: deutsch, español, français, 日本語.

#### LilyPond — Notation Reference