LilyPond — Notation Reference

This manual provides a reference for all notation that can be produced with LilyPond version 2.24.3. 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 https://lilypond.org/.


1. Musical notation

This chapter explains how to create musical notation.


1.1 Pitches

[image of music]

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
}

[image of music]

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 e' g' c''
  c'4 g b c'
  \clef bass
  c,4 e, g, c
  c,4 g,, b,, c,
}

[image of music]

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

{
  \fixed c' {
    \clef treble
    c4 e g c'
    c4 g, b, c
  }
  \clef bass
  \fixed c, {
    c4 e g c'
    c4 g, b, c
  }
}

[image of music]

Pitches in the music expression following \fixed are unaffected by any enclosing \relative, discussed next.

See also

Music Glossary: Pitch names.

Snippets: Pitches.


Relative octave entry

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

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

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

Here is the relative mode shown in action:

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

[image of music]

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

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

[image of music]

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

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

[image of music]

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

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

[image of music]

\relative has no effect on \chordmode blocks.

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

[image of music]

\relative is not allowed inside of \chordmode blocks.

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

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

[image of music]

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

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

[image of music]

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''2 fis
  c2 ges
  b2 eisis
  b2 feses
}

[image of music]

In complex situations, it is sometimes useful to get back to a certain pitch regardless of what happened before. This can be done using \resetRelativeOctave:

\relative {
  <<
    { c''2 d }
    \\
    { e,,2 f }
  >>
  \resetRelativeOctave c''
  c2
}

[image of music]

See also

Music Glossary: fifth, interval, Pitch names.

Notation Reference: Octave checks.

Snippets: Pitches.

Internals Reference: RelativeOctaveMusic.


Accidentals

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

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

\relative c'' { ais1 aes aisis aeses }

[image of music]

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

\relative c'' { a4 aes a2 }

[image of music]

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

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

[image of music]

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

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

[image of music]

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

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

[image of music]

Selected Snippets

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

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

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

[image of music]

Preventing extra naturals from being automatically added

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

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

[image of music]

See also

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

Learning Manual: Pitches 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 symbols do 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' re mi sib
}

[image of music]

The available languages and the note names they define are:

LanguageNote Names
nederlandsc d e f g a bes b
català or
 catalan
do re mi fa sol la sib si
deutschc d e f g a b h
englishc d e f g a bf/b-flat b
español or
 espanol
do re mi fa sol la sib si
françaisdo /re mi fa sol la sib si
italianodo re mi fa sol la sib si
norskc d e f g a b h
português or
 portugues
do re mi fa sol la sib si
suomic d e f g a b h
svenskac d e f g a b h
vlaamsdo re mi fa sol la sib si

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

Languagesharpflatdouble sharpdouble flat
nederlandsisesisiseses
català or
 catalan
d/sbdd/ssbb
deutschisesisiseses
englishs/-sharpf/-flatss/x/-sharpsharpff/-flatflat
español or
 espanol
sbss/xbb
françaisdbdd/xbb
italianodbddbb
norskiss/isess/esississ/isisessess/eses
português or
 portugues
sbssbb
suomiisesisiseses
svenskaissessississessess
vlaamskbkkbb

In Dutch, German, Norwegian, and Finnish, aes is contracted to as; in Dutch and Norwegian, however, both forms are accepted by LilyPond. Exactly the same holds for es and ees, aeses and ases, and finally eeses and eses.

In German and Finnish, LilyPond additionally provides the more frequent form asas for ases.

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

[image of music]

Some music uses microtones whose alterations are fractions of a ‘normal’ sharp or flat. The following table lists note name suffixes for quarter tone accidentals; here the prefixes semi- and sesqui- respectively mean ‘half’ and ‘one and a half’.

Languagesemi-sharpsemi-flatsesqui-sharpsesqui-flat
nederlandsihehisiheseh
català or
 catalan
qd/qsqbtqd/tqstqb
deutschihehisiheseh
englishqsqftqstqf
español or
 espanol
cscbtcstcb
françaissdsbdsdbsb
italianosdsbdsdbsb
norskihehissih/isihesseh/eseh
português or
 portugues
sqtbqtstqtbtqt
suomiihehisiheseh
svenskaihehissihesseh
vlaamshkhbkhkbhb

In German, there are similar name contractions for microtones as with normal pitches described above.

\language "deutsch"

\relative c'' { asah2 eh aih eisih }

[image of music]

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''2 d='
  e2 f
}

[image of music]

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

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

[image of music]

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

\relative {
  c''4 f g f

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

[image of music]

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 {
    \key d \major
    d'4 fis a d
  }
}

[image of music]

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

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

[image of music]

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' d e f }
\new Staff {
  \transpose c cis { \music }
  \transpose c des { \music }
}

[image of 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 (eqv? n 6) (eqv? n 2)))
       (set! a (- a 2))
       (set! n (+ n 1)))
      ((and (< a -1) (or (eqv? n 0) (eqv? 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 naturalize 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 (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 { }
}

[image of music]

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.

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


Inversion

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

\inversion around-pitch to-pitch musicexpr

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

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

[image of music]

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

See also

Notation Reference: Modal transformations, Retrograde, Transpose.


Retrograde

A music expression can be reversed to produce its retrograde:

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

\new Staff {
  \music
  \retrograde \music
}

[image of music]

Known issues and warnings

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

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' d e f g a b }
motif = \relative { c'8 d e f g a b c }

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

[image of music]

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

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

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

[image of music]

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' cis d dis e f fis g gis a ais b }
motif = \relative { c'8 d e f g a b c }

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

[image of music]

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 { ees' f fis gis a b c d }
motif = \relative { c'8. ees16 fis8. a16 b8. gis16 f8. d16 }

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

[image of music]

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' g' }
motive = \relative { c' c g' c, }

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

[image of music]

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

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

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

[image of music]

See also

Notation Reference: Inversion, Retrograde, Transpose.


1.1.3 Displaying pitches

This section discusses how to alter the output of pitches.


Clef

Without any explicit command, the default clef for LilyPond is the treble (or G) clef.

c'2 c'

[image of music]

However, the clef can be changed by using the \clef command and an appropriate clef name. Middle C is shown in each of the following examples.

\clef treble
c'2 c'
\clef alto
c'2 c'
\clef tenor
c'2 c'
\clef bass
c'2 c'

[image of music]

For the full range of possible clef names see Clef styles.

Specialized clefs, such as those used in Ancient music, are described in Mensural clefs and Gregorian clefs. Music that requires tablature clefs is discussed in Default tablatures and Custom tablatures.

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

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

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

[image of music]

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

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

[image of music]

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

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

\clef treble { c'2 c' } \break
\clef bass { c'2 c' } \break
\clef alto
  \set Staff.explicitClefVisibility = #end-of-line-invisible
  { c'2 c' } \break
  \unset Staff.explicitClefVisibility
\clef bass { c'2 c' } \break

[image of music]

By default, a clef that has previously been printed will not be reprinted if the same \clef command is issued again and will be ignored. The command \set Staff.forceClef = ##t changes this behavior.

  \clef treble
  c'1
  \clef treble
  c'1
  \set Staff.forceClef = ##t
  c'1
  \clef treble
  c'1

[image of music]

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

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

  \clef "treble"
  c'1
  \clef "bass"
  c'1
  \clef "treble"
  c'1
  \override Staff.Clef.full-size-change = ##t
  \clef "bass"
  c'1
  \clef "treble"
  c'1
  \revert Staff.Clef.full-size-change
  \clef "bass"
  c'1
  \clef "treble"
  c'1

[image of music]

Selected Snippets

Tweaking clef properties

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

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

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

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

  % The following clef changes do not preserve
  % the normal relationship between notes, key signatures
  % 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.clefTransposition = #7
  c'1
  \set Staff.clefTransposition = #0
  \set Staff.clefPosition = #0
  c'1

  % Return to the normal clef:

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

[image of music]

See also

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

Installed Files: ‘scm/parser-clef.scm’.

Snippets: Pitches.

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

Known issues and warnings

Ottavation numbers attached to clefs are treated as separate grobs. So any \override done to the Clef will also need to be applied, as a separate \override, to the ClefModifier grob.

\new Staff \with {
  \override Clef.color = #(universal-color 'blue)
  \override ClefModifier.color = #(universal-color 'vermillion)
}

\clef "treble_8" c'4

[image of music]


Key signature

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

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

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

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

[image of music]

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

freygish = #`((0 . ,NATURAL) (1 . ,FLAT) (2 . ,NATURAL)
    (3 . ,NATURAL) (4 . ,NATURAL) (5 . ,FLAT) (6 . ,FLAT))

\relative {
  \key c \freygish c'4 des e f
  \bar "||" \key d \freygish d es fis g
}

[image of music]

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

\override Staff.KeySignature.flat-positions = #'((-5 . 5))
\override Staff.KeyCancellation.flat-positions = #'((-5 . 5))
\clef bass \key es \major es g bes d'
\clef treble \bar "||" \key es \major es' g' bes' d''

\override Staff.KeySignature.sharp-positions = #'(2)
\bar "||" \key b \major b' fis' b'2

[image of music]

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
}

[image of music]

Non-traditional key signatures

The commonly used \key command sets the keyAlterations 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.keyAlterations =
  #`(((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.

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

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

\include "arabic.ly"
\relative do' {
  \set Staff.keyAlterations = #`((0 . ,SEMI-FLAT)
                                 (1 . ,SEMI-FLAT)
                                 (2 . ,FLAT)
                                 (5 . ,FLAT)
                                 (6 . ,SEMI-FLAT))
%\set Staff.extraNatural = ##f
  re reb \dwn reb resd
  dod dob dosd \dwn dob |
  dobsb dodsd do do |
}

[image of music]

See also

Music Glossary: church mode, scordatura.

Learning Manual: Pitches and key signatures.

Snippets: Pitches.

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


Ottava brackets

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

\relative c'' {
  a2 b
  \ottava #-2
  a2 b
  \ottava #-1
  a2 b
  \ottava #0
  a2 b
  \ottava #1
  a2 b
  \ottava #2
  a2 b
}

[image of music]

By default, only a number is printed at the start of the bracket. That setting may be changed to include an abbreviated ordinal, either in superscript or in normal letters (the latter was formerly used by default); the default bold font weight of these characters may also be altered, as explained in Selecting font and font size.

The following example demonstrates various options, as well as how to go back to the current default behavior:

\relative c'' {
  \ottava #1
  a'2 b
  \ottava #2
  a'2 b
  \bar "||"
  \set Staff.ottavationMarkups = #ottavation-ordinals
  \ottava #1
  a,2 b
  \ottava #2
  a'2 b
  \bar "||"
  \override Staff.OttavaBracket.font-series = #'medium
  \set Staff.ottavationMarkups = #ottavation-simple-ordinals
  \ottava #1
  a,2 b
  \ottava #2
  a'2 b
  \bar "||"
  \revert Staff.OttavaBracket.font-series
  \set Staff.ottavationMarkups = #ottavation-numbers
  \ottava #1
  a,2 b
  \ottava #2
  a'2 b
}

[image of music]

Selected Snippets

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

Short text is especially useful when a brief ottava is used.

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

[image of music]

Adding an ottava marking to a single voice

If you have more than one voice on the staff, setting octavation in one voice transposes the position of notes in all voices for the duration of the ottava bracket. If the octavation is only intended to apply to one voice, the Ottava_spanner_engraver should be moved to Voice context.

\layout {
  \context {
    \Staff
    \remove Ottava_spanner_engraver
  }
  \context {
    \Voice
    \consists Ottava_spanner_engraver
  }
}

{
  \clef bass
  << { <g d'>1~ q2 <c' e'> }
  \\
    {
      r2.
      \ottava -1
      <b,,, b,,>4 ~ |
      q2
      \ottava 0
      <c e>2
    }
  >>
}

[image of music]

Modifying the Ottava spanner slope

It is possible to change the slope of the Ottava spanner.

\relative c'' {
  \override Staff.OttavaBracket.stencil = #ly:line-spanner::print
  \override Staff.OttavaBracket.bound-details =
    #`((left . ((Y . 0)
                (attach-dir . ,LEFT)
                (padding . 0)
                (stencil-align-dir-y . ,CENTER)))
       (right . ((Y . 5.0) ; Change the number here
                 (padding . 0)
                 (attach-dir . ,RIGHT)
                 (text . ,(make-draw-dashed-line-markup
                           (cons 0 -1.2))))))
  \override Staff.OttavaBracket.left-bound-info =
     #ly:horizontal-line-spanner::calc-left-bound-info-and-text
  \override Staff.OttavaBracket.right-bound-info =
     #ly:horizontal-line-spanner::calc-right-bound-info
  \ottava #1
  c1
  c'''1
}

[image of music]

See also

Music Glossary: octavation.

Notation Reference: Selecting font and font size.

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" \with {
    instrumentName = "Vln"
    midiInstrument = "violin"
  }
  \relative c'' {
    % not strictly necessary, but a good reminder
    \transposition c'
    \key c \major
    g4( c8) r c r c4
  }
  \new Staff = "clarinet" \with {
    instrumentName = \markup { Cl (B\flat) }
    midiInstrument = "clarinet"
  }
  \relative c'' {
    \transposition bes
    \key d \major
    a4( d8) r d r d4
  }
>>

[image of music]

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

flute = \relative c'' {
  \key f \major
  \cueDuring "clarinet" #DOWN {
    R1 _\markup\tiny "clarinet"
    c4 f e d
    R1 _\markup\tiny "clarinet"
  }
}
clarinet = \relative c'' {
  \key aes \major
  \transposition a
  aes4 bes c des
  R1^\markup { muta in B\flat }
  \key g \major
  \transposition bes
  d2 g,
}
\addQuote "clarinet" \clarinet
<<
  \new Staff \with { instrumentName = "Flute" }
    \flute
  \new Staff \with { instrumentName = "Cl (A)" }
    \clarinet
>>

[image of music]

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 <<
  \accidentalStyle voice
  { … }
>>

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

\accidentalStyle StaffGroup.voice

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

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

musicB = {
  \clef bass
  \new Voice {
    \voiceTwo \relative {
      <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 {
  <<
    \new Staff = "up" {
      \accidentalStyle default
      \musicA
    }
    \new Staff = "down" {
      \accidentalStyle default
      \musicB
    }
  >>
}

[image of music]

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 {
  <<
    \new Staff = "up" {
      %%% change the next line as desired:
      \accidentalStyle Score.default
      \musicA
    }
    \new 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:

[image of music]

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.

[image of music]

modern

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

[image of music]

modern-cautionary

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

[image of music]

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:

[image of music]

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.

[image of music]

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 unless qualified with a second argument.

[image of music]

piano-cautionary

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

[image of music]

choral

This rule is a combination of the modern-voice and the piano style. It shows all accidentals required for singers that only follow their own voice, as well as additional accidentals for readers that follow all voices of an entire ChoirStaff simultaneously.

This accidental style applies to the current ChoirStaff unless qualified with a second argument.

[image of music]

choral-cautionary

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

[image of music]

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.

[image of music]

neo-modern-cautionary

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

[image of music]

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.

[image of music]

neo-modern-voice-cautionary

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

[image of music]

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.

[image of music]

dodecaphonic-no-repeat

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

[image of music]

dodecaphonic-first

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

[image of music]

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.

[image of music]

no-reset

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

[image of music]

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.

[image of 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!>’.

In alternative endings, cautionary cancellation should be based on the previous played measure, but it is based on the previous printed measure. In the following example, the natural c in the second alternative does not need a natural sign:

[image of music]

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

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

[image of music]


Alternate accidental glyphs

Non-Western and ancient notation systems have their own accidentals. The glyphs are controlled through the alterationGlyphs property of the Staff context and similar context types. The predefined values for this property are listed in Accidental glyph sets.

\layout {
  \context {
    \Staff
    alterationGlyphs = #alteration-vaticana-glyph-name-alist
  }
}

{ ces' c' cis' }

[image of music]

The property may also be set to a custom associative list mapping alterations to glyph names. Alterations are given as fractions in tones. Glyphs are listed at Accidental glyphs.

\layout {
  \context {
    \Staff
    alterationGlyphs =
      #'((-1/2 . "accidentals.flat.arrowdown")
         (0 . "accidentals.natural.arrowup")
         (1/2 . "accidentals.sharp.arrowup"))
  }
}

{ ces' c' cis' }

[image of music]

The padding-pairs property of KeySignature and KeyCancellation objects is an associative list mapping pairs of glyphs to the padding that should be added between these glyphs in key signatures.

\layout {
  \context {
    \Staff
    alterationGlyphs =
      #'((-1/2 . "accidentals.flat.arrowdown")
         (0 . "accidentals.natural.arrowup")
         (1/2 . "accidentals.sharp.arrowup"))
    \override KeySignature.padding-pairs =
      #'((("accidentals.sharp.arrowup" . "accidentals.sharp.arrowup")
            . 0.25)
         (("accidentals.flat.arrowdown" . "accidentals.flat.arrowdown")
            . 0.3))
    \override KeyCancellation.padding-pairs =
      #'((("accidentals.natural.arrowup" . "accidentals.natural.arrowup")
            . 0.7))
  }
}

{
  \key cis \major
  ces' c'
  \key ces \major
  cis'
}

[image of music]

See also

Notation Reference: Accidental glyph sets, Accidental glyphs.

Internals Reference: accidental-switch-interface, Alteration_glyph_engraver, key-signature-interface.


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 {
  aes' c e2
  cis,1
}

[image of music]

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

[image of music]

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

[image of music]

Changing the ambitus gap

It is possible to change the default gap between the ambitus noteheads and the line joining them.

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

[image of music]

Ambitus after key signature

By default, ambitus are positioned at the left of the clef. The \ambitusAfter function allows for changing this placement. Syntax is \ambitusAfter grob-interface (see Graphical Object Interfaces for a list of possible values for grob-interface.)

A common use case is printing the ambitus between key signature and time signature.

\new Staff \with {
  \consists Ambitus_engraver
} \relative {
  \ambitusAfter key-signature
  \key d \major
  es'8 g bes cis d2
}

[image of music]

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:

\relative c'' {
  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
}

[image of music]

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:

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

[image of music]

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

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

[image of music]

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 similar shorthand for diamond shapes:

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

[image of music]

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
}

[image of music]

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
   (make-engraver
    (acknowledgers
     ((note-head-interface 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
}

[image of music]

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 (Harmonia Sacra), Walker, and Aiken (Christian Harmony) styles:

\relative c'' {
  \aikenHeads
  c, d e f g2 a b1 c \break
  \aikenThinHeads
  c,4 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
}

[image of music]

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:

\relative c'' {
  \key a \minor
  \aikenHeads
  a b c d e2 f g1 a \break
  \aikenHeadsMinor
  a,4 b c d e2 f g1 a \break
  \aikenThinHeadsMinor
  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
}

[image of music]

Predefined commands

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

Selected Snippets

Aiken head thin variant noteheads

Aiken head white notes get harder to read at smaller staff sizes, especially with ledger lines. Losing interior white space makes them appear as quarter notes.

\score {
  {
    \aikenHeads
    c''2 a' c' a

    % Switch to thin-variant noteheads
    \set shapeNoteStyles = ##(doThin reThin miThin
                              faThin sol laThin tiThin)
    c'' a' c' a
  }
}

[image of music]

Direction of merged ’fa’ shape note heads

Using property NoteCollision.fa-merge-direction, the direction of ‘fa’ shape note heads (‘fa’, ‘faThin’, etc.) can be controlled independently of the stem direction if two voices with the same pitch and different stem directions are merged. If this property is not set, the ‘down’ glyph variant is used.

{
  \clef bass

  << { \aikenHeads
       f2
       \override Staff.NoteCollision.fa-merge-direction = #UP
       f2 }
  \\ { \aikenHeads
       f2
       f2 }
  >>
}

[image of music]

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

[image of music]

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
} \relative {
  e''8 e g a a16( bes) a8 g
  \improvisationOn
  e8 ~
  2 ~ 8 f4 f8 ~
  2
  \improvisationOff
  a16( bes) a8 g e
}

[image of music]

Predefined commands

\improvisationOn, \improvisationOff.

See also

Snippets: Pitches.

Internals Reference: Pitch_squash_engraver, Voice, RhythmicStaff.


1.2 Rhythms

[image of music]

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


1.2.1 Writing rhythms


Durations

The durations of notes are entered using numbers and dots. The number entered is based on the reciprocal value of the length of the note. For example, a quarter note is designated using the numerical value of 4 as it is a 1/4 note, a half note using 2, an eighth using 8 and so on. Durations as short as 1024 notes can be entered but shorter values, while possible, can only be entered as beamed notes. Also see Beams.

For notes longer than a whole use the \longa – double breve – and \breve commands. A note with the duration of a quadruple breve is possible using the \maxima command but is only supported within ancient music notation. See Ancient notation.

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

[image of music]

Here are the same durations with automatic beaming turned off.

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

[image of music]

Isolated durations – durations without a pitch – that occur within a music sequence will take their pitch from the preceding note or chord.

\relative {
  \time 8/1
  c'' \longa \breve 1 2
  4 8 16 32 64 128 128
}

[image of music]

Isolated pitches – pitches without a duration – that occur within a music sequence will take their duration from the preceding note or chord. If there is no preceding duration, then default for the note is always 4, a quarter note.

\relative { a' a a2 a a4 a a1 a }

[image of music]

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

\relative { a'4 b c4. b8 a4. b4.. c8. }

[image of music]

To avoid clashing with staff lines, dots on notes are normally moved up. In polyphonic situations however, they can be placed, manually, above or below the staff as required. See Direction and placement.

Some note durations cannot be represented using just numbers and dots but only by tying two or more notes together. See Ties.

To specify durations that align the syllables of lyrics and notes together see Vocal music.

Notes can also be spaced proportionately to their duration, see Proportional notation.

Predefined commands

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

Selected Snippets

Alternative breve notes

Breve notes are also available with two vertical lines on each side of the notehead instead of one line and in baroque style.

\relative c'' {
  \time 4/2
  c\breve |
  \override Staff.NoteHead.style = #'altdefault
  b\breve
  \override Staff.NoteHead.style = #'baroque
  b\breve
  \revert Staff.NoteHead.style
  a\breve
}

[image of music]

Changing the number of augmentation dots per note

The number of augmentation dots on a single note can be changed independently of the dots placed after the 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 |
}

[image of music]

See also

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

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

Snippets: Rhythms.

Internals Reference: Dots, DotColumn.

Known issues and warnings

While there is no fundamental limit to rest durations (longest or shortest), there is a limit to the number of glyphs possible so only rests between 1024 and \maxima may be printed.


Tuplets

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

\tuplet fraction { music }

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

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

[image of music]

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

\relative {
  g'2 r8 \tuplet 3/2 8 { cis16 d e e f g g f e }
}

[image of music]

Tuplet brackets may be manually placed above or below the staff:

\relative {
  \tupletUp \tuplet 3/2 { c''8 d e }
  \tupletNeutral \tuplet 3/2 { c8 d e }
  \tupletDown \tuplet 3/2 { f,8 g a }
  \tupletNeutral \tuplet 3/2 { f8 g a }
}

[image of music]

Tuplets may be nested:

\relative {
  \autoBeamOff
  c''4 \tuplet 5/4 { f8 e f \tuplet 3/2 { e[ f g] } } f4
}

[image of music]

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

Tuplet brackets may be replaced with slurs, as is preferred in many older editions:

\relative {
  \tuplet 3/2 4 {
    \override TupletBracket.tuplet-slur = ##t
    c'4 e8 d4 f8
    \override TupletBracket.bracket-visibility = ##t
    e f g f e d
  } c1
}

[image of music]

By default, a bracket is only printed if all of the notes it spans are not beamed together; in some cases (for example with slurs, as in the example above) it may be preferrable to change that behavior, through the bracket-visibility property as detailed in one of the following snippets.

More generally, either or both the TupletBracket and TupletNumber objects may be hidden or shown as explained in Visibility of objects; however, a more flexible way of modifying the duration of notes without printing a tuplet bracket is also introduced in Scaling durations.

Predefined commands

\tupletUp, \tupletDown, \tupletNeutral.

Selected Snippets

Entering several tuplets using only one tuplet command

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

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

\relative c' {
  \time 2/4
  \tupletSpan 4
  \tuplet 3/2 { c8^"\\tupletSpan 4" c c c c c }
  \tupletSpan \default
  \tuplet 3/2 { c8^"\\tupletSpan \\default" c c c c c }
  \tuplet 3/2 4 { c8^"\\tuplet 3/2 4 {...}" c c c c c }
}

[image of music]

Changing the tuplet number

By default, only the numerator of the tuplet number is printed over the tuplet bracket, i.e., the numerator of the argument to the \tuplet command.

Alternatively, num:den of the tuplet number may be printed, or the tuplet number may be suppressed altogether.

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

[image of music]

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)
  \tuplet 3/2  { c4. c4. c4. c4. }
  \once \override TupletNumber.text =
    #(tuplet-number::non-default-tuplet-fraction-text 12 7)
  \tuplet 3/2  { c4. c4. c4. c4. }
  \once \override TupletNumber.text =
    #(tuplet-number::append-note-wrapper
      (tuplet-number::non-default-tuplet-fraction-text 12 7)
      (ly:make-duration 3 0))
  \tuplet 3/2  { c4. c4. c4. c4. }
  \once \override TupletNumber.text =
    #(tuplet-number::append-note-wrapper
      tuplet-number::calc-denominator-text
      (ly:make-duration 2 0))
  \tuplet 3/2  { c8 c8 c8 c8 c8 c8 }
  \once \override TupletNumber.text =
    #(tuplet-number::append-note-wrapper
      tuplet-number::calc-fraction-text
      (ly:make-duration 2 0))
  \tuplet 3/2  { c8 c8 c8 c8 c8 c8 }
  \once \override TupletNumber.text =
    #(tuplet-number::fraction-with-notes
      (ly:make-duration 2 1) (ly:make-duration 3 0))
  \tuplet 3/2  { c4. c4. c4. c4. }
  \once \override TupletNumber.text =
    #(tuplet-number::non-default-fraction-with-notes 12
      (ly:make-duration 3 0) 4 (ly:make-duration 2 0))
  \tuplet 3/2  { c4. c4. c4. c4. }
}

[image of music]

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), 'if-no-beam (only print a bracket if there is no beam), or #f (never print a bracket). The latter is in fact equivalent to omitting the TupletBracket object altogether from the printed output.

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

\new Voice {
  \relative c' {
    \override Score.TextMark.non-musical = ##f
    \textMark "default" \music
    \override TupletBracket.bracket-visibility = #'if-no-beam
    \textMark \markup \typewriter "'if-no-beam" \music
    \override TupletBracket.bracket-visibility = ##t
    \textMark \markup \typewriter "#t" \music
    \override TupletBracket.bracket-visibility = ##f
    \textMark \markup \typewriter "#f" \music
    \omit TupletBracket
    \textMark \markup \typewriter "omit" \music
  }
}

[image of music]

Printing tuplet brackets on the note head side

Whichever option you choose for controlling the tuplet bracket visibility, it will show or hide the tuplet bracket irrespectively of tuplet bracket placement (stem side or note head side). However, when placing the tuplet bracket on the note head side some authors recommend always printing the tuplet bracket. The option visible-over-note-heads can be used to achieve this.

music = \relative c'' {
  \tupletNeutral \tuplet 3/2 { c16[ d e } f8]
  \tupletUp \tuplet 3/2 { c8 d e }
}

\new Voice {
  \relative c' {
    \time 2/4
    \override TupletBracket.visible-over-note-heads = ##t
    \override Score.TextMark.non-musical = ##f
    { \textMark \markup "default" \music }
    \override TupletBracket.bracket-visibility = #'if-no-beam
    { \textMark \markup \typewriter "'if-no-beam" \music }
  }
}

[image of music]

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 { \tuplet 3/2 { c[ b a] } }
  % Insert a manual line break within a tuplet
  \tuplet 3/2 { c[ b \bar "" \break a] }
  \repeat unfold 5 { \tuplet 3/2 { c[ b a] } }
  c8
}

[image of music]

See also

Music Glossary: triplet, tuplet, polymetric.

Learning Manual: Tweaking methods.

Notation Reference: Direction and placement, Visibility of objects, Time administration, Scaling durations, The \tweak command, Polymetric notation.

Snippets: Rhythms.

Internals Reference: TupletBracket, TupletNumber, TimeScaledMusic.


Scaling durations

The duration of single notes, rests or chords may be multiplied by a fraction N/M by appending *N/M (or *N if M is 1) to the duration. Factors may also be added by using Scheme expressions evaluating to a number or musical length like *#(ly:music-length music). This is convenient for scaling a duration of ‘1’ to let a note or multi-measure rest stretch to a length derived from a music variable.

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

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

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

[image of music]

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

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

\relative {
  \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 {
    <c' a>4 c8 b
  }
}

[image of music]

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

See also

Notation Reference: Tuplets, Invisible rests, Polymetric notation.

Snippets: Rhythms.

Known issues and warnings

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


Ties

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

Ties that connect notes to nothing are called laissez vibrer articulation; see Laissez vibrer for the \laissezVibrer command. Ties that connect nothing to notes (as needed in seconda volta sections, for example), can be entered with the \repeatTie command; see Repeat tie.

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

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

{ a'2~ 4~ 16 r r8 }

[image of music]

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

{ a'2~ 4~ 16 r r8 }

[image of music]

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

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

[image of music]

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

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

\relative c' {
  <c e g>2~ 2 |
  <c e g>4~ <c e g c>
    <c~ e g~ b> <c e g b> |
}

[image of music]

When a tie continues into alternative endings, you have to specify the repeated tie as follows:

\relative {
  \repeat volta 2 { c'' g <c e>2~ }
  \alternative {
    % the following note is tied normally
    \volta 1 { <c e>2. r4 }
    % the following note has a repeated tie
    \volta 2 { <c e>2\repeatTie d4 c }
  }
}

[image of music]

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

[image of music]

Ties may be made to curve up or down manually; see Direction and placement.

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

\relative c' {
  \tieDotted
  c2~ 2
  \tieDashed
  c2~ 2
  \tieHalfDashed
  c2~ 2
  \tieHalfSolid
  c2~ 2
  \tieSolid
  c2~ 2
}

[image of music]

Custom dash patterns can be specified:

\relative c' {
  \tieDashPattern #0.3 #0.75
  c2~ 2
  \tieDashPattern #0.7 #1.5
  c2~ 2
  \tieSolid
  c2~ 2
}

[image of music]

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

Override whiteout and layer layout properties of objects that should cause a gap in ties.

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

[image of music]

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
}

[image of music]

Engraving ties manually

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

Note that LilyPond makes a distinction between exact and inexact values for the first number. If using an exact value (i.e., either an integer or a fraction like (/ 4 5)), the value serves as a rough vertical position that gets further tuned by LilyPond to make the tie avoid staff lines. If using an inexact value like a floating point number, it is taken as the vertical position without further adjustments.

\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>
  \override TieColumn.tie-configuration =
    #'((0 . 1) (-2 . 1) (-4 . 1))
  <c e g>2~ <c e g>
}

[image of music]

See also

Music Glossary: tie, laissez vibrer.

Notation Reference: Slurs, Automatic note splitting.

Snippets: Expressive marks, Rhythms.

Internals Reference: LaissezVibrerTie, LaissezVibrerTieColumn, TieColumn, Tie.

Known issues and warnings

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

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


1.2.2 Writing rests

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


Rests

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

\new Staff {
  % These two lines are just to prettify this example
  \time 16/1
  \omit Staff.TimeSignature
  % 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
}

[image of music]

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.

\relative { a'4\rest d4\rest }

[image of music]

Selected Snippets

Rest styles

Rests may be used in various styles.

\new Staff \relative c {
  \omit Score.TimeSignature
  \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 ""
  \break

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

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

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

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

[image of music]

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 1024th to maxima (8× whole).


Invisible rests

There are two forms of invisible rests: the spacer rest named ‘s’, and the \skip command. The spacer rest is a note that does not produce output. Like any other note or rest, its duration sets the default duration of following notes.

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

[image of music]

Also like other notes and rests, it implicitly causes Staff and Voice contexts to be created if none exist.

{ s1 s s }

[image of music]

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. The \skip command accepts either an explicit duration or a piece of music as an argument and skips the duration of the argument. The duration of the \skip is ignored if lyrics derive their durations from the notes in an associated melody through \addlyrics or \lyricsto.

<<
  {
    a'2 \skip2 a'2 a'2
  }
  \new Lyrics {
    \lyricmode {
      foo2 \skip 1 bla2
    }
  }
>>

[image of music]

When the argument to \skip is music, the default duration of the following note is implicitly set by the last note of the argument. However, to preserve backward compatibility with the legacy implementation of \skip, a numeric duration argument does not affect the duration of the subsequent note.

<<
  {
    \repeat unfold 12 { a'4 }
  }
  {
    a'4 \skip 2 a' |
    a'4 \skip { a'8 a' a' a' } a' a' |
    s2 a'
  }
>>

[image of music]

The \skip command preserves the effect of an enclosing unfoldRepeats command, unlike the skip-of-length Scheme function.

MyCadenza = \fixed c' {
  \repeat volta 2 {
    d8 e f g g4 f4
  }
}

music = <<
  \new Staff {
    \MyCadenza
    c'1
  }
  \new Staff {
    #(skip-of-length MyCadenza)
    c'1
  }
  \new Staff {
    \skip \MyCadenza
    c'1
  }
>>

\unfoldRepeats \music

[image of music]

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

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

[image of music]

See also

Learning Manual: Visibility and color of objects.

Notation Reference: Hidden notes, Visibility of objects.

Snippets: Rhythms.

Internals Reference: SkipMusic.

Known issues and warnings

Because duration and music arguments to the \skip command affect the duration of subsequent music differently, it is good practice to provide an explicit duration for the music immediately following the command.


Full measure rests

Rests for one or more full measures are entered like notes with the note name uppercase ‘R’. Their duration is entered identically to the duration notation used for notes, including the ability to use duration multipliers, as explained in Scaling durations:

% Rest measures contracted to single measure
\compressMMRests {
  R1*4
  R1*24
  R1*4
  b'2^"Tutti" b'4 a'4
}

[image of music]

The example above also demonstrates how to compress multiple empty measures, as explained in Compressing empty measures.

The duration of a multi-measure rest must always be equal to the length of one or several measures. Therefore, some time signatures require the use of augmentation dots or fractions:

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

[image of music]

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 |

[image of music]

Markups can be added to multi-measure rests.

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

[image of music]

Note: Markups and articulations attached to multi-measure rests are MultiMeasureRestText and MultiMeasureRestScript types, not TextScript and Script. 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
\override Script.color = #blue
R1^"wrong"
R1\fermata
% This is the correct object name to be specified
\override MultiMeasureRestText.padding = #5
\override MultiMeasureRestScript.color = #blue
R1^"right"
R1\fermata

[image of music]

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

Predefined commands

\textLengthOn, \textLengthOff, \compressMMRests.

Selected Snippets

Multi-measure rest length control

Multi-measure rests have length according to their total duration which is under the control of MultiMeasureRest.space-increment. Note that the default value is 2.0.

\relative c' {
  \compressEmptyMeasures
  R1*2 R1*4 R1*64 R1*16
  \override Staff.MultiMeasureRest.space-increment = 2.5
  R1*2 R1*4 R1*64 R1*16
}

[image of music]

Positioning multi-measure rests

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

The positioning of multi-measure rests can be controlled as follows:

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

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

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

  % Using compressed bars in multiple voices requires another override
  % in all voices to avoid multiple instances being printed
  \compressMMRests
  <<
   \revert MultiMeasureRest.direction
    { R1*3 }
    \\
   \revert MultiMeasureRest.direction
    { R1*3 }
  >>
}

[image of music]

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 an empty chord with an attached markup before the multi-measure rest. Text attached to a spacer rest in this way is left-aligned to the position where the note would be placed in the measure, but if the measure length is determined by the length of the text, the text will appear to be centered.

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

[image of music]

See also

Music Glossary: multi-measure rest.

Notation Reference: Durations, Scaling durations, Compressing empty measures, Text, Formatting text, Text scripts.

Snippets: Rhythms.

Internals Reference: MultiMeasureRest, MultiMeasureRestNumber, MultiMeasureRestScript, 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.


Caesuras

The \caesura command calls for unmetered silence: typically, a short break in sound that does not shorten the previous note.

\fixed c'' { c2. \caesura d4 }

[image of music]

In chants and hymns, \caesura can serve more generally as a phrase division; for more information, see the references at the end of this section. For a break in sound that shortens the previous note, see Breath marks.

Articulations may follow \caesura to indicate the relative duration or significance of the break; these create CaesuraScript grobs.

\fixed c'' { c2. \caesura \fermata d4 }

[image of music]

By default, \caesura creates a BreathingSign grob. The breath element of the caesuraType context property controls which of several predefined signs \caesura creates. See List of breath marks.

\fixed c'' {
  \set Score.caesuraType = #'((breath . curvedcaesura))
  c2. \caesura d4
}

[image of music]

To designate one or more CaesuraScript grobs to be created as a normal part of an unarticulated caesura, set the scripts element of the caesuraType context property. (Additional scripts can still be attached as articulations.) In conjunction with the breath element, the scripts listed in the script element attach to the BreathingSign; otherwise, if a BarLine is present, they attach to it.

The caesuraTypeTransform context property can be set to a Scheme function to enable a degree of automatic adaptation. The at-bar-line-substitute-caesura-type function generator supports styles where the notation differs at a bar line.

\fixed c' {
  \set Score.caesuraType =
    #'((breath . spacer)
       (scripts . (outsidecomma)))
  \set Score.caesuraTypeTransform =
    #(at-bar-line-substitute-caesura-type
      '((scripts . (fermata))))
  c'2. \caesura d'4
  b1 \caesura
  a1
}

[image of music]

Predefined commands

\caesura.

Selected Snippets

Positioning opposing fermatas on a bar line

This snippet demonstrates a command that prints fermatas both above and below a bar line. If there would not otherwise be a bar line, it adds a double bar line. Semantically, the command codes a longer-than-normal caesura, which might be considered misuse depending on the situation.

twoWayFermata = {
  \once \set Staff.caesuraType = #'((underlying-bar-line . "||"))
  \once \set Staff.caesuraTypeTransform = ##f
  \caesura ^\fermata _\fermata
}

music = {
  f'1 \twoWayFermata
  R1
  f'2 \twoWayFermata f'2
  R1
  b'1 \twoWayFermata \fine
}

\new GrandStaff <<
  \new Staff \music
  \new Staff \music
>>

[image of music]

See also

Music Glossary: caesura.

Notation Reference: Breath marks, Divisiones, Kievan bar lines, Phrase bar lines in hymn tunes.

Snippets: Expressive marks.

Internals Reference: BreathingSign, Caesura_engraver, CaesuraEvent, CaesuraScript, caesuraTypeTransform, caesuraType.


1.2.3 Displaying rhythms


Time signature

The time signature is set as follows:

\time 2/4 c''2
\time 3/4 c''2.

[image of music]

Mid-measure time signature changes are covered in Upbeats.

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

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

[image of music]

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

\relative c'' {
  % 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
}

[image of music]

Mensural time signatures are covered in Mensural time signatures.

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

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

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

[image of music]

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

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

[image of music]

\overrideTimeSignatureSettings takes four arguments:

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

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

\score {
  \relative {
    \repeat unfold 8 { c'8 } |
    \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 } |
  }
}

[image of music]

Different values of default time signature properties can be established for different staves by enabling polymetric notation (see Polymetric notation).

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

[image of music]

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

Predefined commands

\numericTimeSignature, \defaultTimeSignature.

Selected Snippets

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

Sometimes, a time signature should not print the whole fraction (for example, 7/4), but only the numerator (digit 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
}

[image of music]

See also

Music Glossary: time signature

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

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

Snippets: Rhythms.

Internals Reference: TimeSignature, Timing_translator.

Known issues and warnings

\numericTimeSignature and \defaultTimeSignature have no effect when used in a MensuralStaff. To use these modern time signatures in a MensuralStaff, either select them already when creating the context:

\new MensuralStaff \with { \numericTimeSignature } {
  c'1
}

[image of music]

or use an explicit \override:

\new MensuralStaff {
  \time 2/2
  c'1
  \override MensuralStaff.TimeSignature.style = #'numbered
  \time 2/2
  c'
  \override MensuralStaff.TimeSignature.style = #'default
  \time 2/2
  c'
}

[image of music]


Metronome marks

A basic metronome mark is simple to write:

\relative {
  \tempo 4 = 120
  c'2 d
  e4. d8 c2
}

[image of music]

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

\relative {
  \tempo 4 = 40 - 46
  c'4. e8 a4 g
  b,2 d4 r
}

[image of music]

Tempo indications with text can be used instead:

\relative {
  \tempo "Allegretto"
    c''4 e d c
    b4. a16 b c4 r4
}

[image of music]

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

\relative {
  \tempo "Allegro" 4 = 160
  g'4 c d e
  d4 b g2
}

[image of music]

In general, the text can be any markup object:

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

[image of music]

A particularly useful markup command is \rhythm, which prints a rhythmic pattern. See Music.

\relative {
  \tempo \markup {
    Swing
    \hspace #0.4
    \rhythm { 8[ 8] } = \rhythm { \tuplet 3/2 { 4 8 } }
  }
  b8 g' c, d ees d16 ees d c r8
}

[image of music]

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

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

[image of music]

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

\compressMMRests {
  \markLengthOn
  \tempo "Molto vivace"
  R1*12
  \tempo "Meno mosso"
  R1*16
  \markLengthOff
  \tempo "Tranquillo"
  R1*20
}

[image of music]

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 {
  indent = 0
  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
}

[image of music]

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

[image of music]

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
}

[image of music]

For more details, see Formatting text.

See also

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

Notation Reference: Formatting text, Creating MIDI output, Full measure rests.

Snippets: Staff notation.

Internals Reference: MetronomeMark.


Upbeats

Partial or pickup measures, such as an anacrusis or an upbeat, are entered using the \partial command:

\partial duration

When \partial is used at the beginning of a score, duration is the length of the music preceding the first bar.

\relative {
  \time 3/4
  \partial 4.
  r4 e'8 | a4 c8 b c4 |
}

[image of music]

When \partial is used after the beginning of a score, duration is the remaining length of the current measure. It does not create a new numbered bar.

\relative {
  \set Score.barNumberVisibility = #all-bar-numbers-visible
  \override Score.BarNumber.break-visibility =
	    #end-of-line-invisible
  \time 9/8
  d''4.~ 4 d8 d( c) b | c4.~ 4. \bar "||"
  \time 12/8
  \partial 4.
  c8( d) e | f2.~ 4 f8 a,( c) f |
}

[image of music]

The \partial command is required when the time signature changes in mid measure, but it may also be used alone.

\relative {
  \set Score.barNumberVisibility = #all-bar-numbers-visible
  \override Score.BarNumber.break-visibility =
	    #end-of-line-invisible
  \time 6/8
  \partial 8
  e'8 | a4 c8 b[ c b] |
  \partial 4
  r8 e,8 | a4 \bar "||"
  \partial 4
  r8 e8 | a4
  c8 b[ c b] |
}

[image of music]

The \partial command sets the Timing.measurePosition property, which is a rational number that indicates how much of the measure has passed.

See also

Music Glossary: anacrusis.

Notation Reference: Grace notes.

Snippets: Rhythms.

Internal Reference: Timing_translator.


Unmetered music

In music such as cadenzas, it may be desirable to disable automatic measure demarcation and all that it entails: numbering bars, resetting accidentals, etc. Music between \cadenzaOn and \cadenzaOff does not count toward the length of a measure.

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

[image of music]

To divide an unmetered passage into irregular measures, temporarily re-enable timing and use \partial to create a tiny measure. The \bar command alone does not start a new measure.

cadenzaMeasure = {
  \cadenzaOff
  \partial 1024 s1024
  \cadenzaOn
}

\relative c'' {
  % Show all bar numbers
  \override Score.BarNumber.break-visibility = #all-visible
  c4 d e d
  \cadenzaOn
  c4 cis \bar "!" d8[ d d] \cadenzaMeasure f4 g4.
  \cadenzaMeasure
  \cadenzaOff
  d4 e d c
}

[image of music]

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

\relative {
  \repeat unfold 8 { c''8 }
  \cadenzaOn
  cis8 c c c c
  \bar"|"
  c8 c c
  \cadenzaOff
  \repeat unfold 8 { c8 }
}

[image of music]

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

Within a cadenza section, automatic breaks are disabled: since there is no metric, it is not possible to determine automatically where they would be appropriate. Therefore, in a long cadenza passage, you must insert possible break points at appropriate places using the \allowBreak command or other solutions in Line breaking.

\relative {
  c'4 f g c, d f g c
  \cadenzaOn
  c4 cis8
  \allowBreak
  d[ cis c cis]
  \allowBreak
  d[ f g a]
  \allowBreak
  ais[ g f g]
  \allowBreak
  d4 f8
  \allowBreak
  d[ cis] c4
  \allowBreak
  a8[ c] g4
}

[image of music]

Predefined commands

\cadenzaOn, \cadenzaOff.

See also

Music Glossary: cadenza.

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

Snippets: Rhythms.


Polymetric notation

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

Different time signatures with equal-length measures

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

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

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

[image of music]

Different time signatures with unequal-length measures

Each staff can be given its own independent time signature as soon as \enablePolymeter is placed in the \layout block.

\layout {
  \enablePolymeter
}

% Now each staff has its own time signature.

\relative <<
  \new Staff {
    \time 3/4
    c'4 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 |
  }
>>

[image of music]

To have just one polymetric score, include \enablePolymeter in a \layout block inside the \score block.

\score {
  <<
    \new Staff { c''1 1 }
    \new Staff { c'2 d' g'2~ 2 }
  >>
}

\score {
  \layout {
    \enablePolymeter
  }
  <<
    \new Staff { \time 4/4 c''1 1 }
    \new Staff { \time 2/4 c'2 d' g'2~ 2 }
  >>
}

[image of music]

When using polymeter, all staves should include a \time command if their meter is not the default 4/4. This is true even for special staves without actual staff lines, such as Dynamics contexts, since the placement of certain spanners like hairpins is synchronized with bar lines.

[image of music]

In order to use this feature with MIDI output, also include \enablePolymeter in a \midi block.

\layout {
  \enablePolymeter
}

\midi {
  \enablePolymeter
}

Compound time signatures

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

\compoundMeter #'(list of lists)

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

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

[image of music]

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

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

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

[image of music]

See also

Music Glossary: polymetric, polymetric time signature, meter.

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

Snippets: Rhythms.

Internals Reference: TimeSignature, Timing_translator, Staff.

Known issues and warnings

Although notes that occur at the same moment in each of the different staves will be placed at the same horizontal location, bar lines (in each staff) may cause inconsistent spacing within each of 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
}
\relative {
  c'2. c8 d4 e f g a b c8 c2 b4 a g16 f4 e d c8. c2 r1*2
}

[image of music]

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

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

\new Voice \with {
  \remove Note_heads_engraver
  \consists Completion_heads_engraver
} \relative {
  \time 9/8 g\breve. d''4. \bar "||"
  \set completionUnit = #(ly:make-moment 3 8)
  g\breve. d4.
}

[image of music]

These engravers split notes with scaled duration, such as those in tuplets, into notes with the same scale factor as in the input note.

\new Voice \with {
  \remove Note_heads_engraver
  \consists Completion_heads_engraver
} \relative {
  \time 2/4 r4
  \tuplet 3/2 {g'4 a b}
  \scaleDurations 2/3 {g a b}
  g4*2/3 a b
  \tuplet 3/2 {g4 a b}
  r4
}

[image of music]

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

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


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" \relative {
      \time 4/4
      c'4 e8 f g2
      r4 g g f
      g1
    }
  }
  \new Lyrics {
    \lyricsto "myRhythm" {
      This is my song
      I like to sing
    }
  }
>>

[image of music]

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

[image of music]

Music containing chords can also be used as input to RhythmicStaff and for use with the Pitch_squash_engraver if the chords are first reduced to single notes with the \reduceChords music function:

\new RhythmicStaff {
  \time 4/4
  \reduceChords {
    <c>2
    <e>2
    <c e g>2
    <c e g>4
    <c e g>4
  }
}

[image of music]

Predefined commands

\improvisationOn, \improvisationOff, \reduceChords.

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

[image of music]

See also

Snippets: Rhythms.

Internals Reference: RhythmicStaff, Pitch_squash_engraver.


1.2.4 Beams


Automatic beams

By default, beams are inserted automatically:

\relative c'' {
  \time 2/4 c8 c c c
  \time 6/8 c8 c c c8. c16 c8
}

[image of music]

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:

\relative c' {
  c4 c8 c8. c16 c8. c16 c8
  \autoBeamOff
  c4 c8 c8. c16 c8.
  \autoBeamOn
  c16 c8
}

[image of music]

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

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

Predefined commands

\autoBeamOff, \autoBeamOn.

Selected Snippets

Beams across line breaks

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

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

[image of music]

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
}

[image of music]

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

[image of music]

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.

Known issues and warnings

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


Setting automatic beam behavior

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

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

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

Beaming based on baseMoment and beatStructure

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

\set Timing.beamExceptions = #'()

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

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

\relative c'' {
  \time 5/16
  c16^"default" c c c c |
  % beamExceptions are unlikely to be defined for 5/16 time,
  % but let's disable them anyway to be sure
  \set Timing.beamExceptions = #'()
  \set Timing.beatStructure = 2,3
  c16^"(2+3)" c c c c |
  \set Timing.beatStructure = 3,2
  c16^"(3+2)" c c c c |
}

[image of music]

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

[image of music]

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
  % No need to disable beamExceptions
  % as they are not defined for 7/8 time
  \set Staff.beatStructure = 2,3,2
  <<
    \new Voice = one {
      \relative {
        a'8 a a a a a a
      }
    }
    \new Voice = two {
      \relative {
        \voiceTwo
        \set Voice.beatStructure = 1,3,3
        f'8 f f f f f f
      }
    }
  >>
}

[image of music]

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
<< \relative {a'8 a a a16 a a a a8 a} \\ \relative {f'4. f8 f f f} >>

% Works correctly with context Staff specified
\set Staff.beatStructure = 3,1,1,2
<< \relative {a'8 a a a16 a a a a8 a} \\ \relative {f'4. f8 f f f} >>

[image of music]

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
% No need to disable beamExceptions
% as they are not defined for 5/8 time
\set Timing.baseMoment = #(ly:make-moment 1/16)
\set Timing.beatStructure = 7,3
\repeat unfold 10 { a'16 }

[image of music]

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

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

Beaming based on beamExceptions

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

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

\relative c'' {
  \time 3/16
  \set Timing.beatStructure = 2,1
  \set Timing.beamExceptions =
    \beamExceptions { 32[ 32] 32[ 32] 32[ 32] }
  c16 c c |
  \repeat unfold 6 { c32 } |
}

[image of music]

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.

\relative a' {
  \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 }
}

[image of music]

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 {c''8} |
% This will beam (3 3 2) because we clear beamExceptions
\set Timing.beamExceptions = #'()
\repeat unfold 8 {c''8}

[image of music]

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

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

[image of music]

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

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

[image of music]

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:

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

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

Selected Snippets

Subdividing beams

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

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

  % Shorten beam by 1/32
  \set baseMoment = #(ly:make-moment 1/8)
  \set beatStructure = 2,2,2,2
  c32[ c c c c c c] r32

  % Shorten beam by 3/32
  \set baseMoment = #(ly:make-moment 1/8)
  \set beatStructure = 2,2,2,2
  c32[ c c c c] r16.
  r2
}

[image of music]

Strict beat beaming

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

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

[image of music]

Conducting signs, measure grouping signs

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

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

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

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

[image of music]

Beam endings in Score context

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

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

[image of music]

See also

Notation Reference: Time signature.

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

Snippets: Rhythms.

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

Known issues and warnings

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

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

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

[image of music]

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 { a'8 }
  }
  \new Staff {
    \time 3/4
    \repeat unfold 6 { a'8 }
  }
>>

[image of music]


Manual beams

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

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

[image of music]

Beaming direction can be set manually using direction indicators:

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

[image of music]

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

\relative {
  \time 2/4
  c''8 c\noBeam c c
}

[image of music]

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

\relative {
  c''4 d8[
  \grace { e32 d c d }
  e8] e[ e
  \grace { f16 }
  e8 e]
}

[image of music]

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.

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

[image of music]

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
      16[]
    }
    % Example 3
    \new RhythmicStaff {
      16 16
      \set stemRightBeamCount = #2
      16 r r
      \set stemLeftBeamCount = #2
      16 16 16
    }
    % Example 4
    \new RhythmicStaff {
      16 16
      \set stemRightBeamCount = #2
      16 r16
      16[]
      r16
      \set stemLeftBeamCount = #2
      16 16
    }
  >>
}

[image of music]

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.

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

[image of music]

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 are used to delimit measures and sections, and to indicate repetition. Normally, simple bar lines are automatically inserted into the printed output at places according to the current time signature. Various commands insert other kinds of bar lines automatically as part of their effect (see Automatic bar lines).

A bar line inserted automatically can be changed to another type with the \bar command:

\relative { e'4 d c2 \bar "!" }

[image of music]

The final note of a measure is not required to end on the automatically inserted 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 inhibit line breaks, leading to a line of highly compressed music or music that flows off the page.

Line breaks are also permitted at manually inserted bar lines even within incomplete measures. To allow a line break without printing a bar line, use \allowBreak; 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.

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

Various single and double bar lines are available for manual insertion:

\relative {
  f'1 \bar "|"
  f1 \bar "."
  g1 \bar "||"     % see \section
  a1 \bar ".|"
  b1 \bar ".."
  c1 \bar "|.|"
  d1 \bar "|."     % see \fine
  e1
}

[image of music]

together with dotted and dashed bar lines:

\relative {
  f'1 \bar ";"
  g1 \bar "!"
  a1
}

[image of music]

and various repeat bar lines:

\relative {
  f'1 \bar ".|:"
  g1 \bar ":..:"
  a1 \bar ":|.|:"
  b1 \bar ":|.:"
  c1 \bar ":.|.:"
  d1 \bar "[|:"
  e1 \bar ":|][|:"
  f1 \bar ":|]"
  g1 \bar ":|."
  a1
}

[image of music]

Ticks and short bar lines are also available; however, in the context of Gregorian chant, using \divisioMinima and \divisioMaior is preferable (see Divisiones).

f'1 \bar "'"
g1 \bar ","
a1

[image of music]

LilyPond supports Kievan notation and provides a special Kievan bar line:

f'1 \bar "k"

[image of music]

Further details of this notation are explained in Typesetting Kievan square notation.

There are various in-staff segno signs which differ in their behavior at line breaks:

\fixed c' {
  c4 4 4 4
  \bar "S"
  d4 4 4 4 \break
  \bar "S"
  e4 4 4 4
  \bar "S-|"
  f4 4 4 4 \break
  \bar "S-|"
  g4 4 4 4
  \bar "S-||"
  a4 4 4 4 \break
  \bar "S-||"
  b4 4 4 4
  \bar "S-S"
  c'4 4 4 4 \break
  \bar "S-S"
  d'1
}

[image of music]

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, which can be customized (see Automatic 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.

\fixed c' {
  c4 4 4 4
  \bar ".|:"
  d4 4 4 4 \break
  \bar ".|:"
  e4 4 4 4
  \bar ".|:-|"
  f4 4 4 4 \break
  \bar ".|:-|"
  g4 4 4 4
  \bar ".|:-||"
  a4 4 4 4 \break
  \bar ".|:-||"
  b4 4 4 4
  \bar ".|:-|."
  c'4 4 4 4 \break
  \bar ".|:-|."
  d'4 4 4 4
}

[image of music]

There are various combinations of repeats with the segno sign:

\fixed c' {
  g,4 4 4 4
  \bar ":|.S"
  a,4 4 4 4 \break
  \bar ":|.S"
  b,4 4 4 4
  \bar ":|.S-S"
  c4 4 4 4 \break
  \bar ":|.S-S"
  d4 4 4 4
  \bar "S.|:-S"
  e4 4 4 4 \break
  \bar "S.|:-S"
  f4 4 4 4
  \bar "S.|:"
  g4 4 4 4 \break
  \bar "S.|:"
  a4 4 4 4
  \bar "S.|:-|"
  b4 4 4 4 \break
  \bar "S.|:-|"
  c'4 4 4 4
  \bar "S.|:-||"
  d'4 4 4 4 \break
  \bar "S.|:-||"
  e'4 4 4 4
  \bar ":|.S.|:"
  f'4 4 4 4 \break
  \bar ":|.S.|:"
  g'4 4 4 4
  \bar ":|.S.|:-S"
  a'4 4 4 4 \break
  \bar ":|.S.|:-S"
  b'1
}

[image of music]

Many of the repeat and segno bar lines above can be inserted automatically by \repeat commands (see Repeats).

New bar line types can be defined with \defineBarLine:

\defineBarLine bartype #'(end begin span)

In addition to bartype (the character string that will then be used to refer to that new bar line), it takes three values: the first two determine the bar line’s appearance when it occurs at a line break, in which case the first and second given glyphs are printed respectively at the end of the system and at the beginning of the next one. The third given glyph is only relevant in multi-staff systems (see Grouping staves), where it is used as span bar, printed between staves.

The \defineBarLine arguments specifying replacement glyphs can be set to #t to copy the mid-line glyph or #f to create no bar line. The empty string, "", yields a zero-width bar line.

After the definiton, the new bar line can be used by \bar bartype.

There are several bar line elements, and there are predefined bar types that use most of them individually. Some elements are primarily intended to be combined with others; those do not have predefined individual bar types.

\defineBarLine ":" #'(#f #t #f)
\defineBarLine "=" #'(#t #f #t)
\defineBarLine "[" #'(#f #t #f)
\defineBarLine "]" #'(#t #f #f)

\new Staff {
  s1 \bar "'"
  s1 \bar ","
  s1 \bar "|"
  s1 \bar "."
  s1 \bar "!"
  s1 \bar ";"
  s1 \bar ":"
  s1 \bar "k"
  s1 \bar "S"
  s1 \bar "="
  s1 \bar "["
  s1 \bar "]"
  s1 \bar ""
}

[image of music]

The "=" bar line provides a double span bar line for use in combination with the segno sign. Using it as a stand-alone double thin bar line is not recommended; \bar "||" is preferred.

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

\defineBarLine "||-dashedSpan" #'(#t #f "!!")

\new StaffGroup <<
  \new Staff \relative c'' {
    c1 \bar "||"
    c1 \bar "||-dashedSpan"
    c1
  }
  \new Staff \relative c'' {
    c1
    c1
    c1
  }
>>

[image of music]

Furthermore, the space character " " serves as a placeholder for defining span bars correctly aligned to the main bar lines:

\defineBarLine ":|.-wrong" #'(#t #f "|.")
\defineBarLine ":|.-right" #'(#t #f " |.")

\new StaffGroup <<
  \new Staff \relative c'' {
    c1 \bar ":|.-wrong"
    c1 \bar ":|.-right"
    c1
  }
  \new Staff \relative c'' {
    c1
    c1
    c1
  }
>>

[image of music]

New bar line types defined using \defineBarLine may even, in turn, be used in a second bar line definition. Such ‘nested’ definitions make it possible to use customized glyphs in places where it would not be otherwise possible, such as system ends:

\defineBarLine "||-dashEverywhere" #'("!!" "!!" "!!")
\defineBarLine "||-advancedDashSpan" #'("||-dashEverywhere" #f "!!")

\new StaffGroup <<
  \new Staff \relative c'' {
    c1 \bar "||"
    c1 \bar "||-advancedDashSpan"
    c1 \bar "||-advancedDashSpan"
  }
  \new Staff \relative c'' {
    c1
    c1
    c1
  }
>>

[image of music]

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

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

<<
  \new StaffGroup <<
    \new Staff \relative {
      e'4 d
      \bar "||"
      f4 e
    }
    \new Staff \relative { \clef bass c'4 g e g }
  >>
  \new Staff \relative { \clef bass c'2 c2 }
>>

[image of music]

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

See also

Notation Reference: Line breaking, Repeats, Grouping staves.

Installed Files: ‘scm/bar-line.scm’.

Snippets: Rhythms.

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


Automatic bar lines

Various commands other than \bar can also create bar lines as part of their effect. The bar lines created in these cases can be changed by setting context properties. If a property is set to '() or is unset, it is ignored; otherwise, the value must be a predefined bar type or one previously defined with the \defineBarLine command (see Bar lines).

Multiple reasons for creating different automatic bar lines may apply at the same time. Conflicts are resolved in part by providing properties for predetermined combinations and in part by a priority scheme. The table below presents the available properties in order of increasing priority.

underlyingRepeatBarType

Used at points of repetition or departure where no bar line would otherwise appear. This is expected when repeated sections are not aligned to measures. Several commands employ this bar type: \codaMark, \inStaffSegno, \repeat segno, \repeat volta, and \segnoMark.

caesuraType underlying-bar-line

Used at \caesura; see Phrase bar lines in hymn tunes.

measureBarType

Used at a measure boundary.

caesuraType bar-line

Used at \caesura; see Phrase bar lines in hymn tunes.

sectionBarType

Used at a section break created by \section.

fineBarType

Used at \fine.

doubleRepeatBarType
doubleRepeatSegnoBarType
endRepeatBarType
endRepeatSegnoBarType
fineSegnoBarType
fineStartRepeatSegnoBarType
segnoBarType
startRepeatBarType
startRepeatSegnoBarType

Only one of these bar types is used at a time; which one is used depends on the structure of the piece.

Properties with startRepeat or endRepeat in the name are used at the start or end of a repeated section created by \repeat volta, and properties with doubleRepeat in the name are used where the end of one repeated section and the start of another coincide.

Properties with segno in the name are used at an in-staff segno, which can be created by \repeat segno or \segnoMark when the segnoStyle property is set to bar-line, or created by \inStaffSegno.

Properties with fine in the name are used at \fine.

Priority applies independently to beginning-, middle-, and end-of-line bar lines, allowing a lower-priority bar line to appear where higher-priority bar types have no glyphs defined (see Bar lines).

\fixed c' {
  c1 \section \break
  \repeat volta 2 d1
}

[image of music]

Selected Snippets

Setting the double repeat default for volte

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

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

[image of music]

See also

Notation Reference: Bar lines, Repeats.

Snippets: Rhythms.

Internals Reference: Repeat_acknowledge_engraver.


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:

\relative c' {
  c1 c c c
  \break
  \set Score.currentBarNumber = #50
  c1 c c c
}

[image of music]

The default behavior of only printing bar numbers at the start of every line can be changed through 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:

\relative c' {
  \override Score.BarNumber.break-visibility = ##(#t #t #t)
  \set Score.currentBarNumber = #11
  c1 | c | c | c |
  \break
  c1 | c | c | c |
}

[image of music]

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.

\layout {
  indent = 0
  ragged-right = ##t
}

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

[image of music]

Printing bar numbers at regular intervals

By setting the barNumberVisibility property, bar numbers can be printed at regular intervals. 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
  % 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
}

[image of music]

Printing bar numbers with changing regular intervals

Using the set-bar-number-visibility context function, bar number intervals can be changed.

\relative c' {
  \override Score.BarNumber.break-visibility = #end-of-line-invisible
  \context Score \applyContext #(set-bar-number-visibility 4)
  \repeat unfold 10 c'1
  \context Score \applyContext #(set-bar-number-visibility 2)
  \repeat unfold 10 c
}

[image of music]

Printing bar numbers for broken measures

By default a BarNumber of a broken measure is not repeated at the beginning of the new line. Use first-bar-number-invisible-save-broken-bars for barNumberVisibility to get a parenthesized BarNumber there.

\layout {
  \context {
    \Score
    barNumberVisibility = #first-bar-number-invisible-save-broken-bars
    \override BarNumber.break-visibility = ##(#f #t #t)
  }
}

\relative c' {
  c1 | d | e | f2 \bar "" \break
  fis | g1 | e2 \bar "" \break
  <>^"reenabled default"
  % back to default -
  % \unset Score.barNumberVisibility would do so as well
  \set Score.barNumberVisibility =
    #first-bar-number-invisible-and-no-parenthesized-bar-numbers
  es | d1 | c
}

[image of music]

Printing bar numbers using modulo-bar-number-visible

If the remainder of the division of the current BarNumber by the first argument of modulo-bar-number-visible equals its second argument print the BarNumber.

Useful to print the BarNumber at certain distances, p.e:

\layout {
  \context {
    \Score
    \override BarNumber.break-visibility = ##(#f #t #t)
    barNumberVisibility = #(modulo-bar-number-visible 3 2)
  }
}

\relative c' {
  c1 | d | e | f \break
  g1 | e | d | c
}

[image of music]

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

[image of music]

Alternative bar numbering

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

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

[image of music]

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
}

[image of music]

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
    \omit BarNumber
    % or:
    %\remove "Bar_number_engraver"
  }
}

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

[image of music]

Measure-centered bar numbers

For film scores, a common convention is to center bar numbers within their measure. This is achieved through setting the centerBarNumbers context property to true. When this is used, the type of the bar number grobs is CenteredBarNumber rather than BarNumber.

This example demonstrates a number of settings: the centered bar numbers are boxed and placed below the staves.

\layout {
  \context {
    \Score
    centerBarNumbers = ##t
    barNumberVisibility = #all-bar-numbers-visible
    \override CenteredBarNumber.stencil
      = #(make-stencil-boxer 0.1 0.25 ly:text-interface::print)
    \override CenteredBarNumberLineSpanner.direction = #DOWN
  }
}

\new StaffGroup <<
  \new Staff \relative c' {
    d4-. f8( e d4) bes'-> |
    d,-. f8( e d4) cis'-> |
    g-. f8( d e4) g-> |
    a,1-> |
  }
  \new Staff \relative c {
    \clef bass
    d4 f8 e d2~ |
    4 f8 e d2~ |
    4 4 2 |
    a1 |
  }
>>

[image of music]

See also

Snippets: Rhythms.

Internals Reference: BarNumber, CenteredBarNumber, CenteredBarNumberLineSpanner, Bar_number_engraver, Centered_bar_number_align_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 |

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

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

Bar checks can also be inserted in lyrics:

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

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

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

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

[image of music]

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.

\relative c'' {
  c1 \mark \default
  c1 \mark \default
  c1 \mark \default
  c1 \mark \default
}

[image of music]

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.

\relative c'' {
  c1 \mark \default
  c1 \mark \default
  c1 \mark #8
  c1 \mark \default
  c1 \mark \default
}

[image of music]

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.rehearsalMarkFormatter = #format-mark-alphabet
\set Score.rehearsalMarkFormatter = #format-mark-box-alphabet
\set Score.rehearsalMarkFormatter = #format-mark-circle-alphabet
\relative c'' {
  \set Score.rehearsalMarkFormatter = #format-mark-box-alphabet
  c1 \mark \default
  c1 \mark \default
  c1 \mark #8
  c1 \mark \default
  c1 \mark \default
}

[image of music]

The style is defined by the property rehearsalMarkFormatter. 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, rehearsalMarkFormatter is set to a predefined procedure. After a few measures, it is set to a procedure that produces a boxed number.

\relative c'' {
  \set Score.rehearsalMarkFormatter = #format-mark-numbers
  c1 \mark \default
  c1 \mark \default
  \set Score.rehearsalMarkFormatter = #format-mark-box-numbers
  c1 \mark \default
  \set Score.rehearsalMarkFormatter = #format-mark-circle-numbers
  c1 \mark \default
  \set Score.rehearsalMarkFormatter = #format-mark-circle-letters
  c1
}

[image of music]

The file ‘scm/translation-functions.scm’ contains the definitions of format-mark-letters (the default format), format-mark-box-letters, format-mark-numbers, and format-mark-box-numbers. 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.

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

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

Selected Snippets

Printing marks on every staff

Although marks are normally only printed above the topmost staff, they may also be printed on every staff.

\score {
  <<
    \new Staff { \mark \default c''1 \textMark "molto" c'' }
    \new Staff { \mark \default c'1 \textMark "molto" c' }
  >>
  \layout {
    \context {
      \Score
      \remove Mark_engraver
      \remove Text_mark_engraver
      \remove Staff_collecting_engraver
    }
    \context {
      \Staff
      \consists Mark_engraver
      \consists Text_mark_engraver
      \consists Staff_collecting_engraver
    }
  }
}

[image of music]

See also

Notation Reference: The Emmentaler font, Formatting text, Aligning objects, Music notation inside markup, Metronome marks, Section labels.

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

Snippets: Rhythms.

Internals Reference: AdHocMarkEvent, RehearsalMark, RehearsalMarkEvent.


Measure counts

Measure counts are a way to number consecutive measures, for example as an aid for musicians to count measures in written-out repeats. Using this feature requires adding the Measure_counter_engraver to a context type, usually Staff or Score.

\layout {
  \context {
    \Staff
    \consists Measure_counter_engraver
  }
}

\relative c' {
  \time 6/8
  \key e \minor
  r4 a8 b c dis
  \startMeasureCount
  \repeat unfold 3 {
    e8 b e g8. fis32 e dis8
  }
  \stopMeasureCount
  b'4. r
}

[image of music]

Broken measures are numbered in parentheses.

\layout {
  \context {
    \Staff
    \consists Measure_counter_engraver
  }
}

\relative c' {
  \time 6/8
  \key e \minor
  r4 a8 b c dis
  \startMeasureCount
  e8 b e g8. fis32 e dis8
  e8 b e \break g8. fis32 e dis8
  e8 b e g8. fis32 e dis8
  \stopMeasureCount
  b'4. r
}

[image of music]

Compressed multi-measure rests receive special treatment: the full measure range is shown.

\layout {
  \context {
    \Staff
    \consists Measure_counter_engraver
  }
  \context {
    \Voice
    \override MultiMeasureRestNumber.direction = #DOWN
  }
}

\compressMMRests {
  \key e \minor
  \startMeasureCount
  \new CueVoice {
    b4.( e'8) b8 r e' r
  }
  R1*2
  \stopMeasureCount
  g'2\> fis'2\!
}

[image of music]

Measure counters honor alternative numbering styles. If the style is numbers-with-letters, they render best with a textual font.

\layout {
  \context {
    \Score
    alternativeNumberingStyle = #'numbers-with-letters
  }
  \context {
    \Staff
    \consists Measure_counter_engraver
    \override MeasureCounter.Y-offset = 6
    \override MeasureCounter.font-encoding = #'latin1
    \override MeasureCounter.font-size = 1
  }
}

\relative c' {
  \startMeasureCount
  \repeat volta 2 {
    c8 d e f c d e f
  }
  \alternative {
    { e4 d c b }
    { g'4 g c2 }
  }
  \bar "|."
  \stopMeasureCount
}

[image of music]

Predefined commands

\startMeasureCount, \stopMeasureCount.

See also

Notation Reference: Modifying context plug-ins, Compressing empty measures, Breaks, Bar numbers.

Internals Reference: Measure_counter_engraver, MeasureCounter, measure-counter-interface.


Section divisions

The \section command marks a point where one section of music ends and another begins. It does not have to be followed by more music: it may also be used to emphasize that the written end of the music is not the end of the piece, such as at a D.C. instruction or where one movement continues into the next without a break. \section normally creates a double bar line, but its effect can depend on other notation, e.g., repeat bar lines.

The \fine command ends the piece, normally with a final bar line. It is not limited to use at the written end of the music: it may also appear inside \repeat (see Al-fine repeats).

A section can optionally be named with \sectionLabel (see Section labels).

\fixed c' {
  f1
  \section
  \sectionLabel "Refrain"
  g1
  a1
  \fine
}

[image of music]

For details on interactions of \fine and \section bar lines with other types of bar lines, and options for changing their appearance, see Automatic bar lines.

See also

Music Glossary: fine.

Notation Reference: Automatic bar lines, Divisiones, Al-fine repeats, Section labels.

Internals Reference: FineEvent, SectionEvent.


1.2.6 Special rhythmic concerns


Grace notes

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

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

[image of music]

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

\relative {
  \acciaccatura d''8 c4
  \appoggiatura e8 d4
  \acciaccatura { g16 f } e2
  \slashedGrace a,8 g4
  \slashedGrace b16 a4(
  \slashedGrace b8 a2)
}

[image of music]

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 \relative { e''2 \grace { c16 d e f } e2 }
  \new Staff \relative { c''2 \grace { g8 b } c2 }
>>

[image of music]

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.

\relative { c''1 \afterGrace d1 { c16[ d] } c1 }

[image of music]

This will place the grace notes after the start of the main note. The point of time where the grace notes are placed is a given fraction of the main note’s duration. The default setting of

afterGraceFraction = 3/4

may be redefined at top level. Individual \afterGrace commands may have the fraction specified right after the command itself instead.

The following example shows the results from setting with the default space, setting it at 15/16, and finally at 1/2 of the main note.

<<
  \new Staff \relative {
    c''1 \afterGrace d1 { c16[ d] } c1
  }
  \new Staff \relative {
    c''1 \afterGrace 15/16 d1 { c16[ d] } c1
  }
  \new Staff \relative {
    c''1 \afterGrace 1/2 d1 { c16[ d] } c1
  }
>>

[image of music]

The effect of \afterGrace can also be achieved using spacers. The following example places the grace note after a space lasting 7/8 of the main note.

\new Voice \relative {
  <<
    { d''1^\trill_( }
    { s2 s4. \grace { c16 d } }
  >>
  c1)
}

[image of music]

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 \relative {
  \acciaccatura {
    \stemDown
    f''16->
    \stemNeutral
  }
  g4 e c2
}

[image of music]

Selected Snippets

Using grace note slashes with normal heads

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

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

[image of music]

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

[image of music]

Redefining grace note global defaults

The global defaults for grace notes are stored in the following identifiers.

startGraceMusic
stopGraceMusic
startAcciaccaturaMusic
stopAcciaccaturaMusic
startAppoggiaturaMusic
stopAppoggiaturaMusic

They are defined in file ly/grace-init.ly. By redefining them other effects may be obtained.

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

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

\relative c'' {
  \acciaccatura d8 c1
}

[image of music]

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

[image of music]

See also

Music Glossary: grace notes, acciaccatura, appoggiatura.

Notation Reference: Scaling durations, Manual beams.

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

Snippets: Rhythms.

Internals Reference: GraceMusic, Grace_beam_engraver, Grace_auto_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 \relative { e''4 \section \grace c16 d2. }
  \new Staff \relative { c''4 \section d2. }
>>

[image of music]

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

<<
  \new Staff \relative { e''4 \section \grace c16 d2. }
  \new Staff \relative { c''4 \section \grace s16 d2. }
>>

[image of music]

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

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

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

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

becomes:

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

Or explicitly change the musical duration:

c'8 \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'4 d8 e f g g4
  f2 g4 g
}

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

[image of music]

Another solution is to use the \skip command.

MyCadenza = \fixed c' {
  \repeat volta 2 {
    d8 e f g g4 f4
  }
}

music = <<
  \new Staff {
    \MyCadenza
    c'1
  }
  \new Staff {
    \skip \MyCadenza
    c'1
  }
>>

\unfoldRepeats \music

[image of music]

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 {
  \set Timing.measureLength = #(ly:make-moment 5/4)
  c'1 c4 |
  c1 c4 |
  c4 c
  \set Timing.measurePosition = #(ly:make-moment 5/8)
  b4 b b8 |
  c4 c1 |
}

[image of music]

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

[image of music]

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:

\relative {
  c''4\staccato c\mordent b2\turn
  c1\fermata
}

[image of music]

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

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

[image of music]

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.

The type of grob that an articulation creates depends on what it is attached to.

\override Score.Script.color = #(universal-color 'vermillion)
\override Score.MultiMeasureRestScript.color = #(universal-color 'blue)
\override Score.CaesuraScript.color = #(universal-color 'orange)
a'2\fermata r\fermata
R1\fermata
g'2 \caesura \fermata f'2

[image of music]

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

For more information about the ordering of Script and TextScript grobs that are attached to 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, dashBang, 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-+ }

[image of music]

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

[image of music]

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. Changing the fraction 2/3 adjusts the horizontal position.

\relative c'' {
  \after 2*2/3 \turn c2( d4) r |
  \after 4 \turn c4.( d8)
  \after 4
  {
    \once \set suggestAccidentals = ##t
    \once \override AccidentalSuggestion.outside-staff-priority = ##f
    \once \override AccidentalSuggestion.avoid-slur = #'inside
    \once \override AccidentalSuggestion.font-size = -3
    \once \override AccidentalSuggestion.script-priority = -1
    \once \hideNotes
    cis8\turn \noBeam
  }
  d4.( e8)
}

[image of music]

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: CaesuraScript, MultiMeasureRestScript, 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, \rfz, and \n. Dynamic marks may be manually placed above or below the staff; see Direction and placement.

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

[image of music]

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 \>; \endcr and \enddecr maybe used instead of \! to end a crescendo or decrescendo mark, respectively. Hairpins are engraved by default using this notation.

\relative c'' {
  c2\< c\!
  d2\< d\f
  e2\< e\>
  f2\> f\!
  e2\> e\mp
  d2\> d\>
  c1\!
}

[image of music]

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 center of the note that has the next \< or \> assigned to it. The next hairpin will then start at the right edge of the same note instead of the usual left edge had it been terminated with \! before. A hairpin ending on a downbeat will stop at the preceding bar line.

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

[image of music]

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

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

[image of music]

Often, marks like crescendo or decrescendo should begin or end at some point of time during a sustained note. This can be achieved with \after, which can also be used to create delayed articulations or text scripts:

<<
  \relative {
    \after 2 \< c'1
    d4\f\> e f g
    \after 2. \pp c,1
    \after 2. \fermata e
    \after 2. ^"Fine." f
  }
  \relative {
    \repeat unfold 12 c'4
    c c c c\fermata
    c c c c
  }
>>

[image of music]

Multiple instances of \after can be used to engrave multiple marks on one note. This is particularly useful when adding a crescendo and decrescendo to the same note:

\relative {
  c''4\< d\! e\> c\!
  \after 4 \< \after 2\> \after 2. \! f1
  \textLengthOn
  \after 4 \> \after 2. ^"hush!" c1
  g4\pp
}

[image of music]

If the first in such a sequence of marks on a single note is supposed to coincide with the onset of the note, it is convenient to attach it to an empty chord <>. This way, all marks can be entered in their natural visual order:

{
  <>\< \after 4 \> \after 2 \! c'1
  % easier to write and read than:
  \after 4 \> \after 2 \! c'1\<
}

[image of music]

The \espressivo command can also 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.

\relative {
  c''2 b4 a
  g1\espressivo
  \after 2. \espressivo c
}

[image of music]

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

\relative {
  g'8\cresc a b c b c d e\mf |
  f8\decresc e d c e\> d c b |
  a1\dim ~ |
  a2. r4\! |
}

[image of music]

Textual marks for dynamic changes can also replace hairpins:

\relative c'' {
  \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\! |
}

[image of music]

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'2 d4 e |
    c4 e e,2 |
    g'4 a g a |
    c1 |
  }
  \new Dynamics {
    s1\< |
    s1\f |
    s2\dim s2-"rit." |
    s1\p |
  }
>>

[image of music]

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

[image of music]

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.

<<
  {
    \after 4 \< \after 2 \> \after 2. \! f'1
    \override Hairpin.minimum-length = #8
    \after 4 \< \after 2 \> \after 2. \! f'1
  }
  {
    \repeat unfold 8 c'4
  }
>>

[image of music]

Aligning the ends of hairpins to NoteColumn directions

The ends of hairpins may be aligned to the LEFT, CENTER or RIGHT of NoteColumn grobs by overriding the property endpoint-alignments, which is a pair of numbers representing the left and right ends of the hairpin. endpoint-alignments are expected to be directions (either -1, 0 or 1). Other values will be transformed with a warning. The right end of a hairpin terminating at a rest is not affected, always ending at the left edge of the rest.

{
  c'2\< <c' d'>\! |
  \override Hairpin.endpoint-alignments = #'(1 . -1)
  c'2\< <c' d'>\! |
  \override Hairpin.endpoint-alignments = #`(,LEFT . ,CENTER)
  c'2\< <c' d'>\! |
}

[image of music]

Moving the ends of hairpins

The ends of hairpins may be offset by setting the shorten-pair property of the Hairpin object. Positive values move endpoints to the right, negative to the left. Unlike the minimum-length property, this property only affects the appearance of the hairpin; it does not adjust horizontal spacing (including the position of bounding dynamics). This method is thus suitable for fine-tuning a hairpin within its allotted space.

{
  c'1~\<
  c'2~ c'\!
  \once \override Hairpin.shorten-pair = #'(2 . 2)
  c'1~\<
  c'2~ c'\!
  \once \override Hairpin.shorten-pair = #'(-2 . -2)
  c'1~\<
  c'2~ c'\!
  c'1~\p-\tweak shorten-pair #'(2 . 0)\<
  c'2~ c'\ffff
}

[image of music]

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

[image of music]

Printing hairpins in various styles

Hairpin dynamics may be created in a variety of styles.

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

[image of music]

Vertically aligned dynamics and textscripts

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

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

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 = #3
  \textLengthOn
  \override TextScript.staff-padding = #1
  \music
}

[image of 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\!
}

[image of music]

Changing text and spanner styles for text dynamics

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

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

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

[image of music]

See also

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

Learning Manual: Articulations and dynamics.

Notation Reference: Direction and placement, New dynamic marks, Enhancing 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 {
  <d' e>16_\moltoF <d e>
  <d e>2..
}

[image of music]

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'1_\roundF
  c1_\boxF
}

[image of music]

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

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

[image of music]

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'4_\roundFdynamic\< d e f
  g,1~_\boxFdynamic\>
  g1
  g'1~\mfEspressDynamic
  g1
}

[image of music]

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 {
  <d' e>16 <d e>
  <d e>2..\moltoF
}

[image of music]

To left-align the dynamic text rather than centering it on a note use a \tweak:

moltoF = \tweak DynamicText.self-alignment-X #LEFT
         #(make-dynamic-script
            (markup #:normal-text "molto"
                    #:dynamic "f"))
\relative {
  <d' e>16 <d e>
  <d e>2..\moltoF <d e>1
}

[image of music]

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

See also

Notation Reference: Formatting text, Selecting font and font size, Enhancing MIDI output, Controlling MIDI dynamics.

Extending LilyPond: Markup construction in Scheme.

Snippets: Expressive marks.


1.3.2 Expressive marks as curves

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


Slurs

Slurs are entered using parentheses:

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

\relative {
  f''4( g a) a8 b(
  a4 g2 f4)
  <c e>2( <b d>2)
}

[image of music]

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

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

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

[image of music]

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

\relative {
  c'4( e g2)
  \slurDashed
  g4( e c2)
  \slurDotted
  c4( e g2)
  \slurSolid
  g4( e c2)
}

[image of music]

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

\relative {
  c'4( e g2)
  \slurHalfDashed
  g4( e c2)
  \slurHalfSolid
  c4( e g2)
  \slurSolid
  g4( e c2)
}

[image of music]

Custom dash patterns for slurs can be defined:

\relative {
  c'4( e g2)
  \slurDashPattern #0.7 #0.75
  g4( e c2)
  \slurDashPattern #0.5 #2.0
  c4( e g2)
  \slurSolid
  g4( e c2)
}

[image of music]

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

[image of music]

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
}

[image of music]

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

[image of music]

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:

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

[image of music]

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

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

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

\relative {
  c'4\( e g2\)
  \phrasingSlurDashed
  g4\( e c2\)
  \phrasingSlurDotted
  c4\( e g2\)
  \phrasingSlurSolid
  g4\( e c2\)
}

[image of music]

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

\relative {
  c'4\( e g2\)
  \phrasingSlurHalfDashed
  g4\( e c2\)
  \phrasingSlurHalfSolid
  c4\( e g2\)
  \phrasingSlurSolid
  g4\( e c2\)
}

[image of music]

Custom dash patterns for phrasing slurs can be defined:

\relative {
  c'4\( e g2\)
  \phrasingSlurDashPattern #0.7 #0.75
  g4\( e c2\)
  \phrasingSlurDashPattern #0.5 #2.0
  c4\( e g2\)
  \phrasingSlurSolid
  g4\( e c2\)
}

[image of music]

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

The \breathe command calls for the performer to shorten the previous note to take a breath.

\fixed c'' { c2. \breathe d4 }

[image of music]

For a short break in sound that is not taken away from the previous note, see Caesuras.

Unlike other expressive marks, a breath mark is treated as a separate music event; therefore, any expressive marks pertaining to the preceding note, and any brackets indicating manual beams, slurs, or phrasing slurs, must be placed before \breathe. \breathe does not accept articulations itself, but see Caesuras.

A breath mark ends an automatic beam; to override this, see Manual beams.

\fixed c'' { c8 \breathe d e f g2 }

[image of music]

The breathMarkType context property controls which of several predefined breath marks the \breathe command creates. See List of breath marks.

\fixed c'' {
  \set breathMarkType = #'tickmark
  c2. \breathe d4
}

[image of music]

See also

Music Glossary: breath mark.

Notation Reference: Caesuras, 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.

\relative c'' {
  c2\bendAfter #+4
  c2\bendAfter #-4
  c2\bendAfter #+6.5
  c2\bendAfter #-6.5
  c2\bendAfter #+8
  c2\bendAfter #-8
}

[image of music]

Selected Snippets

Adjusting the shape of falls and doits

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

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

[image of music]

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

\relative {
  g'2\glissando g'
  c2\glissando c,
  \afterGrace f,1\glissando f'16
}

[image of music]

A glissando can connect notes across staves:

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

[image of music]

A glissando can connect notes in chords. If anything other than a direct one-to-one pairing of the notes in the two chords is required, the connections between the notes are defined by setting \glissandoMap to a Scheme list. The elements are pairs of integers; each pair (x . y) creates a glissando line from the x-th note of the first chord to the y-th note of the second chord. Notes are numbered from zero in the order in which they appear in the input ‘.ly’ file. Not all notes need be part in a glissando.

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

[image of music]

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

[image of music]

Adding timing marks to long glissandi

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

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

glissandoSkipOn = {
  \override NoteColumn.glissando-skip = ##t
  \hide NoteHead
  \override NoteHead.no-ledgers = ##t
}

glissandoSkipOff = {
  \revert NoteColumn.glissando-skip
  \undo \hide NoteHead
  \revert NoteHead.no-ledgers
}

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

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

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

[image of music]

Making glissandi breakable

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

glissandoSkipOn = {
  \override NoteColumn.glissando-skip = ##t
  \hide NoteHead
  \override NoteHead.no-ledgers = ##t
}

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

[image of music]

Extending glissandi across repeats

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

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

repeatGliss = #(define-music-function (grace)
  (ly:pitch?)
  #{
    % the next two lines ensure the glissando is long enough
    % to be visible
    \once \override Glissando.springs-and-rods
      = #ly:spanner::set-spacing-rods
    \once \override Glissando.minimum-length = #3.5
    \once \hideNotes
    \grace $grace \glissando
  #})

\score {
  \relative c'' {
    \repeat volta 3 { c4 d e f\glissando }
    \alternative {
      { g2 d }
      { \repeatGliss f g2 e }
      { \repeatGliss f e2 d }
    }
  }
}

music =  \relative c' {
  \voiceOne
  \repeat volta 2 {
    g a b c\glissando
  }
  \alternative {
    { d1 }
    { \repeatGliss c \once \omit StringNumber e1\2 }
  }
}

\score {
  \new StaffGroup <<
    \new Staff <<
      \new Voice { \clef "G_8" \music }
    >>
    \new TabStaff  <<
      \new TabVoice { \clef "moderntab" \music }
    >>
  >>
}

[image of music]

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:

\relative { <c' e g c>1\arpeggio }

[image of music]

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

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

[image of music]

These predefined commands internally modify the arpeggio-direction property; see their full definition in the ‘ly/property-init.ly’ file.

Special bracketed arpeggio symbols can be created:

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

[image of music]

These predefined commands internally override the Arpeggio object’s stencil property, and may also adapt its X-extent (that is, the horizontal dimension it takes not to collide with other objects).

The dash properties of the parenthesis arpeggio are controlled with the dash-definition property (see 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
    }
  }
>>

[image of music]

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

[image of music]

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

[image of music]

See also

Music Glossary: arpeggio.

Notation Reference: Slurs, Ties.

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

Snippets: Expressive marks.

Internals Reference: Arpeggio, Slur, PianoStaff.

Known issues and warnings

Predefined commands such as \arpeggioArrowUp only apply to the current context, and thus will not affect arpeggios spanning several voices or staves. In such cases, these commands need to be used in a \context block within \layout, or in a \with block, as explained in Changing context default settings. Alternatively, rather than using predefined shortcuts, it may be advisable to directly override the relevant properties for the Arpeggio object in the appropriate context; for example:

\override Staff.Arpeggio.stencil = #ly:arpeggio::brew-chord-bracket

to print cross-voice arpeggio brackets at the Staff level, or

\override PianoStaff.Arpeggio.arpeggio-direction = #UP

to print cross-staff arrowed arpeggios (pointing upwards) in a PianoStaff context.

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

The simple way of setting parenthesis-style arpeggio brackets does not work for cross-staff arpeggios; see Cross-staff stems.


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:

\relative {
  d''1\startTrillSpan
  d1
  c2\stopTrillSpan
  r2
}

[image of music]

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

\relative {
  d''1\startTrillSpan
  \break
  d1
  c2\stopTrillSpan
  r2
}

[image of music]

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

\relative {
  d''1\startTrillSpan
  d1
  b1\startTrillSpan
  d2\stopTrillSpan
  r2
}

[image of music]

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.

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

[image of music]

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.

\relative {
  \pitchedTrill
  d''2\startTrillSpan fis
  d2
  c2\stopTrillSpan
  r2
}

[image of music]

The Accidental of the first pitched trill in a measure is always printed, even for naturals.

{
  \key d \major
  \pitchedTrill
  d'2\startTrillSpan cis d\stopTrillSpan
  \pitchedTrill
  d2\startTrillSpan c d\stopTrillSpan
  \pitchedTrill
  d2\startTrillSpan e d\stopTrillSpan
}

[image of music]

Subsequent accidentals (of the same note in the same measure) will need to be added manually.

\relative {
  \pitchedTrill
  eis''4\startTrillSpan fis
  eis4\stopTrillSpan
  \pitchedTrill
  eis4\startTrillSpan cis
  eis4\stopTrillSpan
  \pitchedTrill
  eis4\startTrillSpan fis
  eis4\stopTrillSpan
  \pitchedTrill
  eis4\startTrillSpan fis!
  eis4\stopTrillSpan
}

[image of music]

Predefined commands

\startTrillSpan, \stopTrillSpan.

See also

Music Glossary: trill.

Notation Reference: Articulations and ornamentations, Grace notes.

Snippets: Expressive marks.

Internals Reference: TrillSpanner, TrillPitchHead, TrillPitchAccidental, TrillPitchParentheses, TrillPitchGroup, Pitched_trill_engraver.


1.4 Repeats

[image of music]

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

volta

This is the standard notation for repeats with or without alternative endings. The repeated section is framed between repeat bar lines, but the starting bar line is omitted when the repeated section begins the piece. Alternative endings are printed in sequence, bracketed, and numbered with the volte to which they apply.

segno

This supports various da capo and dal segno cases. The repeated section begins with a segno mark, except at the start of the piece. Alternative endings are printed in sequence and marked with coda marks, and a section label such as ‘Coda’ can optionally be applied to the final alternative. The repeated section ends with an instruction such as D.S.

unfold

The repeated music is written out in full a specified number of times.

percent

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

tremolo

This is used to write tremolo beams.

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


1.4.1 Long repeats

This section discusses how to input long (usually multi-measure) repeats.


Written-out repeats

The \repeat unfold command repeats music by writing it out a number of times. The syntax is the same as the \repeat volta and \repeat segno commands, which are documented in following sections.

To avoid redundancy, unfolding is not demonstrated in detail here; however, some of the examples in following sections illustrate repeats in multiple forms using the \unfoldRepeats command to convert the volta or segno form to the unfold form. For another important use of the \unfoldRepeats command, see Using repeats with MIDI.

There are some points of interest specific to the \repeat unfold command.

In some cases, especially in a \relative context, the outcome of unfolding is not the same as of writing the input music expression multiple times, e.g.,

\repeat unfold 2 { a'4 b c d | }

differs from the following by an octave change:

a'4 b c d |
a'4 b c d |

Also, nesting \repeat unfold can be practical in ways that nesting \repeat volta or \repeat segno would not be.

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.


Simple repeats

This is the syntax for a repeat without variation:

\repeat volta repeatcount musicexpr

where musicexpr is the music expression to be repeated.

\fixed c'' {
  \repeat volta 2 { c2 f }
  R1
  \repeat volta 2 { g2 c }
}

[image of music]

A starting bar line is not automatically printed at the beginning of a piece; however, it is possible to add one with \bar ".|:".

\fixed c'' {
  \repeat volta 2 { \bar ".|:" c2 f }
}

[image of music]

A repeated section that starts in the middle of a measure usually ends at the same position in a later measure so that the two ends make a complete measure. The repeat bar lines are not measure boundaries in such cases, so no bar checks should be placed there. Likewise, no \partial command should be placed within the repeated music, because the measures are complete; however, a \partial command should be placed before the repeat when there is a truly incomplete measure the first time through.

\fixed c'' {
  \partial 4
  \repeat volta 2 {
    c4
    c2 d
    g4 g g
  }
  \repeat volta 2 {
    e4
    f2 g
    c2.
  }
}

[image of music]


Alternative endings

Repeats with alternative endings can be written two ways. This is the preferred syntax:

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

where musicexpr is a music expression, musicexpr… is any number of them, and numberlist is a comma-separated list of volta numbers chosen from the range 1 to repeatcount.

\fixed c'' {
  \repeat volta 6 {
    c4 d e f
    \alternative {
      \volta 1,2,3 { c2 e }
      \volta 4,5 { f2 d }
      \volta 6 { e2 f }
    }
  }
  c1
}

[image of music]

An older syntax where the \alternative block follows outside the repeated music expression is still supported and has the same effect.

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

\volta specifications within an \alternative block are optional on an all-or-none basis. If they are omitted, alternatives are used once each, but the first is repeated as needed to satisfy the repeat count.

\fixed c'' {
  \repeat volta 6 {
    c4 d e f
    \alternative {
      { c2 e }
      { f2 d }
      { e2 f }
    }
  }
  c1
}

[image of music]

\alternative blocks can be nested.

music = \fixed c' {
  \repeat volta 3 {
    s1_"A"
    \alternative {
      \volta 1 { s1_"B" }
      \volta 2,3 {
        s1_"C"
        \once \set Score.voltaSpannerDuration = #(ly:make-moment 1)
        s1_"D"
        \alternative {
          \volta 2 { s1_"E" }
          \volta 3 { s1_"F" }
        }
      }
    }
  }
  \fine
}

\score { \music }
\score { \unfoldRepeats \music }

[image of music]

Note: Every element in an \alternative block is treated as an alternative ending. Something as simple as a bar check on the wrong side of a bracket can produce unexpected results.

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

Note: When alternative bar numbering is enabled, it is applied to the outermost bracketed alternatives.


Other variation in repeated sections

An \alternative block can be used within a \repeat block to produce notation similar to alternative endings (see Alternative endings).

\fixed c'' {
  \repeat volta 2 {
    R1
    \alternative {
      \volta 1 { c1 }
      \volta 2 { d1 }
    }
    R1
  }
}

[image of music]

The \volta command is not limited to use on the elements of an \alternative block. It can be used anywhere within a \repeat to designate music for particular volte, though it does not create brackets in other cases.

When a \repeat is unfolded, volta-specific music is omitted from every volta to which it does not apply. Providing an empty Scheme list in place of volta numbers removes the music entirely.

music = \repeat volta 3 {
  \volta #'() { s1*0^\markup { \bold "3×" } }
  \volta 1 { s1*0_\markup { \italic dolce } }
  g''1
}

\score { \music }
\score { \unfoldRepeats \music }

[image of music]

When a \repeat is unfolded, it may be desirable not only to filter out volta-specific music, but also to add music that was not present in the folded form. The \unfolded command designates music to be ignored until the enclosing \repeat is unfolded.

music = \fixed c' {
  \repeat volta 2 {
    c1
    <<
      \volta #'() {
        \once \override TextSpanner.bound-details.left.text =
          "2nd time tacet"
        s4*7\startTextSpan s4\stopTextSpan
      }
      \volta 1 { f4 f f f | f f f f }
      \volta 2 { \unfolded { R1*2 } }
    >>
    c'1
  }
  \fine
}

\score { \music }
\score { \unfoldRepeats \music }

[image of music]

Note: The \volta and \unfolded commands function with respect to the innermost repeat enclosing them.


Al-fine repeats

The \fine command marks the end of the music but does not enforce it. When a repeat containing \fine is unfolded, the \fine command is unfolded like any other music. For correct unfolding, it is necessary to specify the volta in which the Fine should be performed and the volte in which any following music should be performed (see Other variation in repeated sections).

music = \fixed c' {
  \repeat volta 2 {
    f1
    \volta 2 \fine
    \volta 1 b1
  }
}

\score { \music }
\score { \unfoldRepeats \music }

[image of music]

As shown immediately above, at the written end of the music, \fine creates a final bar line without a Fine instruction. To force Fine to appear in such cases, set the finalFineTextVisibility context property.

\fixed c' {
  \set Score.finalFineTextVisibility = ##t
  f1
  \fine
}

[image of music]

To change the text that \fine prints, set the fineText context property.

\fixed c' {
  \set Score.fineText = "Fine."
  \repeat volta 2 {
    f1
    \volta 2 \fine
    \volta 1 b1
  }
}

[image of music]

For details on interactions with other types of bar lines and options for changing their appearance, see Automatic bar lines.

See also

Music Glossary: fine.

Notation Reference: Automatic bar lines, Other variation in repeated sections, Section divisions.

Snippets: Repeats.

Internals Reference: FineEvent, Jump_engraver, JumpScript.


Segno repeat structure

\repeat segno differs from \repeat volta only in the resulting notation. Refer to the preceding sections for general information on entering music with repetition, alternatives, and variation. This section covers particulars of segno notation without fully reiterating the input syntax.

\repeat segno notates repetition with D.C. or D.S. instructions. It marks the beginning of the repeated section with a segno mark when it is not the beginning of the piece. It also marks alternative endings with coda marks in lieu of volta brackets, provided that the endings are intended to be performed in order, e.g., not \volta 1,3 then \volta 2,4.

When alternative bar numbering is enabled, it is applied to alternatives notated with volta brackets whether they are created by \repeat segno or \repeat volta, but it is not applied to alternative endings notated with coda marks.

Demonstrations of common uses follow.

al fine

Repeat instructions include al Fine if a \fine command appears at any prior point (see Al-fine repeats).

music = \fixed c' {
  f1
  \repeat segno 2 {
    g1
    \volta 2 \fine
    \volta 1 a1
  }
  \section
}

\score { \music }
\score { \unfoldRepeats \music }

[image of music]

alla coda

The beginning of each alternative ending is marked with an implied \codaMark \default. Repeat instructions in alternatives include ‘al … e poi la …’ referring to the mark at the first alternative and the mark to skip to. Provided that the duration of the final alternative is zero, the automatic mark is suppressed, allowing a section label to be set instead.

music = \fixed c' {
  f1
  \repeat segno 2 {
    g1
    \alternative {
      \volta 1 { \repeat unfold 4 { a2 } }
      \volta 2 \volta #'() {
        \section
        \sectionLabel "Coda"
      }
    }
  }
  b1
  \fine
}

\score { \music }
\score { \unfoldRepeats \music }

[image of music]

The return instruction can be abbreviated by setting an alternative formatting procedure (see Segno repeat appearance).

da capo

Repeat instructions include D.C. when the repeated section begins at the beginning of the score. The supported da capo cases parallel the supported dal segno cases.

music = \fixed c' {
  \repeat segno 2 {
    g1
  }
  \fine
}

\score { \music }
\score { \unfoldRepeats \music }

[image of music]

dal segno

Repeat instructions include D.S. when the repeated section begins after the beginning of the score. The beginning of the repeated section is marked with an implied \segnoMark \default.

music = \fixed c' {
  f1
  \repeat segno 2 {
    g1
  }
  \repeat segno 2 {
    a1
  }
  \fine
}

\score { \music }
\score { \unfoldRepeats \music }

[image of music]

A dal-segno repeat starting at the beginning of the score can be forced (see Segno repeat appearance).

multiple return

A repeat instruction to be performed more than once includes ‘… V.’. The number of times the instruction is performed is one less than the number of times the passage is performed.

music = \fixed c' {
  \repeat segno 3 {
    g1
  }
  \fine
}

\score { \music }
\score { \unfoldRepeats \music }

[image of music]

See also

Music Glossary: da capo, dal segno, fine.

Notation Reference: Al-fine repeats, Alternative endings, Automatic bar lines, Other variation in repeated sections, Section divisions, Section labels, Simple repeats.

Snippets: Repeats.

Internals Reference: CodaMark, JumpScript, SectionLabel, SegnoMark.


Segno repeat appearance

The marks and return instructions that \repeat segno creates are adjustable in some respects.

Return instructions are formatted with the Scheme procedure specified in the dalSegnoTextFormatter property. There is a predefined alternative formatter that creates shorter instructions.

\fixed c' {
  \set Score.dalSegnoTextFormatter = #format-dal-segno-text-brief
  f1
  \repeat segno 2 {
    g1
    \alternative {
      \volta 1 { a1 }
      \volta 2 \volta #'() {
        \section
        \sectionLabel "Coda"
      }
    }
  }
  b1
  \fine
}

[image of music]

The sequence numbers of the marks at the beginning of the repeated section and the beginning of the first alternative may be set explicitly without interfering with automatic return instructions (see Manual repeat marks).

\fixed c' {
  \repeat segno 2 {
    \volta #'() { \segnoMark 2 }
    g1
    \alternative {
      \volta 1 {
        \volta #'() { \codaMark 2 }
        \repeat unfold 8 { a4 }
      }
      \volta 2 \volta #'() {
        \section
        \sectionLabel "Coda"
      }
    }
  }
  b1
  \fine
}

[image of music]

Without the explicit \segnoMark 2, the above would have been rendered as a da-capo repeat.

As an alternative to printing a segno as a mark above the staff, it is possible to print it as a bar line by setting the segnoStyle property to bar-line. To avoid ambiguity, only the first segno bar remains unmarked.

\fixed c' {
  \set Score.segnoStyle = #'bar-line
  R1
  \repeat unfold 3 {
    \repeat segno 2 {
      R1*2
    }
  }
  \fine
}

[image of music]

Where a segno bar coincides with other special bar lines, a combination bar line is chosen automatically from a predetermined set. For each supported combination, the bar line can be customized by setting a context property (see Automatic bar lines).

Segno and coda marks are formatted with procedures specified in the segnoMarkFormatter and codaMarkFormatter properties. These are interchangeable with procedures used to format rehearsal marks (see Rehearsal marks).

\fixed c' {
  \set Score.segnoMarkFormatter = #format-mark-numbers
  \set Score.segnoStyle = #'bar-line
  R1
  \repeat unfold 3 {
    \repeat segno 2 {
      R1*2
    }
  }
  \fine
}

[image of music]

There is a predefined alternative segno formatter that prints a mark even over the first bar line:

\fixed c' {
  \set Score.segnoMarkFormatter = #format-segno-mark
  \set Score.segnoStyle = #'bar-line
  R1
  \repeat unfold 3 {
    \segnoMark \default
    R1*2
  }
}

[image of music]

There is a predefined alternative coda mark formatter that uses \varcoda signs.

\fixed c' {
  \set Score.codaMarkFormatter = #format-varcoda-mark
  R1
  \repeat unfold 3 {
    \codaMark \default
    R1*2
  }
}

[image of music]

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

[image of music]

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

[image of music]

Alternative bar numbering

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

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

[image of music]

See also

Music Glossary: repeat, volta.

Notation Reference: Automatic bar lines, Bar lines, Modifying context plug-ins, Modifying ties and slurs, Time administration.

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

Snippets: Repeats.

Internals Reference: VoltaBracket, RepeatedMusic, VoltaRepeatedMusic, UnfoldedRepeatedMusic.

Known issues and warnings

For repeats in volta form, spanners (slurs, etc.) that cross into alternatives work for the first alternative only. They likewise cannot wrap around from the end of an alternative back to the beginning of the repeated section.

The visual appearance of a continuing slur or tie in subsequent alternatives can be achieved with \repeatTie if the slur extends into only one note in the alternative block, although this method does not work in TabStaff; see Repeat tie. Other methods which may be tailored to indicate continuing slurs over several notes in alternative blocks, and which also work in TabStaff contexts, are shown in Modifying ties and slurs.

The visual appearance of a continuing glissando in subsequent alternatives can be achieved by coding a glissando starting on a hidden grace note. See Extending glissandi across repeats.

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 volta-style repeats. Its value is a Scheme list. In general, each element is itself a list, '(command args…), but a command with no arguments may be abbreviated to a symbol; e.g., '((start-repeat)) may be given as '(start-repeat).

end-repeat

End a repeated section.

\relative {
  c''1
  d4 e f g
  \set Score.repeatCommands = #'(end-repeat)
  c1
}

[image of music]

start-repeat

Start a repeated section.

\relative {
  c''1
  \set Score.repeatCommands = #'(start-repeat)
  d4 e f g
  c1
}

[image of music]

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

volta text

If text is markup, start a volta bracket with that label; if text is #f, end a volta bracket. A volta bracket which is not ended explicitly will not be printed.

\relative {
  f''4 g a b
  \set Score.repeatCommands = #'((volta "2"))
  g4 a g a
  \set Score.repeatCommands = #'((volta #f))
  c1
}

[image of music]

Multiple repeat commands may occur at the same point:

\relative {
  f''4 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))
}

[image of music]

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''1
  \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))
}

[image of music]

Segno and coda marks can be created with the \segnoMark, \inStaffSegno, and \codaMark commands. This is the syntax for the mark commands:

\codaMark n
\segnoMark n

where n is a sequence number, or \default to use the next automatically. Rehearsal, segno, and coda marks are counted independently.

\fixed c' {
  e1
  \segnoMark \default
  e1
  \segnoMark \default
  g1
  \codaMark \default
  g1
  \codaMark \default
  b1
  \codaMark 96
  b1
  \segnoMark 96
}

[image of music]

At the beginning of a piece, \segnoMark \default and \codaMark \default create no mark. Specify ‘1’ to force a mark.

\fixed c' {
  \segnoMark 1
  f1
}

[image of music]

The \inStaffSegno command is equivalent to \segnoMark \default with the extra effect of temporarily setting the segnoStyle property to bar-line to force printing it as a bar line.

\fixed c' {
  e1
  \inStaffSegno
  g1
  \segnoMark \default
  b1
}

[image of music]

For more information on changing the appearance of segno and coda marks, see Segno repeat appearance.

To create arbitrary jump instructions, use the \jump command.

\fixed c' {
  \time 2/4
  f4 a
  b4 c'8 d'
  c'4 c
  \jump "Gavotte I D.C."
  \section
}

[image of music]

See also

Notation Reference: Bar lines, Formatting text, Rehearsal marks, Segno repeat appearance.

Snippets: Repeats.

Internals Reference: CodaMark, Jump_engraver, JumpScript, Mark_engraver, SegnoMark, SegnoRepeatedMusic, VoltaBracket, VoltaRepeatedMusic.


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.

\relative c'' {
  \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 }
}

[image of music]

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

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

[image of music]

\relative {
  \repeat percent 3 { c''4 d e f | c2 g' }
}

[image of music]

Note that the correct time offset to access the DoublePercentRepeat grob is the beginning of the repeat’s second bar, which can be easily achieved with \after.

\new Voice \with { \consists Balloon_engraver }
  { \after 1*3
      \balloonGrobText DoublePercentRepeat #'(-1 . 2) "repeat"
    \repeat percent 2 { g'1 | a'1 } }

[image of music]

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

\relative {
  \repeat percent 4 { c''8. <d f>16 }
  \repeat percent 2 { \tuplet 3/2 { r8 c d } e4 }
}

[image of music]

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

[image of music]

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

[image of music]

Isolated percent repeats

Isolated percents can also be printed.

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

\relative c'' {
  \makePercent s1
}

[image of music]

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.

Known issues and warnings

Percent repeats will not contain anything else apart from the percent sign itself; in particular, timing changes will not be repeated.

\repeat percent 3 { \time 5/4 c2. 2 \time 4/4 2 2 }

[image of music]

Any meter changes or \partial commands need to occur in parallel passages outside of any percent repeat, e.g in a separate timing track.

<<
  \repeat percent 3 { c2. 2 2 2 }
  \repeat unfold 3 { \time 5/4 s4*5 \time 4/4 s1 }
>>

[image of music]


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:

\relative c'' {
  \repeat tremolo 8 { c16 d }
  \repeat tremolo 6 { c16 d }
  \repeat tremolo 2 { c16 d }
}

[image of music]

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

[image of music]

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

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

[image of music]

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

[image of music]

See also

Snippets: Repeats.


1.5 Simultaneous notes

[image of music]

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.

\relative {
  <a' c e>1 <a c e>2 <f a c e>4 <a c>8. <g c e>16
}

[image of music]

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

\relative {
  <a' c e>1\fermata <a c e>2-> <f a c e>4\prall <a c>8.^! <g c e>16-.
}

[image of music]

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

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

[image of music]

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

\relative {
  <a'\f c( e>1 <a c) e>\f <a\< c e>( <a\! c e>)
  <a c e>\< <a c e> <a c e>\!
}

[image of music]

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

\relative {
  \grace { g'8( a b }
  <> ) \p \< -. -\markup \italic "sempre staccato"
  \repeat unfold 4 { c4 e }  c1\f
}

[image of music]

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.

\relative {
  <a' c e>1 <f a c> <a c e> <f' a c> <b, e b,>
}

[image of music]

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 note heads. Depending on the situation, better representations might involve


Chord repetition

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

\relative {
  <a' c e>1 q <f a c>2 q
}

[image of music]

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.

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

[image of music]

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

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

[image of music]

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

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

[image of music]

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

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

[image of music]

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

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

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

[image of music]

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

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
  << \relative { a'4 b g2 }
     \relative { d'4 g c,2 } >>
}

[image of music]

\relative {
  % single first note
  a' << \relative { a'4 b g }
       \relative { d'4 g c, } >>
}

[image of music]

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

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

[image of music]

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

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

% no single first note
<< \relative { a'4 b g2 }
   \relative { d'4 g2 c,4 } >>

[image of music]

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

Known issues and warnings

If notes from two or more voices, with no shifts specified, have stems in the same direction, the message

warning: This voice needs a \voiceXx or \shiftXx setting

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

\override NoteColumn.ignore-collision = ##t

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


Clusters

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

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

[image of music]

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"
    \relative { \voiceOne r8 r16 g'' e8. f16 g8[ c,] f e16 d }
  \new Voice= "second"
    \relative { \voiceTwo d''16 c d8~ 16 b c8~ 16 b c8~ 16 b8. }
>>

[image of music]

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.

Note that Voice is a bottom-level context (see Bottom-level contexts – voices). In TabStaff one would use TabVoice instead.

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:

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

[image of music]

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

In TabStaff one needs to use TabVoice.

If the same music should appear in Staff and TabStaff the general Bottom context may be used (see Bottom-level contexts – voices).

mus =
\relative
  \new Bottom = "melody" {
    a'4
    <<
      {
        \voiceOne
        g f
      }
      \new Bottom {
        \voiceTwo
        d2
      }
    >>
    \oneVoice
    e4
  }

<<
  \new Staff \mus
  \new Lyrics \lyricsto "melody" {
    This is my song.
  }
>>

<<
  \new TabStaff \mus
  \new Lyrics \lyricsto "melody" {
    This is my song.
  }
>>

[image of music]

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 Bottom contexts of the current type, typically Voice or TabVoice (see Bottom-level contexts – voices). These new Bottom contexts are created implicitly and are given the fixed names "1", "2", etc.

The first example could be typeset as follows:

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

[image of music]

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.

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

[image of music]

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

[image of music]

When a different voice entry order is desired, the command \voices may be convenient:

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

[image of music]

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

Identical rhythms

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

\new Voice <<
  \relative { e''4 f8 d e16 f g8 d4 }
  \relative { c''4 d8 b c16 d e8 b4 }
>>

[image of music]

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:

<<
  \relative { \voiceOneStyle d''4 c2 b4 }
  \\
  \relative { \voiceTwoStyle e'2 e }
  \\
  \relative { \voiceThreeStyle b2. c4 }
  \\
  \relative { \voiceFourStyle g'2 g }
>>

[image of music]

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.

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

[image of music]

Notes with different note heads may be merged as shown below. In this example the note heads on beat 1 of bar 1 are now merged:

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

[image of music]

Quarter and half notes are not merged in this way, since it would be difficult to tell them apart.

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

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

[image of music]

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.

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

[image of music]

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 {
  %% abbreviated entry
  <<
    { f''2  }  % 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
  >>
}

[image of music]

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
  <<
    \new Voice  {
      \voiceOne
      a4. a8
      e'4 e4. e8
      f4 d4. c8
    }
    \new Voice {
      \voiceTwo
      d,2
      d4 cis2
      d4 bes2
    }
    \new Voice {
      \voiceThree
      f'2
      bes4 a2
      a4 s2
    }
    \new Voice {
      \voiceFive
      s2
      g4 g2
      f4 f2
    }
  >>
}

[image of music]

Moving dotted notes in polyphony

When a dotted note in the upper voice is moved to avoid a collision with a note in another voice, the default is to move the upper note to the right. This behaviour can be over-ridden by using the prefer-dotted-right property of NoteCollision.

\new Staff \relative c' <<
  {
    f2. f4
    \override Staff.NoteCollision.prefer-dotted-right = ##f
    f2. f4
    \override Staff.NoteCollision.prefer-dotted-right = ##t
    f2. f4
  }
  \\
  { e4 e e e e e e e e e e e }
>>

[image of music]

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

[image of music]

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.

Known issues and warnings

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

\mergeDifferentlyHeadedOn
<< \relative { c'16 a' b a } \\ \relative { c'2 } >>
\override NoteColumn.ignore-collision = ##t
<< \relative { c'16 a' b a } \\ \relative { c'2 } >>

[image of music]


Merging rests

When using multiple voices it is common to merge rests which occur in both parts. This can be accomplished using Merge_rests_engraver.

voiceA = \relative { d''4 r d2 | R1 | }
voiceB = \relative { fis'4 r g2 | R1 | }
\score {
  <<
    \new Staff \with {
      instrumentName = "unmerged"
    }
    <<
      \new Voice { \voiceOne \voiceA }
      \new Voice { \voiceTwo \voiceB }
    >>
    \new Staff \with {
      instrumentName = "merged"
      \consists Merge_rests_engraver
    }
    <<
      \new Voice { \voiceOne \voiceA }
      \new Voice { \voiceTwo \voiceB }
    >>
  >>
}

[image of music]

Setting the context property suspendRestMerging to #t allows for turning off rest merging temporarily.


Automatic part combining

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

The syntax for automatic part combining is:

\partCombine musicexpr1 musicexpr2

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

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

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

<<
  \new Staff \instrumentOne
  \new Staff \instrumentTwo
  \new Staff \partCombine \instrumentOne \instrumentTwo
>>

[image of music]

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

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

instrumentOne = \relative {
  a4 b c d |
  e f g a |
  b c d e |
}

instrumentTwo = \relative {
  c'4 c c c |
  c c c c |
  c c c c |
}

<<
  \new Staff \partCombine \instrumentOne \instrumentTwo
  \new Staff \partCombine #'(2 . 3) \instrumentOne \instrumentTwo
>>

[image of music]

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

\partCombine
  \relative … musicexpr1
  \relative … musicexpr2

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

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

instrumentOne = \relative c' {
  \partCombineApart c2^"apart" e |
  \partCombineAutomatic e2^"auto" e |
  \partCombineChords e'2^"chord" e |
  \partCombineAutomatic c2^"auto" c |
  \partCombineApart c2^"apart"
    \once \partCombineChords e^"chord once" |
  c2 c |
}
instrumentTwo = \relative {
  c'2 c |
  e2 e |
  a,2 c |
  c2 c' |
  c2 c |
  c2 c |
}

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

[image of music]

Using \partCombine with lyrics

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

Selected Snippets

Combining two parts on the same staff

The part combiner tool ( \partCombine command ) allows the combination of several different parts on the same staff. Text directions such as “solo” or “a2” are added by default; to remove them, simply set the property printPartCombineTexts to f.

For vocal scores (hymns), there is no need to add “solo/a2” texts, so they should be switched off. However, it might be better not to use it if there are any solos, as they won’t be indicated. In such cases, standard polyphonic notation may be preferable.

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

%% Combining pedal notes with clef changes

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 \with { instrumentName = "Standard polyphony" }

      << \musicUp \\ \musicDown >>

    \new Staff \with {
      instrumentName = "PartCombine without text"
      printPartCombineTexts = ##f
    }

    \partCombine \musicUp \musicDown

    \new Staff \with { instrumentName = "PartCombine with text" }
      \partCombine \musicUp \musicDown
    >>
  \layout {
    indent = 6.0\cm
    \context {
      \Score
      \override SystemStartBar.collapse-height = #30
    }
  }
}

[image of music]

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

[image of music]

See also

Music Glossary: a due, part.

Notation Reference: Writing parts.

Snippets: Simultaneous notes.

Internals Reference: PartCombineMusic, Voice.

Known issues and warnings

All \partCombine… functions can only accept two voices.

\partCombine… functions cannot be placed inside a \tuplet or \relative block.

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

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

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

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

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


Writing music in parallel

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

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

\parallelMusic voiceA,voiceB,voiceC {
  % Bar 1
  r8 g'16 c'' e'' g' c'' e'' r8 g'16 c'' e'' g' c'' e'' |
  r16 e'8.~   4              r16 e'8.~   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.~   4              r16 d'8.~   4              |
  c'2                        c'2                        |

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

[image of music]

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.~ 4        r16 e8.~  4         |
  c2                c                   |

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

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

[image of music]

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

[image of music]

See also

Learning Manual: Organizing pieces with variables.

Snippets: Simultaneous notes.


1.6 Staff notation

[image of music]

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 and referencing contexts.

The basic staff context is Staff:

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

[image of music]

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

[image of music]

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 }

[image of music]

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

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

[image of music]

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

The GregorianTranscriptionStaff context creates a staff to notate modern Gregorian chant. It engraves divisiones as bar lines, but it does not show measure bar lines.

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

[image of music]

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

See also

Music Glossary: staff, staves.

Notation Reference: Creating and referencing contexts, Percussion staves, Showing melody rhythms, Default tablatures, Predefined 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-staff 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 \relative { c''1 c }
  \new Staff \relative { c''1 c }
>>

[image of music]

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

\new StaffGroup <<
  \new Staff \relative { c''1 c }
  \new Staff \relative { c''1 c }
>>

[image of music]

In a ChoirStaff, the group starts with a bracket, but bar lines are not connected.

\new ChoirStaff <<
  \new Staff \relative { c''1 c }
  \new Staff \relative { c''1 c }
>>

[image of music]

In a GrandStaff, the group begins with a brace, and bar lines are connected between the staves.

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

[image of music]

The PianoStaff is identical to a GrandStaff, except that it supports printing the instrument name directly. For details, see Instrument names.

\new PianoStaff \with { instrumentName = "Piano" }
<<
  \new Staff \relative { c''1 c }
  \new Staff \relative { \clef bass c1 c }
>>

[image of music]

The OneStaff is a staff group that places separate contexts in the same vertical alignment. This example shows three staves sharing the same space. Here, the Time_signature_engraver has been moved from the staves to the OneStaff context to prevent it from being repeated for each staff.

\layout {
  \context {
    \OneStaff
    \consists Time_signature_engraver
  }
  \context {
    \Staff
    \remove Time_signature_engraver
  }
  \context {
    \DrumStaff
    \remove Time_signature_engraver
  }
}

\new OneStaff {
  \new Staff {
    c'4 4 d'4 4 e'2 d'
  }
  \drums {
    hihat4 hh bassdrum bd
  }
  \new Staff {
    c'4 4 d'4 4 e'2 d'
  }
}

[image of music]

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

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

Selected Snippets

Use square bracket at the start of a staff group

The system start delimiter SystemStartSquare can be used by setting it explicitly in a StaffGroup or ChoirStaff context.

\score {
  \new StaffGroup { <<
  \set StaffGroup.systemStartDelimiter = #'SystemStartSquare
    \new Staff { c'4 d' e' f' }
    \new Staff { c'4 d' e' f' }
  >> }
}

[image of music]

Display bracket with only one staff in a system

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

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

\score {
  \new StaffGroup <<
    % Must be lower than the actual number of staff lines
    \override StaffGroup.SystemStartBracket.collapse-height = #4
    \override Score.SystemStartBar.collapse-height = #4
    \new Staff {
      c'1
    }
  >>
}
\score {
  \new PianoStaff <<
    \override PianoStaff.SystemStartBrace.collapse-height = #4
    \override Score.SystemStartBar.collapse-height = #4
    \new Staff {
      c'1
    }
  >>
}

[image of music]

Mensurstriche layout (bar lines between the staves)

Mensurstriche, bar lines between but not through staves, can be printed by setting measureBarType to "-span|" and using a grouping context that allows span bars, such as StaffGroup.

\layout {
  \context {
    \Staff
    measureBarType = "-span|"
  }
}

music = \fixed c'' {
  c1
  d2 \section e2
  f1 \fine
}

\new StaffGroup <<
  \new Staff \music
  \new Staff \music
>>

[image of music]

See also

Music Glossary: brace, bracket, grand staff, mensurstrich.

Notation Reference: Instrument names, Defining new contexts.

Snippets: Staff notation.

Internals Reference: Staff, StaffGroup, ChoirStaff, GrandStaff, PianoStaff, OneStaff, SystemStartBar, SystemStartBrace, SystemStartBracket, SystemStartSquare.


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 \relative { c''2 c | c2 c }
  \new StaffGroup <<
    \new Staff \relative { g'2 g | g2 g }
    \new StaffGroup \with {
      systemStartDelimiter = #'SystemStartSquare
    }
    <<
      \new Staff \relative { e'2 e | e2 e }
      \new Staff \relative { c'2 c | c2 c }
    >>
  >>
>>

[image of music]

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'' <<
  \override StaffGroup.SystemStartSquare.collapse-height = #4
  \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 }
>>

[image of music]

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''4 c c c
          \break
          c4 c c c
        }
      }
      \new Staff {
        \relative {
          c''4 c c c
          \break
          c4 c c c
        }
      }
    >>
  }
  \paper {
    system-separator-markup = \slashSeparator
    tagline = ##f
  }
}

[image of music]

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 \stopStaff and \startStaff commands can be used to stop or (re)start the staff lines respectively, from being printed at any point witin a score.

\relative {
  \stopStaff f''4 d \startStaff g, e
  f'4 d \stopStaff g, e
  f'4 d \startStaff g, e
}

[image of music]

Predefined commands

\startStaff, \stopStaff.

The lines of a staff belong to the StaffSymbol grob (including ledger lines) and can be modified using StaffSymbol properties, but these modifications must be made before the staff is (re)started.

The number of staff lines can be altered:

\relative {
  f''4 d \stopStaff
  \override Staff.StaffSymbol.line-count = #2
  \startStaff g, e |

  f'4 d \stopStaff
  \revert Staff.StaffSymbol.line-count
  \startStaff g, e |
}

[image of music]

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

\relative {
  f''4 d \stopStaff
  \override Staff.StaffSymbol.line-positions = #'(1 3 5 -1 -3)
  \startStaff g, e |
  f'4 d \stopStaff
  \override Staff.StaffSymbol.line-positions = #'(8 6.5 -6 -8 -0.5)
  \startStaff g, e |
}

[image of music]

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

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

\new Staff \with {
  \override StaffSymbol.thickness = #3
} \relative {
  f''4 d g, e
}

[image of music]

It is also possible to set ledger line thickness independently of staff lines.

\new Staff \with {
  \override StaffSymbol.thickness = #2
  \override StaffSymbol.ledger-line-thickness = #'(0.5 . 0.4)
} \relative {
  f'''4 a, a,, f
}

[image of music]

The first value is multiplied by the staff line thickness, the second by the staff space and then the two values are added together to give the new thickness of the ledger line.

The vertical positions of ledger lines can be altered,

\new Staff \with {
  \override StaffSymbol.ledger-positions = #'(-3 -2 -1 2 5 6)
} \relative {
  f'''4 a, a,, f
}

[image of music]

Additional ledger lines can be made to appear above or below note heads depending on the current position relative to other note heads that also have their own ledger lines.

\new Staff \with {
  \override StaffSymbol.ledger-extra = #4
} \relative {
  f'''4 a, d, f,
}

[image of music]

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

\relative d' {
  \override Staff.StaffSymbol.line-positions = #'(-8 0 2 4)
  d4 e f g
  \stopStaff
  \startStaff
  \override Staff.StaffSymbol.ledger-positions = #'(-8 -6 (-4 -2) 0)
  d4 e f g
}

[image of music]

The distance between staff lines can be altered. This affects ledger line spacing as well.

\new Staff \with {
  \override StaffSymbol.staff-space = #1.5
} \relative {
  f'''4 d, g, e,
}

[image of music]

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
}
\relative { a4 e' f b | d1 }

[image of music]

Selected Snippets

Making some staff lines thicker than the others

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

{
  \override Staff.StaffSymbol.line-positions =
    #'(-4 -2 -0.2 0 0.2 2 4)
  d'4 e' f' g'
}

[image of music]

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''4 b d c
  <<
    { c4 b d c }
    \new Staff { e4 d f e }
  >>
  c4 b c2
}

[image of music]

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''4 b d c
  <<
    { c4 b d c }

    \new Staff \with {
      \remove Time_signature_engraver
      alignAboveContext = "main"
      \magnifyStaff #2/3
      firstClef = ##f
    }
    { e4 d f e }
  >>
  c4 b c2
}

[image of music]

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
    \hide Clef
    \magnifyStaff #2/3
  }
  { \stopStaff s1*6 }

  \new Staff \relative {
    c'4 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
  }
>>

[image of music]

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

<<
  \new Staff = "ossia" \with {
    \remove Time_signature_engraver
    \hide Clef
    \magnifyStaff #2/3
    \RemoveAllEmptyStaves
  } \relative {
    R1*3
    c''4 e8 d c2
  }
  \new Staff \relative {
    c'4 b c2
    e4 f e2
    g4 a g2 \break
    c4 b c2
    g4 a g2
    e4 d c2
  }
>>

[image of music]

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

[image of music]

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 { a''8 f e16 d c b a2 }

[image of music]

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

\layout {
  \context {
    \Staff
    \RemoveEmptyStaves
  }
}

\relative <<
  \new Staff {
    e'4 f g a \break
    b1 \break
    a4 b c2
  }
  \new Staff {
    c,4 d e f \break
    R1 \break
    f4 g c,2
  }
>>

[image of music]

A staff is considered empty when it contains only multi-measure rests, rests, skips, or a combination of these elements. All other musical objects (that cause a staff not to be considered as empty) are listed in the keepAliveInterfaces context property, as initially set in the ‘ly/engraver-init.ly’ file.

\RemoveEmptyStaves and \RemoveAllEmptyStaves are both predefined shortcuts that set such properties as remove-empty and remove-first for the VerticalAxisGroup object, as explained in Context modification identifiers.

The Keep_alive_together_engraver allows groups of staves to only be removed together and not individually. By default, it is part of the PianoStaff context: a piano part will only be hidden when both of its staves are empty. Similarly, a common engraving practice in orchestral scores is to remove empty groups of staves rather than individual staves; that can be achieved by adding the Keep_alive_together_engraver to the relevant staff grouping context, as explained Modifying context plug-ins (see Grouping staves for the context names).

\layout {
  \context {
    \StaffGroup
    \RemoveEmptyStaves
    \consists Keep_alive_together_engraver
  }
}

In the following example, staves devoted to wind instruments are removed in the second system; however, the double bass is not, because it is part of the larger group of fretted strings, which is playing.

[image of music]

The Keep_alive_together_engraver internally uses the remove-layer property of a staff’s VerticalAxisGroup to decide whether to print it or not when it is considered empty. That property may also be set directly, in which case it acts as a priority index: values closest to zero take precedence over higher numbers, and thus staves whose remove-layer is higher will be masked in favor of staves of a lower number.

This is particularly useful for ‘divisi’ staves, where some individual parts (see Writing parts) occasionally need to be expanded to more than one staff. In the following example, two parts are routed to three staves; however, all three staves are never printed at the same time:

Such substitutions are applied not just to notes, chords and other musical events that occur immediately after the new setting, but to the whole system where it takes place.

\layout {
  short-indent = 2\cm
  indent = 3\cm
  \context {
    \Staff
    keepAliveInterfaces = #'()
  }
}

violI = {
  \repeat unfold 24 { d'4 }
  \once \unset Staff.keepAliveInterfaces
  <d' g''>2
  \repeat unfold 14 { d'4 }
  \bar "|."
}

violII = {
  \repeat unfold 24 { g4 }
  <g d'>2
  \repeat unfold 14 { g4 }
  \bar "|."
}

\new StaffGroup \with { \consists Keep_alive_together_engraver } <<
  \new Staff \with {
    instrumentName = "Violins"
    shortInstrumentName = "V I & II"
    \override VerticalAxisGroup.remove-layer = 2
  } <<  \violI \\ \violII  >>
  \new Staff \with {
    instrumentName = "Violin I"
    shortInstrumentName = "V I"
    \RemoveAllEmptyStaves
    \override VerticalAxisGroup.remove-layer = 1
  } \violI
  \new Staff \with {
    instrumentName = "Violin II"
    shortInstrumentName = "V II"
    \RemoveAllEmptyStaves
    \override VerticalAxisGroup.remove-layer = 1
  } \violII
>>

[image of music]

\RemoveAllEmptyStaves can also be used to create ossia sections for a staff. For details, see Ossia staves.

Predefined commands

\RemoveEmptyStaves, \RemoveAllEmptyStaves.

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, Context modification identifiers, Grouping staves, Modifying context plug-ins.

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

Snippets: Staff notation.

Internals Reference: ChordNames, FiguredBass, Lyrics, Staff, VerticalAxisGroup, Staff_symbol_engraver, Axis_group_engraver, Keep_alive_together_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:

\omit StaffSymbol
\override NoteHead.no-ledgers = ##t

For the Known issues and warnings associated with \RemoveEmptyStaves see Changing context default settings.


1.6.3 Writing parts

This section explains how to prepare parts for orchestral or ensemble music, which often requires to insert instrument names into the score. Methods to quote other voices and to format cue notes are also described, as well as a way to contract multiple consecutive empty measures in individual parts.

Aditionally, a method for printing divisi staves, sometimes used in individual or desk parts, can be found in Hiding staves.


Instrument names

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

\new Staff \with {
  instrumentName = "Violin "
  shortInstrumentName = "Vln. "
} \relative {
  c'4.. g'16 c4.. g'16 \break | c1 |
}

[image of music]

\markup can be used to create more complex instrument names:

\new Staff \with {
  instrumentName = \markup {
    \column { "Clarinetti"
      \line { "in B" \smaller \flat }
    }
  }
} \relative {
  c''4 c,16 d e f g2
}

[image of music]

When two or more staff contexts are grouped together, the instrument names and short instrument names are centered by default. To center multi-line instrument names, \center-column must be used:

<<
  \new Staff \with {
    instrumentName = "Flute"
  } \relative {
    f''2 g4 f
}
  \new Staff \with {
    instrumentName = \markup {
      \center-column { "Clarinet"
        \line { "in B" \smaller \flat }
      }
    }
  } \relative { c''4 b c2 }
>>

[image of music]

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.

<<
  \new Staff \with {
    instrumentName = "Alto Flute in G"
    shortInstrumentName = "Flt."
  } \relative {
    f''2 g4 f \break
    g4 f g2
  }
  \new Staff \with {
    instrumentName = "Clarinet"
    shortInstrumentName = "Clar."
  } \relative {
    c''4 b c2 \break
    c2 b4 c
  }
>>

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

[image of music]

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

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

prepPiccolo = <>^\markup \italic { muta in Piccolo }

prepFlute = <>^\markup \italic { muta in Flauto }

setPiccolo = {
  <>^\markup \bold { Piccolo }
  \transposition c''
}

setFlute = {
  <>^\markup \bold { Flute }
  \transposition c'
}

\new Staff \with {
  instrumentName = "Flute"
  shortInstrumentName = "Flt."
}
\relative {
  g'1 g g g \break
  g1 g \prepPiccolo R R \break
  \set Staff.instrumentName = "Piccolo"
  \set Staff.shortInstrumentName = "Picc."
  \setPiccolo
  g1 g g g \break
  g1 g \prepFlute R R \break
  \set Staff.instrumentName = "Flute"
  \set Staff.shortInstrumentName = "Flt."
  \setFlute
  g1 g g g
}

[image of music]

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 reenter 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 {
  a'4 gis g gis | b4^"quoted" r8 ais\p a4( f)
}

oboeNotes = \relative {
  c''4 cis c b \quoteDuring "flute" { s1 }
}

\addQuote "flute" { \fluteNotes }

\score {
  <<
    \new Staff \with { instrumentName = "Flute" } \fluteNotes
    \new Staff \with { instrumentName = "Oboe" } \oboeNotes
  >>
}

[image of music]

If the music expression used in \quoteDuring contains notes instead of spacer or multi-measure rests then the quote will appear as polyphony and may produce unexpected results.

fluteNotes = \relative {
  a'4 gis g gis | b4^"quoted" r8 ais\p a4( f)
}

oboeNotes = \relative {
  c''4 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
  >>
}

[image of music]

If an \unfoldRepeats command in a music expression is required to be printed when using \quoteDuring, then it too must also contain its own \unfoldRepeats command;

fluteNotes = \relative {
  \repeat volta 2 { a'4 gis g gis }
}

oboeNotesDW = \relative {
  \repeat volta 2 \quoteDuring "incorrect" { s1 }
}

oboeNotesW = \relative {
  \repeat volta 2 \quoteDuring "correct" { s1 }
}


\addQuote "incorrect" { \fluteNotes }

\addQuote "correct" { \unfoldRepeats \fluteNotes }

\score {
  \unfoldRepeats
  <<
    \new Staff \with { instrumentName = "Flute" }
    \fluteNotes
    \new Staff \with { instrumentName = "Oboe (incorrect)" }
    \oboeNotesDW
    \new Staff \with { instrumentName = "Oboe (correct)" }
    \oboeNotesW
  >>
}

[image of music]

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''4 cis c b \quoteDuring "clarinet" { s1 }
}

\addQuote "clarinet" { \clarinetNotes }


\score {
  <<
    \new Staff \with { instrumentName = "Clarinet" } \clarinetNotes
    \new Staff \with { instrumentName = "Oboe" } \oboeNotes
  >>
}

[image of music]

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 {
  a'2 g2 |
  b4\<^"quoted" r8 ais a4\f( c->)
 }

oboeNotes = \relative {
  c''2. 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
  >>
 }

[image of music]

Quotes can also be tagged, see Using tags.

See also

Notation Reference: Instrument transpositions, Using tags.

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

Snippets: Staff notation.

Internals Reference: Music classes, QuoteMusic, Voice.

Known issues and warnings

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


Formatting cue notes

The simplest way to format cue notes is to explicitly create a CueVoice context within the part.

\relative {
  R1
  <<
    { e'2\rest r4. e8 }
    \new CueVoice {
      \stemUp d'8^"flute" c d e fis2
    }
  >>
  d,4 r a r
}

[image of music]

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

\relative {
  \clef "bass"
  R1
  <<
    { e'2\rest r4. \cueClefUnset e,8 }
    \new CueVoice {
      \cueClef "treble" \stemUp d''8^"flute" c d e fis2
    }
  >>
  d,,4 r a r
}

[image of music]

The \cueClef and \cueClefUnset command can also be used without a CueVoice if required.

\relative {
  \clef "bass"
  R1
  \cueClef "treble"
  d''8^"flute" c d e fis2
  \cueClefUnset
  d,,4 r a r
}

[image of music]

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

The syntax is:

\cueDuring quotename #direction music

and

\cueDuringWithClef quotename #direction #clef music

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

fluteNotes = \relative {
  r2. c''4 | d8 c d e fis2 | g2 d |
}

oboeNotes = \relative c'' {
  R1
  <>^\markup \tiny { flute }
  \cueDuring "flute" #UP { R1 }
  g2 c,
}

\addQuote "flute" { \fluteNotes }

\new Staff {
  \oboeNotes
}

[image of music]

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

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

oboeNotes = \relative {
  r2 r8 d''16(\f f e g f a)
  g8 g16 g g2.
}
\addQuote "oboe" { \oboeNotes }

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

[image of music]

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

fluteNotes = \relative {
  r2. c''4 d8 c d e fis2 g2 d2
}

bassoonNotes = \relative c {
  \clef bass
  R1
  \clef treble
  <>^\markup \tiny { flute }
  \cueDuring "flute" #UP { R1 }
  \clef bass
  g4. b8 d2
}

\addQuote "flute" { \fluteNotes }

\new Staff {
  \bassoonNotes
}

[image of music]

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

fluteNotes = \relative {
  r2. c''4 d8 c d e fis2 g2 d2
}

bassoonNotes = \relative c {
  \clef bass
  R1
  <>^\markup { \tiny "flute" }
  \cueDuringWithClef "flute" #UP "treble" { R1 }
  g4. b8 d2
}

\addQuote "flute" { \fluteNotes }

\new Staff {
  \bassoonNotes
}

[image of music]

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

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

piccoloNotes = \relative {
  \clef "treble^8"
  R1
  c'''8 c c e g2
  c4 g g2
}

bassClarinetNotes = \relative c' {
  \key d \major
  \transposition bes,
  d4 r a r
  \transposedCueDuring "piccolo" #UP d { R1 }
  d4 r a r
}

\addQuote "piccolo" { \piccoloNotes }

<<
  \new Staff \piccoloNotes
  \new Staff \bassClarinetNotes
>>

[image of music]

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

fluteNotes = \relative {
  r2. c''4 d8 c d e fis2 g2 d2
}

bassoonNotes = \relative c {
  \clef bass
  R1
  \tag #'part {
    \clef treble
    <>^\markup \tiny { flute }
  }
  \cueDuring "flute" #UP { R1 }
  \tag #'part \clef bass
  g4. b8 d2
}

\addQuote "flute" { \fluteNotes }

\new Staff {
  \bassoonNotes
}

\new StaffGroup <<
  \new Staff {
    \fluteNotes
  }
  \new Staff {
    \removeWithTag #'part { \killCues { \bassoonNotes } }
  }
>>

[image of music]

See also

Notation Reference: Quoting other voices, Instrument transpositions, Instrument names, Clef, Musical cues, Using tags.

Snippets: Staff notation.

Internals Reference: CueVoice, Voice.

Known issues and warnings

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


Compressing empty measures

By default, all measures are printed even if they are empty – which can happen if a rhythmic event (such as notes, rests or invisible rests) is so long as to span several measures. This behavior can be changed by contracting all empty measures into a single one, as illustrated here (the second part of this example, with expanded measures, actually reverts back to the default behavior):

\override Score.BarNumber.break-visibility = ##(#f #t #t)
\time 2/4
\compressEmptyMeasures
c'1 d'1. e'\breve
\bar "||"
\expandEmptyMeasures
c'1 d'1. e'\breve

[image of music]

Although that notation is syntactically correct, it may be confusing from a musical point of view, as illustrated in the previous example; hence the need for measure numbers to be explicitly printed, using the syntax described in Using break-visibility.

Where such a notation may become more useful is when applied to Full measure rests. A multi-measure rest will then 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
\compressEmptyMeasures
r1 | R1*17 | R1*4 |
\expandEmptyMeasures
% Rest measures expanded again
\time 3/4
R2.*2 |

[image of music]

Unlike \compressEmptyMeasures, the music function \compressMMRests will only apply to rests, leaving any other events uncompressed. As a function rather than a property setting, its syntax differs slightly in that it must be followed by a music expression:

\compressMMRests {
  % Rests are compressed...
  R1*7
  % ... but notes can still span multiple measures.
  g'1 a'1*2 d'1
  R1*2
}

[image of music]

All of the commands described in this section actually rely on the skipBars internal property, which is set in the Score context as explained in The \set command.

Predefined commands

\compressEmptyMeasures, \expandEmptyMeasures, \compressMMRests.

Selected Snippets

Numbering single measure rests

Multi measure rests show their length by a number except for single measures. This can be changed by setting restNumberThreshold.

{
  \compressEmptyMeasures
  R1 R1*10 R1*11 \bar "||"
  \set restNumberThreshold = 0
  R1 R1*10 R1*11 \bar "||"
  \set restNumberThreshold = 10
  R1 R1*10 R1*11
}

[image of music]

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'' {
  \compressMMRests {
    R1*2 | R1*5 | R1*9
    \override MultiMeasureRest.expand-limit = #3
    R1*2 | R1*5 | R1*9
  }
}

[image of music]

See also

Notation Reference: Using break-visibility, Full measure rests, The \set command.

Internals Reference: MultiMeasureRest, MultiMeasureRestNumber, MultiMeasureRestScript, MultiMeasureRestText.


1.7 Editorial annotations

[image of music]

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

Note:
For font sizes of text, see Selecting font and font size.
For staff size, see Setting the staff size.
For cue notes, see Formatting cue notes.
For ossia staves, see Ossia staves.

To change the size of the notation without changing the staff size, specify a magnification factor with the \magnifyMusic command:

\new Staff <<
  \new Voice \relative {
    \voiceOne
    <e' e'>4 <f f'>8. <g g'>16 <f f'>8 <e e'>4 r8
  }
  \new Voice \relative {
    \voiceTwo
    \magnifyMusic 0.63 {
      \override Score.SpacingSpanner.spacing-increment = #(* 1.2 0.63)
      r32 c'' a c a c a c r c a c a c a c
      r c a c a c a c a c a c a c a c
    }
  }
>>

[image of music]

The \override in the example above is a bug workaround. See the “Known issues and warnings” at the end of this section.

If a normal sized note head is merged with a smaller one, the size of the smaller note may need to be reset (with ‘\once \normalsize’) so that the stems and accidentals align properly:

\new Staff <<
  \key fis \minor
  \mergeDifferentlyDottedOn
  \new Voice \relative {
    \voiceOne
    \magnifyMusic 0.63 {
      \override Score.SpacingSpanner.spacing-increment =
        #(* 1.2 0.63)

      \once \normalsize cis'32( cis' gis b a fis
        \once \normalsize d d'
      \once \normalsize cis, cis' gis b a gis
        \once \normalsize fis fis'
      \once \normalsize fis, fis' ais, cis b gis
        \once \normalsize eis eis'
      \once \normalsize a, a' bis, d cis b
        \once \normalsize gis gis')
    }
  }
  \new Voice \relative {
    \voiceTwo
    cis'8. d16 cis8. fis16 fis8. eis16 a8. gis16
  }
>>

[image of music]

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

Note: The \magnifyMusic command should not be used when also resizing the staff. See Setting the staff size.

Resizing individual layout objects

An individual layout object can be resized by using the \tweak or \override commands to adjust its font-size property:

\relative {
  % resize a note head
  <f' \tweak font-size -4 b e>-5
  % resize a fingering
  bes-\tweak font-size 0 -3
  % resize an accidental
  \once \override Accidental.font-size = -4 bes!-^
  % resize an articulation
  \once \override Script.font-size = 4 bes!-^
}

[image of music]

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

Understanding the fontSize property

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

\relative {
  \time 3/4
  d''4---5 c8( b a g) |
  \set fontSize = -6
  e'4-- c!8-4( b a g) |
  \set fontSize = 0
  fis4---3 e8( d) fis4 |
  g2.
}

[image of music]

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

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

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

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

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

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

% the default font-size for NoteHead is 0
% the default font-size for Fingering is -5
c''4-3

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

\override Fingering.font-size = 0
% the effective font size for Fingering is now -3
c''4-3

[image of music]

The following shorthand commands are also available:

CommandEquivalent toRelative size
\teeny\set fontSize = -371%
\tiny\set fontSize = -279%
\small\set fontSize = -189%
\normalsize\set fontSize = 0100%
\large\set fontSize = 1112%
\huge\set fontSize = 2126%
\relative c'' {
  \teeny
  c4.-> d8---3
  \tiny
  c4.-> d8---3
  \small
  c4.-> d8---3
  \normalsize
  c4.-> d8---3
  \large
  c4.-> d8---3
  \huge
  c4.-> d8---3
}

[image of music]

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

Predefined commands

\magnifyMusic, \teeny, \tiny, \small, \normalsize, \large, \huge.

See also

Notation Reference: Selecting font and font size, Setting the staff size, Formatting cue notes, Ossia staves.

Installed Files: ‘ly/music-functions-init.ly’, ‘ly/property-init.ly’.

Snippets: Editorial annotations.

Internals Reference: font-interface.

Known issues and warnings

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

\magnifyMusic mag {
  \newSpacingSection
  \override Score.SpacingSpanner.spacing-increment = #(* 1.2 mag)
  [music]
  \newSpacingSection
  \revert Score.SpacingSpanner.spacing-increment
}

Fingering instructions

Fingering instructions can be entered using ‘note-digit’:

\relative { c''4-1 d-2 f-4 e-3 }

[image of music]

Markup texts or strings may be used for finger changes.

\relative {
  c''4-1 d-2 f\finger \markup \tied-lyric "4~3" c\finger "2 - 3"
}

[image of music]

A thumb fingering can be added (e.g., cello music) to indicate that a note should be played with the thumb.

\relative { <a'_\thumb a'-3>2 <b_\thumb b'-3> }

[image of music]

Fingerings for chords can also be added to individual notes by adding them after the pitches.

\relative {
  <c''-1 e-2 g-3 b-5>2 <d-1 f-2 a-3 c-5>
}

[image of music]

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, it must be used within a chord construct <>, even for single notes. Orientation for string numbers and right-hand fingerings may be set in a similar way.

\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
  \set stringNumberOrientations = #'(up left down)
  <f\3 a\2 c\1>1
  \set strokeFingerOrientations = #'(down right up)
  <c\rightHandFinger #1 e\rightHandFinger #2 c'\rightHandFinger #4 >
}

[image of music]

Allowing fingerings to be printed inside the staff

By default, vertically oriented fingerings are positioned outside the staff; that behavior, however, may be disabled. Attention needs to be paid to situations where fingerings and stems are in the same direction: by default, fingerings will avoid only beamed stems. That setting can be changed to avoid no stems or all stems; the following example demonstrates these two options, as well as how to go back to the default behavior.

\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
  a8[-1 b]-2 g-0 r
  \override Fingering.add-stem-support = ##f
  a[-1 b]-2 g-0 r
  \override Fingering.add-stem-support = ##t
  a[-1 b]-2 g-0 r
  \override Fingering.add-stem-support = #only-if-beamed
  a[-1 b]-2 g-0 r
}

[image of music]

See also

Notation Reference: Direction and placement.

Snippets: Editorial annotations.

Internals Reference: FingeringEvent, fingering-event, Fingering_engraver, New_fingering_engraver, Fingering.


Gliding fingers

For stringed instruments a gliding finger is often indicated by a line connecting the same finger to be used for notes played at different positions on the same string. This line is initiated with \\glide entered before a Fingering and ends with the next occurence of the same finger. The line may be printed in various styles.

mus = {
  \set fingeringOrientations = #'(right)
  <a'\glide-1>2.
  \set fingeringOrientations = #'(left)
  <d'-1>4
}

{
  <>^"line"
  \mus
  <>^"stub-left"
  \override FingerGlideSpanner.style = #'stub-left
  \mus
  <>^"stub-right"
  \override FingerGlideSpanner.style = #'stub-right
  \mus
  <>^"stub-both"
  \override FingerGlideSpanner.style = #'stub-both
  \mus
  <>^"dashed-line"
  \override  FingerGlideSpanner.style = #'dashed-line
  \mus
  \break
  <>^"dotted-line"
  \override FingerGlideSpanner.style = #'dotted-line
  \mus
  <>^"bow"
  \override FingerGlideSpanner.style = #'bow
  \mus
  <>^"trill"
  \override FingerGlideSpanner.style = #'trill
  \mus
  <>^"zigzag"
  \override FingerGlideSpanner.style = #'zigzag
  \mus
}

[image of music]

If style is set to 'bow the direction of the bow may be adjusted using direction modifiers.

{
  \override FingerGlideSpanner.style = #'bow
  \set fingeringOrientations = #'(down)
  <b\glide-1>4 <d'-1>
  \set fingeringOrientations = #'(up)
  <e''\glide-2> <c''-2>

  \set fingeringOrientations = #'(down)
  <b^\glide-1>4 <d'-1>
  \set fingeringOrientations = #'(up)
  <e''^\glide-2> <c''-2>

  \set fingeringOrientations = #'(down)
  <b_\glide-1>4 <d'-1>
  \set fingeringOrientations = #'(up)
  <e''_\glide-2> <c''-2>
}

[image of music]

If the Finger_glide_engraver is moved to Staff context Fingering grobs from different Voice contexts may be connected.

\score {
  \new Staff <<
    \new Voice {
      \voiceOne
      \set fingeringOrientations = #'(right)
      <e''-3>2
      \set fingeringOrientations = #'(left)
      <d''-\tweak bound-details.left.padding #2.5 \glide-2>
      <c''-2>
      \bar "||"
    }
    \new Voice {
      \voiceTwo
      \set fingeringOrientations = #'(right)
      <c''\glide-2>
      \set fingeringOrientations = #'(left)
      <b'-\tweak bound-details.left.padding #2.5 \glide-4>
      <a'-4>
    }
  >>
  \layout {
    ragged-right = ##f
    \context {
      \Voice
      \remove Finger_glide_engraver
    }
    \context {
      \Staff
      \consists Finger_glide_engraver
    }
  }
}

[image of music]

See also

Notation Reference: Direction and placement.

Internals Reference: FingeringGlideEvent, fingering-glide-event, Finger_glide_engraver, finger-glide-interface, FingerGlideSpanner.

Known issues and warnings

Multiple glides with the same finger are not supported and lead to unexpected results. A workaround is to use different fingers and to use \tweak text.

{
    \clef "G_8"
    <a\glide-1 cis'\glide-1>2 <bes-1 d'-1>
    <a\glide-1 cis'\glide-\tweak text "1"-2>2
    <bes-1 d'-\tweak text "1"-2>
}

[image of music]


Hidden notes

Hidden (or invisible or transparent) notes can be useful in preparing theory or composition exercises.

\relative {
  c''4 d
  \hideNotes
  e4 f
  \unHideNotes
  g a
  \hideNotes
  b
  \unHideNotes
  c
}

[image of music]

Note heads, stems, and flags, and rests are invisible. Beams are invisible if they start on a hidden note. Objects that are attached to invisible notes are still visible.

\relative c'' {
  e8(\p f g a)--
  \hideNotes
  e8(\p f g a)--
}

[image of music]

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
c''4 c''
\override NoteHead.color = #(x11-color 'SlateGrey)
d''
\override Stem.color = "deepskyblue"
e''

[image of music]

In addition to a limited set of simple colors available as predefined variables (see ‘Normal colors’ in List of colors), any color may be entered as a string. That string may be either a CSS-style predefined color name, or a hexadecimal color code prefixed by the # character (inside the double quotes):

\override NoteHead.color = "lightsalmon"
\override Flag.color = "#E30074"
\override Beam.color = "#5e45ad"
\override Rest.color = "#3058"
g'8 \huge r4 a'16 f'

[image of music]

If that color code includes an alpha channel for semi-transparency, by using an eight-character code "#RRGGBBAA" or its shorthand form "#RGBA", it will be used in SVG output but not in PostScript/PDF output. In the previous example, the rest can be seen through only if the code is compiled with the SVG backend, as explained in Alternative output formats.

In a different way, the full range of colors defined for X11 can be accessed by using the Scheme function x11-color. That function takes one argument, which can be a symbol, such as 'DarkSeaGreen4, or a string, such as "DarkSeaGreen4". The first form is quicker to write and slightly more efficient; however, the second form also makes it possible to specify X11 colors as multiple words: in this instance, "dark sea green 4".

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

\new Staff \with {
  instrumentName = \markup {
    \with-color #(x11-color 'SlateGrey) "Clarinet"
    }
  }
  \relative c'' {
  \override Staff.StaffSymbol.color = #(x11-color 'SlateBlue2)
  gis8 a
  \override Beam.color = #(x11-color "medium turquoise")
  gis a
  \override Accidental.color = #(x11-color 'orange)
  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
}

[image of music]

LilyPond also supports a set of eight color names that is unambiguous to both color-blind and non-color-blind people. Use universal-color to access them.

\markup \with-color #(universal-color 'vermillion) vermillion

[image of music]

Exact RGB colors can be specified using the Scheme function rgb-color. This function takes three arguments used respectively for the red, green and blue channels, and an optional alpha number for semi-transparency. (All values must be numbers from 0 to 1.) Again, transparency is only supported in SVG output; for example, in the following fragment the staff’s clef can be seen through when rendered in SVG.

\new Staff \with {
    instrumentName = \markup {
      \with-color #(x11-color 'red) "Clarinet"
      }
    \override Clef.color = #(rgb-color 0 0 0 0.5)
  }
\relative c'' {
  \override Staff.StaffSymbol.color = #(x11-color 'SlateBlue2)
  \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
}

[image of music]

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 CSS colors are recommended, as detailed in List of colors.

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


Staff highlights

For analytical or pedagogical purposes, it may be useful to “highlight” musical passages, for example in order to show local tonality. This can be done using the \staffHighlight command, which expects a color. For all ways to enter colors, see Coloring objects. The highlight is terminated using \stopStaffHighlight.

\relative {
  \time 2/4
  c'4 4
  \staffHighlight "lightsteelblue"
  g'8( fis g4)-.
  \stopStaffHighlight
  c2
}

[image of music]

If there are consecutive highlights, it is not necessary to write \stopStaffHighlight, as \staffHighlight also implicitly terminates the current highlight, if any. Similarly, it is not necessary to add \stopStaffHighlight at the end of the piece. This is particularly handy if every measure is to be highlighted.

\relative {
  \time 2/4
  \staffHighlight "lightpink"
  c'4 4
  \staffHighlight "lightsteelblue"
  g'8( fis g4)-.
  \staffHighlight "lightpink"
  c2
}

[image of music]

By default, staves are highlighted separately.

music = {
  \time 2/4
  \staffHighlight "lightpink"
  c'4 4
  \staffHighlight "lightsteelblue"
  g'8( fis g4)-.
  \staffHighlight "lightpink"
  c2
}

<<
  \new Staff \music
  \new Staff \music
>>

[image of music]

However, several staves can be highlighted together by moving Staff_highlight_engraver to a higher context than Staff (or RhythmicStaff, or similar). This is done using the \consists and \remove commands; See Modifying context plug-ins for more information. For example, if the engraver is moved to Score, the highlights are shared by all staves.

\layout {
  \context {
    \Staff
    \remove Staff_highlight_engraver
  }
  \context {
    \Score
    \consists Staff_highlight_engraver
  }
}

music = {
  \time 2/4
  \staffHighlight "lightpink"
  c'4 4
  \staffHighlight "lightsteelblue"
  g'8( fis g4)-.
  \staffHighlight "lightpink"
  c2
}

<<
  \new Staff \music
  \new Staff \music
>>

[image of music]

Staff_highlight_engraver may also be moved to intermediate contexts such as StaffGroup.

music = {
  \time 2/4
  \staffHighlight "lightpink"
  c'4 4
  \staffHighlight "lightsteelblue"
  g'8( fis g4)-.
  \staffHighlight "lightpink"
  c2
}

<<
  \new StaffGroup \with { \consists Staff_highlight_engraver } <<
    \new Staff \with { \remove Staff_highlight_engraver } \music
    \new Staff \with { \remove Staff_highlight_engraver } \music
  >>
  \new Staff \music
>>

[image of music]

The StaffHighlight.shorten-pair property may be used to tweak the horizontal start and end of the highlight span.

{
  c'1
  \once \override Staff.StaffHighlight.shorten-pair = #'(1.0 . 1.0)
  \staffHighlight lightsteelblue
  c'1
}

[image of music]

Predefined commands

\staffHighlight, \stopStaffHighlight.

See also

Notation Reference: Coloring objects, Modifying context plug-ins.

Internals Reference: StaffHighlight, staff-highlight-interface, Staff_highlight_engraver, StaffHighlightEvent, staff-highlight-event.

Known issues and warnings

The behavior of highlights may not be what is expected at start repeat bar lines. The shorten-pair property demonstrated above can be used to work around this issue.

{
  \staffHighlight "lightsteelblue"
  c'1
  \stopStaffHighlight
  \repeat volta 2 { c'1 }
  c'1
}

[image of music]


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.

\relative {
  c''2 \parenthesize d
  c2 \parenthesize <c e g>
  c2 <c \parenthesize e g>
}

[image of music]

Non-note objects may be parenthesized as well. For articulations, a hyphen is needed before the \parenthesize command.

\relative {
  c''2-\parenthesize -. d
  c2 \parenthesize r
}

[image of music]

When \parenthesize applies to a chord, all of its notes are enclosed in the parentheses.

\relative c' {
  \parenthesize <e f>
}

[image of music]

To parenthesize only certain notes in a chord, use a parallel music construct << … >>.

\new Voice \relative c {
  <<
    { \tweak Parentheses.font-size 0 \parenthesize <ces des> }
    { \parenthesize ees' }
    { \tweak Parentheses.font-size -2 \parenthesize <c' e> }
  >>
}

[image of music]

A second form of the \parenthesize command involves a grob path: either \parenthesize ContextName.GrobName or just \parenthesize GrobName (the latter implying the bottommost context, typically Voice). This should be added before the musical moment, like a \once \override. This form makes it possible to parenthesize grobs that are only caused indirectly by events.

\new Staff \relative <<
  {
    \parenthesize NoteHead
    c'1
  }
  \new CueVoice {
    s2
    \voiceOne
    \once \override Staff.Parentheses.font-size = 3
    \parenthesize Staff.CueClef
    \cueClef treble
    e'8 f a g
  }
>>

[image of music]

See also

Snippets: Editorial annotations.

Internals Reference: Parenthesis_engraver, Parentheses, parentheses-interface.

Known issues and warnings

Currently, the font-size property of the Parentheses grob has to be adjusted manually to obtain correctly sized parentheses on chords and some other objects.


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
}

[image of music]

Automatically changing the stem direction of the middle note based on the melody

LilyPond can alter the stem direction of the middle note on a staff so that it follows the melody, by adding the Melody_engraver to the Voice context.

The context property suspendMelodyDecisions may be used to turn off this behavior locally.

\relative c'' {
  \time 3/4
  a8 b g f b g |
  \set suspendMelodyDecisions = ##t
  a  b g f b g |
  \unset suspendMelodyDecisions
  c  b d c b c |
}

\layout {
  \context {
    \Voice
    \consists "Melody_engraver"
    \autoBeamOff
  }
}

[image of music]

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.


Note names

Note names can be printed as text, by using the NoteNames context. When used simultaneously with a regular staff, that makes it possible to synchronize each note with its name, printed above or below the Staff.

\language "italiano"
melody = \relative do'' {
  fad2 si,8 dod re mi fad4. re8 fad2
}

<<
  \new NoteNames { \melody }
  \new Staff { \key si \minor \melody }
  \new NoteNames {
    \set printNotesLanguage = "deutsch"
    \set printAccidentalNames = ##f
    \melody
  }
>>

[image of music]

By default, note names are printed in the same language used for music entry; however, the printNotesLanguage property allows to select any other language available (see Note names in other languages). Whether accidentals should be printed or not is determined through the printAccidentalNames property.

By setting both that property to a symbol and printOctaveNames to #t, note names can be obtained that closely resemble LilyPond entry syntax. If a more generalistic result is desired, ‘scientific’ octave names may also be obtained.

melody = \relative c'' {
  fis2 b,8 cis d e fis4. d8 fis2
}

<<
  \new NoteNames {
    \set printOctaveNames = ##t
    \set printAccidentalNames = #'lily
    \melody
  }
  \new Staff { \key b \minor \melody }
  \new NoteNames {
    \set printOctaveNames = #'scientific
    \melody
  }
>>

[image of music]

The noteNameSeparator property defines how chords will be printed. Other formatting functions may be defined as noteNameFunction; such a function must expect a pitch and a context argument, even if one of these can then be ignored.

somechords = \relative c' {
  <b d fis>2 <b cis e g> <b d fis> q
}

<<
  \new NoteNames {
    \set noteNameSeparator = "+"
    \somechords
  }
  \new Staff { \key b \minor \somechords }
  \new NoteNames {
    \set noteNameFunction =
      #(lambda (pitch ctx)
         (alteration->text-accidental-markup
          (ly:pitch-alteration pitch)))
    \somechords
  }
>>

[image of music]

See also

Notation Reference: Note names in other languages.

Internals Reference: NoteName, NoteNames, Note_name_engraver.


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 }
\relative c'' {
  \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.
}

[image of music]

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

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

\new Voice \with { \consists Balloon_engraver }
\relative c'' {
  \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.
}

[image of music]

The default behavior for the attachment point of the line on the frame and the alignment of the balloon text is demonstrated below.

[image of music]

The default calculation of the attachment point can be overruled using the X-attachment and Y-attachment properties, which take values between -1 and 1, with the limits corresponding to the left (resp. bottom) and right (resp. top) of the frame. Alignment of the text is controlled by text-alignment-X and text-alignment-Y, which have a similar form.

\new Voice \with {
  \consists Balloon_engraver
}
{
  \once \override BalloonText.Y-attachment = -0.5
  \once \override BalloonText.text-alignment-X = 0.0
  \balloonGrobText Rest #'(1 . 3.5) "rest"
  r4
}

[image of music]

Predefined commands

\balloonLengthOn, \balloonLengthOff.

See also

Snippets: Editorial annotations.

Internals Reference: AnnotateOutputEvent, Balloon_engraver, BalloonText, 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 {
      \stemUp
      c''4. d8 e8 f g4
    }
    \new Staff \relative {
      \clef bass
      \stemDown
      c4 g' f e
    }
  >>
}

[image of music]

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

[image of music]

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''2\startGroup
  d\stopGroup
}

[image of music]

Analysis brackets may be nested.

\layout {
  \context {
    \Voice
    \consists Horizontal_bracket_engraver
  }
}
\relative {
  c''4\startGroup\startGroup
  d4\stopGroup
  e4\startGroup
  d4\stopGroup\stopGroup
}

[image of music]

Selected Snippets

Analysis brackets above the staff

Simple horizontal analysis brackets are added below the staff by default. The following example shows a way to place them above the staff instead.

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

\relative c'' {
  \once \override HorizontalBracket.direction = #UP
  c2\startGroup
  d2\stopGroup
}

[image of music]

Analysis brackets with labels

Text markup may be added to analysis brackets through the text property of the HorizontalBracketText grob. Adding different texts to brackets beginning at the same time requires the \tweak command.

Bracket text will be parenthesized after a line break.

\paper { tagline = ##f }

\layout {
  \context {
    \Voice
    \consists "Horizontal_bracket_engraver"
    \override HorizontalBracket.direction = #UP
  }
}

{
  \once\override HorizontalBracketText.text = "a"
    c''\startGroup d''\stopGroup
    \once\override HorizontalBracketText.text = "a'"
    e''\startGroup d''\stopGroup |
  c''-\tweak HorizontalBracketText.text
        \markup \bold \huge "b" \startGroup
     -\tweak HorizontalBracketText.text "a" \startGroup
    d''\stopGroup
    e''-\tweak HorizontalBracketText.text "a'" \startGroup
    d''\stopGroup\stopGroup |
  c''-\tweak HorizontalBracketText.text foo \startGroup
    d'' e'' f'' | \break
  g'' a'' b'' c'''\stopGroup
}

[image of music]

Measure spanner

Measure spanners are an alternate way to print annotated brackets. As opposed to horizontal brackets, they extend between two bar lines rather than two notes. The text is displayed in the center of the bracket.

\paper { tagline = ##f }

\layout {
  \context {
    \Staff
    \consists Measure_spanner_engraver
  }
}

<<
  \new Staff \relative c'' {
    \key d \minor
    R1*2
    \tweak text "Answer"
    \startMeasureSpanner
    \tuplet 3/2 8 {
      a16[ b c] d[ c b]  c[ d e] f[ e d]
    }
    e8 a gis g
    fis f e d~ d c b e
    \stopMeasureSpanner
  }
  \new Staff \relative c' {
    \key d \minor
    \tweak text "Subject"
    \tweak direction #DOWN
    \startMeasureSpanner
    \tuplet 3/2 8 {
      d16[ e f] g[ f e] f[ g a] bes[ a g]
    }
    a8 d cis c
    b bes a g~ g f e a
    \stopMeasureSpanner
    \tweak text "Counter-subject"
    \tweak direction #DOWN
    \startMeasureSpanner
    f8 e a r r16 b, c d e fis g e
    a gis a b c fis, b a gis e a4 g8
    \stopMeasureSpanner
  }
>>

[image of music]

See also

Internals Reference: Horizontal_bracket_engraver, HorizontalBracket, horizontal-bracket-interface, HorizontalBracketText, horizontal-bracket-text-interface, Measure_spanner_engraver, MeasureSpanner, measure-spanner-interface, Staff.


1.8 Text

[image of music]

This section explains how to include text (with various formatting) in music scores.


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

Simple text objects are entered as strings between double quotes (these are optional for a single word). The markup mode is a richer tool that can accept a variety of advanced text formatting and graphical enhancements, as detailed in Formatting text.

As such, markup blocks may be used:

Many other text-based objects may be entered as markup blocks, even if that is not their primary use.

In fact, it is possible to use \markup to customize the appearance of virtually any graphical object (or ‘grob’), by overriding either its text property if it has one, or its stencil property. Some of the logic that makes this a possibility is explained in Flexible architecture.

The following example illustrates the ubiquity of markup blocks, not only as some of the objects listed above, but also by replacing musical objects with text objects through various methods.

\header { title = \markup "Header" }

dyn =
#(make-dynamic-script #{ \markup \text "DynamicText" #})

\markup \box "Top-level markup"

\score {
  <<
    \new ChordNames
    \with {
      majorSevenSymbol = \markup "majorSevenSymbol"
    }
    \chordmode { c1:maj7 }
    \new Staff {
      \tempo \markup "MetronomeMark"
      \textMark "TextMark"
      \once \override TupletNumber.text =
        \markup "TupletNumber"
      \tuplet 3/2 {
        \once \override NoteHead.stencil =
          #ly:text-interface::print
        \once \override NoteHead.text =
          \markup \lower #0.5 "NoteHead"
        c''8^\markup \italic "TextScript"
        a'\finger \markup \text "Fingering"
        \once \override Rest.stencil =
          #(lambda (grob)
             (grob-interpret-markup grob #{
               \markup  "Rest"
               #}))
        r
      }
    }
    \new Lyrics \lyricmode {
      \markup \smallCaps "LyricText" 1
    }
    \new Dynamics { s1\dyn }
  >>
}

[image of music]

See also

Notation Reference: Formatting text, Text scripts, Text spanners, Text marks, Separate text, Fingering instructions, Common notation for vocal music, Displaying chords, New dynamic marks, Dynamics, Balloon help.

Essay on automated music engraving: Flexible architecture.

Snippets: Text.


Text scripts

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

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

[image of music]

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.

\relative {
  a'8^\markup { \italic pizz. } g f e
  a4_\markup { \tiny scherz. \bold molto } f }

[image of music]

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.

\relative {
  a'8^"pizz." g f e
  \textLengthOn
  a4_"scherzando" f
}

[image of music]

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

\relative {
  \override TextSpanner.bound-details.left.text = "rit."
  b'1\startTextSpan
  e,\stopTextSpan
}

[image of music]

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.

\relative {
  \override TextSpanner.bound-details.left.text =
    \markup { \upright "rit." }
  b'1\startTextSpan c
  e,\stopTextSpan
}

[image of music]

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.

The texts at the bounds of a text spanner may collide.

{
  \once \override TextSpanner.bound-details.left.text = "The text is"
  \once \override TextSpanner.bound-details.right.text = "too long"
  c'2\startTextSpan d'2\stopTextSpan
}

[image of music]

Workarounds can be found in Horizontal spacing.

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

[image of music]

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 (mymarkup) (markup?)
   (make-music 'CrescendoEvent
               'span-direction START
               'span-type 'text
               'span-text mymarkup))
mydecresc =
#(define-music-function (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
}

[image of music]

See also

Notation Reference: Line styles, Dynamics, Formatting text.

Snippets: Text, Expressive marks.

Internals Reference: TextSpanner.


Section labels

The \sectionLabel command marks the beginning of a named passage. It is well suited for use at a section division created with \section, but it does not imply \section and may be used alone.

\fixed c' {
  \sectionLabel "Verse"
  c2 g
  \section
  \sectionLabel "Chorus"
  g2 c
  \bar "|."
}

[image of music]

See also

Notation Reference: Formatting text, Rehearsal marks, Section divisions.

Snippets: Text.

Internals Reference: SectionLabel, SectionLabelEvent.


Text marks

Text marks are textual objects that, unlike text scripts (see Text scripts), are not printed over notes but between notes, often aligned to a bar line.

Note: Older LilyPond versions used the \mark command for text marks, even though it is primarily intended for rehearsal marks (see Rehearsal marks). The \textMark and \textEndMark commands are better suited for text marks with regard to their default settings as well as the ability to have several text marks at the same moment. It is therefore recommended to use \textMark and \textEndMark instead of \mark "Text" or \mark \markup …. Note that if converting code that uses \mark for text marks, overrides using RehearsalMark should be changed to TextMark.

Before using text marks, it is recommended to seek a more specific command, if available. For text that identifies a section, use \sectionLabel (see Section labels). For jump instructions, use \jump (see Manual repeat marks). These commands have different default layout settings, and they create separate objects which can be styled differently from generic text marks in stylesheets.

A text mark is entered using either \textMark or \textEndMark. The \textMark command draws a left-aligned mark.

\fixed c'' {
  \textMark "Fl. 1 solo"
  c4 e g2
  \textMark "A due"
  e4 g c'2
}

[image of music]

If a line break occurs at the point \textMark is used, the text appears on the next system.

\fixed c'' {
  \textMark "Fl. 1 solo"
  c4 e g2
  \break
  \textMark "A due"
  e4 g c'2
}

[image of music]

Unlike \textMark, \textEndMark creates a right-aligned mark. If it occurs on a line break, it is printed on the preceding system.

\fixed c' {
  \repeat volta 2 {
    c4 e8 f g2
    e4 f8 g c'2
    \textEndMark "ad lib"
  }
  \break
  c'4 8 8 4 8 8
  c'1
}

[image of music]

Complex text formatting may be added using a \markup block (see Formatting text).

\relative {
  <c' e>1
  \textMark \markup { \italic { colla parte } }
  <d f>2 <e g>
  <c f aes>1
}

[image of music]

The \markLengthOn and \markLengthOff commands (see Metronome marks) can also be used on text marks.

{
  \mark \default
  c'2 2
  \textEndMark "long mark text"
  \markLengthOn
  2 2
  \mark \default
  2 2
  \textEndMark "long mark text"
}

[image of music]

Text marks may be printed below the staff.

\fixed c' {
  c4 g c'8 b c4 e' c' c2
  c4 g c'8 b c4 e' c' g2
  e'4 c' c'8 b c'4
  g4 c' c2~ c1
  \tweak direction #DOWN
    \tweak font-size #-1
      \textEndMark "Composed on November 13th, 2020"
}

[image of music]

There can be several text marks at the same moment. Their stacking order can be overridden using the outside-staff-priority property (see Vertical collision avoidance). Alternatively, a single text mark with \markup \column { … } can achieve the same effect.

\fixed c' {
  \repeat volta 2 {
    c4 g c'8 b c4 e' c' c2
    \textEndMark "ad lib."
    \tweak outside-staff-priority 1200
      \tweak font-size -1
        \textEndMark "2nd time a due"
  }
}

[image of music]

The alignment of a text mark can be changed.

{
  c'8 8 8 8 8 8 8 8
  \textMark \markup \column {
    \line { Left-aligned mark }
    \line { (default for \concat { \typewriter "\\textMark" ) } }
  }
  d'8 8 8 8 8 8 8 8
}

{
  c'8 8 8 8 8 8 8 8
  \tweak self-alignment-X #CENTER
    \textMark "Centered mark"
  d'8 8 8 8 8 8 8 8
}

{
  c'8 8 8 8 8 8 8 8
  \tweak self-alignment-X #RIGHT
    \textMark \markup \right-column {
      \line { Right-aligned mark }
      \line { (default for \concat { \typewriter "\\textEndMark" ) } }
    }
  d'8 8 8 8 8 8 8 8
}

[image of music]

Predefined commands

\textMark, \textEndMark, \markLengthOn, \markLengthOff.

Selected Snippets

Printing marks on every staff

Although marks are normally only printed above the topmost staff, they may also be printed on every staff.

\score {
  <<
    \new Staff { \mark \default c''1 \textMark "molto" c'' }
    \new Staff { \mark \default c'1 \textMark "molto" c' }
  >>
  \layout {
    \context {
      \Score
      \remove Mark_engraver
      \remove Text_mark_engraver
      \remove Staff_collecting_engraver
    }
    \context {
      \Staff
      \consists Mark_engraver
      \consists Text_mark_engraver
      \consists Staff_collecting_engraver
    }
  }
}

[image of music]

See also

Notation Reference: Metronome marks, Rehearsal marks, Section labels, Formatting text, Music notation inside markup, The Emmentaler font.

Snippets: Text.

Internals Reference: TextMarkEvent, Text_mark_engraver, TextMark.


Separate text

A \markup or \markuplist 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...
}

[image of music]

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
}

[image of music]

Using \markuplist, separate text blocks can be spread over multiple pages, making it possible to print text documents or books entirely within LilyPond. For a description of this feature and the specific syntax it requires, see Text markup introduction.

Predefined commands

\markup, \markuplist.

Selected Snippets

Stand-alone two-column markup

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

\markup {
  \fill-line {
    \hspace #1
    \column {
      \line { O sacrum convivium }
      \line { in quo Christus sumitur, }
      \line { recolitur memoria passionis ejus, }
      \line { mens impletur gratia, }
      \line { futurae gloriae nobis pignus datur. }
      \line { Amen. }
    }
    \hspace #2
    \column \italic {
      \line { O sacred feast }
      \line { in which Christ is received, }
      \line { the memory of His Passion is renewed, }
      \line { the mind is filled with grace, }
      \line { and a pledge of future glory is given to us. }
      \line { Amen. }
    }
    \hspace #1
  }
}

[image of music]

See also

Notation Reference: Formatting text, File structure, Multiple scores in a book.

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 or \markuplist block is used to typeset text with an extensible syntax called “markup mode”. Such blocks can be used in many contexts (see Text objects overview).

In markup mode, words are written as-is. A single word does not need any quotes.

\markup intenso

[image of music]

Several words can be grouped together by enclosing them in quotes.

\markup "molto intenso"

[image of music]

Apart from grouping, quoting also allows writing special characters such as ‘\’ and ‘#’ without affecting the formatting of the text. Double quotation marks themselves may be printed by preceding them with backslashes.

\relative {
  a'1^"\italic markup..."
  a_\markup { \italic "... prints \"italic\" letters!" }
  a a
}

[image of music]

Formatting is achieved through markup commands. Their name is written preceded by a backslash. They expect a number of arguments specific to the command. For an exhaustive list of \markup-specific commands, see Text markup commands.

\markup \italic "string. assai"
\markup \with-color "red" intenso

[image of music]

Markup commands can be nested. The markup block ends when all commands have received their arguments.

\markup \with-color "red" \italic intenso

[image of music]

Several markup expressions can be grouped together within braces to form a so-called markup list. Without further formatting, the elements of a markup list are typeset in a row.

\markup { molto \italic intenso }

[image of music]

Some commands do not expect a markup but a markup list, allowing for more complex text arrangements than printing in a row.

\markup \center-column {
  \bold "Des Simplicius Simplicissimus Jugend"
  "Karl Amadeus Hartmann"
}

[image of music]

Also, some commands do not return a markup but a markup list. The result can then be used where a markup list is expected. For a list of these commands, see Text markup list commands.

\markup \string-lines
    "Twinkle, twinkle, little star,
     How I wonder what you are!"

[image of music]

\markup \center-column \string-lines
    "Twinkle, twinkle, little star,
     How I wonder what you are!"

[image of music]

Elements of a nested markup list are simply treated as elements of the main markup list.

\markup \center-column {
  \bold "Des Simplicius Simplicissimus Jugend"
  { Karl Amadeus \smallCaps Hartmann }
}

[image of music]

To group elements of a nested markup list in a row, apply the \line command to the markup list. This stacks elements from the markup list horizontally into a single markup.

\markup \center-column {
  \bold "Des Simplicius Simplicissimus Jugend"
  \line { Karl Amadeus \smallCaps Hartmann }
}

[image of music]

A special feature is the handling of commands taking markups when applied to markup lists. When a command expects a markup as its last argument, and a markup list is given for this argument, the markup command is applied to each of the individual markups in the list.

\markup \box { Karl Amadeus \smallCaps Hartmann }

[image of music]

In this case, the result is in turn a markup list, which can be passed to a command expecting a markup list, or to one expecting a markup, with again the mapping behavior described above in the latter case.

\markup \center-column \box { Karl Amadeus \smallCaps Hartmann }
\markup \rotate #30 \box { Karl Amadeus \smallCaps Hartmann }

[image of music]

Apply \line to a markup list in order to make it treated as a single markup argument.

\markup \box { Karl Amadeus \smallCaps Hartmann }
\markup \box \line { Karl Amadeus \smallCaps Hartmann }

[image of music]

When the entire content of a \markup expression is a markup list, it is implicitly typeset using the \line command. Thus, elements are stacked horizontally and grouped as a single, unbreakable text block. The \markuplist command acts differently: it expects a markup list, and prints the individual markups on the page, stacking them vertically, and allowing page breaks. The following example illustrates this difference.

\markup \box \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.
}

\markuplist \box \wordwrap-lines {
  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.
}

[image of music]

Markups can be stored in variables, to be reused in any context where a markup is accepted. For example, such a variable can be directly attached to notes:

allegro = \markup \bold \large Allegro

{
  d''8.^\allegro
  d'16 d'4 r2
}

[image of music]

The \etc syntax allows to define custom shorthands usable as markup commands.

\markup reddish = \markup \with-color "tomato" \etc

\markup { molto \reddish intenso }

[image of music]

The inner workings of markup commands and how to implement more complex ones is explained in Markup functions.

See also

Notation Reference: Text objects overview, Text markup commands, Text markup list commands.

Extending LilyPond: Markup functions.

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

Snippets: Text.

Internals Reference: TextScript.

Known issues and warnings

Syntax error messages for markup mode can be confusing.


Selecting font and font size

Basic font switching is supported in markup mode:

\relative {
  d''1^\markup {
    \bold { Più mosso }
    \italic { non troppo \underline Vivo }
  }
  r2 r4 r8
  d,_\markup { \italic quasi \smallCaps Tromba }
  f1 d2 r
}

[image of music]

The font size can be altered, relative to the global staff size, in a number of different ways.

It can be set to predefined size.

\relative b' {
  b1_\markup { \huge Sinfonia }
  b1^\markup { \teeny da }
  b1-\markup { \normalsize camera }
}

[image of music]

It can be set relative to its previous value.

\relative b' {
  b1_\markup { \larger Sinfonia }
  b1^\markup { \smaller da }
  b1-\markup { \magnify #0.6  camera }
}

[image of music]

It can be increased or decreased relative to the value set by the global staff size.

\relative b' {
  b1_\markup { \fontsize #-2 Sinfonia }
  b1^\markup { \fontsize #1 da }
  b1-\markup { \fontsize #3 camera }
}

[image of music]

It can also be set to a fixed point size, regardless of the global staff size.

\relative b' {
  b1_\markup { \abs-fontsize #20 Sinfonia }
  b1^\markup { \abs-fontsize #8 da }
  b1-\markup { \abs-fontsize #14 camera }
}

[image of music]

If the text includes spaces, then it is best to put it all inside quote marks, so that the size of each space is appropriate for the size of the other characters.

\markup \fontsize #6 \bold { Sinfonia da camera }
\markup \fontsize #6 \bold { "Sinfonia da camera" }

[image of music]

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

[image of music]

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

[image of music]

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

[image of music]

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.

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

Snippets: Text.

Internals Reference: TextScript.

Known issues and warnings

Using the font sizing commands \teeny, \tiny, \small, \normalsize, \large, and \huge will lead to inconsistent line spacing compared to using \fontsize.


Text alignment

This subsection discusses how to place text in markup mode. Markup objects can also be moved as a whole, using the syntax described in Moving objects.

Markup objects may be aligned in different ways. By default, a text indication is aligned on its left edge: in the following example, there is no difference between the first and the second markup. That example also demonstrates various syntactically correct ways of placing the alignment commands:

\relative {
  d''1-\markup { poco }
  f
  d-\markup { \left-align poco }
  f
  d-\markup { \center-align { poco } }
  f
  d-\markup \right-align { poco }
}

[image of music]

Horizontal alignment may be fine-tuned using a numeric value:

\relative {
  a'1-\markup { \halign #-1 poco }
  e'
  a,-\markup { \halign #0 poco }
  e'
  a,-\markup { \halign #0.5 poco }
  e'
  a,-\markup { \halign #2 poco }
}

[image of music]

Lastly, words and any other objects may be moved by preceding them with padding. Negative padding is also supported, and will move any objects that follow in the opposite direction. Although padding is normally invisible, in the following example some commands have been added to make it appear more clearly:

\relative {
  d''1-\markup { poco }
  f
  d-\markup { \with-color #darkred \box \hspace #4 poco }
  f
  d-\markup { \with-color #darkred \box \hspace #-4 poco }
  f
  d-\markup { \with-color #darkred \box \hspace #10 poco }
}

[image of music]

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 can be set in a similar way. As stated above, markup objects can be moved as a whole; however, it is also possible to move specific elements inside a markup block.

\relative {
  d'2^\markup {
    Acte I
    \raise #2 { Scène 1 }
  }
  a'
  g_\markup {
    \lower #4 \bold { Très modéré }
  }
  a
  d,^\markup \raise #4 \italic {
    Une forêt.
  }
  a'4 a g2 a
}

[image of music]

Some commands can affect both the horizontal and vertical alignment of text objects in markup mode:

\relative {
  d'2^\markup {
    Acte I
    \translate #'(-1 . 2) "Scène 1"
  }
  a'
  g_\markup {
    \general-align #Y #3.2 \bold "Très modéré"
  }
  a
  d,^\markup \translate-scaled #'(-1 . 2) \teeny {
   "Une forêt."
  }
  a'4 a g2 a
}

[image of music]

Here again, padding (either positive or negative) is a convenient way of positioning objects vertically, when inserted into markup columns:

\relative {
  d'2^\markup {
    Acte I
    \column {
      \with-color #darkred \box \vspace #-1
      "Scène 1"
    }
  }
  a'
  g_\markup \column {
    \with-color #darkred \box \vspace #1
    "Très modéré"
  }
  a
  d,^\markup \column {
   "Une forêt."
    \with-color #darkred \box \vspace #2
  }
  a'4 a g2 a
}

[image of music]

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

[image of music]

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

[image of music]

Elements may be spread to fill any specified width by overriding the line-width property. By default it is set to #f which indicates the entire line:

\markup {
  \column {
    \fill-line { left center right }
    \null
    \override #'(line-width . 30)
    \fill-line { left center right }
  }
}

[image of music]

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

[image of music]

An exhaustive list of text alignment commands can be found in Align.

See also

Learning Manual: Moving objects.

Notation Reference: Align, Text marks.

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

Snippets: Text.

Internals Reference: TextScript.


Graphic notation inside markup

Various graphic objects may be added to a score, using markup commands.

Some markup commands allow decoration of text elements with graphics, as demonstrated in the following example.

\markup \fill-line {
  \center-column {
    \circle Jack
    \box "in the box"
    \null
    \line {
      Erik Satie
      \hspace #3
      \bracket "1866 - 1925"
    }
    \null
    \rounded-box \bold Prelude
  }
}

[image of music]

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"
  }
  \box \pad-around #3 "String quartet keeps very even time."
}

[image of music]

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

[image of music]

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:

c'1^\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'

[image of music]

An exhaustive list of graphics-specific commands can be found in Graphic.

See also

Notation Reference: Align, Dimensions, Editorial annotations, Graphic.

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

Snippets: Text.

Internals Reference: TextScript.


Music notation inside markup

Various musical notation elements may be added to a score, inside a markup object.

Notes and accidentals can be entered using markup commands:

a'2 a'^\markup {
  \note {4} #1
  =
  \note-by-number #1 #1 #1.5
}
b'1_\markup {
  \natural \semiflat \flat
  \sesquiflat \doubleflat
}
\glissando
a'1_\markup {
  \natural \semisharp \sharp
  \sesquisharp \doublesharp
}
\glissando b'

[image of music]

Other notation objects may also be printed in markup mode:

\relative {
  g1 bes
  ees\finger \markup \tied-lyric "4~1"
  fis_\markup { \dynamic rf }
  bes^\markup {
    \beam #8 #0.1 #0.5
  }
  cis
  d-\markup {
    \markalphabet #8
    \markletter #8
  }
}

[image of music]

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

\relative {
  c''2
  c'^\markup { \musicglyph "eight" }
  c,4
  c,8._\markup { \musicglyph "clefs.G_change" }
  c16
  c2^\markup { \musicglyph "timesig.neomensural94" }
}

[image of music]

Another way of printing non-text glyphs is described in Music fonts. This is useful for printing braces of various sizes.

The markup mode also supports diagrams for specific instruments:

\relative {
  c''1^\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"
  }
}

[image of music]

Such diagrams are documented in Instrument Specific Markup.

A whole score can even be nested inside a markup object:

\relative {
  c'4 d^\markup {
    \score {
      \relative { c'4 d e f }
    }
  }
  e f |
  c d e f
}

[image of music]

An exhaustive list of music notation related commands can be found in Music.

See also

Notation Reference: Music, The Emmentaler font, Music fonts.

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

Snippets: Text.

Internals Reference: TextScript.

Known issues and warnings

Vertical spacing of a \score inside a markup object is controlled by baseline-skip. Any \paper settings are ignored.


1.8.3 Fonts

Fonts in LilyPond are handled by several libraries; two of them are of relevance to the user: FontConfig is used to detect available fonts, and selected fonts are then rendered by Pango to display text strings.

This section shows how to access fonts in LilyPond, and how to change them in scores.


Finding fonts

In addition to any font already installed on the operating system, more fonts may be added to the ones detected by FontConfig (and thus available in LilyPond scores) by the following commands:

#(ly:font-config-add-font "path/to/font-file")
#(ly:font-config-add-directory "path/to/directory/")

Both commands accept either absolute or relative paths, which makes it possible to compile a score on any system by simply distributing the relevant font files together with the LilyPond input files.

To verify that the desired fonts are found by FontConfig, use the command #(ly:font-config-display-fonts), which prints the complete list of available fonts to the console log. It also shows the actual font names to be used with LilyPond; these may differ from the file names themselves.

See Single entry fonts and Entire document fonts how to access fonts in general.


Font families

Three generic aliases for text font families1 are available: ‘roman’ (serif), ‘sans’, and ‘typewriter’. Depending on the backend, these families get mapped to different font family aliases.

For the svg backend:

generic familySVG font family
romanserif
sanssans-serif
typewritermonospace

‘serif’, ‘sans-serif’, and ‘monospace’ are ‘generic-family’ in SVG and CSS specifications.

For other backends:

generic familydefault font family aliasfont families contained in alias
romanLilyPond SerifC059, Century SchoolBook URW, Century Schoolbook L, TeX Gyre Schola, DejaVu Serif, …, serif
sansLilyPond Sans SerifNimbus Sans, Nimbus Sans L, TeX Gyre Heros, DejaVu Sans, …, sans-serif
typewriterLilyPond MonospaceNimbus Mono PS, Nimbus Mono, Nimbus Mono L, TeX Gyre Cursor, DejaVu Sans Mono, …, monospace

If a character does not exist in the appropriate font of the first listed family, the appropriate font of the next listed family gets used instead for that character.

Note that the URW font families distributed with LilyPond (‘C059’, ‘Nimbus Sans’, and ‘Nimbus Mono PS’) have a peculiarity: By default, in addition to the standard ligatures like ‘fl’ or ‘ffi’, they substitute the string ‘Nr.’ with the Numero Sign (U+2116) if the ‘latn’ script is selected. To circumvent this locally, insert a zero-width non-joiner character (ZWNJ, U+200C) between the ‘N’ and ‘r’ characters. To circumvent this globally, use the following code to make LilyPond always insert a ZWNJ character.

\paper {
  #(add-text-replacements!
      `(("Nr." . ,(format #f "N~ar." (ly:wide-char->utf-8 #x200C)))))
}

‘LilyPond Serif’, ‘LilyPond Sans Serif’, and ‘LilyPond Monospace’ are font family aliases defined in the additional FontConfig configuration file ‘00-lilypond-fonts.conf’, which can be usually found in directory ‘/usr/local/share/lilypond/2.24.3/fonts’, and which is used exclusively by LilyPond.

Each font family may include different shapes and series. The following example demonstrates that, including code to also change the size. The value supplied to font-size is taken relative to the default font size.

\override Score.TextMark.font-family = #'typewriter
\textMark "Ouverture"
\override Voice.TextScript.font-shape = #'italic
\override Voice.TextScript.font-series = #'bold
d''2.^\markup "Allegro"
\override Voice.TextScript.font-size = #-3
c''4^"smaller"

[image of music]

A similar syntax may be used in markup mode; however, in most cases it is preferable to use the simpler syntax explained in Selecting font and font size:

\markup {
  \column {
    \line {
      \override #'((font-shape . italic) (font-size . 4))
      Idomeneo,
    }
    \line {
      \override #'(font-family . typewriter) {
        \override #'(font-series . bold) re
        di
      }
      \override #'(font-family . sans) Creta
    }
  }
}

[image of music]


Font features

When using OpenType fonts, font features can be used.2 Note that not all OpenType fonts have all features. If you request a feature that does not exist in the chosen font, the feature is simply ignored. The example below uses the font ‘TeX Gyre Schola’ (this is, the roman style of the family).

\markup { \override #'(font-name . "TeX Gyre Schola")
          normal style: Hello HELLO }
\markup { \override #'(font-name . "TeX Gyre Schola")
          \caps { small caps: Hello } }
\markup { \override #'(font-name . "TeX Gyre Schola")
          \override #'(font-features . ("smcp"))
          { true small caps: Hello } }

\markup { \override #'(font-name . "TeX Gyre Schola")
          normal number style: 0123456789 }
\markup { \override #'(font-name . "TeX Gyre Schola")
          \override #'(font-features . ("onum"))
          { old number style: 0123456789 } }

\markup { \override #'(font-name . "TeX Gyre Schola")
          \override #'(font-features . ("salt 0"))
          { stylistic alternate 0: εφπρθ } }
\markup { \override #'(font-name . "TeX Gyre Schola")
          \override #'(font-features . ("salt 1"))
          { stylistic alternate 1: εφπρθ } }

\markup { \override #'(font-name . "TeX Gyre Schola")
          \override #'(font-features . ("onum" "smcp" "salt 1"))
          { multiple features: Hello 0123456789 εφπρθ } }

[image of music]

For the full OpenType font feature list see https://www.microsoft.com/typography/otspec/featurelist.htm; for identifying features of OpenType fonts see https://lists.gnu.org/archive/html/lilypond-devel/2017-08/msg00004.html.

Although it is easy to switch between preconfigured fonts, it is also possible to use other fonts. For more information, see Single entry fonts and Entire document fonts.

See also

Notation Reference: The Emmentaler font, Music notation inside markup, Rotating objects, Selecting font and font size, Font.


Single entry fonts

Almost all outline fonts installed on the operating system and recognized by FontConfig may be used in a score, with the exception of bitmap fonts (which are not supported by design) and OpenType Variation Fonts (which are not supported yet).

LilyPond calls function pango_font_description_from_string from the Pango library to access fonts; it uses the following syntax form for font names.3

[family-list] [style-options]

where family-list is a comma-separated list of families optionally terminated by a comma, and style-options a whitespace-separated list of words where each word describes one of style, variant, weight, stretch, or gravity.

The following words are understood as styles: Normal (the default), Roman, Oblique, Italic.

The following words are understood as variants: Small-Caps. Default is no variant.

The following words are understood as weights: Thin, Ultra-Light, Extra-Light, Light, Semi-Light, Demi-Light, Book, Regular (the default), Medium, Semi-Bold, Demi-Bold, Bold, Ultra-Bold, Extra-Bold, Heavy, Black, Ultra-Black, Extra-Black.

The following words are understood as stretch values: Ultra-Condensed, Extra-Condensed, Condensed, Semi-Condensed, Semi-Expanded, Expanded, Extra-Expanded, Ultra-Expanded. Default is no stretch.

The following words are understood as gravity values: Not-Rotated, South, Upside-Down, North, Rotated-Left, East, Rotated-Right, West. Default is no gravity.

Assuming the syntax is correct, setting a font name never fails. If none of the font families are known (or no font family is given), FontConfig returns a default font depending on the operating system. If none of the style options are known (or no style option is given), default values are used.

In the following example, the font for the time signature is set to ‘Bitstream Charter’. Since no style option is given, FontConfig uses default values as specified above. For the markup string, the list of font families is set to ‘Bitstream Vera Sans’ and ‘sans-serif’, which tells FontConfig to try ‘Bitstream Vera Sans’ first; if it is not available, it tries the generic font family ‘sans-serif’ as described in Font families. The style for the markup is set to ‘Oblique Bold’, which makes FontConfig try to find a font that is both oblique and bold. If that fails, it tries to find an oblique or bold font. If that fails again, it tries to match a font with default style options.

Note that FontConfig also checks whether the requested glyph is actually present in the font. In case it is missing, another font gets tried (following the above algorithm) until the glyph is eventually found. Only if FontConfig fails to find any font with the appropriate glyph a symbol for a missing glyph is shown (which is normally a rectangular box or simply some whitespace).

\override Staff.TimeSignature.font-name = "Bitstream Charter"
\override Staff.TimeSignature.font-size = #2
\time 3/4

a'1_\markup {
  \override #'(font-name .
               "Bitstream Vera Sans, sans-serif, Oblique Bold")
    { Vera Oblique Bold }
}

[image of music]

Note: If any of the above style options is part of the font (family) name you must use a trailing comma after the name even if you do not select a style option. A typical example is ‘Times New Roman’: If specified as "Times New Roman", FontConfig searches for a font ‘Times New’ in roman style. Only if you say "Times New Roman," this font is really accessed.

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

lilypond -dshow-available-fonts

See also

Notation Reference: Finding fonts, Font families, Entire document fonts.

Snippets: Text.


Entire document fonts

It is possible to change the fonts used in LilyPond’s default font families by calling the function make-pango-font-tree. The arguments are substitutions for the ‘roman’, ‘sans’ and ‘typewriter’ font families (in that order), followed by a scaling factor. Similar to single fonts (see Single entry fonts), font families are set up by using comma-separated lists of font family names, but without style options.4

Note that make-pango-font-tree resets the notation fonts to ‘emmentaler’ as the default.

The example below adjusts the font size in relation to the global staff size.

\paper {
  #(define fonts
    (make-pango-font-tree "Linux Libertine O"
                          "Nimbus Sans, Nimbus Sans L"
                          "DejaVu Sans Mono"
                          (/ staff-height pt 20)))
}

\relative c'{
  c1-\markup {
    roman,
    \sans sans,
    \typewriter typewriter. }
}

[image of music]

LilyPond provides an alternative, more flexible interface to set global font families. It allows you to change only specific font family names, leaving others set to default values. The following example has the same effect as the above make-pango-font-tree example; the syntax for font family names is identical. If you do not change the staff size from the default of 20pt, the line containing the #:factor keyword is unnecessary.

\paper {
  #(define fonts
    (set-global-fonts
     #:roman "Linux Libertine O"
     #:sans "Nimbus Sans, Nimbus Sans L"
     #:typewriter "DejaVu Sans Mono"
     ; unnecessary if the staff size is default
     #:factor (/ staff-height pt 20)
    ))
}

Additionally, set-global-fonts can also set the music notation fonts. The following example has the same effect as the previous examples, because it uses the default notation fonts. For more information, see Replacing the notation font.

\paper {
  #(define fonts
    (set-global-fonts
     #:music "emmentaler"            ; default
     #:brace "emmentaler"            ; default
     #:roman "Linux Libertine O"
     #:sans "Nimbus Sans, Nimbus Sans L"
     #:typewriter "DejaVu Sans Mono"
     ; unnecessary if the staff size is default
     #:factor (/ staff-height pt 20)
    ))
}

Note that each call to set-global-fonts completely resets both the main notation and text fonts.5 If any font category is left unspecified, the respective default font (family) gets used for that category. Each call of set-global-fonts affects all \book blocks that follow it. If there are multiple \book blocks and you want to use different fonts for each, simply call set-global-fonts again, like this:

\paper {
  #(define fonts
    (set-global-fonts
     …
    ))
}
\book {
  …
}

\paper {
  #(define fonts
    (set-global-fonts
     …
    ))
}
\book {
  …
}

See also

Notation Reference: Finding fonts, Font families, Single entry fonts, Selecting font and font size, Font, Replacing the notation font.


Music fonts

LilyPond neither uses FontConfig nor Pango for accessing music notation fonts but handles them by itself. As a consequence, the interface is different. This section describes how to insert music symbols into markup strings.

Music notation fonts are a collection of specific glyphs that can be accessed with several encodings. The following syntax allows LilyPond’s various Emmentaler glyphs6 to be used directly in markup mode:

a'1^\markup {
  \vcenter {
    \override #'(font-encoding . fetaBraces)
    \lookup "brace120"
    \override #'(font-encoding . fetaText)
    \column { 1 3 sf }
    \override #'(font-encoding . fetaMusic)
    \lookup "noteheads.s0petrucci"
  }
}

[image of music]

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

When accessing braces with the ‘fetaBraces’ encoding, 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, with 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.


2. Specialist notation

This chapter explains how to create musical notation for specific types of instrument or in specific styles.

Orchestral and ensemble music is not addressed in a separate section; however, several notions commonly useful in orchestral scores are found in References for opera and stage musicals.


2.1 Vocal music

[image of 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.

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 }

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

\relative { d''8 c16 a bes8 f ees' d c4 }
\addlyrics { „Schad’ um das schö -- ne grü -- ne Band, }

[image of music]

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 { \time 3/4 e'4 e4. e8 d4 e d c2. }
\addlyrics { "\"I" am so lone -- "ly,\"" said she }

[image of music]

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

[image of music]

See also

Learning Manual: Songs.

Notation Reference: Automatic syllable durations, Fonts, Formatting text, Input modes, Manual syllable durations, Special characters.

Internals Reference: LyricText.

Snippets: Text.


Aligning lyrics to a melody

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

\new Lyrics \lyricmode { … }

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

Lyrics can be aligned with melodies in two main ways:

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:

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" \relative {
    a'1 a4. a8 a2
  }
  \new Lyrics \lyricsto "melody" {
    These are the words
  }
>>

[image of music]

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

Using \addlyrics

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

{ 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'2 e4 g2. }
  \addlyrics { play the game }
}

[image of music]

More stanzas can be added by adding more \addlyrics sections:

{
  \time 3/4
  \relative { c'2 e4 g2. }
  \addlyrics { play the game }
  \addlyrics { speel het spel }
  \addlyrics { joue le jeu }
}

[image of music]

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

Using associatedVoice

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

\set associatedVoice = "lala"

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

Here is an example demonstrating its use:

<<
  \new Staff <<
    \time 2/4
    \new Voice = "one" \relative {
      \voiceOne
      c''4 b8. a16 g4. r8 a4 ( b ) c2
    }
    \new Voice = "two" \relative {
      \voiceTwo
       s2 s4. f'8 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.
  }
>>

[image of music]

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.

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" \relative {
    c''2 a f f e e
  }
  \new Lyrics \lyricmode {
    c4. -- a -- f -- f -- e2. -- e
  }
>>

[image of music]

<<
  \new Staff {
    \relative {
      c''2 c2
      d1
    }
  }
  \new Lyrics {
    \lyricmode {
      I2 like4. my8 cat!1
    }
  }
  \new Staff {
    \relative {
      c'8 c c c c c c c
      c8 c c c c c c c
    }
  }
>>

[image of music]

This technique is useful when writing dialogue over music, see Dialogue over music.

To change syllable alignment, simply override the self-alignment-X property:

<<
  \new Voice = "melody" \relative {
    \time 3/4
    c'2 e4 g2 f
  }
  \new Lyrics \lyricmode {
    \override LyricText.self-alignment-X = #LEFT
    play1 a4 game4
  }
>>

[image of music]

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 the tilde symbol (~) to get a lyric tie.

{
  \relative {
    \autoBeamOff
    r8 b' c fis, fis c' b e,
  }
  \addlyrics
  {
    % Ensure hyphens are visible
    \override LyricHyphen.minimum-distance = #1.0
    Che_in ques -- ta_e_in quel -- l'al -- tr'on -- da
  }
  \addlyrics { "Che in" ques -- "ta e in" quel -- l'al -- tr'on -- da }
  \addlyrics { Che~in ques -- ta~e~in quel -- l'al -- tr'on -- da }
}

[image of music]

See also

Internals Reference: LyricCombineMusic.


Multiple notes to one syllable

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

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

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

There are five ways in which melismata can be indicated:

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" \relative {
    \time 3/4
    \set melismaBusyProperties = #'()
    c'4 d ( e )
    g8 [ f ] f4 ~ 4
  }
  \new Lyrics \lyricsto "melody" {
    Ky -- ri -- e e -- le -- i -- son
  }
>>

[image of music]

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" \relative {
    \time 3/4
    \set melismaBusyProperties = #'()
    c'4 d ( e )
    g8 [ f ] ~ 4 ~ f
  }
  \new Lyrics \lyricsto "melody" {
    Ky -- ri -- _ e __ _ _ _
  }
>>

[image of music]

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.

By default a hyphen is not repeated after a system break when the next line begins with a new syllable. Setting the after-line-breaking property to #t allows hyphens to be drawn in such situations.

See also

Internals Reference: LyricExtender, LyricHyphen.


Gradual changes of vowel

Vowel transitions (gradual changes of vowel or sustained consonant), which may be indicated by arrows between syllables, are entered with the command \vowelTransition (see Gould pp. 452–453). The arrow shows the length of the transition, and it is by default always drawn (space is added if necessary in tightly engraved music). Ties between notes of unchanged pitch or slurs show that there is no new articulation, despite a change of vowel. The minimum length of the arrows may be adjusted with the minimum-length property of VowelTransition.

{
  c'2 c'
  \set melismaBusyProperties = #'()
  c'2 ~ c'
  \time 3/2
  d'4( e' f' e' f'2
  e'2.)
}
\addlyrics
{
  Ah \vowelTransition oh,
  ah \vowelTransition oh,
  ah \vowelTransition _ _ _ _
  oh.
}

[image of music]

See also

Musical Glossary: vowel transition.

Internals Reference: VowelTransition.


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

[image of music]

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''4 c c c }
contraltoMusic = \relative { a'4 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
      }
    }
  >>
}

[image of music]

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''4 c c c }
      }
    }
    \new Lyrics {
      \lyricsto "melody" {
        Here are the words
      }
    }
  >>
}

[image of music]

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''4 c c c }
      }
    }
    \new Lyrics \with { alignAboveContext = "staff" } {
      \lyricsto "melody" {
        Here are the words
      }
    }
  >>
}

[image of music]

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''4 c c c }
      }
    }
    \context Lyrics = "lyrics" {
      \lyricsto "melody" {
        Here are the words
      }
    }
  >>
}

[image of music]

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''4 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 { a'4 a a a }
      }
    }
    \context Lyrics = "sopranos" {
      \lyricsto "sopranos" {
        Sop -- ra -- no words
      }
    }
    \context Lyrics = "contraltos" {
      \lyricsto "contraltos" {
        Con -- tral -- to words
      }
    }
  >>
}

[image of music]

Other combinations of lyrics and staves may be generated by elaborating these examples, or by examining the templates in the Learning Manual, see Vocal ensembles templates.

Selected Snippets

Obtaining 2.12 lyrics spacing in newer versions

The vertical spacing engine changed since 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))
    }
  }
}

[image of music]

See also

Learning Manual: Vocal ensembles templates.

Notation Reference: Context layout order, Creating and referencing contexts.


Placing syllables horizontally

To increase the spacing between lyrics, set the minimum-distance property of LyricSpace.

\relative c' {
  c c c c
  \override Lyrics.LyricSpace.minimum-distance = #1.0
  c c c c
}
\addlyrics {
  longtext longtext longtext longtext
  longtext longtext longtext longtext
}

[image of music]

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
  }
  \addlyrics {
  longtext longtext longtext longtext
  longtext longtext longtext longtext
  }
  \layout {
    \context {
      \Lyrics
      \override LyricSpace.minimum-distance = #1.0
    }
  }
}

[image of music]

Selected Snippets

Lyrics alignment

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

\layout { ragged-right = ##f }
\relative c'' {
  c1
  c1
  c1
}
\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"
}

[image of music]

Known issues and warnings

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

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 {
          a'4 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. }
      }
    }
  >>
}

[image of music]

The words will then be correctly expanded if the repeats are unfolded.

\score {
  \unfoldRepeats {
    <<
      \new Staff {
        \new Voice = "melody" {
          \relative {
            a'4 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. }
        }
      }
    >>
  }
}

[image of music]

If the repeated section is to be unfolded and has different words, simply enter all the words:

\score {
  <<
    \new Staff {
      \new Voice = "melody" {
        \relative {
          a'4 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.
      }
    }
  >>
}

[image of music]

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 {
          a'4 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.
	}
      >>
    }
  >>
}

[image of music]

More verses may be added in a similar way:

\score {
  <<
    \new Staff {
      \new Voice = "singleVoice" {
        \relative {
	  a'4 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.
    }
  >>
}

[image of music]

However, if this construct is embedded within a multi-staff context such as a ChoirStaff the lyrics of the second and third verses will appear beneath the bottom staff.

To position them correctly use alignBelowContext:

\score {
  <<
    \new Staff {
      \new Voice = "melody" {
        \relative {
	  a'4 a a a
	  \repeat volta 3 { b4 b b b }
          c4 c c c
	}
      }
    }
    \new Lyrics = "firstVerse" \lyricsto "melody" {
      Not re -- peat -- ed.
      <<
        { The first time words.	}
	\new Lyrics = "secondVerse"
        \with { alignBelowContext = "firstVerse" } {
	  \set associatedVoice = "melody"
	  Sec -- ond time words.
	}
	\new Lyrics = "thirdVerse"
        \with { alignBelowContext = "secondVerse" } {
	  \set associatedVoice = "melody"
	  The third time words.
	}
      >>
      The end sec -- tion.
    }
    \new Voice = "harmony" {
      \relative {
        f'4 f f f \repeat volta 2 { g8 g g4 g2 } a4 a8. a16 a2
      }
    }
  >>
}

[image of music]

Repeats with alternative endings

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

\score {
  <<
    \new Staff {
      \time 2/4
      \new Voice = "melody" {
        \relative {
          a'4 a a a
          \repeat volta 2 { b4 b }
          \alternative {
            \volta 1 { b b }
            \volta 2 { b c }
          }
        }
      }
    }
    \new Lyrics {
      \lyricsto "melody" {
        Not re -- peat -- ed.
        \repeat volta 2 { Re -- peat -- }
        \alternative {
          \volta 1 { ed twice. }
          \volta 2 { ed twice. }
        }
      }
    }
  >>
}

[image of music]

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

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

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

\score {
  <<
    \new Staff {
      \time 2/4
      \new Voice = "melody" {
        \relative {
          \repeat volta 2 { b'4 b }
          \alternative {
            \volta 1 { b b }
            \volta 2 { 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.
      }
    }
  >>
}

[image of music]

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 {
          \set melismaBusyProperties = #'()
          \repeat volta 2 { b'4 b ~}
          \alternative {
            \volta 1 { b b }
            \volta 2 { b \repeatTie c }
          }
          \unset melismaBusyProperties
          c4 c
        }
      }
    }
    \new Lyrics {
      \lyricsto "melody" {
        \repeat volta 2 { Here's a __ }
        \alternative {
          \volta 1 { \skip 1 verse }
          \volta 2 { \skip 1 sec }
        }
        ond one.
      }
    }
  >>
}

[image of music]

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 {
          \repeat volta 2 { b'4 b ~}
          \alternative {
            \volta 1 { b b }
            \volta 2 { 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.
      }
    }
  >>
}

[image of music]

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 {
          \repeat volta 2 { b'4 b ~}
          \alternative {
            \volta 1 { b b }
            \volta 2 { 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.
      }
    }
  >>
}

[image of music]

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

[image of music]

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 {
        <<
          {
            \voiceOne
            e'4 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
    }
  >>
}

[image of music]

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


Polyphony with shared lyrics

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

soprano = \relative { b'8( c d c) d2 }
alto = \relative { g'2 b8( a g a) }
words = \lyricmode { la __ la __ }

\new Staff <<
  \new Voice = "sopranoVoice" { \voiceOne \soprano }
  \new Voice { \voiceTwo \alto }
  \new Lyrics \lyricsto "sopranoVoice" \words
>>

[image of music]

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

soprano = \relative { b'8( c d c) d2 }
alto = \relative { g'2 b8( a g a) }
aligner = \relative { b'8( c d c) b( a g a) }
words = \lyricmode { la __ la __ }

\new Staff <<
  \new Voice { \voiceOne \soprano }
  \new Voice { \voiceTwo \alto }
  \new NullVoice = "aligner" \aligner
  \new Lyrics \lyricsto "aligner" \words
>>

[image of music]

This method also can be used with the \partCombine function, which does not allow lyrics on its own:

soprano = \relative { b'8( c d c) d2 }
alto = \relative { g'2 b8( a g a) }
aligner = \relative { b'8( c d c) b( a g a) }
words = \lyricmode { la __ la __ }

\new Staff <<
  \new Voice \partCombine \soprano \alto
  \new NullVoice = "aligner" \aligner
  \new Lyrics \lyricsto "aligner" \words
>>

[image of music]

Known issues and warnings

The \addlyrics function only works with Voice lyrics and so cannot be used with NullVoice.

The \partCombine function is described in Automatic part combining.

Lastly, this method can be used even when the voices are in different staves, and is not limited to only two voices:

soprano = \relative { b'8( c d c) d2 }
altoOne = \relative { g'2 b8( a b4) }
altoTwo = \relative { d'2 g4( fis8 g) }
aligner = \relative { b'8( c d c) d( d d d) }
words = \lyricmode { la __ la __ }

\new ChoirStaff \with {\accepts NullVoice } <<
  \new Staff \soprano
  \new NullVoice = "aligner" \aligner
  \new Lyrics \lyricsto "aligner" \words
  \new Staff \partCombine \altoOne \altoTwo
>>

[image of music]


2.1.3 Stanzas


Adding stanza numbers

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

\new Voice \relative {
  \time 3/4 g'2 e4 a2 f4 g2.
} \addlyrics {
  \set stanza = "1. "
  Hi, my name is Bert.
} \addlyrics {
  \set stanza = "2. "
  Oh, ché -- ri, je t'aime
}

[image of music]

These numbers are put just before the start of the first syllable. Two lines of a stanza can also be grouped together, for example in case of a repeat with different lyrics:

leftbrace = \markup {
  \override #'(font-encoding . fetaBraces)
  \lookup "brace80"
}

stanzaOneOne = \lyricmode {
  \set stanza = \markup {
    \column { \vspace #.33 "1. "}
    \leftbrace
  }
  Child, you’re mine and I love you.
  Lend thine ear to what I say.
}

stanzaOneThree = \lyricmode {
  Child, I have no great -- er joy
  Than to have you walk in truth.
}

\new Voice {
  \repeat volta 2 {
    c'8 c' c' c' c' c' c'4
    c'8 c' c' c' c' c' c'4
  }
}
\addlyrics { \stanzaOneOne }
\addlyrics { \stanzaOneThree }

[image of music]


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

[image of music]


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 \relative {
  \time 3/4 g'2 e4 a2 f4 g2.
} \addlyrics {
  \set vocalName = "Bert "
  Hi, my name is Bert.
} \addlyrics {
  \set vocalName = "Ernie "
  Oh, ché -- ri, je t'aime
}

[image of music]


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 \new Voice = "lahlah" {
    \set Staff.autoBeaming = ##f
    c'4
    \slurDotted
    f8.[( g16])
    a4
  }
  \new Lyrics \lyricsto "lahlah" {
    more slow -- ly
  }
  \new Lyrics \lyricsto "lahlah" {
    go
    \set ignoreMelismata = ##t
    fas -- ter
    \unset ignoreMelismata
    still
  }
>>

[image of music]

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 {
    f'4 \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.
  }
>>

[image of music]

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. In the case of a grace note at the very beginning of a piece of music, using a \with, or a \context block within \layout, is recommended:

<<
  \new Voice = melody \relative c' {
    \grace { c16( d e f }
    g1) f
  }
  \new Lyrics \with { includeGraceNotes = ##t }
  \lyricsto melody {
    Ah __ fa
  }
>>

[image of music]

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 \new Voice = "lahlah" {
    \set Staff.autoBeaming = ##f
    c'4
    <<
      \new Voice = "alternative" {
        \voiceOne
        \tuplet 3/2 {
          % 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
  } >>

[image of music]

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 several different ways to force linebreaks when using \markup. For inputting a whole string you may use \string-lines with manually inserted \n or automatic line breaks as entered or \wordwrap-string. If inner formatting code is used a combination of \line and \column is recommended.

melody = \relative {
  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
  >>
}

\markup \column \string-lines
  "Verse 2. \n Everywhere that Mary went \n The lamb was sure to go."

\markup \column \string-lines
  "Verse 3.
   All the children laughed and played,
   To see a lamb at school."

\markup \column {
  \line \italic { Verse 4. }
  \line { And so the teacher turned it out, }
  \line { But still it lingered near. } }

\markup \wordwrap-string "
  Verse 5.

  Mary took it home again,

  It was against the rule."

[image of music]


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'4 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 {
    % moves the column off the left margin;
    % can be removed if space on the page is tight
    \hspace #0.1
    \column {
      \line { \bold "2."
        \column {
          "This is verse two."
          "It has two lines."
        }
      }
      % adds vertical spacing between verses
      \combine \null \vspace #0.1
      \line { \bold "3."
        \column {
          "This is verse three."
          "It has two lines."
        }
      }
    }
    % adds horizontal spacing between columns
    \hspace #0.1
    \column {
      \line { \bold "4."
        \column {
          "This is verse four."
          "It has two lines."
        }
      }
      % adds vertical spacing between verses
      \combine \null \vspace #0.1
      \line { \bold "5."
        \column {
          "This is verse five."
          "It has two lines."
        }
      }
    }
    % gives some extra space on the right margin;
    % can be removed if page space is tight
    \hspace #0.1
  }
}

[image of music]

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:

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 }
  \new Staff \relative c'' {
    a4 e c8 e r4
    b2 c4( d)
  }
  \addlyrics { One day this shall be free __ }
>>

[image of music]

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 rehearsal of a cappella choral works. The notes for each vocal part are placed in a Voice context, with each staff being given either a single vocal part (i.e., one Voice) or a pair of vocal parts (i.e., two Voices).

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

Several common topics in choral music are described fully elsewhere:

Predefined commands

\oneVoice, \voiceOne, \voiceTwo.

See also

Learning Manual: Four-part SATB vocal score, Vocal ensembles templates.

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:

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 { g'4\f g g g }
      }
    }
    \new Staff {
      \new Voice {
        \relative { d'4 d d\p d }
      }
    }
  >>
  \layout {
    \context {
      \Score
      \override DynamicText.direction = #UP
      \override DynamicLineSpanner.direction = #UP
    }
  }
}

[image of music]

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, Breaks, Vertical spacing.

Internals Reference: VerticalAxisGroup, StaffGrouper.

Selected Snippets

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

[image of music]

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:

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

In addition to vocal and stage ensembles, most of the following notions may apply to nearly any orchestral and ensemble music:

See also

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

Notation Reference: Creating footnotes, 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 {
        \clef "G_8"
        c'4 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 {
        a4 a a a
        a4 a a a
      }
    }
  >>
}

[image of music]

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.

\relative c' {
  \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
}

[image of music]

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

kaspar = {
  \clef "G_8"
  \set Staff.shortVocalName = "Kas."
  \set Staff.midiInstrument = "voice oohs"
  <>^\markup \smallCaps "Kaspar"
}

melchior = {
  \clef "bass"
  \set Staff.shortVocalName = "Mel."
  \set Staff.midiInstrument = "choir aahs"
  <>^\markup \smallCaps "Melchior"
}

\relative c' {
  \kaspar
  c4 c c c
  \melchior
  a4 a a a
  \kaspar
  c4 c c c
}

[image of music]

See also

Learning Manual: Organizing pieces with variables.

Notation Reference: Text, Text markup commands.


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 {
  s4 s4 e'' g
}
\addQuote "flute" { \flute }

pianoRH = \relative {
  c''4. g8
  % position name of cue-ing instrument just before the cue notes,
  % and above the staff
  <>^\markup { \right-align { \tiny "Flute" } }
  \cueDuring "flute" #UP { g4 bes4 }
}
pianoLH = \relative { c4 <c' e> e, <g c> }

\score {
  \new PianoStaff <<
    \new Staff {
      \pianoRH
    }
    \new Staff {
      \clef "bass"
      \pianoLH
    }
  >>
}

[image of music]

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.

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
  <>_\markup { \right-align { \tiny "Clar." } }
  \cueDuring "clarinet" #DOWN { c4. g8 }
  g4 bes4
}
pianoLH = \relative { c4 <c' e> e, <g c> }

\score {
  <<
    \new PianoStaff <<
      \new Staff {
        \new Voice {
          \pianoRH
        }
      }
      \new Staff {
        \clef "bass"
        \pianoLH
      }
    >>
  >>
}

[image of music]

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
   (instrument name dir music)
   (string? string? ly:dir? ly:music?)
   #{
     \cueDuring $instrument #dir {
       \once \override TextScript.self-alignment-X = #RIGHT
       \once \override TextScript.direction = $dir
       <>-\markup { \tiny #name }
       $music
     }
   #})

flute = \relative c'' {
  \transposition c'
  s4 s4 e g
}
\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
      }
    >>
  >>
}

[image of music]

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

\relative {
  a'4^\markup { \smallCaps { Alex - } \italic { He's gone } } a a a
  a4 a a^\markup { \smallCaps { Bethan - } \italic Where? } a
  a4 a a a
}

[image of music]

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

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

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

Here is an example illustrating how this might be done.

music = \relative {
  \repeat unfold 3 { a'4 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 }
    }
  >>
}

[image of 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 typesetting 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 = { \hide Staff.Stem }

\relative c' {
  \stemOff
  a'4 b c2 |
}

[image of music]

Chants often omit measure bar lines or use shortened or dotted bar lines to indicate pauses in the music. To set a chant with no musical meter, see Unmetered music. To retain all the effects of a time signature but disable automatic measure bar lines, set measureBarType to '(). Without regular bar lines, you might need to take steps to control horizontal spacing; see Line breaking.

\score {
  \new StaffGroup <<
    \new Staff {
      \relative {
        a'4 b c2 |
        a4 b c2 | \section
        a4 b c2 |
      }
    }
    \new Staff {
      \relative {
        a'4 b c2 |
        a4 b c2 | \section
        a4 b c2 |
      }
    }
  >>
  \layout {
    \context {
      \Staff
      measureBarType = #'()
      forbidBreakBetweenBarLines = ##f
    }
  }
}

[image of music]

Measure bar lines can also be modified on a staff-by-staff basis; see Modifying context plug-ins.

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

\relative a' {
  a4
  \cadenzaOn
  b c2
  a4 b c2
  \bar "'"
  a4 b c2
  \bar ","
  a4 b c2
  \bar ";"
  a4 b c2
  \bar "!"
  a4 b c2
  \bar "||"
}

[image of music]

Alternatively, the notation used in Gregorian chant for pauses or rests is sometimes used even though the rest of the notation is modern.

divisioMinima = \caesura
divisioMaior = { \caesura \shortfermata }
divisioMaxima = { \caesura \fermata }
finalis = \section

\score {
  \relative {
    g'2 a4 g
    \divisioMinima
    g2 a4 g
    \divisioMaior
    g2 a4 g
    \divisioMaxima
    g2 a4 g
    \finalis
  }
  \layout {
    \context {
      \Staff
      \remove Caesura_engraver
      \consists Divisio_engraver
      \EnableGregorianDivisiones
      caesuraType = #'((breath . chantquarterbar))
      measureBarType = #'()
      forbidBreakBetweenBarLines = ##f
    }
  }
}

[image of music]

Chants usually omit the time signature and often omit the clef too.

\score {
  \new Staff {
    \relative {
      a'4 b c2 |
      a4 b c2 |
      a4 b c2 |
    }
  }
  \layout {
    \context {
      \Staff
      \remove Time_signature_engraver
      \remove Clef_engraver
      measureBarType = #'()
      forbidBreakBetweenBarLines = ##f
    }
  }
}

[image of music]

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'1 | c2 b | a1 |
  a1 | d2 c | c b | c1 |
}

AltoMusic = \relative {
  e'1 | g2 g | f1 |
  f1 | f2 e | d d | e1 |
}

TenorMusic = \relative {
  c'1 | c2 c | c1 |
  d1 | g,2 g | g g | g1 |
}

BassMusic =  \relative {
  c1 | e2 e | f1 |
  d1 | b2 c | g' g | c,1 |
}

global = {
  \time 2/2
  \skip 1*3 \section
  \skip 1*4 \fine
}

% 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)
          fineBarType = "||"
        }
        \context {
          \Staff
          \remove Time_signature_engraver
        }
      }
    }  % End score
  }
}  % End markup

[image of music]

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 Psalm chant, where verses aren’t always the same length.

stemOff = \hide Staff.Stem
stemOn  = \undo \stemOff

\score {
  \new Staff \with { \remove "Time_signature_engraver" }
  {
    \key g \minor
    \cadenzaOn
    \stemOff a'\breve bes'4 g'4
    \stemOn a'2 \section
    \stemOff a'\breve g'4 a'4
    \stemOn f'2 \section
    \stemOff a'\breve^\markup { \italic flexe }
    \stemOn g'2 \fine
  }
}

[image of music]

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 GregorianTranscriptionStaff <<
    \new GregorianTranscriptionVoice = "melody" \chant
    \new GregorianTranscriptionLyrics = "one" \lyricsto melody \verba
  >>
}

[image of music]

See also

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

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

[image of music]

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

[image of music]

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

[image of music]

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

[image of music]

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

[image of music]

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.

See also

Learning Manual: Psalms, Vocal ensembles templates.

Notation Reference: Fonts, Formatting text.


Phrase bar lines in hymn tunes

The \caesura command can be configured to create phrase bar lines that interact well with other automatic bar lines (see Automatic bar lines).

In the following examples, the source code for the tune in ‘old-hundredth-example.ly’ uses \caesura between poetic lines and \fine at the end. There are no \fermata or \bar commands; those symbols appear in the output because of the caesura configuration.

The Boston Handel and Haydn Society Collection of Church Music (1830) has a thick bar after each phrase. For this tune, it also has fermatas over the bar lines:

\layout {
  \context {
    \Score 
    caesuraType = #'((bar-line . ".")
                     (scripts . (fermata)))
    fineBarType = ".."
  }
}
\include "old-hundredth-example.ly"

[image of music]

J.S. James’ Original Sacred Harp (1911) has a thick bar when a line is broken in mid-measure at the end of a phrase.

\layout {
  \context {
    \Score 
    caesuraType = #'((underlying-bar-line . "x-."))
    fineBarType = ".."
  }
}
\include "old-hundredth-example.ly"

[image of music]


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 a bar line 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 \caesura \break
  s2 | s1 | s2 \breathe s2 | s1 | s2 \fine
}

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

\layout {
  \context {
    \Score
    caesuraType = #'((bar-line . "||"))
    fineBarType = "||"
  }
}

\paper {  % Start paper block
  indent = 0     % don't indent first system
  line-width = 130   % shorten line length to suit music
}  % End paper block

[image of music]


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

[image of music]

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:

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, or explicitly instantiated, for example by using the empty chord, <>, see Chorded notes.

\new PianoStaff <<
  \new Staff = "up" {
    % enforce creation of all contexts at this point of time
    <>
    \change Staff = "down" c2
    \change Staff = "up" c'2
  }
  \new Staff = "down" {
    \clef bass
    % keep staff alive
    s1
  }
>>

[image of music]

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

[image of music]

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 = #4
    e''2\p\< d''\>
    c''1\!
  }
  \new Staff = "down" <<
    {
      \clef bass
      s4. e,8\rest g,2\rest
      c1
    } \\ {
      c8\( g c'
      \change Staff = "up"
      e' g' b'-3 a' g'\)
      f'1
    }
  >>
>>

[image of music]

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.

See also

Learning Manual: Fixing overlapping notation.

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

Snippets: Keyboards.

Internals Reference: Beam, ContextChange.

Known issues and warnings

Beam collision avoidance does not work for automatic beams that end right before a change in staff. In this case use manual beams.


Changing staff automatically

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

\autoChange …music

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

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

[image of music]

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

music = {
  g8 b a c' b8 d' c'8 e'
  d'8 r f' g' a'2
}

\autoChange d' \music
\autoChange b \with { \clef soprano } \music
\autoChange d' \with { \clef alto } \with { \clef tenor } \music

[image of music]

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 {
        g8 b a c b d c e
        d8 r fis, g a2
      }
    }
  }
  \new Staff = "down" {
    \key g \major
    \clef bass
  }
>>

[image of music]

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
    c'1
    \change Staff = "two"
    b2 a
  }
  \new Staff = "two" {
    \clef bass
    s1*2
  }
>>

[image of music]

A staff-change line between chords connects the chords’ “last notes” as written in the source file; this can be used to quickly adjust the line’s vertical start and end positions.

\new PianoStaff <<
  \new Staff = "one" {
    <c' e' g'>1
    \showStaffSwitch
    \change Staff = "two"
    <a c' f>1
    \hideStaffSwitch
    \change Staff = "one"
    <e' g' c'>1
    \showStaffSwitch
    \change Staff = "two"
    <f a c'>1
  }
  \new Staff = "two" {
    \clef bass
    s1*4
  }
>>

[image of music]

Predefined commands

\showStaffSwitch, \hideStaffSwitch.

See also

Snippets: Keyboards.

Internals Reference: Note_head_line_engraver, VoiceFollower.

Selected Snippets

Cross staff stems

This snippet shows the use of the Span_stem_engraver and \crossStaff to connect stems across staves automatically.

The stem length need not be specified, as the variable distance between noteheads and staves is calculated automatically.

\layout {
  \context {
    \PianoStaff
    \consists "Span_stem_engraver"
  }
}

{
  \new PianoStaff <<
    \new Staff {
      <b d'>4 r d'16\> e'8. g8 r\!
      e'8 f' g'4 e'2
    }
    \new Staff {
      \clef bass
      \voiceOne
      \autoBeamOff
      \crossStaff { <e g>4 e, g16 a8. c8} d
      \autoBeamOn
      g8 f g4 c2
    }
  >>
}

[image of music]

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

[image of music]

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.

\relative {
  c''4\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
}

[image of music]

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.

\relative {
  c''4\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 "|."
}

[image of music]

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.

A complete list of all available accordion registers can be found in Accordion Registers.

Selected Snippets

Accordion register symbols

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

#(use-modules (lily accreg))

\new PianoStaff
<<
  \new Staff \relative {
    \clef treble
    \discant "10"
    r8 s32 f'[ bes f] s e[ a e] s d[ g d] s16 e32[ a]
    <<
      { r16 <f bes> r <e a> r <d g> }
      \\
      { d r a r bes r }
    >> |
    <cis e a>1
  }

  \new Staff \relative {
    \clef treble
    \freeBass "1"
    r8 d'32 s16. c32 s16. bes32 s16. a32[ cis] s16
    \clef bass \stdBass "Master"
    <<
      { r16 <f, bes d>^"b" r <e a c>^"am" r <d g bes>^"gm" |
      <e a cis>1^"a" }
      \\
      { d8_"D" c_"C" bes_"B" | a1_"A" }
    >>
  }
>>

[image of music]

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:

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
cis''1_\markup \concat \vcenter {
  [D \flat C \sharp B|E \sharp F \sharp G A \flat] }
c''!1_\markup \concat \vcenter {
  [ C \natural ] }

[image of music]

or pedal diagrams:

\textLengthOn
cis''1_\markup { \harp-pedal "^v-|vv-^" }
c''!1_\markup { \harp-pedal "^o--|vv-^" }

[image of music]

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

[image of music]

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:

See also

Learning Manual: String quartet templates.

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:

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

[image of music]

Roman numerals can be used for string numbers (rather than the default circled Arabic numbers), as explained in String number indications.

Alternatively, string indications may be printed using markup commands; articulation scripts may also indicate open strings.

a'4 \open
\romanStringNumbers
a'\2
a'2^\markup { \small "sul A" }

[image of music]

Predefined commands

\downbow, \upbow, \open, \romanStringNumbers.

See also

Notation Reference: Articulations and ornamentations, String number indications, 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.

\relative d'' {
  d4 e4.
  \harmonicsOn
  d8 e e
  d4 e4.
  \harmonicsOff
  d8 e e
}

[image of music]

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:

d''2^\flageolet d''_\flageolet

[image of music]

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.

\relative e' {
  <e a\harmonic>2.  <c g'\harmonic>4
  \set harmonicDots = ##t
  <e a\harmonic>2.  <c g'\harmonic>4
}

[image of music]

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.

\relative {
  c'4\snappizzicato
  <c' e g>4\snappizzicato
  <c' e g>4^\snappizzicato
  <c, e g>4_\snappizzicato
}

[image of music]


2.4 Fretted string instruments

[image of music]

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:

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.

\clef "treble_8"
c4\5 e\4 g2\3
<c\5 e\4 g\3>1

[image of music]

When fingerings and string indications are used together, their placement can be controlled by the order in which the two items appear in the code only if they appear inside of an explicit chord: applied to whole chords or single notes outside of chords, fingerings are placed using a different mechanism.

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

[image of music]

String numbers may also, as is customary with unfretted strings, be printed in Roman numerals and placed below the staff rather than above.

\clef "treble_8"
c'2\2
a\3
\romanStringNumbers
c'\2
\set stringNumberOrientations = #'(down)
a\3
\arabicStringNumbers
g1\4

[image of music]

Most behaviors of string number indications (namely, the StringNumber object), including their placement, may be set in the same way as fingerings: see Fingering instructions.

Predefined commands

\arabicStringNumbers, \romanStringNumbers.

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 {
  a,8 a' <c e> a
  d,8 a' <d f> a
}

[image of music]

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

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

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

[image of music]

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~ 2\!
  c'2.\prall\)
}

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

[image of music]

By default pitches are assigned to the lowest playing position on the fretboard (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 don’t want to have string number indications appear in traditional notation, you can override the respective stencil. Usually it will be more comfortable to define the playing position by using the value of minimumFret. The default value for minimumFret is 0.

Even when minimumFret is set, open strings are used whenever possible. This behavior can be changed by setting restrainOpenStrings to #t.

\layout { \omit Voice.StringNumber }
\new StaffGroup <<
   \new Staff \relative {
     \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 {
     c16 d e f g4
     c,16\5 d\5 e\4 f\4 g4\4
     \set TabStaff.minimumFret = #5
     \set TabStaff.restrainOpenStrings = ##t
     c,16 d e f g4
   }
>>

[image of music]

Chord constructs can be repeated by the chord repetition symbol q. In combination with tabulatures, its behavior of removing string and finger numbers alongside with other events is cumbersome, so you’ll want to run

\chordRepeats #'(string-number-event fingering-event)

explicitly on music expressions in tabulature using Chord repetition. This particular command is so common that it is available as \tabChordRepeats.

guitar = \relative {
  r8 <gis-2 cis-3 b-0>~ q4 q8~ 8 q4
}

\new StaffGroup <<
  \new Staff {
    \clef "treble_8"
    \guitar
  }
  \new TabStaff {
    \tabChordRepeats \guitar
  }
>>

[image of music]

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

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

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

[image of music]

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

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

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

[image of music]

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

\layout { \omit Voice.StringNumber }
firstHarmonic = {
  d'4\4\harmonic
  g'4\3\harmonic
  b'2\2\harmonic
}
\score {
  <<
    \new Staff {
      \clef "treble_8"
      \firstHarmonic
    }
    \new TabStaff { \firstHarmonic }
  >>
}

[image of music]

Note that the command \harmonic must always be attached to single notes (possibly inside of a chord) instead of whole chords. 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 {
      \clef "treble_8"
      \fretHarmonics
    }
    \new TabStaff { \fretHarmonics }
  >>
}

[image of music]

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 {
      \clef "treble_8"
      \ratioHarmonics
    }
    \new TabStaff { \ratioHarmonics }
  >>
}

[image of music]

String bendings can be added to tablature notation. A bending is introduced by appending \^ to the note or chord to be bent; it terminates automatically at the next note or chord. Available are the following styles: the default prints a curve with an arrow head up or down, 'hold a dashed horizontal line, 'pre-bend a vertical line with an arrow head, and 'pre-bend-hold a vertical line with an arrow head continued by a dashed line.

bend-styles = {
  <>^"default"
  f'4\^ g'4\^ f'2

  <>^"'hold"
  \grace f'4\^ g'1\bendHold \^ g'1

  <>^"'pre-bend"
  \grace f'4\preBend \^ g'1\bendHold \^ g'1

  <>^"'pre-bend-hold"
  \grace f'4\preBendHold \^ g'1\bendHold \^ g'1\^ f'

  \bar "|."
}

\score {
  \new StaffGroup
  <<
    \new Staff {
      \override TextScript.font-size = -2
      \clef "G_8"
      \bend-styles
    }
    \new TabStaff \bend-styles
  >>
  \layout {
    \context {
      \Voice
      \omit StringNumber
    }
    \context {
      \TabStaff
      minimumFret = #5
    }
    \context {
      \TabVoice
      \consists Bend_spanner_engraver
    }
  }
}

[image of music]

Open strings are usually not bent. To have them bent as well set the property bend-me to #t. To exclude other notes from being bent set it to #f.

mus = {
  <>^"default"
  <a b f'>4\^
  <ais b fis'>\^
  <a b f'>2

  <>^"bend open strings"
  <a \tweak bend-me ##t b f'>4\^
  <ais \tweak bend-me ##t bis fis'>\^
  <a b f'>2

  <>^"exclude other strings"
  <g \tweak bend-me ##f b\3 d'>4\^
  <a e'\2 >\^
  <g \tweak bend-me ##f b\3 d'>2

  \bar "|."
}

\score {
  \new StaffGroup
  <<
    \new Staff {
      \override TextScript.font-size = -2
      \clef "G_8"
      \mus
    }
    \new TabStaff \mus
  >>
  \layout {
    \context {
      \Voice
      \omit StringNumber
    }
    \context {
      \TabVoice
      \consists Bend_spanner_engraver
    }
  }
}

[image of music]

For consecutive bendings the starting bend may need to have an appropriate setting for details.successive-level. For convenience there is the function bendStartLevel, taking an integer.

printNext = -\tweak details.target-visibility ##t \etc

mus = {
  c'4\3\^ cis'\3 \^ d'2\3

  \grace bes4\3\preBendHold \bendStartLevel 2 \printNext \^
  d'4\3\bendHold \^ d'2\3\^ des'4\3 \^ c'1\3

  \bar "|."
}

\score {
  \new StaffGroup
  <<
    \new Staff {
      \override TextScript.font-size = -2
      \clef "G_8"
      \mus
    }
    \new TabStaff \mus
  >>
  \layout {
    \context {
      \Voice
      \omit StringNumber
    }
    \context {
      \TabVoice
      \consists Bend_spanner_engraver
    }
  }
}

[image of music]

Per default the BendSpanner ends at the following note or chord even if it is tied to the starting note or chord. A single NoteColumn may be skipped by using \skipNC. A group of NoteColumns can be skipped by using \skipNCs at the beginning and \endSkipNCs at the end.

bends-with-ties-and-skips = {
  a'4~\^ \skipNC a'4~ \skipNC a'4 b'4
  a'4~ a'4~\^ \skipNC a'4 b'4
  a'4~ a'4~ a'4\^ b'4
  c'2\^ d'~ \bendHold \^ \skipNC d'~ d'\^ c'
  \grace { c'8-\preBendHold \^ }
  \skipNCs d'2~ d'2~ \endSkipNCs d'\^ c'2
  \bar "|."
}

\score {
  \new StaffGroup
  <<
    \new Staff {
      \clef "G_8"
      \bends-with-ties-and-skips
    }
    \new TabVoice \bends-with-ties-and-skips
  >>
  \layout {
    \context {
      \Voice
      \omit StringNumber
    }
    \context {
      \TabStaff
      minimumFret = #3
      restrainOpenStrings = ##t
    }
    \context {
      \TabVoice
      \consists Bend_spanner_engraver
    }
  }
}

[image of music]

Predefined commands

\skipNCs, \skipNC, \endSkipNCs.

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.concaveness = #10000
    g,,16 b d g b d g b
  }
}

[image of music]

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"
        \new Voice = "upper" \upper
        \new Voice = "lower" \lower
      >>
      \new TabStaff = "guitar tab" <<
        \new TabVoice = "upper" \upper
        \new TabVoice = "lower" \lower
      >>
    >>
  >>
}

[image of music]

Open string harmonics in tablature

This snippet demonstrates open-string harmonics.

openStringHarmonics = {
  \textSpannerDown
  \override TextSpanner.staff-padding = #3
  \override TextSpanner.dash-fraction = #0.3
  \override TextSpanner.dash-period = #1

  %first harmonic
  \override TextSpanner.bound-details.left.text =
    \markup\small "1st harm. "
  \harmonicByFret #12 e,2\6\startTextSpan
  \harmonicByRatio #1/2 e,\6\stopTextSpan

  %second harmonic
  \override TextSpanner.bound-details.left.text =
    \markup\small "2nd harm. "
  \harmonicByFret #7 e,\6\startTextSpan
  \harmonicByRatio #1/3 e,\6
  \harmonicByFret #19 e,\6
  \harmonicByRatio #2/3 e,\6\stopTextSpan
  %\harmonicByFret #19 < e,\6 a,\5 d\4 >
  %\harmonicByRatio #2/3 < e,\6 a,\5 d\4 >

  %third harmonic
  \override TextSpanner.bound-details.left.text =
    \markup\small "3rd harm. "
  \harmonicByFret #5 e,\6\startTextSpan
  \harmonicByRatio #1/4 e,\6
  \harmonicByFret #24 e,\6
  \harmonicByRatio #3/4 e,\6\stopTextSpan
  \break

  %fourth harmonic
  \override TextSpanner.bound-details.left.text =
    \markup\small "4th harm. "
  \harmonicByFret #4 e,\6\startTextSpan
  \harmonicByRatio #1/5 e,\6
  \harmonicByFret #9 e,\6
  \harmonicByRatio #2/5 e,\6
  \harmonicByFret #16 e,\6
  \harmonicByRatio #3/5 e,\6\stopTextSpan

  %fifth harmonic
  \override TextSpanner.bound-details.left.text =
    \markup\small "5th harm. "
  \harmonicByFret #3 e,\6\startTextSpan
  \harmonicByRatio #1/6 e,\6\stopTextSpan
  \break

  %sixth harmonic
  \override TextSpanner.bound-details.left.text =
    \markup\small "6th harm. "
  \harmonicByFret #2.7 e,\6\startTextSpan
  \harmonicByRatio #1/7 e,\6\stopTextSpan

  %seventh harmonic
  \override TextSpanner.bound-details.left.text =
    \markup\small "7th harm. "
  \harmonicByFret #2.3 e,\6\startTextSpan
  \harmonicByRatio #1/8 e,\6\stopTextSpan

  %eighth harmonic
  \override TextSpanner.bound-details.left.text =
    \markup\small "8th harm. "
  \harmonicByFret #2 e,\6\startTextSpan
  \harmonicByRatio #1/9 e,\6\stopTextSpan
}

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

[image of music]

Fretted-string harmonics in tablature

Demonstrates fretted-string harmonics in tablature

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
  <d''\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 #7 d4\4
  \harmonicByFret #5 g2\3
  %touch harmonics (TCH)
  a4 \harmonicByFret #9 g2.\3
}

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

[image of music]

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\glissando }
  \unHideNotes
  c'4\3
  \afterGrace d'4\3\glissando {
  \stemDown \hideNotes
  g16 }
  \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
      \omit StringNumber
      % or:
      %\override StringNumber.stencil = ##f
    }
  }
}

[image of music]

Chord glissando in tablature

Slides for chords are indicated by default in both Staff and TabStaff.

String numbers are necessary for TabStaff because automatic string calculations are different for chords and for single notes.

myMusic = \relative c' {
  <c e g>1 \glissando <f a c>
}

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

\score {
  <<
    \new Staff {
      \clef "treble_8"
      \myMusic
    }
    \new TabStaff \with { \override Glissando.style = #'none } {
      \myMusic
    }
  >>
}

[image of music]

Hammer on and pull off

Hammer-on and pull-off can be obtained using slurs.

\new TabStaff {
  \relative c' {
    d4( e\2)
    a( g)
  }
}

[image of music]

Hammer on and pull off using voices

The arc of hammer-on and pull-off is upwards in voices one and three and downwards in voices two and four:

\new TabStaff {
  \relative c' {
    << { \voiceOne g2( a) }
    \\ { \voiceTwo a,( b) }
    >> \oneVoice
  }
}

[image of music]

Hammer on and pull off using chords

When using hammer-on or pull-off with chorded notes, only a single arc is drawn. However “double arcs” are possible by setting the doubleSlurs property to #t.

\new TabStaff {
  \relative c' {
    % chord hammer-on and pull-off
    \set doubleSlurs = ##t
    <g' b>8( <a c> <g b>)
  }
}

[image of music]

See also

Notation Reference: Chord repetition, Glissando, Harmonics, Stems, Written-out repeats.

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

[image of music]

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 Voice \with {
    \omit StringNumber
  } {
    \clef "bass_8"
    \relative {
      c,4 d e f
    }
  }
  \new TabStaff \with {
    stringTunings = #bass-tuning
  } {
    \relative {
      c,4 d e f
    }
  }
>>

[image of music]

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-tunings-init.ly’.

Any desired string tuning can be created. The \stringTuning function can be used to define a string tuning which can be used to set stringTunings for the current context.

Its argument is a chord construct defining 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 {
    \set Staff.stringTunings = \stringTuning <c' g' d'' a''>
    \mynotes
  }
>>

[image of music]

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 previous example could also be written as follows:

custom-tuning = \stringTuning <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
  }
>>

[image of music]

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

\stringTuning creates such an object from chord input.

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.

To let all TabStaff contexts use the same custom tuning by default, you can use

\layout {
  \context {
    \TabStaff
    stringTunings = \stringTuning <c' g' d'' a''>
  }
}

A modern tab clef can also be used.

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

[image of music]

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

TabStaff may support microtones like quarter tones, which can be played using bendings. supportNonIntegerFret = ##t needs to be set in Score context. However, microtones are not supported in FretBoards.

\layout {
  \context {
    \Score
    supportNonIntegerFret = ##t
  }
}

custom-tuning = \stringTuning <e, a, d ges beh eeh'>

mus = \relative {
  eeses'4
  eeseh
  ees
  eeh
  e
  eih
  eis
  eisih
  eisis
}

<<
  \new Staff << \clef "G_8" \mus >>
  \new TabStaff \with { stringTunings = \custom-tuning } \mus
>>

[image of music]

See also

Notation Reference: Absolute octave entry, Predefined fret diagrams.

Installed Files: ‘ly/string-tunings-init.ly’, ‘scm/tablature.scm’.

Snippets: Fretted strings.

Internals Reference: Tab_note_heads_engraver, Scheme functions.

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.

<<
  \new ChordNames {
    \chordmode {
      c1 d:m
    }
  }
  \new 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;"
    }
  }
>>

[image of music]

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

<<
  \new ChordNames {
     \chordmode {
       f1 g
     }
  }
  \new 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;"
    }
  }
>>

[image of music]

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

<<
  \new ChordNames {
     \chordmode {
       f1 g
     }
  }
  \new 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;"
    }
  }
>>

[image of music]

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.

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

[image of music]

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

<<
  \new ChordNames {
    \chordmode {
      c1 d:m
    }
  }
  \new 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;"
    }
  }
>>

[image of music]

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

<<
  \new ChordNames {
    \chordmode {
      c1 d:m
    }
  }
  \new 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;"
    }
  }
>>

[image of music]

Fret-diagrams may be printed left-handed

\markup
  \center-column {
    "C"
    "(left-handed)"
     \override #`(fret-diagram-details . ((handedness . ,LEFT)))
     \fret-diagram "6-x;5-3-3;4-2-2;3-o;2-1;1-o;"
  }

[image of music]

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.

<<
  \new ChordNames {
    \chordmode {
      c1 d:m
    }
  }
  \new 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;"
    }
  }
>>

[image of music]

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

<<
  \new ChordNames {
    \chordmode {
      f1 g
    }
  }
  \new 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-);"
    }
  }
>>

[image of music]

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

<<
  \new ChordNames {
    \chordmode {
      c1 d:m
    }
  }
  \new 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;"
    }
  }
>>

[image of music]

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

Only one indication per string can be included in a \fret-diagram-terse markup. To have multiple indications per string use a fret diagram or \fret-diagram-verbose 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.

<<
    \new ChordNames {
      \chordmode {
        c1 d:m
      }
    }
  \new 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)
      )
    }
  }
>>

[image of music]

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.

Fingering indication dots can be colored as well as parenthesized; the parenthesis’s color can also be altered independently.

Markups can be placed into the dots as well.

<<
    \new ChordNames {
      \chordmode {
        f1 g c c b
      }
    }
  \new 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 g c' e' g'>1^\markup {
      \fret-diagram-verbose #'(
        (capo 3)
        (mute 6)
        (place-fret 4 5 1)
        (place-fret 3 5 2)
        (place-fret 2 5 3)
      )
    }
    \override Voice.TextScript.size = 1.4
    <c g c' e' g'>1^\markup {
      \fret-diagram-verbose #'(
        (place-fret 6 3 1 red parenthesized default-paren-color)
        (place-fret 5 3 1 inverted)
        (place-fret 4 5 2 blue parenthesized)
        (place-fret 3 5 3 blue)
        (place-fret 2 5 4 blue)
        (place-fret 1 3 1 inverted)
      )
    }
    \override Voice.TextScript.size = 1.5
    <b, fis b dis' fis'>1^\markup
      \override #'(fret-diagram-details . ((finger-code . in-dot)))
      \fret-diagram-verbose #`(
        (place-fret 5 2 1)
        (place-fret 4 4 "fis" red)
        (place-fret 3 4 "b" red)
        (place-fret
          2 4
          ,#{ \markup
                \concat {
                  \vcenter "d"
                  \fontsize #-5
                  \musicglyph "accidentals.sharp"} #}
          red)
        (place-fret 1 2 1)
      )
  }
>>

[image of music]

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

[image of music]

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

[image of music]

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"
\new FretBoards {
  \chordmode {
    c1 d
  }
}

[image of music]

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 Staff.stringTunings = #ukulele-tuning
  \myChords
}

[image of music]

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 Staff.stringTunings = #mandolin-tuning
  \myChords
}

[image of music]

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

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

[image of music]

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
}

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

[image of music]

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 }
}
<<
  \new ChordNames {
    \mychordlist
  }
  \new FretBoards {
    \mychordlist
  }
>>

[image of music]

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

See Predefined fretboard diagrams for a complete list of the predefined fret diagrams. If there is no entry in the table for a chord, the FretBoards engraver calculates a fret diagram using the automatic fret diagram functionality, see Automatic fret diagrams.

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

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

[image of music]

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
}

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

[image of music]

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

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

[image of music]

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

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

[image of music]

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

% shorthand
oo = #(define-music-function
       (grob-path value)
       (list? scheme?)
       #{ \once \override $grob-path = #value #})

<<
  \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
      \oo FretBoard.size #'1.0
      \oo FretBoard.fret-diagram-details.barre-type #'straight
      \oo FretBoard.fret-diagram-details.dot-color #'black
      \oo FretBoard.fret-diagram-details.finger-code #'below-string
      c'
      \oo FretBoard.fret-diagram-details.barre-type #'none
      \oo FretBoard.fret-diagram-details.number-type #'arabic
      \oo FretBoard.fret-diagram-details.orientation #'landscape
      \oo FretBoard.fret-diagram-details.mute-string #"M"
      \oo FretBoard.fret-diagram-details.label-dir #LEFT
      \oo FretBoard.fret-diagram-details.dot-color #'black
      c'
      \oo FretBoard.fret-diagram-details.finger-code #'below-string
      \oo FretBoard.fret-diagram-details.dot-radius #0.35
      \oo FretBoard.fret-diagram-details.dot-position #0.5
      \oo FretBoard.fret-diagram-details.fret-count #3
      d
    }
  }
  \new Voice {
    c'1 | c' | c' | d'
  }
>>

[image of music]

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

[image of music]

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
}

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

[image of music]

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

[image of music]

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.

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

[image of music]

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-);"
<<
  \new ChordNames {
    \chordmode {
      c1 c c
    }
  }
  \new FretBoards {
    <c e g c' e'>1
    \predefinedFretboardsOff
    <c e g c' e'>1
    \predefinedFretboardsOn
    <c e g c' e'>1
  }
  \new Staff {
    \clef "treble_8"
    <c e g c' e'>1
    <c e g c' e'>1
    <c e g c' e'>1
  }
>>

[image of music]

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.

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

[image of music]

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

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

[image of music]

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 using \rightHandFinger followed by a number.

Note: If the number is entered in Scheme notation, remember to append a space before following it with a closing > or similar.

\clef "treble_8"
c4\rightHandFinger #1
e\rightHandFinger #2
g\rightHandFinger #3
c'\rightHandFinger #4
<c\rightHandFinger #1 e\rightHandFinger #2
 g\rightHandFinger #3 c'\rightHandFinger #4 >1

[image of music]

For convenience, \rightHandFinger may be abbreviated to something shorter, for example \RH, by adding the appropriate definition at the source file’s top level:

RH = \rightHandFinger \etc

Most behaviors of right-hand fingerings (namely, the StrokeFinger object) may be set in the same way as ordinary fingerings: see Fingering instructions.

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.

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

  \set strokeFingerOrientations = #'(right)
  c\RH #1
}

[image of music]

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
}

[image of music]

See also

Notation Reference: Fingering instructions.

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.

\relative {
  \clef "treble_8"
  b,16 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
}

[image of music]

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 {
  \clef "treble_8"
  \override NoteHead.style = #'harmonic-mixed
  d'8^\markup { \italic \fontsize #-2 "harm. 12" } <g b>4
}

[image of music]

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

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

[image of 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.s2do"  = 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
  }
}

[image of music]

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. As an exception, the fifth is specified in these chord names, whereas it is usually left out in other chords (e.g., major or minor triads).

ChordsAndSymbols = {
  \chordmode {
    e,,1:5
    a,,:5.8
    \set TabStaff.restrainOpenStrings = ##t
    \set minimumFret = #8
    c,:5
    f,:5.8
  }
  \set minimumFret = #2
  \set restrainOpenStrings = ##f
  <a, e> <a cis' e'>
  <g d' g'>
}
\score {
  <<
    \new ChordNames {
    \ChordsAndSymbols
    }
    \new Staff {
      \clef "treble_8"
      \ChordsAndSymbols
    }
    \new TabStaff {
      \ChordsAndSymbols
    }
  >>
}

[image of music]

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:

music = {
  g8 d' g'\5 a b g e d' |
  g4 d''8\5 b' a'\2 g'\5 e'\2 d' |
  g4
}

<<
  \new Staff \with { \omit StringNumber }
  { \clef "treble_8"  \music }
  \new TabStaff \with {
    tablatureFormat = #fret-number-tablature-format-banjo
    stringTunings = #banjo-open-g-tuning
  }
  { \music }
>>

[image of music]

A number of common tunings for the five-string banjo are predefined: banjo-open-g-tuning (gDGBD), banjo-c-tuning (gCGBD), banjo-modal-tuning (gDGCD), banjo-open-d-tuning (aDF#AD), banjo-open-dm-tuning (aDFAD), banjo-double-c-tuning (gCGCD) and banjo-double-d-tuning (aDGDE).

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

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

See also

Installed Files: ‘ly/string-tunings-init.ly’.

Snippets: Fretted strings.


2.4.4 Lute


Lute tablatures

LilyPond supports tablature for lute.

To get additional bass strings use additionalBassStrings, where the pitches of those strings are set. They will be printed below lowest line as: a, /a, //a, ///a, 4, 5, etc.

fret-letter-tablature-format for tablatureFormat should be used, probably also fretLabels for further customizing.

m = { f'4 d' a f d a, g, fis, e, d, c,  \bar "|." }

\score {
  <<
    \new Staff { \clef bass \cadenzaOn  \m }
    \new TabStaff \m
  >>
  \layout {
    \context {
      \Score
      tablatureFormat = #fret-letter-tablature-format
    }
    \context {
      \TabStaff
      stringTunings = \stringTuning <a, d f a d' f'>
      additionalBassStrings = \stringTuning <c, d, e, fis, g,>
      fretLabels = #'("a" "b" "r" "d" "e" "f" "g" "h" "i" "k")
    }
  }
}

[image of music]

Known issues and warnings

Using FretBoards with additionalBassStrings is not supported and will yield unsatisfying results.


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

See also

Notation Reference: Showing melody rhythms, Instantiating new staves, Creating MIDI output.

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
}

[image of music]

This is shorthand for:

\new DrumStaff \drummode {
  hihat4 hh bassdrum bd
}

[image of music]

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 percussion
  bd4 4 4 4
  \clef treble
  hh4 4 4 4
}

[image of music]

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

See also

Notation Reference: Creating MIDI output, Percussion notes.

Installed Files: ‘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, as described in Tremolo repeats.

\drums {
  \time 2/4
  sn16 8 16 8 8:32 ~
  8 8 4:32 ~
  4 8 16 16
  4 r4
}

[image of music]

Sticking can be indicated by placing a markup for "R" or "L" above or below notes, as discussed in Direction and placement. The staff-padding property may be overridden to achieve a pleasing baseline.

\drums {
  \repeat unfold 2 {
    sn16^"L" 16^"R" 16^"L" 16^"L" 16^"R" 16^"L" 16^"R" 16^"R"
    \stemUp
    sn16_"L" 16_"R" 16_"L" 16_"L" 16_"R" 16_"L" 16_"R" 16_"R"
  }
}

[image of music]

See also

Notation Reference: Tremolo repeats.

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: Creating MIDI output.

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

[image of music]

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

[image of music]

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:

[image of music]

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.

agostini-drums-style

Invented by the French percussionist Dante Agostini in 1965, this notation is commonly employed in France but also elsewhere.

[image of music]

weinberg-drums-style

Based on the work of Norman Weinberg, published in his Guidelines for Drumset Notation.

[image of music]

timbales-style

This typesets timbales on a two line staff:

[image of music]

congas-style

This typesets congas on a two line staff:

[image of music]

bongos-style

This typesets bongos on a two line staff:

[image of music]

percussion-style

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

[image of music]

Custom percussion styles may also be defined, as explained in Custom percussion staves.

See also

Learning Manual: I'm hearing Voices.

Notation Reference: Custom percussion staves.

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

Snippets: Percussion.


Custom percussion staves

Custom percussion styles may be defined, to which the drumStyleTable property may then be set. Existing notations may be redefined as an association list where each entry has to be comprised of four items: a name, the note head style (or default), an articulation sign if needed (or #f if not), and the note head’s position on the staff. That list must then be converted into a Scheme hash table, using the alist->hash-table function.

#(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 \with { drumStyleTable = #(alist->hash-table mydrums) }
  <<
    \new DrumVoice { \voiceOne \up }
    \new DrumVoice { \voiceTwo \down }
  >>

[image of music]

New names may also be added to these custom notations through the drumPitchNames variable, that may be redefined as an association list (or augmented by appending a new list to its existing value, as demonstrated below), but also through its individual entries. This also makes it possible to define aliases: alternate input shorthand for some notations.

drumPitchNames =
  #(append
    '((leftsnap . sidestick)
      (rightsnap . ridecymbal))
    drumPitchNames)

drumPitchNames.ls = #'sidestick
drumPitchNames.rs = #'ridecymbal

\drums {
  leftsnap4. rightsnap8 leftsnap4 rightsnap
  ls8 rs ls rs ls4 rs
}

[image of music]

In a similar manner, the drumPitchTable property associates a specific pitch (meaning a different instrument sound, as provided by available MIDI soundfonts) to each notation. That property needs to be defined as a hash table, which is again converted from an association list (stored by default as the midiDrumPitches variable). Redefining these associations is achieved as explained above, either by defining an entire association list or through individual entries. The following example demonstrates how to create a whole notation set with its own input syntax, custom notations and corresponding MIDI output.

drumPitchNames.dbass      = #'dbass
drumPitchNames.dba        = #'dbass  % 'db is in use already
drumPitchNames.dbassmute  = #'dbassmute
drumPitchNames.dbm        = #'dbassmute
drumPitchNames.do         = #'dopen
drumPitchNames.dopenmute  = #'dopenmute
drumPitchNames.dom        = #'dopenmute
drumPitchNames.dslap      = #'dslap
drumPitchNames.ds         = #'dslap
drumPitchNames.dslapmute  = #'dslapmute
drumPitchNames.dsm        = #'dslapmute

#(define djembe-style
  '((dbass      default  #f         -2)
    (dbassmute  default  stopped    -2)
    (dopen      default  #f          0)
    (dopenmute  default  stopped     0)
    (dslap      default  #f          2)
    (dslapmute  default  stopped     2)))

midiDrumPitches.dbass     = g
midiDrumPitches.dbassmute = fis
midiDrumPitches.dopen     = a
midiDrumPitches.dopenmute = gis
midiDrumPitches.dslap     = b
midiDrumPitches.dslapmute = ais

test = \drummode { dba4 do ds dbm dom dsm }

\score {
  \new DrumStaff \with {
    \override StaffSymbol.line-count = #3
    instrumentName = "Djembé "
    drumStyleTable = #(alist->hash-table djembe-style)
    drumPitchTable = #(alist->hash-table midiDrumPitches)
  } {
    \time 3/4
    \test
  }
  \layout {}
  \midi {}
}

[image of music]

See also

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

Snippets: Percussion.

Internals Reference: DrumStaff, DrumVoice.


Ghost notes

Also known as dead, muted, silenced or false notes; ghost notes can be created using the \parenthesize command, see Parentheses.

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

[image of music]

See also

Notation Reference: Parentheses.

Snippets: Percussion.


2.6 Wind instruments

[image of music]

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:

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

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 =#(lambda (g)
  (+ (ly:self-alignment-interface::centered-on-x-parent g)
     (ly:self-alignment-interface::x-aligned-on-self g)))
}

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

[image of music]

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 = #(lambda (g)
    (+ (ly:self-alignment-interface::centered-on-x-parent g)
       (ly:self-alignment-interface::x-aligned-on-self g)))
}

\score {
  \new Staff \with {
    \remove "Time_signature_engraver"
    \omit Stem
    \omit Flag
    \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
  }
}

[image of music]

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 }

[image of music]

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 c-flat or f-flat. Similarly, the piobaireachd high g can be written g-flat when it occurs in light music.

See also

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

[image of music]

See also

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

Woodwind diagrams are created as markups:

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

[image of music]

Keys can be open, partially-covered, ring-depressed, or fully covered. The angle of partially-covered keys can be specified:

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

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

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

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

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

c''1^\markup {
  \center-column {
    "one half, vertical"
    \override #'(woodwind-diagram-details . ((fill-angle . 90)))
    \woodwind-diagram #'flute #'((cc . (one1h))
                                 (lh . ())
                                 (rh . ()))
  }
}

[image of music]

Trills are indicated as shaded keys, or in non-graphical mode, as either circled (the default) or shaded text:

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

c''1^\markup {
  \override #'(graphical . #f)
  \woodwind-diagram #'bass-clarinet
                    #'((cc . (threeT four))
                       (lh . ())
                       (rh . (b fisT)))
}

c''1^\markup {
  \override #'(graphical . #f)
  \override #'(woodwind-diagram-details . ((text-trill-circled . #f)))
  \woodwind-diagram #'bass-clarinet
                    #'((cc . (threeT four))
                       (lh . ())
                       (rh . (b fisT)))
}

[image of music]

A variety of trills can be displayed:

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

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

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

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

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

[image of music]

The list of all possible keys and settings for a given instrument can be displayed on the console using #(print-keys-verbose 'flute) or in the log file using #(print-keys-verbose 'flute (current-error-port)), although they will not show up in the music output.

Creating new diagrams is possible, although this will require Scheme ability and may not be accessible to all users. The patterns for the diagrams are in files ‘scm/define-woodwind-diagrams.scm’ and ‘scm/display-woodwind-diagrams.scm’.

Predefined commands

Selected Snippets

Woodwind diagrams listing

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

\layout {
  indent = 0
}

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

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

[image of music]

Graphical and text woodwind diagrams

In many 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)))
    }
}

[image of music]

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

[image of music]

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 in the log file, but not in the music. If output to the console is wanted, omit the (current-error-port) from the commands.

#(print-keys-verbose 'piccolo (current-error-port))
#(print-keys-verbose 'flute (current-error-port))
#(print-keys-verbose 'flute-b-extension (current-error-port))
#(print-keys-verbose 'tin-whistle (current-error-port))
#(print-keys-verbose 'oboe (current-error-port))
#(print-keys-verbose 'clarinet (current-error-port))
#(print-keys-verbose 'bass-clarinet (current-error-port))
#(print-keys-verbose 'low-bass-clarinet (current-error-port))
#(print-keys-verbose 'saxophone (current-error-port))
#(print-keys-verbose 'soprano-saxophone (current-error-port))
#(print-keys-verbose 'alto-saxophone (current-error-port))
#(print-keys-verbose 'tenor-saxophone (current-error-port))
#(print-keys-verbose 'baritone-saxophone (current-error-port))
#(print-keys-verbose 'bassoon (current-error-port))
#(print-keys-verbose 'contrabassoon (current-error-port))

\score {c''1}

[image of music]

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

[image of music]

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 }

[image of music]

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:

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

[image of music]

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.


Common chords

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

\chordmode { c2 f4 g }

[image of music]

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

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

[image of music]

Seventh chords can be created:

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

[image of music]

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.

ModifierActionExample
NoneThe default action; produces a major triad. [image of music]
m, m7The minor chord. This modifier lowers the 3rd. [image of music]
dim, dim7The diminished chord. This modifier lowers the 3rd, 5th and (if present) the 7th step. [image of music]
augThe augmented chord. This modifier raises the 5th step. [image of music]
maj, maj7The 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. [image of music]

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
}

[image of music]

As a special exception, c:5 produces a ‘power chord’ only consisting of root and fifth.

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
}

[image of music]

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:3.5.6 c:3.7.8 c:3.6.13
}

[image of music]

Added steps can be as high as desired.

\chordmode {
  c4:3.5.15 c:3.5.20 c:3.5.25 c:3.5.30
}

[image of music]

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

[image of music]

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
}

[image of music]

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. When sus is followed by either a 2nd or 4th step, it is equivalent to ^3, otherwise to sus4, namely 5.4.

\chordmode {
  c1:sus c:sus2 c:sus4 c:5.4
}

[image of music]

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

\chordmode {
  c'1 c'/e c'/f
}

[image of music]

If the added pitch is already part of the chord, this may be used to print chord inversions, in which case the pitch is not added but merely moved to the bottom of the chord. It may however be treated as an added note (and thus printed twice), by using the syntax /+pitch.

\chordmode {
  c'1 c'/g c'/+e
}

[image of music]

Automatic chord inversions and voicings are demonstrated in Chord inversions and specific voicings.

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

See also

Notation Reference: Chord inversions and specific voicings, 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:3.5.5-.5+ }

[image of music]


Chord inversions and specific voicings

In addition to chord modifiers and added bass notes, various functions may be used to automatically print chords in a specific inversion or voicing – for example the so-called ‘drop 2’ voicing commonly used in jazz music.

\chordmode {
  \dropNote 2 {
    c2:maj7 d:m7
  }
  \invertChords 1 d1:maj7
}

[image of music]

Unlike added bass notes shown in Extended and altered chords this only affects the way chords are printed on a staff, and not chord names written with letters. Furthermore, these functions may be used not only in chord mode but also with <...> chords constructs explained in Chorded notes.

See also

Notation Reference: Extended and altered chords, Chorded notes.

Snippets: Chords.


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

[image of music]

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:

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

[image of music]

When passed to a ChordNames context, rests (including multi-measure rests) cause the text “N.C.” (No Chord) to be displayed.

myChords = \chordmode {
  c1
  r1
  g1
  R1
  c1
}

<<
  \new ChordNames \myChords
  \new Staff \myChords
>>

[image of music]

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

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

[image of music]

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

[image of music]

Selected Snippets

Showing chords at changes

By default, every chord entered is printed; this behavior can be modified so that chord names are printed 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 }
  }
>>

[image of music]

Simple lead sheet

When put together, chord names, a melody, and lyrics form a lead sheet:

<<
  \chords { c2 g:sus4 f e }
  \new Staff \relative c'' {
    a4 e c8 e r4
    b2 c4( d)
  }
  \addlyrics { One day this shall be free __ }
>>

[image of music]

Customizing the no-chord symbol

By default, rests in a ChordNames context cause the “N.C.” symbol to be printed. This markup can be customized.

<<
  \chords {
    R1
    \set noChordSymbol = "—"
    R1
    \set noChordSymbol = \markup \italic "Ssh!"
    R1
  }
  {
    R1*3
  }
>>

[image of music]

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). (Other chord naming systems may be implemented through Scheme functions, as demonstrated by the “Chord names alternative” snippet in Chords.) A list of common jazz chords notations may be found on the chart in Chord name chart.

The default naming system may be tweaked easily in a number of ways. To begin with, predefined commands allow to use different languages for the root pitch. These include \germanChords, \semiGermanChords, \italianChords and \frenchChords:

[image of music]

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
}

[image of music]

The chord name display can also 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.

additionalPitchPrefix

When the chord name contains additional pitches, they can optionally be prefixed with some text. The default is no prefix, in order to avoid too much visual clutter, but for small numbers of additional pitches this can be visually effective.

\new ChordNames {
  <c e g d'>    % add9
  \set additionalPitchPrefix = "add"
  <c e g d'>    % add9
}

[image of music]

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 small amount of horizontal space. By setting chordNameSeparator, you can use any desired markup for a separator. This does not affect the separator between a chord and its bass note; to customize that, use slashChordSeparator.

\chords {
  c4:7.9- c:7.9-/g
  \set chordNameSeparator = \markup { "/" }
  \break
  c4:7.9- c:7.9-/g
}

[image of music]

slashChordSeparator

Chords can be played over a bass note other than the conventional root of the chord. These are known as “inversions” or “slash chords”, because the default way of notating them is with a forward slash between the main chord and the bass note. Therefore the value of slashChordSeparator defaults to a forward slash, but you can change it to any markup you choose.

\chords {
  c4:7.9- c:7.9-/g
  \set slashChordSeparator = \markup { " over " }
  \break
  c4:7.9- c:7.9-/g
}

[image of music]

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.

minorChordModifier

Minor chords are often denoted via a ‘m’ suffix to the right of the root of the chord. However some idioms prefer other suffices, such as a minus sign.

\chords {
  c4:min f:min7
  \set minorChordModifier = \markup { "-" }
  \break
  c4:min f:min7
}

[image of music]

chordPrefixSpacer

The modifier for minor chords as determined by minorChordModifier is usually printed immediately to the right of the root of the chord. A spacer can be placed between the root and the modifier 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
}

<<
   \new ChordNames \theMusic
   \new Voice \theMusic
>>

[image of music]

chord name major7

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

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

[image of music]

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
}

[image of music]

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

[image of music]

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
}

[image of music]

See also

Notation Reference: Chord name chart, Common chord modifiers.

Essay on automated music engraving: Literature list.

Installed Files: ‘scm/chords-ignatzek-names.scm’, ‘scm/chord-entry.scm’, ‘ly/chord-modifiers-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 }
>>

[image of music]


Chord grids

In some European countries, particularly France, jazz musicians use so-called ‘chord grids’, which notate chords visually by placing them in squares.

[image of music]

Although they are omitted in the rest of this section for brevity, it is recommended to use the following \paper settings for chord grids:

\paper {
  indent = 0
  ragged-right = ##f
}

indent = 0 ensures that the first line is not indented as it would normally be (see \paper variables for shifts and indents). ragged-right = ##f is necessary for single-line grids to ensure they span the whole page; see \paper variables for widths and margins.

In order to create a chord grid, instantiate a ChordGrid context.

\new ChordGrid \chordmode { c1 d1:m e1:7 f1:7+ }

[image of music]

Each square is automatically subdivided.

\new ChordGrid \chordmode {
  c1
  d2 c2
  e2. c4
}

[image of music]

Chords spanning a complete measure are centered within their square. Chords lasting half a measure take half the square, and those lasting a quarter of a measure take a quarter of the square. This summary picture shows the default rules for subdividing the square:

[image of music]

The \medianChordGridStyle changes the default display of squares with four chords of equal length to use the style recommended by Philippe Baudoin in his book Jazz, mode d’emploi (“Jazz, user instructions”).

\layout {
  \context {
    \ChordGrid
    \medianChordGridStyle
  }
}

[image of music]

In chord grids, rests cause the noChordSymbol to be printed, just like in a regular ChordNames context (see Printing chord names).

\new ChordGrid \chordmode { c1 r2 c2 R1 }

[image of music]

Skips cause blank space. They can occupy part of a square.

\new ChordGrid \chordmode { c1 s2 c2 s1 }

[image of music]

Selected Snippets

Customizing the chord grid style

Custom divisions of chord squares can be defined through the measure-division-lines-alist and measure-division-chord-placement-alist properties of ChordSquare. These are both alists. Their keys are measure divisions, namely lists which give the fraction of the measure that each chord (or rest, or skip) represents. More precisely, a measure division alist is made of positive, exact numbers adding up to 1, for example: '(1/2 1/4 1/4). The exactness requirement means that, e.g., 1/2 is valid but not 0.5.

The values in measure-division-lines-alist are lists of lines, which are represented as (x1 y1 x2 y2). The line starts at the point (x1 . y1) and ends at (x2 . y2). Coordinates are expressed in the [-1, 1] scale relative to the extent of the square.

The values in measure-division-chord-placement-alist are lists of (x . y) pairs giving the placement of the respective chords.

This example defines a peculiar chord grid style that has a rule for measures divided in three equal parts.

\paper {
  line-width = 10\cm
  ragged-right = ##f
}

\new ChordGrid \with {
  \override ChordSquare.measure-division-lines-alist =
    #'(((1) . ())
       ((1/3 1/3 1/3) . ((-1 -0.4 0 1) (0 -1 1 0.4))))
  \override ChordSquare.measure-division-chord-placement-alist =
    #'(((1) . ((0 . 0)))
       ((1/3 1/3 1/3) . ((-0.7 . 0.5) (0 . 0) (0.7 . -0.5))))
}
\chordmode {
  \time 3/4
  c2.
  c4 c4 c4
}

[image of music]

See also

Music Glossary: chord grid.

Internals Reference: ChordGrid, ChordGridScore, GridChordName, ChordSquare, Grid_chord_name_engraver, Chord_square_engraver.


2.7.3 Figured bass

[image of music]

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

[image of music]

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. See Input modes for more information on different 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
  }
}

[image of music]

Accidentals (including naturals) may be used for modifying scale steps. These are entered by appending ‘+’ (for sharps), ‘-’ (for flats) or ‘!’ (for naturals) after the number. For double accidentals the modifier is applied twice. For the modification of the third step the number is often omitted, which can be achieved by using ‘_’ instead of a number.

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

[image of music]

If used without accidental, ‘_’ creates an empty figure which nevertheless takes up space. This can be used for controlling the stacking of bass figures.

<<
  {
    \clef bass
    g2 c4
  }
  \figures {
    <_ 5 4>4 <8 _ 3>8 <7>
  }
>>

[image of music]

Augmented and diminished steps can be indicated.

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

[image of music]

A backward slash through a figure is also available.

\figures {
  <5> <5\\>
}

[image of music]

For some figures, special backward slash glyphs are provided.

\figures {
  <8 6\\> <9 7\\> <9\\ 7>
}

[image of music]

Brackets can be added around accidentals, figures, and consecutive groups of figures.

\figures {
  <9[-] 8 [7-] 5 [4[!] 2+]>
}

[image of music]

Any text markup can be inserted as a figure.

\figures {
  <\markup { \fontsize #-5 \number 6 \teeny \super (1) } 5>
}

[image of music]

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

[image of music]

In this case, the extender lines replace existing figures, unless the continuation lines have been explicitly terminated with \!.

<<
  \figures {
    \bassFigureExtendersOn
    <6 4>4 <6 4> <6\! 4\!> <6 4>
  }
  {
    \clef bass
    d4 d c c
  }
>>

[image of music]

The table below summarizes the figure modifiers available.

modifierpurposeexample
+, -, !accidentals [image of music]
\+, /augmented and diminished steps [image of music]
\\raised by a semitone [image of music]
\!end of continuation line [image of music]

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.

If plus signs appear after the number, specially designed glyphs are provided for some figures.

\figures {
  <5\+> <5+ 4\+> <6 4- 2\+> r
  \set figuredBassAlterationDirection = #RIGHT
  <5\+> <5+ 4\+> <6 4- 2\+> r
  \set figuredBassPlusDirection = #RIGHT
  <5\+> <5+ 4\+> <6 4- 2\+> r
  \set figuredBassAlterationDirection = #LEFT
  <5\+> <5+ 4\+> <6 4- 2\+> r
}

[image of music]

Adjusting figured bass alteration glyphs

In figured bass, specially designed glyphs for 6\\, 7\\, and 9\\ are used by default. Similarly, specially designed glyphs for symbols 2\+, 4\+, and 5\+ are used by default if plus signs appear after the number.

To change that, pass an alist to figuredBassPlusStrokedAlist and set the glyph in question to #f (or omit it).

\figures {
  \set figuredBassPlusDirection = #RIGHT
  <6\\> <7\\> <9\\> r
  <2\+> <4\+> <5\+> r

  \set figuredBassPlusStrokedAlist =
    #'((2 . "figbass.twoplus")
       ;; (4 . "figbass.fourplus")
       ;; (5 . "figbass.fiveplus")
       (6 . "figbass.sixstroked")
       ;; (7 . "figbass.sevenstroked")
       ;; (9 . "figbass.ninestroked")
      )
  <6\\> <7\\> <9\\> r
  <2\+> <4\+> <5\+> r
}

[image of music]

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''4 c'8 r8 c,4 c'
  }
  \new FiguredBass {
    \figuremode {
      <4>4 <10 6>8 s8
      <6 4>4 <6 4>
    }
  }
>>

[image of music]

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

[image of music]

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

[image of music]

The horizontal alignment of numbers in a figured bass stack that have more than a single digit can be controlled with the context property figuredBassLargeNumberAlignment.

<<
  \new Voice {
    \clef bass
    r2 d | d d | a2
  }
  \new FiguredBass \figuremode {
    s2 <10+ 8> |
    \set figuredBassLargeNumberAlignment = #RIGHT
    <11 9>2
    \set figuredBassLargeNumberAlignment = #LEFT
    <10+ 9>2 |
    <_+>2
  }
>>

[image of music]

The vertical distance of figured bass elements can be controlled with subproperties minimum-distance and padding of staff-staff-spacing.

<<
  { \clef bass g,2 c, }
  \figures {
    \once \override BassFigureLine
                    .staff-staff-spacing.minimum-distance = 3
    <7 _-> <7- _->
  }
>>

[image of music]

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

[image of music]


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


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


Tuplets in contemporary music


Contemporary time signatures


Extended polymetric notation


Beams in contemporary music


Bar lines in contemporary music


2.8.3 Graphical notation

Rhythmic items may be continued by a duration line, which gets represented by a DurationLine grob. Possible styles are 'beam, 'line, 'dashed-line, 'dotted-line, 'zigzag, 'trill and 'none. The duration line may end with a hook (beam-style only) or an arrow.

\layout {
  \context {
    \Voice
    \consists Duration_line_engraver
    \omit Stem
    \omit Flag
    \omit Beam
    \override NoteHead.duration-log = 2
  }
}

{
  a'1\- s2 r
  \once \override DurationLine.style = #'line
  a'1\- s2 r
  \once \override DurationLine.style = #'dashed-line
  \once \override DurationLine.dash-period = 2
  a'1\- s2 r
  \once \override DurationLine.style = #'dotted-line
  \once \override DurationLine.dash-period = 1
  \once \override DurationLine.bound-details.right.padding = 1
  a'1\- s2 r
  \once \override DurationLine.thickness = 2
  \once \override DurationLine.style = #'zigzag
  a'1\- s2 r
  \once \override DurationLine.style = #'trill
  a'1\- s2 r
  \once \override DurationLine.style = #'none
  a'1\- s2 r
  \once \override DurationLine.bound-details.right.end-style = #'arrow
  a'1\- s2 r
  \override DurationLine.bound-details.right.end-style = #'hook
  a'1\- s2 r
  \override DurationLine.details.hook-direction = #DOWN
  a'1\- s2 r
  \bar "|."
}

[image of music]


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


Scores and musical examples


2.9 Ancient notation

[image of music]

Support for ancient notation includes features for mensural notation, Gregorian chant notation, and Kievan square 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 predefined contexts for these styles.

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

Some notational concepts are introduced specifically for ancient notation,

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:

Three styles emulate the appearance of late-medieval and renaissance manuscripts and prints of mensural music:

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


Predefined contexts

For Gregorian chant and mensural notation, there are predefined 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 predefined contexts VaticanaVoice, VaticanaStaff, MensuralVoice, MensuralStaff, KievanVoice, and KievanStaff.

See also

Music Glossary: mensural notation.

Notation Reference: Gregorian chant contexts, Mensural contexts, Kievan 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.

\relative {
  \[ g' c, a' f d' \]
  a g f
  \[ e f a g \]
}

[image of music]

Three other ligature styles are available: ‘Vaticana’ for Gregorian chant, ‘Mensural’ for mensural music (only white mensural ligatures are supported for mensural music, and with certain limitations), and ‘Kievan’ for Kievan melismata. 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. For more information, see White mensural ligatures, Gregorian square neume ligatures, and Kievan melismata.

See also

Music Glossary: ligature.

Notation Reference: White mensural ligatures, Gregorian square neume ligatures.

Known issues and warnings

Spacing required for ligatures is not currently implemented and, as a result, there may end up being too much space between them. Line breaking may also be unsatisfactory.

Lyrics might not align as expected when using ligatures.

Accidentals must not be printed within a ligature, but instead 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:

\score {
  \relative {
    a'1
    \break
    g
  }
  \layout {
    \context {
      \Staff
      \consists Custos_engraver
      \override Custos.style = #'mensural
    }
  }
}

[image of music]

The custos glyph is selected by the style property. The styles supported are vaticana, medicaea, hufnagel, and mensural.

\new Lyrics \lyricmode {
  \markup { \column {
    \typewriter "vaticana "
    \line { " " \musicglyph "custodes.vaticana.u0" }
  } }
  \markup { \column {
    \typewriter "medicaea "
    \line { " " \musicglyph "custodes.medicaea.u0" }
  }}
  \markup { \column {
    \typewriter "hufnagel "
    \line { " " \musicglyph "custodes.hufnagel.u0" }
  }}
  \markup { \column {
    \typewriter "mensural "
    \line { " " \musicglyph "custodes.mensural.u0" }
  }}
}

[image of music]

See also

Music Glossary: custos.

Snippets: Ancient notation.

Internals Reference: Custos.


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" \relative {
      \hide Score.BarNumber {
        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
    }
  >>
}

[image of music]

See also

Music Glossary: mensural notation.


Mensural clefs

Mensural clefs are supported using 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.

\override NoteHead.style = #'vaticana.punctum
\clef "vaticana-do1"
c'1

[image of music]

\override NoteHead.style = #'medicaea.punctum
\clef "medicaea-do3"
c'1

[image of music]

\override NoteHead.style = #'hufnagel.punctum
\clef "hufnagel-fa2"
c'1

[image of music]

\override NoteHead.style = #'neomensural
\clef "neomensural-c4"
c'1

[image of music]

It is possible to manually force a clef glyph to be typeset on an arbitrary line, as described in Clef. For the complete range of possible clefs see Clef styles.

See also

Music Glossary: mensural notation, clef.

Notation Reference: Gregorian clefs, Clef.

Installed Files: ‘scm/parser-clef.scm’.

Snippets: Pitches.

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

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

[image of music]

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:

[image of music]

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:

The neomensural, mensural, and petrucci styles differ from the baroque style by:

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

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

[image of music]

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.

\relative c' {
  \override Flag.style = #'mensural
  \override Stem.thickness = #1.0
  \override NoteHead.style = #'mensural
  \autoBeamOff
  c8 d e f c16 d e f c32 d e f s8
  c'8 d e f c16 d e f c32 d e f
}

[image of music]

Note that the innermost flare of each mensural flag 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

Vertically aligning each flag with a staff line assumes that stems always end either exactly on or exactly in the middle of 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 ancient styles are neomensural, and mensural.

The following example demonstrates these styles:

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

[image of music]

There are no 32nd and 64th rests specifically for the mensural or neo-mensural styles. Rests from the default style are used.

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. Mensural notation rarely used a natural sign: instead the appropriate sharp or flat is used. For example, a B natural in the key of F major would be indicated with a sharp. However, if specifically called for, the natural sign is taken from the vaticana style.

[image of music]

The way to use this style is covered in Alternate accidental glyphs. It is the default in the MensuralStaff context.

See also

Music Glossary: mensural notation, Pitch names, accidental, key signature.

Notation Reference: Pitches, Accidentals, Automatic accidentals, Alternate accidental glyphs, Accidental glyph sets, 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.

\relative {
  fis' gis
  \set suggestAccidentals = ##t
  ais bis
}

[image of music]

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
  \new MensuralVoice  {
    \once \set suggestAccidentals = ##t
    bes'4 a2 g2 \ficta fis8 \ficta e! fis2 g1
  }
}

[image of music]

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 {
  \relative {
    \set Score.timing = ##f
    \set Score.measureBarType = #'()
    \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 \]
    \[ e1 a, g\breve \]
  }
  \layout {
    \context {
      \Voice
      \remove Ligature_bracket_engraver
      \consists Mensural_ligature_engraver
    }
  }
}

[image of music]

Without replacing Ligature_bracket_engraver with Mensural_ligature_engraver, the same music looks as follows:

[image of music]

See also

Music Glossary: ligature.

Notation Reference: Gregorian square neume ligatures, Ligatures.

Known issues and warnings

Horizontal spacing of ligatures may be 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 contexts VaticanaVoice, VaticanaStaff, and VaticanaLyrics can be used to engrave a piece of Gregorian chant in the style of the Editio Vaticana. These contexts initialize all relevant context and grob properties to proper values; 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 VaticanaLyrics \lyricsto "cantus" {
      San -- ctus, San -- ctus, San -- ctus
    }
  >>
}

[image of music]


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.

DescriptionSupported ClefsExample
Editio Vaticana style do clefvaticana-do1, vaticana-do2,
vaticana-do3
[image of music]
Editio Vaticana style fa clefvaticana-fa1, vaticana-fa2 [image of music]
Editio Medicaea style do clefmedicaea-do1, medicaea-do2,
medicaea-do3
[image of music]
Editio Medicaea style fa clefmedicaea-fa1, medicaea-fa2 [image of music]
hufnagel style do clefhufnagel-do1, hufnagel-do2,
hufnagel-do3
[image of music]
hufnagel style fa clefhufnagel-fa1, hufnagel-fa2 [image of music]
hufnagel style combined do/fa clefhufnagel-do-fa [image of music]

See also

Music Glossary: clef.

Notation Reference: Clef.


Gregorian accidentals and key signatures

Accidentals for the three different Gregorian styles are available:

[image of music]

As shown, not all accidentals are supported by each style. When trying to access an unsupported accidental, LilyPond will switch to a different style.

How to switch between styles is covered in Alternate accidental glyphs.

See also

Music Glossary: accidental, key signature.

Notation Reference: Pitches, Accidentals, Automatic accidentals, Alternate accidental glyphs, 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 indicating 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. 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 the predefined staff contexts for Gregorian chant configure \caesura to produce an ancient caesura mark.

[image of music]

Predefined commands

\virgula, \caesura, \divisioMinima, \divisioMaior, \divisioMaxima, \finalis.

See also

Music Glossary: caesura, divisio.

Notation Reference: Breath marks.

Installed Files: ‘ly/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 Script.padding = #-0.1
    a\ictus_"ictus " \break
    a\circulus_"circulus " \break
    a\semicirculus_"semicirculus " \break
    a\accentus_"accentus " \break
    \[ a_"episema" \episemInitium \pes b
       \flexa a b \episemFinis \flexa a \]
  }
}

[image of music]

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

[image of music]

See also

Notation Reference: Breath marks.

Internals Reference: Divisio.

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

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

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 neumes

Basic and Liquescent formsOutputLilyPond code
Punctum [image of music]\[ b \]
[image of music]\[ \cavum b \]
[image of music]\[ \linea b \]
Punctum Auctum Ascendens [image of music]\[ \auctum \ascendens b \]
Punctum Auctum Descendens [image of music]\[ \auctum \descendens b \]
Punctum inclinatum [image of music]\[ \inclinatum b \]
Punctum Inclinatum Auctum [image of music]\[ \inclinatum \auctum b \]
Punctum Inclinatum Parvum [image of music]\[ \inclinatum \deminutum b \]
Virga [image of music]\[ \virga b' \]

Two-note ligatures

Clivis vel Flexa [image of music]\[ b \flexa g \]
Clivis Aucta Descendens [image of music]\[ b \flexa \auctum \descendens g \]
Clivis Aucta Ascendens [image of music]\[ b \flexa \auctum \ascendens g \]
Cephalicus [image of music]\[ b \flexa \deminutum g \]
Podatus/Pes [image of music]\[ g \pes b \]
Pes Auctus Descendens [image of music]\[ g \pes \auctum \descendens b \]
Pes Auctus Ascendens [image of music]\[ g \pes \auctum \ascendens b \]
Epiphonus [image of music]\[ g \pes \deminutum b \]
Pes Initio Debilis [image of music]\[ \deminutum g \pes b \]
Pes Auctus Descendens
Initio Debilis
[image of music]\[ \deminutum g \pes \auctum
\descendens b \]

Multi-note ligatures

Torculus [image of music]\[ a \pes b \flexa g \]
Torculus Auctus Descendens [image of music]\[ a \pes b \flexa \auctum
\descendens g \]
Torculus Deminutus [image of music]\[ a \pes b \flexa \deminutum g \]
Torculus Initio Debilis [image of music]\[ \deminutum a \pes b \flexa g \]
Torculus Auctus Descendens
Initio Debilis
[image of music]\[ \deminutum a \pes b \flexa \auctum
\descendens g \]
Torculus Deminutus
Initio Debilis
[image of music]\[ \deminutum a \pes b \flexa
\deminutum g \]
Porrectus [image of music]\[ a \flexa g \pes b \]
Porrectus Auctus Descendens [image of music]\[ a \flexa g \pes \auctum
\descendens b \]
Porrectus Deminutus [image of music]\[ a \flexa g \pes \deminutum b \]
Climacus [image of music]\[ \virga b \inclinatum a
\inclinatum g \]
Climacus Auctus [image of music]\[ \virga b \inclinatum a
\inclinatum \auctum g \]
Climacus Deminutus [image of music]\[ \virga b \inclinatum a
\inclinatum \deminutum g \]
Scandicus [image of music]\[ g \pes a \virga b \]
Scandicus Auctus Descendens [image of music]\[ g \pes a \pes
\auctum \descendens b \]
Scandicus Deminutus [image of music]\[ g \pes a \pes \deminutum b \]

Special signs

Quilisma [image of music]\[ g \pes \quilisma a \pes b \]
Quilisma Pes Auctus Descendens [image of music]\[ g \quilisma a \pes \auctum
\descendens b \]
Oriscus [image of music]\[ \oriscus b \]
Pes Quassus [image of music]\[ \oriscus g \pes \virga b \]
Pes Quassus Auctus Descendens [image of music]\[ \oriscus g \pes \auctum
\descendens b \]
Salicus [image of music]\[ g \oriscus a \pes \virga b \]
Salicus Auctus Descendens [image of music]\[ g \oriscus a \pes \auctum
\descendens b \]
(Apo)stropha [image of music]\[ \stropha b \]
Stropha Aucta [image of music]\[ \stropha \auctum b \]
Bistropha [image of music]\[ \stropha b \stropha b \]
Tristropha [image of music]\[ \stropha b \stropha b
\stropha b \]
Trigonus [image of music]\[ \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 Typesetting Kievan square notation


Kievan contexts

As with Mensural and Gregorian notation, the predefined KievanVoice and KievanStaff contexts can be used to engrave a piece in square notation. These contexts initialize all relevant context properties and grob properties to proper values, so you can immediately go ahead entering the chant:

% Font settings for Cyrillic
\paper {
  #(define fonts
    (set-global-fonts
     #:roman "Linux Libertine O,serif"
   ))
}

\score {
  <<
    \new KievanVoice = "melody" \relative c' {
      \cadenzaOn
        c4 c c c c2 b\longa
        \fine
    }
    \new Lyrics \lyricsto "melody" {
      Го -- спо -- ди по -- ми -- луй.
    }
  >>
}

[image of music]

See also

Music Glossary: kievan notation.

Known issues and warnings

LilyPond supports Kievan notation of the Synodal style, as used in the corpus of chantbooks printed by the Russian Holy Synod in the 1910’s and recently reprinted by the Moscow Patriarchate Publishing House. LilyPond does not support the older (less common) forms of Kievan notation that were used in Galicia to notate Rusyn plainchant.


Kievan clefs

There is only one clef used in Kievan notation (the Tse-fa-ut Clef). It is used to indicate the position of c:

  \clef "kievan-do"
  \kievanOn
  c'

[image of music]

See also

Music Glossary: kievan notation, clef.

Notation Reference: Clef.


Kievan notes

For Kievan square notation, the appropriate note head style needs to be chosen and the flags and stems need to be turned off. This is accomplished by calling the \kievanOn function, which sets the appropriate properties of the note head, stems, and flags. Once Kievan note heads are not needed, these properties can be reverted by calling the \kievanOff function.

The Kievan final note, which usually comes at the end of a piece of music, may be selected by setting the duration to \longa. The Kievan recitative mark, used to indicate the chanting of several syllables on one note, may be selected by setting the duration to \breve. The following example demonstrates the various Kievan note heads:

\autoBeamOff
\cadenzaOn
\kievanOn
b'1 b'2 b'4 b'8 b'\breve b'\longa
\kievanOff
b'2

[image of music]

See also

Music Glossary: kievan notation, note head.

Notation Reference: Note head styles.

Known issues and warnings

LilyPond automatically determines if the stem up or stem down form of a note is drawn. When setting chant in square notation, however, it is customary to have the stems point in the same direction within a single melisma. This can be done manually by setting the direction property of the Stem object.


Kievan accidentals

The kievan style provides a sharp and a flat sign different from the default style. There is no natural sign in Kievan notation. The sharp sign is not used in Synodal music but may occur in earlier manuscripts. It has been included primarily for the sake of compatibility.

\clef "kievan-do"
\set Staff.alterationGlyphs =
  #alteration-kievan-glyph-name-alist
bes' dis'

[image of music]

See also

Music Glossary: kievan notation, accidental.

Notation Reference: Accidentals, Automatic accidentals, Alternate accidental glyphs, The Emmentaler font.


Kievan bar lines

In a KievanStaff, there are no measures, but the \caesura command creates a phrase bar line, and the \section and \fine commands create a special section bar line.

\new KievanStaff {
  c'4 4 4 4 4 4 \caesura  % \bar "."
  d'4 4 4 4 4 4 \section  % \bar "k"
  e'4 4 4 4 4 4 \fine
}

[image of music]

See also

Notation Reference: Bars, The Emmentaler font.


Kievan melismata

Notes within a Kievan melisma are usually placed close to each other and the melismata separated by whitespace. This is done to allow the chanter to quickly identify the melodic structures of Znamenny chant. In LilyPond, melismata are treated as ligatures and the spacing is implemented by the Kievan_ligature_engraver.

When the KievanVoice and KievanStaff contexts are used, the Kievan_ligature_engraver is enabled by default. In other contexts, it can be invoked by replacing the Ligature_bracket_engraver with the Kievan_ligature_engraver in the layout block:

\layout {
  \context {
    \Voice
    \remove Ligature_bracket_engraver
    \consists Kievan_ligature_engraver
  }
}

The spacing between the notes within a Kievan ligature can be controlled by setting the padding property of the KievanLigature.

The following example demonstrates the use of Kievan ligatures:

% Font settings for Cyrillic
\paper {
  #(define fonts
    (set-global-fonts
     #:roman "Linux Libertine O,serif"
   ))
}

\score {
  <<
    \new KievanVoice = "melody" \relative c' {
      \cadenzaOn
        e2 \[ e4( d4 ) \] \[ c4( d e  d ) \] e1 \fine
    }
    \new Lyrics \lyricsto "melody" {
      Га -- врі -- и -- лу
    }
  >>
}

[image of music]

See also

Music Glossary: ligature.

Notation Reference: White mensural ligatures, Gregorian square neume ligatures, Ligatures.

Known issues and warnings

Horizontal spacing of ligatures is poor.


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


Incipits

It is customary when transcribing mensural music into modern notation to place an indication of how the initial rests and note or notes of the original version appeared – including the original clefs. This is called an incipit. The \incipit command uses the indent of the main staff to set the width occupied by the incipit, and incipit-width to set the width of the incipit staff.

\score {
  \new Staff <<
    \new Voice = Tenor {
      \set Staff.instrumentName = "Tenor"
      \override Staff.InstrumentName.self-alignment-X = #RIGHT
      \incipit { \clef "mensural-c4" \key f \major r\breve r1 c'1 }
      \clef "treble_8"
      \key f \major
      R1 r2 c'2 |
      a4. c'8
    }
    \new Lyrics \lyricsto Tenor { Cyn -- thia your }
  >>
  \layout
  {
    indent = 5\cm
    incipit-width = 3\cm
  }
}

[image of music]

Known issues and warnings

Note that instrumentName must be set in the music for the incipit to be produced. If no instrument name is required then use \set Staff.instrumentName = "".


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.

Mensurstriche, bar lines between but not through staves, can be printed by setting measureBarType to "-span|" and using a grouping context that allows span bars, such as StaffGroup.

\layout {
  \context {
    \Staff
    measureBarType = "-span|"
  }
}

music = \fixed c'' {
  c1
  d2 \section e2
  f1 \fine
}

\new StaffGroup <<
  \new Staff \music
  \new Staff \music
>>

[image of music]


Transcribing Gregorian chant

Gregorian chant can be transcribed into modern notation with a number of simple tweaks.

Stems. The GregorianTranscriptionVoice context does not create stems. You can extend this behavior to other contexts by removing Stem_engraver:

\layout {
  …
  \context {
    \Voice
    \remove Stem_engraver
  }
}

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. An alternative is to use \cadenzaOn and \cadenzaOff.

The predefined staff contexts for ancient music do not create measure bar lines. You can extend this behavior to all other contexts with \set Score.measureBarType = #'() or to particular staves with \set Staff.measureBarType = #'().

The predefined staff contexts for ancient music allow line breaks without bar lines. You can extend this behavior to all other contexts with \set Score.forbidBreakBetweenBarLines = ##f or to particular staves with \set Staff.forbidBreakBetweenBarLines = ##f.

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 {
  \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 GregorianTranscriptionStaff <<
    \new GregorianTranscriptionVoice = "melody" {
      \chant
    }
    \new GregorianTranscriptionLyrics = "one" {
      \lyricsto "melody" \verba
    }
  >>
}

[image of music]

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, as below.

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 the Stem_engraver and manually \omit Stem and \undo \omit Stem.

\include "gregorian.ly"
chant = \relative {
  \clef "G_8"
  \set Score.timing = ##f
  \omit Stem
  c'\breve \hide NoteHead c c c c c
  \undo \hide NoteHead
  \undo \omit Stem \stemUp c4 b4 a
  \omit Stem c2 c4 \divisioMaior
  c\breve \hide NoteHead c c c c c c c
  \undo \hide NoteHead 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 GregorianTranscriptionStaff <<
    \new GregorianTranscriptionVoice = "melody" {
      \chant
    }
    \new GregorianTranscriptionLyrics = "one" {
      \lyricsto "melody" \verba
    }
  >>
  \layout {
    \context {
      \GregorianTranscriptionVoice
      \consists Stem_engraver
    }
  }
}

[image of music]

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 {
  \time 1/4
  \override Lyrics.LyricText.X-extent  = #'(0 . 3)
  d'4 \tuplet 3/2 { f8 a g } g a a4 g f8 e
  d4 f8 g g8 d f g a g f4 g8 a a4  s
  \tuplet 3/2 { 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 GregorianTranscriptionStaff <<
    \new GregorianTranscriptionVoice = "chant" {
      \spiritus
    }
    \new GregorianTranscriptionLyrics = "one" {
      \lyricsto "chant" \spirLyr
    }
  >>
  \layout {
    \context {
      \GregorianTranscriptionStaff
      measureBarType = ""
      \override BarLine.X-extent = #'(-1 . 1)
      \hide Beam
      \hide TupletNumber
      \hide TupletBracket
    }
  }
}

[image of music]


Ancient and modern from one source

Using tags to produce mensural and modern music from the same source

Using tags, it is possible to produce both mensural and modern notation from the same music. In this snippet, a function menrest is introduced, allowing mensural rests to be pitched as in the original, but with modern rests in the standard staff position. Tags can also be used where other differences are needed: for example using “whole measure rests” (R1, R\breve, etc.) in modern music, but normal rests (r1, r\breve, etc.) in the mensural version. Converting mensural music to its modern equivalent is usually referred to as “transcription”.

menrest = #(define-music-function (note)
  (ly:music?)
#{
    \tag #'mens $(make-music 'RestEvent note)
    \tag #'mod $(make-music 'RestEvent note 'pitch '())
#})

MenStyle = {
  \autoBeamOff
  \override NoteHead.style = #'petrucci
  \override Score.BarNumber.transparent = ##t
  \override Stem.neutral-direction = #up
}

finalis = \section

Music = \relative c'' {
  \set Score.tempoHideNote = ##t
  \key f \major
  \time 4/4
  g1 d'2 \menrest bes4 bes2 a2 r4 g4 fis2.
  \finalis
}

MenLyr = \lyricmode { So farre, deere life, deare life }
ModLyr = \lyricmode { So far, dear life, dear life }

\score {
  \keepWithTag #'mens {
    <<
      \new MensuralStaff
      {
        \new MensuralVoice = Cantus
          \clef "mensural-c1" \MenStyle \Music
      }
      \new Lyrics \lyricsto Cantus \MenLyr
    >>
  }
}

\score {
  \keepWithTag #'mod {
    \new ChoirStaff <<
      \new Staff
      {
        \new Voice = Sop \with {
          \remove "Note_heads_engraver"
          \consists "Completion_heads_engraver"
          \remove "Rest_engraver"
          \consists "Completion_rest_engraver" }
        {
          \shiftDurations #1 #0 { \autoBeamOff \Music }
        }
      }
      \new Lyrics \lyricsto Sop \ModLyr
    >>
  }
}

[image of music]


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.

Some types of non-Western music and folk/traditional music often employ alternative or extended tuning systems that do not fit easily into standard, classical notation.

Standard notation is still used but with pitch differences being implicit. For example, Arabic music is notated with semi and quarter tone accidentals but with precise pitch alterations being determined by context. In the case of Arabic music, the init file ‘arabic.ly’ provides a suitable set of macros and definitions that extend the standard notation using Italian note names. For more details see Arabic music.

Other types of music require extended or unique notations, for example, Turkish classical music (also known as Ottoman classical music) employs melodic forms known as makamlar where intervals are based on 1/9 divisions of the whole tone. Standard, Western staff notes are still used, but with special accidentals uniquely defined in the files ‘turkish-makam.ly’. For more information on Turkish classical music and makamlar see Turkish classical music.

Other, related init files are also available; ‘hel-arabic.ly’ and ‘makam.ly’.

To locate these init files on your system, see Other sources of information.

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

See also

Notation Reference: Common notation for non-Western music, Key signature, Manual beams.

Snippets: World music.


Arabic note names

Traditional Arabic note names can be quite long and so may not always be suitable for the purpose of music writing.

The ‘hel-arabic.ly’ file allows English note names to be used. This is a rast scale using ‘hel-arabic.ly’;

\include "hel-arabic.ly"
\relative {
\key c \rast
  c' d edb f | g a bdb c | c bb a g | f d c
}

[image of music]

The ‘arabic.ly’ file allows Italian (or Solfege) note names to be used instead. This is a rast scale using ‘arabic.ly’;

\include "arabic.ly"
\relative {
  do' re misb fa | sol la sisb do | sisb la sol fa | misb re do
}

[image of music]

“Rast” is a heptatonic scale that uses quarter tone intervals and is considered the most important and central scale of the “Arabic Maqamat”. For the full list of supported Arabic scales please refer to either the ‘hel-arabic.ly’ or ‘arabic.ly’ files that are both included with LilyPond.

The use of standard Western notation to notate non-Western music is discussed in Common notation for non-Western music. Also see Note names in other languages.

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 {
  \set Staff.extraNatural = ##f
  dod' dob dosd \dwn dob dobsb dodsd do do
}

[image of music]

See also

Notation Reference: Note names in other languages, Common notation for non-Western music, Including LilyPond files.

Installed Files: ‘ly/arabic.ly’ ‘ly/hel-arabic.ly

Snippets: World music.


Arabic key signatures

In addition to the minor and major key signatures, Arabic key signatures are defined in either ‘hel-arabic.ly’ or ‘arabic.ly’ files and define many different maqam groups.

In general, a maqam uses the key signature of its group, or a neighbouring group, and varying accidentals are marked throughout the music. Arabic maqams only allow for limited modulations, due to the nature of Arabic musical instruments.

Here is an example of the key signature for a “maqam muhayer” piece of music:

\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 also appear in the title.

Other maqams in the same bayati group, as shown in the table below (e.g., 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 do not change their fundamental nature, as siblings.

The other maqam in the same group (nawa) is related to bayati by modulation and is shown in the table in parentheses for those that are modulations of their base maqam. Nawa, for example, can be indicated as follows:

\key sol \bayati

In Arabic music, the same term, for example bayati, that is used to indicate a maqam group, will also be a maqam that is usually the most important in the group so can also be thought of as a base maqam.

Here is one suggested grouping that maps the more common maqams to key signatures:

maqam groupkeyfinalisOther maqmas in group (finalis)
ajammajorsibjaharka (fa)
bayatibayatirehussaini, muhayer, saba, ushaq, nawa (sol)
hijazkurdreshahnaz, shad arban (sol), hijazkar (do)
iraqiraqsisb-
kurdkurdrehijazkar kurd (do)
nahawandminordobusalik (re), farah faza (sol)
nakrizminordonawa athar, hisar (re)
rastrastdomahur, yakah (sol)
sikahsikahmisbhuzam

Selected Snippets

Non-traditional key signatures

The commonly used \key command sets the keyAlterations 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.keyAlterations =
  #`(((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.

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

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

\include "arabic.ly"
\relative do' {
  \set Staff.keyAlterations = #`((0 . ,SEMI-FLAT)
                                 (1 . ,SEMI-FLAT)
                                 (2 . ,FLAT)
                                 (5 . ,FLAT)
                                 (6 . ,SEMI-FLAT))
%\set Staff.extraNatural = ##f
  re reb \dwn reb resd
  dod dob dosd \dwn dob |
  dobsb dodsd do do |
}

[image of music]

See also

Music Glossary: maqam, bayati, rast, sikah, iraq, kurd.

Learning Manual: Pitches and key signatures.

Notation Reference: Key signature.

Installed Files: ‘ly/arabic.ly’ ‘ly/hel-arabic.ly

Snippets: World music, Pitches.

Internals Reference: KeySignature.


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 behavior and/or use compound time signatures.

Selected Snippets

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
  \accidentalStyle forget
  \cadenzaOn
  sol4 sol sol sol fad mib sol1 fad8 mib re4. r8 mib1 fad sol
}

[image of music]

See also

Music Glossary: semai, taqasim.

Notation Reference: Manual beams, Automatic beams, Unmetered music, Automatic accidentals, Setting automatic beam behavior, Time signature.

Installed Files: ‘ly/arabic.ly’ ‘ly/hel-arabic.ly

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 {
  \header {
    title = "Semai Muhayer"
    composer = "Jamil Bek"
  }
  \relative {
    \set Staff.extraNatural = ##f
    \set Staff.autoBeaming = ##f
    \key re \bayati
    \time 10/8

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

[image of music]

See also

Installed Files: ‘ly/arabic.ly’ ‘ly/hel-arabic.ly

Snippets: World music.


Further reading for Arabic music

There are some variations in the details of how maqams are grouped, despite agreement of grouping maqams related through common lower tetra chords or by modulation. There are also some inconsistencies, even within the same texts, on how key signatures for a particular maqam should be specified. However, it is common to use a key signature per ‘group’ of maqams instead of individual key signatures for each maqam separately.


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 at roughly the same time as 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) are constructed.

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 that makamlar employ a completely different set of intervals compared to Western scales and modes:

From a modern, notational point of view it is convenient to use standard, Western staff notes (c, d, e, etc.) but with custom accidentals that raise or lower notes by intervals of 1/9, 4/9, 5/9 or 8/9 of a tone.

These custom accidentals are defined in the file ‘turkish-makam.ly’.

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.


Turkish key signatures

Lilypond supports over 200 makam key signature definitions – well beyond what is used in Turkish classical music – with each makam having its own specific tonic / finalis pitch (known as ‘karar’ in Turkish).

It is important to be aware of the finalis of each makam. Here is an example where g is the default tonic and rast is the name of the makam.

\key g \rast

The correct accidentals, koma flat (b1) and koma sharp (f4), (both in relation to the tonic g), will be displayed automatically.

Selected Snippets

Turkish Makam example

This template uses the start of a well-known Turkish Saz Semai that is familiar in the repertoire in order to illustrate some of the elements of Turkish music notation.

\paper { tagline = ##f }

% Initialize makam settings
\include "turkish-makam.ly"

\header {
    title = "Hüseyni Saz Semaisi"
    composer = "Lavtacı Andon"
}

\relative {
  \set Staff.extraNatural = ##f
  \set Staff.autoBeaming = ##f

  \key a \huseyni
  \time 10/8

  a'4 g'16 [fb] e8. [d16] d [c d e] c [d c8] bfc |
  a16 [bfc a8] bfc c16 [d c8] d16 [e d8] e4 fb8 |
  d4 a'8 a16 [g fb e] fb8 [g] a8. [b16] a16 [g] |
  g4 g16 [fb] fb8. [e16] e [g fb e] e4 r8 |
}

[image of music]


Further reading for Turkish music


2.10.4 Persian classical music

This section highlights issues that are relevant to notating Persian classical music.


Persian music notation

The notation for Persian classical music commonly uses two accidentals for microtones, sori and koron. Invented by Ali-Naqi Vaziri around 1935, they indicate raising and lowering a pitch by (approximately) a quarter tone, respectively.

[image of music]

The file ‘persian.ly7 provides support for koron and sori; they can be obtained by appending ‘k’ (koron) and ‘o’ (sori) to the English note symbols.

LilyPond supports tunings for all major Persian modes in all keys, sufficient to notate the gushehs (central nuclear melodies) of all dastgahs (musical modal systems).

The note immediately following a koron is sometimes8 lowered by about 20 cents. This is not notated but considered part of the tuning. However, for getting better MIDI support you can make a sound flat by appending ‘v’ to the note name (‘vlat’). This note should actually also get a strong vibrato, and the vibrato and low tuning are perceptually integrated (serialism). This is just for MIDI and has no effect on the notation itself.

There are no further tuning issues in Persian music. Since the music is monophonic, the difference between just intonation (for example) and equal temperament is merely academic – there are no chords where out-of-tune intervals would be noticeable.

The following suffixes to English note names are provided.

ffdouble-flat
fflat
kkoron (about quarter flat, -3/10 of whole tone, 60 cents)
osori (about quarter sharp, 2/10 of whole tone, 40 cents)
ssharp
xdouble-sharp
v20 cent flat-tuned note (“vlat”, not notated)
fvflat, tuned 20 cents down (notated as a normal flat)
svsharp, tuned 20 cents down (notated as a normal sharp; does never occur in traditional Persian music)

Persian tunings

Dastgahs can have many tunings; it has become common to name tunings after representative dastgahs featuring them. The following Persian tunings are provided to be used as the second argument of the \key command. Note that in practice not all tunings are used in all keys.

\shur‘Shur’ gushehs with natural 5th degree
\shurk‘Shur’ gushehs with koron 5th degree
\esfahan
\mokhalefsegah
\chahargah
\mahurthe same as \major but used in a completely different context
\delkashMahur

In dastgah ‘Shur’, the 5th degree can either be natural or koron, so two tunings are provided (\shur, \shurk). Secondary dastgahs ‘Dashti’, ‘Abuata’, and ‘Bayat-e-tork’ use \shur, the derived dastgah ‘Afshari’ uses \shurk. ‘Nava’ on G is like ‘Shur’ on D (a 4th apart). The tuning of ‘Segah’ is \shurk. Other tunings are \esfahan (‘Homayoun’ on C is like ‘Esfahan’ on G, a 5th apart), \chahargah, and \mokhalefsegah. For dastgahs ‘Mahur’ and ‘Rast-panjgah’ the same tuning \mahur can be used.

All the various modulatory gushehs in all dastgahs can be notated with these tunings, with the exception of ‘Delkash’ in ‘Mahur’, but traditionally the peculiar accidentals there are notated explicitly (however, ‘persian.ly’ also defines a tuning \delkashMahur).

As an example, Chahargah in D can be input with the following.

\include "persian.ly"

\relative c' {
  \key d \chahargah
  bk'8 a gs fo r g ak g |
  fs ek d c d ef16 d c4 |
}

[image of music]


Persian key signatures

By default, the order of accidentals in Persian key signatures is flats followed by korons, then sharps followed by soris (then double flats, then double sharps).

An alternative key order, similar to the one used in ‘turkish-makam.ly’, can be selected. Here, the order is flats or korons (or double flats), then sharps or soris (or double sharps). In other words, korons and soris are handled equal to flats and sharps, respectively.

\include "persian.ly"

{
  \key b \chahargah b'1 |
  \set Staff.keyAlterationOrder = \persianAltKeyAlterationOrder
  \key b \chahargah b'1 |
}

[image of music]


Further reading on Persian music


3. General input and output

This section deals with general LilyPond input and output issues, rather than specific notation.


3.1 Input modes

The way in which the notation contained within an input file is interpreted is determined by the current input mode. In general, there are two ways of specifying the mode: a long form, e.g. \chordmode, and a short form, e.g. \chords. The long form is typically used when supplying input to a variable or when entering input directly into an explicitly created context. The short form implicitly creates a context of the correct type for the input and passes the input directly to it. It is useful in simple situations when there is no requirement to explicitly create the receiving context.

Chord mode

This is activated with the \chordmode command, and causes input to be interpreted with the syntax of chord notation, see Chord notation. Music in chord mode is rendered as chords on a staff when entered into a Staff context, as chord names when entered into a ChordNames context or as fretboards when entered into a FretBoards context.

Chord mode is also activated with the \chords command. This also causes the following input to be interpreted with the syntax of chord notation but in addition it implicitly creates a new ChordNames context and renders the input into it as chord names, 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. Music in drum mode is rendered as percussion notes when entered into a DrumStaff context.

Drum mode is also activated with the \drums command. This also causes the following input to be interpreted with the syntax of drum notation but in addition it implicitly creates a new DrumStaff context and renders the input into it as percussion notes, 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. Music in figure mode is rendered as figured bass when entered into a FiguredBass context or a Staff context.

Figure mode is also activated with the \figures command. This also causes the following input to be interpreted with the figured bass syntax but in addition it implicitly creates a new FiguredBass context and renders the input into it as figured bass, 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, enter notes or chords in either note mode or chord mode and render them in a FretBoards context, see Automatic fret diagrams. Alternatively, fret diagrams can be entered as 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. Input in lyric mode is rendered as lyric syllables when entered into a Lyrics context.

Lyric mode is also activated with the \lyrics command. This also causes the following input to be interpreted as lyric syllables but in addition it implicitly creates a new Lyrics context and renders the input into it as lyric syllables.

Lyric mode is also activated with the \addlyrics command. This also implicitly creates a new Lyrics context and in addition it adds an implicit \lyricsto command which associates the following lyrics with the preceding music, see Automatic syllable durations.

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.


3.2 Input structure

The main format of input for LilyPond are text files. By convention, these files end with ‘.ly’.


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

[image of music]

<<
  \new Staff { c'4 c' c' c' }
  \new Staff { d'4 d' d' d' }
>>

[image of music]

{
  \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.2.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.2.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 behavior is to append a version number suffix for each name which may clash, so

\book {
  \score { … }
  \paper { … }
}
\book {
  \score { … }
  \paper { … }
}
\book {
  \score { … }
  \paper { … }
}

in source file ‘eightminiatures.ly’ produces

eightminiatures.pdf
eightminiatures-1.pdf
eightminiatures-2.pdf

as output files.


3.2.4 Output file names

LilyPond provides facilities to allow you to control what file names are used by the various backends when producing output files.

In the previous section, we saw how LilyPond prevents name clashes when producing several outputs 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
eightminiatures-Nocturne.pdf

by adding a \bookOutputSuffix declaration inside each \book block.

\book {
  \bookOutputSuffix "Romanze"
  \score { … }
  \paper { … }
}
\book {
  \bookOutputSuffix "Menuetto"
  \score { … }
  \paper { … }
}
\book {
  \bookOutputSuffix "Nocturne"
  \score { … }
  \paper { … }
}

You can also specify a different output filename for book block, by using \bookOutputName declarations

\book {
  \bookOutputName "Romanze"
  \score { … }
  \paper { … }
}
\book {
  \bookOutputName "Menuetto"
  \score { … }
  \paper { … }
}
\book {
  \bookOutputName "Nocturne"
  \score { … }
  \paper { … }
}

The file above produces the following output files.

Romanze.pdf
Menuetto.pdf
Nocturne.pdf

3.2.5 File structure

A ‘.ly’ file may contain any number of toplevel expressions, where a toplevel expression is one of the following:

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:

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:

See also

Learning Manual: How LilyPond input files work.

Notation Reference: Titles explained, The \layout block.


3.3 Titles and headers

Almost all printed music includes a title and the composer’s name; some pieces include a lot more information.


3.3.1 Creating titles headers and footers


Titles explained

Each \book block in a single input file produces a separate output file, see File structure. Within each output file three types of titling areas are provided: Book Titles at the beginning of each book, Bookpart Titles at the beginning of each bookpart and Score Titles at the beginning of each score.

Values of titling fields such as title and composer are set in \header blocks. (For the syntax of \header blocks and a complete list of the fields available by default see Default layout of bookpart and score titles). Book Titles, Bookpart Titles and Score Titles can all contain the same fields, although by default the fields in Score Titles are limited to piece and opus.

\header blocks may be placed in four different places to form a descending hierarchy of \header blocks:

The values of the fields filter down this hierarchy, with the values set higher in the hierarchy persisting unless they are overridden by a value set lower in the hierarchy, so:

It is not necessary to provide \header blocks in all four places: any or even all of them may be omitted. Similarly, simple input files may omit the \book and \bookpart blocks, leaving them to be created implicitly.

If the book has only a single score, the \header block should normally be placed at the top of the file so that just a Bookpart Title is produced, making all the titling fields available for use.

If the book has multiple scores a number of different arrangements of \header blocks are possible, corresponding to the various types of musical publications. For example, if the publication contains several pieces by the same composer a \header block placed at the top of the file specifying the book title and the composer with \header blocks in each \score block specifying the piece and/or opus would be most suitable, as here:

\header {
  title = "SUITE I."
  composer = "J. S. Bach."
}

\score {
  \header {
    piece = "Prélude."
  }
  \new Staff \relative {
    \clef bass
    \key g \major
    \repeat unfold 2 { g,16( d' b') a b d, b' d, } |
    \repeat unfold 2 { g,16( e' c') b c e, c' e, } |
  }
}

\score {
  \header {
    piece = "Allemande."
  }
  \new Staff \relative {
    \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) |
  }
}

[image of music]

More complicated arrangements are possible. For example, text fields from the \header block in a book can be displayed in all Score Titles, with some fields overridden and some manually suppressed:

\book {
  \paper {
    print-all-headers = ##t
  }
  \header {
    title = "DAS WOHLTEMPERIRTE CLAVIER"
    subtitle = "TEIL I"
    % Do not display the default LilyPond footer for this book
    tagline = ##f
  }
  \markup { \vspace #1 }
  \score {
    \header {
      title = "PRAELUDIUM I"
      opus = "BWV 846"
      % Do not display the subtitle for this score
      subtitle = ##f
    }
    \new PianoStaff <<
      \new Staff { s1 }
      \new Staff { \clef "bass" s1 }
    >>
  }
  \score {
    \header {
      title = "FUGA I"
      subsubtitle = "A 4 VOCI"
      opus = "BWV 846"
      % Do not display the subtitle for this score
      subtitle = ##f
    }
    \new PianoStaff <<
      \new Staff { s1 }
      \new Staff { \clef "bass" s1 }
    >>
  }
}

[image of music]

See also

Notation Reference: File structure, Default layout of bookpart and score titles, Custom layout for titles.


Default layout of bookpart and score titles

This example demonstrates all printed \header variables:

\book {
  \header {
    % The following fields are centered
    dedication = "Dedication"
    title = "Title"
    subtitle = "Subtitle"
    subsubtitle = "Subsubtitle"

    % The following fields are evenly spread on one line;
    % the field "instrument" also appears on following pages
    instrument = \markup \with-color #green "Instrument"
    poet = "Poet"
    composer = "Composer"

    % The following fields are placed at opposite ends
    %of the same line
    meter = "Meter"
    arranger = "Arranger"

    % The following fields are centered at the bottom
    tagline = "The tagline goes at the bottom of the last page"
    copyright = "The copyright goes at the bottom of the first page"
  }
  \score {
    \header {
      % The following fields are placed at opposite ends
      % of the same line
      piece = "Piece 1"
      opus = "Opus 1"
    }
    { s1 }
  }
  \score {
    \header {
      % The following fields are placed at opposite ends
      % of the same line
      piece = "Piece 2 on the same page"
      opus = "Opus 2"
    }
    { s1 }
  }
  \pageBreak
  \score {
    \header {
      % The following fields are placed at opposite ends
      % of the same line
      piece = "Piece 3 on a new page"
      opus = "Opus 3"
    }
    { s1 }
  }
}

[image of music]

Note that

To change the default layout see Custom layout for titles.

If a \book block starts immediately with a \bookpart block, no Book Title will be printed, as there is no page on which to print it. If a Book Title is required, begin the \book block with some markup material or a \pageBreak command.

Use the breakbefore variable inside a \header block that is itself in a \score block, to make the higher-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 {
    \header {
      piece = "This is the Music"
      breakbefore = ##t
    }
    \repeat unfold 4 { e'' e'' e'' e'' }
  }
}

[image of music]

See also

Learning Manual: How LilyPond input files work,

Notation Reference: Custom layout for titles, 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:

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:

The default LilyPond footer text can be changed by adding a tagline in the top-level \header block.

\book {
  \header {
    tagline = "... music notation for Everyone"
  }
  \score {
    \relative {
      c'4 d e f
    }
  }
}

[image of music]

To remove the default LilyPond footer text, the tagline can be set to #f.


3.3.2 Custom titles headers and footers


Custom text formatting for titles

Standard \markup commands can be used to customize any header, footer and title text within the \header block.

\score {
  \header {
    piece = \markup { \fontsize #4 \bold "PRAELUDIUM I" }
    opus = \markup { \italic "BWV 846" }
  }
  { s1 }
}

[image of music]

See also

Notation Reference: Formatting text.


Custom layout for titles

\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, change either or both of the following \paper variables:

The placement of titles when using the default values of these \markup variables is shown in the examples in Default layout of bookpart and score titles.

The default settings for scoreTitleMarkup as defined in ‘ly/titling-init.ly’ are:

scoreTitleMarkup = \markup { \column {
  \if \should-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 {
  \header {
    piece = "PRAELUDIUM I"
    opus = "BWV 846"
  }
  { s1 }
}

[image of music]

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 {
    \header {
      piece = "PRAELUDIUM I"
      opus = "BWV 846"
    }
    { s1 }
  }
}

[image of music]

Text fields not normally effective in score \header blocks can be printed in the Score Title area if print-all-headers is placed inside the \paper block. A disadvantage of using this method is that text fields that are intended specifically for the Bookpart Title area need to be manually suppressed in every \score block. See Titles 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 {
    \header {
      piece = "MENUET"
      composer = "Christian Petzold"
    }
    { s1 }
  }
  \score {
    \header {
      piece = "RONDEAU"
      composer = "François Couperin"
    }
    { s1 }
  }
}

[image of music]

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 {
    \header {
      piece = "FUGA I"
      mycustomtext = "A 4 VOCI" %% User-defined field
      opus = "BWV 846"
    }
    { s1 }
  }
}

[image of music]

See also

Notation Reference: Titles explained.


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:

The \markup command \if can be used to add markup conditionally to header and footer text defined within the \paper block, using the following syntax within \markup:

\if condition argument

The condition is tested each time the markup is interpreted. The resulting markup is argument if the condition is true, but empty if false. Typical conditions include tests for page numbers (first page, last page, specific page, …). To test for the condition being false, replace \if with \unless.

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 {
        \if \should-print-page-number
        \fromproperty #'page:page-number-string
      }
    }
    evenFooterMarkup = \oddFooterMarkup
  }
  \score {
    \new Staff { s1 \break s1 \break s1 }
  }
}

[image of music]

Here is a list of all predefined procedures available for use with \if and \unless.

SyntaxCondition tested
\on-first-pageFirst page in the book?
\on-last-pageLast page in the book?
\on-first-page-of-partFirst page in the book part?
\on-last-page-of-partLast page in the book part?
\on-page nOn page number n?
\single-pageDoes the book fit on just one page?
\should-print-page-numbers-globalPrint page numbers in the book? 9
\should-print-page-numberPrint the number of the current page?
\should-print-all-headersIs print-all-headers true?

See also

Notation Reference: Titles explained, Default layout of bookpart and score titles, Conditionals.

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


3.3.3 Creating output file metadata

In addition to being shown in the printed output, \header variables are also used to set metadata for output files. For example, with PDF files, this metadata could be displayed by PDF readers as the properties of the PDF file. For each type of output file, only the \header definitions of blocks that define separate files of that type, and blocks higher in the block hierarchy, will be consulted. Therefore, for PDF files, only the \book level and the top level \header definitions affect the document-wide PDF metadata, whereas for MIDI files, all headers above or at the \score level are used.

For example, setting the title property of the header block to ‘Symphony I’ will also give this title to the PDF document, and use it as the sequence name of the MIDI file.

\header {
  title = "Symphony I"
}

If you want to set the title of the printed output to one value, but have the title property of the PDF to have a different value, you can use pdftitle, as below.

\header {
  title = "Symphony I"
  pdftitle = "Symphony I by Beethoven"
}

The variables title, subject, keywords, subtitle, composer, arranger, poet, author and copyright all set PDF properties and can all be prefixed with ‘pdf’ to set a PDF property to a value different from the printed output.

The PDF property Creator is automatically set to ‘LilyPond’ plus the current LilyPond version, and CreationDate and ModDate are both set to the current date and time. ModDate can be overridden by setting the header variable moddate (or pdfmoddate) to a valid PDF date string.

The title variable sets also the sequence name for MIDI. The midititle variable can be used to set the sequence name independently of the value used for typeset output.


3.3.4 Creating footnotes

Footnotes may be used in many different situations. In all cases, a ‘footnote mark’ is placed as a reference in text or music, and the corresponding ‘footnote text’ appears at the bottom of the same page, separated from the music by a horizontal line. The appearance of this separator can be changed by setting the paper variable footnote-separator-markup, see \paper variables concerning headers and markups.

Footnotes within music expressions and footnotes in stand-alone text outside music expressions are created in different ways.


Footnotes in music expressions

Music footnotes overview

Footnotes in music expressions fall into two categories:

Event-based footnotes

are attached to a particular event. Examples for such events are single notes, articulations (like fingering indications, accents, dynamics), and post-events (like slurs and manual beams). The general form for event-based footnotes is as follows:

[direction] \footnote [mark] offset footnote music
Time-based footnotes

are bound to a particular point of time in a musical context. Some commands like \time and \clef don’t actually use events for creating objects like time signatures and clefs. Neither does a chord create an event of its own: its stem or flag is created at the end of a time step (nominally through one of the note events inside). Exactly which of a chord’s multiple note events will be deemed the root cause of a stem or flag is undefined. So for annotating those, time-based footnotes are preferable as well.

A time-based footnote allows such layout objects to be annotated without referring to an event. The general form for time-based footnotes is:

\footnote [mark] offset footnote [Context].GrobName

The elements for both forms are:

direction

If (and only if) the \footnote is being applied to a post-event or articulation, it must be preceded with a direction indicator (‘-’, ‘_’, ‘^’) in order to attach music (with a footnote mark) to the preceding note or rest.

mark

is a markup or string specifying the footnote mark which is used for marking both the reference point and the footnote itself at the bottom of the page. It may be omitted (or equivalently replaced with \default) in which case a number in sequence will be generated automatically. By default, such numerical sequences restart on each page containing a footnote. Footnotes may be numbered consecutively across page beaks by setting the variable reset-footnotes-on-new-page to #f, see \paper variables concerning headers and markups.

offset

is a number pair such as ‘#(2 . 1)’ specifying the X and Y offsets in units of staff spaces from the boundary of the object where the mark should be placed. Positive values of the offsets are taken from the right/top edge, negative values from the left/bottom edge and zero implies the mark is centered on the edge.

Context

is the context in which the grob being footnoted is created. It may be omitted if the grob is in a bottom context, e.g., a Voice context.

GrobName

specifies a type of grob to mark (like ‘Flag’). If it is specified, the footnote is not attached to a music expression in particular, but rather to all grobs of the type specified which occur at that moment of musical time.

footnote

is the markup or string specifying the footnote text to use at the bottom of the page.

music

is the music event or post-event or articulation that is being annotated.

Event-based footnotes

A footnote may be attached to a layout object directly caused by the event corresponding to music with the syntax:

\footnote [mark] offset footnote music
\book {
  \header { tagline = ##f }
  \relative c'' {
    \footnote #'(-1 . 3) "A note" a4
    a4
    \footnote #'(2 . 2) "A rest" r4
    a4
  }
}

[image of music]

Marking a whole chord with an event-based footnote is not possible: a chord, even one containing just a single note, does not produce an actual event of its own. However, individual notes inside of the chord can be marked:

\book {
  \header { tagline = ##f }
  \relative c'' {
    \footnote #'(2 . 3) "Does not work" <a-3>2
    <\footnote #'(-2 . -3) "Does work" a-3>4
    <a-3 \footnote #'(3 . 1/2) "Also works" c-5>4
  }
}

[image of music]

If the footnote is to be attached to a post-event or articulation the \footnote command must be preceded by a direction indicator (‘-’, ‘_’, ‘^’), and followed by the post-event or articulation to be annotated as the music argument. In this form the \footnote can be considered to be simply a copy of its last argument with a footnote mark attached to it. The syntax is:

direction \footnote [mark] offset footnote music
\book {
  \header { tagline = ##f }
  \relative {
    a'4_\footnote #'(0 . -1) "A slur forced down" (
    b8^\footnote #'(1 . 0.5) "A manual beam forced up" [
    b8 ]
    c4 )
    c-\footnote #'(1 . 1) "Tenuto" --
  }
}

[image of music]

Time-based footnotes

If the layout object being footmarked is indirectly caused by an event (like an Accidental or Stem caused by a NoteHead event), the GrobName of the layout object is required after the footnote text instead of music:

\book {
  \header { tagline = ##f }
  \relative c'' {
    \footnote #'(-1 . -3) "A flat" Accidental
    aes4 c
    \footnote #'(-1 . 0.5) "Another flat" Accidental
    ees
    \footnote #'(1 . -2) "A stem" Stem
    aes
  }
}

[image of music]

Note, however, that when a GrobName is specified, a footnote is attached to all grobs of that type at the current time step:

\book {
  \header { tagline = ##f }
  \relative c' {
    \footnote #'(-1 . 3) "A flat" Accidental
    <ees ges bes>4
    \footnote #'(2 . 0.5) "Articulation" Script
    c'->-.
  }
}

[image of music]

A note inside of a chord can be given an individual (event-based) footnote. A ‘NoteHead’ is the only grob directly caused from a chord note, so an event-based footnote command is only suitable for adding a footnote to the ‘NoteHead’ within a chord. All other chord note grobs are indirectly caused. The \footnote command itself offers no syntax for specifying both a particular grob type as well as a particular event to attach to. However, one can use a time-based \footnote command for specifying the grob type, and then prefix this command with \single in order to have it applied to just the following event:

\book {
  \header { tagline = ##f }
  \relative c'' {
    < \footnote #'(1 . -2) "An A" a
      \single \footnote #'(-1 . -1) "A sharp" Accidental
      cis
      \single \footnote #'(0.5 . 0.5) "A flat" Accidental
      ees fis
    >2
  }
}

[image of music]

Note: When footnotes are attached to several musical elements at the same musical moment, as they are in the example above, the footnotes are numbered from the higher to the lower elements as they appear in the printed output, not in the order in which they are written in the input stream.

Layout objects like clefs and key change signatures are mostly caused as a consequence of changed properties rather than actual events. Others, like bar lines and bar numbers, are a direct consequence of timing. For this reason, footnotes on such objects have to be based on their musical timing. Time-based footnotes are also preferable when marking features like stems and beams on chords: while such per-chord features are nominally assigned to one event inside the chord, relying on a particular choice would be imprudent.

The layout object in question must always be explicitly specified for time-based footnotes, and the appropriate context must be specified if the grob is created in a context other than the bottom context.

\book {
  \header { tagline = ##f }
  \relative c'' {
    r1 |
    \footnote #'(-0.5 . -1) "Meter change" Staff.TimeSignature
    \time 3/4
    \footnote #'(1 . -1) "Chord stem" Stem
    <c e g>4 q q
    \footnote #'(-0.5 . 1) "Bar line" Staff.BarLine
    q q
    \footnote #'(0.5 . -1) "Key change" Staff.KeySignature
    \key c \minor
    q
  }
}

[image of music]

Custom marks can be used as alternatives to numerical marks, and the annotation line joining the marked object to the mark can be suppressed:

\book {
  \header { tagline = ##f }
  \relative c' {
    \footnote "*" #'(0.5 . -2) \markup { \italic "* The first note" }
    a'4 b8
    \footnote \markup { \super "$" } #'(0.5 . 1)
      \markup { \super "$" \italic " The second note" } e
    c4
    \once \override Score.Footnote.annotation-line = ##f
    b-\footnote \markup \tiny "+" #'(0.1 . 0.1)
      \markup { \super "+" \italic " Editorial" } \p
  }
}

[image of music]

More examples of custom marks are shown in Footnotes in stand-alone text.


Footnotes in stand-alone text

These are for use in markup outside of music expressions. They do not have a line drawn to their point of reference: their marks simply follow the referenced markup. Marks can be inserted automatically, in which case they are numerical. Alternatively, custom marks can be provided manually.

Footnotes to stand-alone text with automatic and custom marks are created in different ways.

Footnotes in stand-alone text with automatic marks

The syntax of a footnote in stand-alone text with automatic marks is

\markup { … \auto-footnote text footnote … }

The elements are:

text

the markup or string to be marked,

footnote

the markup or string specifying the footnote text to use at the bottom of the page.

For example:

\book {
  \header { tagline = ##f }
  \markup {
    "A simple"
    \auto-footnote "tune" \italic " By me"
    "is shown below.  It is a"
    \auto-footnote "recent" \italic " Aug 2012"
    "composition."
  }
  \relative {
    a'4 b8 e c4 d
  }
}

[image of music]

Footnotes in stand-alone text with custom marks

The syntax of a footnote in stand-alone text with custom marks is

\markup { … \footnote mark footnote … }

The elements are:

mark

is a markup or string specifying the footnote mark which is used for marking the reference point. Note that this mark is not inserted automatically before the footnote itself.

footnote

is the markup or string specifying the footnote text to use at the bottom of the page, preceded by the mark.

Any easy to type character such as ‘*’ or ‘+’ may be used as a mark, as shown in Footnotes in music expressions. Alteratively, ASCII aliases may be used (see ASCII aliases):

\book {
  \paper { #(include-special-characters) }
  \header { tagline = ##f }
  \markup {
    "A simple tune"
    \footnote "*" \italic "* By me"
    "is shown below.  It is a recent"
    \footnote \super &dagger; \concat {
      \super &dagger; \italic " Aug 2012"
    }
    "composition."
  }
  \relative {
    a'4 b8 e c4 d
  }
}

[image of music]

Unicode character codes may also be used to specify marks (see Unicode):

\book {
  \header { tagline = ##f }
  \markup {
    "A simple tune"
    \footnote \super \char##x00a7 \concat {
      \super \char##x00a7 \italic " By me"
    }
    "is shown below.  It is a recent"
    \footnote \super \char##x00b6 \concat {
      \super \char##x00b6 \italic " Aug 2012"
    }
    "composition."
  }
  \relative {
    a'4 b8 e c4 d
  }
}

[image of music]

See also

Learning Manual: Objects and interfaces.

Notation Reference: ASCII aliases, Balloon help, List of special characters, Text marks, Text scripts, Unicode.

Internals Reference: FootnoteEvent, Footnote, Footnote_engraver.

Known issues and warnings

Multiple footnotes for the same page can only be stacked, one above the other; they cannot be printed on the same line.

Footnote marks may collide with staves, \markup objects, other footnote marks and annotation lines.


3.3.5 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" "?" }
}

[image of music]

The \page-ref markup command takes three arguments:

  1. the label, a Scheme symbol, for example #'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”, i.e., a two digit number.

Predefined commands

\label, \page-ref.


3.3.6 Table of contents

A table of contents is included using the \markuplist \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.

\markuplist \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 % ...
    \tocItem actI \markup "Act I"
    f'4 % ...
    \tocItem actI.sceneI \markup "Scene 1"
    g'4 % ...
    \tocItem actI.sceneI.recitativo \markup "Recit."
    a'4 % ...
  }
}

Optionally, a label can be associated with a particular item, or a hierarchical list of existing labels, finishing with that item’s label. That latter case allows to mark the item as a ‘child’ of the preceding labeled items, thus making the score’s structure apparent in the table of contents.

Markups used for formatting the table of contents are defined in the \paper block. There are three ‘predefined’ markups already available;

Any of these variables can be changed.

Here is an example translating the table of contents’ title into French:

\paper {
  tocTitleMarkup = \markup \huge \column {
    \fill-line { \null "Table des matières" \null }
    \hspace #1
  }

Here is an example changing the font size of the elements in the table of contents:

tocItemMarkup = \markup \large \fill-line {
  \fromproperty #'toc:text \fromproperty #'toc:page
}

Note how the element text and page numbers are referred to in the tocItemMarkup definition.

The \tocItemWithDotsMarkup command can be included within the tocItemMarkup to fill the line, between a table of contents item and its corresponding page number, with dots:

\header { tagline = ##f }
\paper {
  tocItemMarkup = \tocItemWithDotsMarkup
}

\book {
  \markuplist \table-of-contents
  \tocItem \markup { Allegro }
  \tocItem \markup { Largo }
  \markup \null
}

[image of music]

In addition to the built-in outline mechanism, custom commands can also be defined to build a more personalized table of contents with different markups In the following example, a new style is defined for entering act and scenes in the table of contents of an opera:

A new markup variable (called tocActMarkup) is defined in the \paper block:

\paper {
  tocActMarkup = \markup \large \column {
    \hspace #1
    \fill-line { \null \italic \fromproperty #'toc:text \null }
    \hspace #1
  }
}

A custom music function (tocAct) is then created – which uses the new tocActMarkup markup definition, and allows to specify a label for each act.

tocAct =
  #(define-music-function (label text) (symbol? markup?)
     (add-toc-item! 'tocActMarkup text label))

Using these custom definitions and modifying some of the existing definitions, the source file could then be written as follows:

[image of music]

The previous example also demonstrates how to use the \fill-with-pattern markup command within the context of a table of contents.

See also

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

Predefined commands

\table-of-contents, \tocItem, tocItemMarkup, tocTitleMarkup, tocFormatMarkup, tocIndentMarkup.


3.4 Working with input files


3.4.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. These second-level \include statements are then interpreted relatively to the path of the file containing that command, which is convenient for multiple files located in the same subdirectory. For example, a general library, libA, may itself use subfiles which are \included by the entry file of that library, like this:

libA/
  libA.ly
  A1.ly
  A2.ly
  …

then the entry file, libA.ly, will contain

\include "A1.ly"
\include "A2.ly"
…

Any ‘.ly’ file can then include the entire library simply with

\include "~/libA/libA.ly"

However, that behavior can be changed globally by passing the command line option ‘-drelative-includes=#f’, or by adding #(ly:set-option 'relative-includes #f) at the top of the main input file. In that case, each file will be included relatively to the location of the main file, regardless of where its \include statement is located. Complex file structures, that require to \include both files relative to the main directory and files relative to some other directory, may even be devised by setting relative-includes to #f or #t at appropriate places in the files.

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.4.2 Different editions from one source

Several methods can be used to generate different versions of a score from the same music source. Variables are perhaps the most useful for combining lengthy sections of music and/or annotation. Tags are more useful for selecting one section from several alternative shorter sections of music, and can also be used for splicing pieces of music together at different points.

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 { a'4 b c b8( a) }
altoMusic = \relative { e'4 e e f }
tenorMusic = \relative { c'4 b e d8( c) }
bassMusic = \relative { 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" {
      \partCombine \sopranoMusic \altoMusic
    }
    \new Staff = "LH" {
      \clef "bass"
      \partCombine \tenorMusic \bassMusic
    }
  >>
>>

[image of music]

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:

FilterResult
Tagged music preceded by
\keepWithTag #'name
or
\keepWithTag #'(name1 name2…)
Untagged music and music tagged with any of the given tag names is included; music tagged with any other tag name is excluded.
Tagged music preceded by
\removeWithTag #'name
or
\removeWithTag #'(name1 name2…)
Untagged music and music not tagged with any of the given tag names is included; music tagged with any of the given tag names 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 or list of symbols (such as #'score or #'(violinI violinII), followed by a music expression. If and only if the symbols are valid LilyPond identifiers (alphabetic characters only, no numbers, underscores, or dashes) which cannot be confused with notes, the #' may be omitted and, as a shorthand, a list of symbols can use the dot separator: i.e., \tag #'(violinI violinII) can be written \tag violinI.violinII. The same applies to \keepWithTag and \removeWithTag. Tagging commands are music functions, thus they cannot be used to filter items that are not music expressions, such as \book or \score blocks.

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'8. c32 d
  \tag #'trills { d8.\trill }
  \tag #'expand { \repeat unfold 3 { e32 d } }
  c32 d
 }

\score {
  \keepWithTag #'trills \music
}
\score {
  \keepWithTag #'expand \music
}

[image of music]

Alternatively, it is sometimes easier to exclude sections of music:

music = \relative {
  g'8. c32 d
  \tag #'trills { d8.\trill }
  \tag #'expand {\repeat unfold 3 { e32 d } }
  c32 d
 }

\score {
  \removeWithTag #'expand
  \music
}
\score {
  \removeWithTag #'trills
  \music
}

[image of 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, or by combining multiple tags into one symbol list:

music = \relative c'' {
  \tag #'a \tag #'both { a4 a a a }
  \tag #'(b both) { b4 b b b }
}
<<
\keepWithTag #'a \music
\keepWithTag #'b \music
\keepWithTag #'both \music
>>

[image of music]

Multiple \removeWithTag filters may be applied to a single music expression to remove several differently named tagged sections. Alternatively, you can use a single \removeWithTag with a list of tags.

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 }
}
\new Voice {
  \removeWithTag #'B
  \removeWithTag #'C
  \music
  \removeWithTag #'(B C)
  \music
}

[image of music]

Using two or more \keepWithTag filters on a single music expression will cause all of the tagged sections to be removed. The first filter will remove all except the one named and any subsequent filters will remove the rest. Using one \keepWithTag command with a list of multiple tags will only remove tagged sections that are not specified in that list.

music = \relative c'' {
  \tag #'violinI { a4 a a a }
  \tag #'violinII { b4 b b b }
  \tag #'viola { c4 c c c }
  \tag #'cello { d4 d d d }
}

\new Staff {
  \keepWithTag #'(violinI violinII)
  \music
}

[image of music]

will print \tags violinI and violinII but not viola or cello.

While \keepWithTag is convenient when dealing with one set of alternatives, the removal of music tagged with unrelated tags is problematic when using them for more than one purpose. In that case ‘groups’ of tags can be declared:

\tagGroup #'(violinI violinII viola cello)

Now all the different tags belong to a single ‘tag group’. Note that individual tags cannot be members of more than one tag group.

\keepWithTag #'violinI …

will now only show music tagged from violinI’s tag group and any music tagged with one of the other tags will removed.

music = \relative {
  \tagGroup #'(violinI violinII viola cello)
  \tag #'violinI { c''4^"violinI" c c c }
  \tag #'violinII { a2 a }
  \tag #'viola { e8 e e2. }
  \tag #'cello { d'2 d4 d }
  R1^"untagged"
}

\new Voice {
  \keepWithTag #'violinI
  \music
}

[image of music]

When using the \keepWithTag command, only tags from the tag groups of the tags given in the command are visible.

Sometimes you want to splice some music at a particular place in an existing music expression. You can use \pushToTag and \appendToTag for adding material at the front or end of various music constructs. The supported places are

Sequential and simultaneous music

If you tagged an entire {…} or <<…>> construct, you can add music expressions at its front or back.

Chords

If you tagged a chord <…>, you can either add notes at its front or back, or articulations for the whole chord.

Notes and rests

If you tagged a note (also inside of a chord) or a rest, you can add articulations to the front or back of its existing articulations. Note that to add other notes, you rather have to put the note inside of a chord and tag the chord. Also note that you cannot tag a single articulation and add to it since it isn’t inherently a list. Instead, tag the note.

music = { \tag #'here { \tag #'here <<c''>> } }

{
  \pushToTag #'here c'
  \pushToTag #'here e'
  \pushToTag #'here g' \music
  \appendToTag #'here c'
  \appendToTag #'here e'
  \appendToTag #'here g' \music
}

[image of music]

Both commands get a tag, the material to splice in at every occurence of the tag, and the tagged expression.

See also

Learning Manual: Organizing pieces with variables.

Notation Reference: Automatic part combining, Including LilyPond files.

Known issues and warnings

Calling \relative on a music expression obtained by filtering music through \keepWithTag or \removeWithTag might cause the octave relations to change, as only the pitches actually remaining in the filtered expression will be considered. Applying \relative first, before \keepWithTag or \removeWithTag, avoids this danger as \relative then acts on all the pitches as input.


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


3.4.3.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
     (arg1 arg2 …)
     (type1? type2? …)
   #{
     …music…
   #})

where

argNThe nth argument.
typeN?A Scheme type predicate for which argN must return #t.
…music…Normal LilyPond input, using $ (in places where only LilyPond constructs are allowed) or # (to use it as a Scheme value or music function argument or music inside of music lists) to reference arguments (e.g., ‘#arg1’).

The list of type predicates is required. Some of the most common type predicates used in music functions are:

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 LilyPond: Music functions.

Installed Files: ‘lily/music-scheme.cc’, ‘scm/c++.scm’, ‘scm/lily.scm’.


3.4.3.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 grob:

padText =
#(define-music-function
     (padding)
     (number?)
   #{
     \once \override TextScript.padding = #padding
   #})

\relative {
  c''4^"piu mosso" b a b
  \padText #1.8
  c4^"piu mosso" b a b
  \padText #2.6
  c4^"piu mosso" b a b
}

[image of music]

In addition to numbers, we can use music expressions such as notes for arguments to music functions:

custosNote =
#(define-music-function
     (note)
     (ly:music?)
   #{
     \tweak NoteHead.stencil #ly:text-interface::print
     \tweak NoteHead.text
        \markup \musicglyph "custodes.mensural.u0"
     \tweak Stem.stencil ##f
     #note
   #})

\relative { c'4 d e f \custosNote g }

[image of music]

Both of those functions are simple single expressions where only the last element of a function call or override is missing. For those particular function definitions, there is a simpler alternative syntax, namely just writing out the constant part of the expression and replacing its final missing element with \etc:

padText =
  \once \override TextScript.padding = \etc

\relative {
  c''4^"piu mosso" b a b
  \padText #1.8
  c4^"piu mosso" b a b
  \padText #2.6
  c4^"piu mosso" b a b
}

[image of music]

custosNote =
  \tweak NoteHead.stencil #ly:text-interface::print
  \tweak NoteHead.text
     \markup \musicglyph "custodes.mensural.u0"
  \tweak Stem.stencil ##f
  \etc

\relative { c'4 d e f \custosNote g }

[image of music]

Substitution functions with multiple arguments can be defined:

tempoPadded =
#(define-music-function
     (padding tempotext)
     (number? markup?)
   #{
     \once \override Score.MetronomeMark.padding = #padding
     \tempo \markup { \bold #tempotext }
   #})

\relative {
  \tempo \markup { "Low tempo" }
  c''4 d e f g1
  \tempoPadded #4.0 "High tempo"
  g4 f e d c1
}

[image of music]


3.4.4 Special characters


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:

[image of music]


Unicode

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, https://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 text mark, as articulation text, in lyrics and as stand-alone text below the score:

\score {
  \relative {
    c''1
    \textMark \markup { \char ##x03A8 }
    c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } }
  }
  \addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
}
\markup { "Copyright 2008--2022" \char ##x00A9 }

[image of music]

To enter the copyright sign in the copyright notice use:

\header {
  copyright = \markup { \char ##x00A9 "2008" }
}

ASCII aliases

A list of ASCII aliases for special characters can be included:

\paper {
  #(include-special-characters)
}

\markup "&flqq; &ndash; &OE;uvre incomplète&hellip; &frqq;"

\score {
  \new Staff { \repeat unfold 9 a'4 }
  \addlyrics {
    This is al -- so wor -- kin'~in ly -- rics: &ndash;_&OE;&hellip;
  }
}

\markup \column {
  "The replacement can be disabled:"
  "&ndash; &OE; &hellip;"
  \override #'(replacement-alist . ()) "&ndash; &OE; &hellip;"
}

[image of music]

You can also make your own aliases, either globally:

\paper {
  #(add-text-replacements!
    '(("100" . "hundred")
      ("dpi" . "dots per inch")))
}
\markup "A 100 dpi."

[image of music]

or locally:

\markup \replace #'(("100" . "hundred")
                    ("dpi" . "dots per inch")) "A 100 dpi."

[image of music]

The replacement is not necessarily a string; it can be an arbitrary markup. On the syntax level, this requires using Scheme quasi-quoting syntax, with a backtick ‘`’ instead of a quote ‘'’ to write the alist.

\markup \replace
  #`(("2nd" . ,#{ \markup \concat { 2 \super nd } #})) "2nd time"

[image of music]

Aliases themselves are not further processed for replacements.

See also

Notation Reference: List of special characters.

Installed Files: ‘ly/text-replacements.ly’.


3.5 Controlling output


3.5.1 Extracting fragments of music

It is possible to output one or more fragments of a score by defining the explicit location of the music to be extracted within the \layout block of the input file using the clip-regions function, and then running LilyPond with the ‘-dclip-systems’ option;

\layout {
  clip-regions
  = #(list
      (cons
       (make-rhythmic-location 5 1 2)
       (make-rhythmic-location 7 3 4)))
}

This example will extract a single fragment of the input file starting after a half note duration in fifth measure (5 1 2) and ending after the third quarter note in the seventh measure (7 3 4).

Additional fragments can be extracted by adding more pairs of make-rhythmic-location entries to the clip-regions list in the \layout block.

By default, each music fragment will be output as a separate EPS file, but other formats such as PDF or PNG can also be created if required. The extracted music is output as if had been literally ‘cut’ from the original printed score so if a fragment runs over one or more lines, a separate output file for each line will be generated.

See also

Notation Reference: The \layout block.

Application Usage: Command-line usage.


3.5.2 Skipping corrected music

When entering or copying music, usually only the music near the end (where new notes are being added) 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 defining a special variable at the source file’s top level, as follows:

showLastLength = R1*5
\score { … }

In this instance, nothing will be rendered but the last five 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 that has already been typeset (for example 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. As a property of the Score context, it affects all voices and staves; see Score – the master of all contexts.

This property is also used to control output to the MIDI file. If some event in the skipped section alters some of its context properties, for example a tempo or instrument change, then that new setting will take effect only at the point in time where skipTypesetting is disabled again:

\relative c' {
  c4 c c c
  \set Score.skipTypesetting = ##t
  d4 d d d
  \tempo 4 = 80
  e4 e e e
  \set Score.skipTypesetting = ##f
  f4 f f f
}

[image of music]

Predefined commands

showLastLength, showFirstLength.

See also

Notation Reference: Interpretation contexts, Score – the master of all contexts.

Internals Reference: All context properties.


3.5.3 Alternative output formats

The default output formats for the printed score are Portable Document Format (PDF) and PostScript (PS). Portable Network Graphics (PNG), Scalable Vector Graphics (SVG) and Encapsulated PostScript (EPS) output formats are available through command line options, see Basic command line options for LilyPond.


SVG Output

SVG output can optionally contain metadata for graphical objects (grobs) like note heads, rests, etc. This metadata can be standard SVG attributes like id and class, or non-standard custom attributes. Specify the attributes and their values by overriding a grob’s output-attributes property with a Scheme association list (alist). The values can be numbers, strings, or symbols. For example:

{
  \once \override NoteHead.output-attributes =
  #'((id . 123)
     (class . "this that")
     (data-whatever . something))
  c
}

The input above will produce the following <g> (group) tag in the SVG file:

<g id="123" class="this that" data-whatever="something">
  ...NoteHead grob SVG elements...
</g>

The <g> tag contains all of the SVG elements for a given grob. (Some grobs generate multiple SVG elements.) In SVG syntax the data- prefix is used for non-standard custom metadata attributes.


3.5.4 Replacing the notation font

Gonville is an alternative set of glyphs to Feta – part of the Emmentaler font – and used in LilyPond. They can be downloaded from:

http://www.chiark.greenend.org.uk/~sgtatham/gonville/

Here are a few sample bars of music set in Gonville:

Gonville_after

Here are a few sample bars of music set in LilyPond’s Feta glyphs:

Gonville_before

Installation Instructions

For more information, see Other sources of information.

Note: ‘gonville-*.otf’ files are for ps and eps backend (for PDF and PostScript outputs). ‘gonville-*.svg’ files are for svg backend without svg-woff option. ‘gonville-*.woff’ files are for svg backend with svg-woff option. For more information, see Advanced command line options for LilyPond.

The following syntax changes the notation font (general and brace) to the Gonville font.

\paper {
  #(define fonts
    (set-global-fonts
     #:music "gonville"
     #:brace "gonville"
   ))
}

Note: Each call to set-global-fonts completely resets both the main notation and text fonts. If any category is left unspecified, then the default font will be used for that category. Each call to set-global-fonts changes the fonts for each \book that follows it, whether created explicitly or implicitly. This means that each \book can have its own set of main fonts by calling set-global-fonts before it. For more information, see Entire document fonts.

See also

Learning Manual: Other sources of information.

Notation Reference: The Emmentaler font, Entire document fonts.

Known issues and warnings

Gonville cannot be used to typeset ‘Ancient Music’ notation and it is likely newer glyphs in later releases of LilyPond may not exist in the Gonville font family. Please refer to the author’s website for more information on these and other specifics, including licensing of Gonville.

Other notation fonts

If you have other notation fonts like ‘fontname-*.otf’, ‘fontname-*.svg’, and ‘fontname-*.woff’, you can use them in the same way as Gonville.

That is, copy the ‘fontname-*.otf’ files to ‘…/share/lilypond/current/fonts/otf’ or ‘…/share/lilypond/X.Y.Z/fonts/otf’. If you have ‘fontname-*.svg’ and ‘fontname-*.woff’ files, copy them to ‘…/share/lilypond/current/fonts/svg’ or ‘…/share/lilypond/X.Y.Z/fonts/svg’.

Note: At the moment, LilyPond expects the font file names to have the following suffixes, all of which must be present in the above installation folder(s) to work properly: ‘-11’, ‘-13’, ‘-14’, ‘-16’, ‘-18’, ‘-20’, ‘-23’, ‘-26’, ‘-brace’. For example, ‘emmentaler-11.otf’, ‘emmentaler-20.svg’, and ‘emmentaler-brace.woff’ etc.

The following syntax changes the notation font (general and brace) to the fontname font.

\paper {
  #(define fonts
    (set-global-fonts
     #:music "fontname" ; font filename without suffix and extension
     #:brace "fontname" ; font filename without suffix and extension
   ))
}

Note: For music and brace categories, specify the font filename without the suffix and extension.


3.6 Creating MIDI output

LilyPond can produce files that conform to the MIDI (Musical Instrument Digital Interface) standard and so allow for the checking of the music output aurally (with the help of an application or device that understands MIDI). Listening to MIDI output may also help in spotting errors such as notes that have been entered incorrectly or are missing accidentals and so on.

MIDI files do not contain sound (like AAC, MP3 or Vorbis files) but require additional software to produce sound from them.


3.6.1 Supported notation for MIDI

The following musical notation can be used with LilyPond’s default capabilities to produce MIDI output;

Panning, balance, expression, reverb and chorus effects can also be controlled by setting context properties, see Context properties for MIDI effects.

When combined with the ‘articulate’ script the following, additional musical notation can be output to MIDI;

See Enhancing MIDI output.


3.6.2 Unsupported notation for MIDI

The following items of musical notation cannot be output to MIDI;


3.6.3 The MIDI block

To create a MIDI output file from a LilyPond input file, insert a \midi block, which can be empty, within the \score block;

\score {
  … music …
  \layout { }
  \midi { }
}

Note: A \score block that, as well as the music, contains only a \midi block (i.e., without the \layout block), will only produce MIDI output files. No notation will be printed.

The default output file extension (.midi) can be changed by using the -dmidi-extension option with the lilypond command:

lilypond -dmidi-extension=mid MyFile.ly

Alternatively, add the following Scheme expression before the start of either the \book, \bookpart or \score blocks. See File structure.

#(ly:set-option 'midi-extension "mid")

See also

Notation Reference: File structure, Creating output file metadata.

Installed Files: ‘scm/midi.scm’.

Known issues and warnings

There are fifteen MIDI channels available and one additional channel (#10) for drums. Staves are assigned to channels in sequence, so a score that contains more than fifteen staves will result in the extra staves sharing (but not overwriting) the same MIDI channel. This may be a problem if the sharing staves have conflicting, channel-based, MIDI properties – such as different MIDI instruments – set.


3.6.4 Controlling MIDI dynamics

It is possible to control the overall MIDI volume, the relative volume of dynamic markings and the relative volume of different instruments.

Dynamic marks translate automatically into volume levels in the available MIDI volume range whereas crescendi and decrescendi vary the volume linearly between their two extremes. It is possible to control the relative volume of dynamic markings, and the overall volume levels of different instruments.


Dynamic marks in MIDI

Only the dynamic markings from ppppp to fffff, including mp, mf and sf have values assigned to them. This value is then applied to the value of the overall MIDI volume range to obtain the final volume included in the MIDI output for that particular dynamic marking. The default fractions range from 0.25 for ppppp to 0.95 for fffff. The complete set of dynamic marks and their associated fractions can be found in ‘scm/midi.scm’.

Selected Snippets

Creating custom dynamics in MIDI output

The following example shows how to create a dynamic marking, not included in the default list, and assign it a specific value so that it can be used to affect MIDI output.

The dynamic mark \rfz is assigned a value of 0.9.

#(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 {
        a'4\pp b c-\rfz
      }
    }
  }
  \layout {}
  \midi {}
}

[image of music]

Installed Files: ‘ly/script-init.ly’ ‘scm/midi.scm’.

Snippets: MIDI.

Internals Reference: Dynamic_performer.


Setting 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 at the start of a voice and on dynamic marks. 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 {
      \set Staff.midiInstrument = "flute"
      … music …
    }
    \new Staff {
      \set Staff.midiInstrument = "clarinet"
      … music …
    }
  >>
  \midi {
    \context {
      \Score
      midiMinimumVolume = #0.2
      midiMaximumVolume = #0.5
    }
  }
}

Simple MIDI instrument equalization can be achieved by setting midiMinimumVolume and midiMaximumVolume properties within the Staff context.

\score {
  \new Staff {
    \set Staff.midiInstrument = "flute"
    \set Staff.midiMinimumVolume = #0.7
    \set Staff.midiMaximumVolume = #0.9
    … music …
  }
  \midi { }
}

For scores with multiple staves and multiple MIDI instruments, the relative volumes of each instrument can be set individually;

\score {
  <<
    \new Staff {
      \set Staff.midiInstrument = "flute"
      \set Staff.midiMinimumVolume = #0.7
      \set Staff.midiMaximumVolume = #0.9
      … music …
    }
    \new Staff {
      \set Staff.midiInstrument = "clarinet"
      \set Staff.midiMinimumVolume = #0.3
      \set Staff.midiMaximumVolume = #0.6
      … music …
    }
  >>
  \midi { }
}

In this example the volume of the clarinet is reduced relative to the volume of the flute.

If these volumes properties are not set then LilyPond still applies a ‘small degree’ of equalization to certain instruments. See ‘scm/midi.scm’.

Installed Files: ‘scm/midi.scm’.

See also

Notation Reference: Score layout.

Internals Reference: Dynamic_performer.

Selected Snippets

Replacing default MIDI instrument equalization

The default MIDI instrument equalizer can be replaced by setting the instrumentEqualizer property in the Score context to a user-defined Scheme procedure that uses a MIDI instrument name as its argument along with a pair of fractions indicating the minimum and maximum volumes respectively to be applied to that specific instrument.

The following example sets the minimum and maximum volumes for flute and clarinet respectively."

#(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 {
        r2 g''\mp g fis~
        4 g8 fis e2~
        4 d8 cis d2
      }
    }
    \new Staff {
      \key g \major
      \set Staff.midiInstrument = "clarinet"
      \new Voice \relative {
        b'1\p a2. b8 a
        g2. fis8 e
        fis2 r
      }
    }
  >>
  \layout { }
  \midi {  }
}

[image of music]

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.


Setting MIDI block properties

The \midi block can contain context rearrangements, new context definitions or code that sets the values of certain properties.

\score {
  … music …
  \midi {
    \tempo 4 = 72
  }
}

Here the tempo is set to 72 quarter note beats per minute. The tempo mark in the \midi block will not appear in the printed score. Although any other \tempo indications specified within the \score block will also be reflected in the MIDI output.

In a \midi block the \tempo command is setting properties during the interpretation of the music and in the context of output definitions; so it is interpreted as if it were a context modification.

Context definitions follow the same syntax as those in a \layout block;

\score {
  … music …
  \midi {
    \context {
      \Voice
      \remove Dynamic_performer
    }
  }
}

This example removes the effect of dynamics from the MIDI output. Note: LilyPond’s translation modules used for sound are called ‘performers’.

See also

Learning Manual: Other sources of information.

Notation Reference: Expressive marks, Score layout.

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

Snippets: MIDI.

Internals Reference: Dynamic_performer.

Known issues and warnings

Some MIDI players do not always correctly handle tempo changes in the midi output.

Changes to the midiInstrument, as well as some MIDI options, at the beginning of a staff may appear twice in the MIDI output.


3.6.5 Using MIDI instruments

MIDI instruments are set using the midiInstrument property within a Staff context.

\score {
  \new Staff {
    \set Staff.midiInstrument = "glockenspiel"
    … music …
  }
  \midi { }
}

or

\score {
  \new Staff \with {midiInstrument = "cello"} {
    … music …
  }
  \midi { }
}

If the instrument name does not match any of the instruments listed in the ‘MIDI instruments’ section, the acoustic grand instrument will be used instead. See MIDI instruments.

See also

Learning Manual: Other sources of information.

Notation Reference: MIDI instruments, Score layout.

Installed Files: ‘scm/midi.scm’.

Known issues and warnings

Percussion instruments that are notated in a DrumStaff context will be output, correctly, to MIDI channel 10 but some pitched, percussion instruments like the xylophone, marimba, vibraphone or timpani, are treated as “normal” instruments so the music for these should be entered in a Staff (not DrumStaff) context to obtain correct MIDI output. A full list of channel 10 drum-kits entries can be found in ‘scm/midi.scm’. See Other sources of information.


3.6.6 Using repeats with MIDI

Repeats can be represented in the MIDI output by applying the \unfoldRepeats command.

\score {
  \unfoldRepeats {
    \repeat tremolo 8 { c'32 e' }
    \repeat percent 2 { c''8 d'' }
    \repeat volta 2 { c'4 d' e' f' }
    \alternative {
      \volta 1 { g' a' a' g' }
      \volta 2 { f' e' d' c' }
    }
  }
  \midi { }
}

In order to restrict the effect of \unfoldRepeats to the MIDI output only, while also generating printable scores, it is necessary to make two \score blocks; one for MIDI (with unfolded repeats) and one for the notation (with volta, tremolo, and percent repeats);

\score {
  … music …
  \layout { }
}
\score {
  \unfoldRepeats {
    … music …
  }
  \midi { }
}

When using multiple voices, each of the voices must contain completely unfolded repeats for correct MIDI output.

See also

Notation Reference: Repeats.


3.6.7 MIDI channel mapping

When generating a MIDI file from a score, LilyPond will automatically assign every note in the score to a MIDI channel, the one on which it should be played when it is sent to a MIDI device. A MIDI channel has a number of controls available to select, for example, the instrument to be used to play the notes on that channel, or to request the MIDI device to apply various effects to the sound produced on the channel. At all times, every control on a MIDI channel can have only a single value assigned to it (which can be modified, however, for example, to switch to another instrument in the middle of a score).

The MIDI standard supports only 16 channels per MIDI device. This limit on the number of channels also limits the number of different instruments which can be played at the same time.

LilyPond creates separate MIDI tracks for each staff, (or discrete instrument or voice, depending on the value of Score.midiChannelMapping), and also for each lyrics context. There is no limit to the number of tracks.

To work around the limited number of MIDI channels, LilyPond supports a number of different modes for MIDI channel allocation, selected using the Score.midiChannelMapping context property. In each case, if more MIDI channels than the limit are required, the allocated channel numbers wrap around back to 0, possibly causing the incorrect assignment of instruments to some notes. This context property can be set to one of the following values:

'staff

Allocate a separate MIDI channel to each staff in the score (this is the default). All notes in all voices contained within each staff will share the MIDI channel of their enclosing staff, and all are encoded in the same MIDI track.

The limit of 16 channels is applied to the total number of staff and lyrics contexts, even though MIDI lyrics do not take up a MIDI channel.

'instrument

Allocate a separate MIDI channel to each distinct MIDI instrument specified in the score. This means that all the notes played with the same MIDI instrument will share the same MIDI channel (and track), even if the notes come from different voices or staves.

In this case the lyrics contexts do not count towards the MIDI channel limit of 16 (as they will not be assigned to a MIDI instrument), so this setting may allow a better allocation of MIDI channels when the number of staves and lyrics contexts in a score exceeds 16.

'voice

Allocate a separate MIDI channel to each voice in the score that has a unique name among the voices in its enclosing staff. Voices in different staves are always assigned separate MIDI channels, but any two voices contained within the same staff will share the same MIDI channel if they have the same name. Because midiInstrument and the several MIDI controls for effects are properties of the staff context, they cannot be set separately for each voice. The first voice will be played with the instrument and effects specified for the staff, and voices with a different name from the first will be assigned the default instrument and effects.

Note: different instruments and/or effects can be assigned to several voices on the same staff by moving the Staff_performer from the Staff to the Voice context, and leaving midiChannelMapping to default to 'staff or set to 'instrument; see the snippet below.

For example, the default MIDI channel mapping of a score can be changed to the 'instrument setting as shown:

\score {
  ...music...
  \midi {
    \context {
      \Score
      midiChannelMapping = #'instrument
    }
  }
}

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"
    }
    \tempo 2 = 72
  }
}

[image of music]


3.6.8 Context properties for MIDI effects

The following context properties can be used to apply various MIDI effects to notes played on the MIDI channel associated with the current staff, MIDI instrument or voice (depending on the value of the Score.midiChannelMapping context property and the context in which the Staff_performer is located; see MIDI channel mapping).

Changing these context properties will affect all notes played on the channel after the change, however some of the effects may even apply also to notes which are already playing (depending on the implementation of the MIDI output device).

The following context properties are supported:

Staff.midiPanPosition

The pan position controls how the sound on a MIDI channel is distributed between left and right stereo outputs. The context property accepts a number between -1.0 (#LEFT) and 1.0 (#RIGHT); the value -1.0 will put all sound power to the left stereo output (keeping the right output silent), the value 0.0 (#CENTER) will distribute the sound evenly between the left and right stereo outputs, and the value 1.0 will move all sound to the right stereo output. Values between -1.0 and 1.0 can be used to obtain mixed distributions between left and right stereo outputs.

Staff.midiBalance

The stereo balance of a MIDI channel. Similarly to the pan position, this context property accepts a number between -1.0 (#LEFT) and 1.0 (#RIGHT). It varies the relative volume sent to the two stereo speakers without affecting the distribution of the stereo signals.

Staff.midiExpression

Expression level (as a fraction of the maximum available level) to apply to a MIDI channel. A MIDI device combines the MIDI channel’s expression level with a voice’s current dynamic level (controlled using constructs such as \p or \ff) to obtain the total volume of each note within the voice. The expression control could be used, for example, to implement crescendo or decrescendo effects over single sustained notes (not supported automatically by LilyPond).

The expression level ranges from 0.0 (no expression, meaning zero volume) to 1.0 (full expression).

Staff.midiReverbLevel

Reverb level (as a fraction of the maximum available level) to apply to a MIDI channel. This property accepts numbers between 0.0 (no reverb) and 1.0 (full effect).

Staff.midiChorusLevel

Chorus level (as a fraction of the maximum available level) to apply to a MIDI channel. This property accepts numbers between 0.0 (no chorus effect) and 1.0 (full effect).

Known issues and warnings

As MIDI files do not contain any actual audio data, changes in these context properties translate only to requests for changing MIDI channel controls in the outputted MIDI files. Whether a particular MIDI device (such as a software MIDI player) can actually handle any of these requests in a MIDI file is entirely up to the implementation of the device: a device may choose to ignore some or all of these requests. Also, how a MIDI device will interpret different values for these controls (generally, the MIDI standard fixes the behavior only at the endpoints of the value range available for each control), and whether a change in the value of a control will affect notes already playing on that MIDI channel or not, is also specific to the MIDI device implementation.

When generating MIDI files, LilyPond will simply transform the fractional values within each range linearly into values in a corresponding (7-bit, or 14-bit for MIDI channel controls which support fine resolution) integer range (0-127 or 0-32767, respectively), rounding fractional values towards the nearest integer away from zero. The converted integer values are stored as-is in the generated MIDI file. Please consult the documentation of your MIDI device for information about how the device interprets these values.


3.6.9 Enhancing MIDI output

The default MIDI output is basic but can be improved by setting MIDI instruments and various \midi block properties.

Additional scripts allow to fine-tune the way dynamics, articulations and rhythm are rendered in MIDI: the ‘articulate’ script and the ‘swing’ script.


The ‘articulate’ script

To use the ‘articulate’ script add the appropriate \include command at the top of the input file;

\include "articulate.ly"

The script creates MIDI output into appropriately ‘time-scaled’ notes to match many articulation and tempo indications. Engraved output however, will also be altered to literally match the MIDI output.

\score {
  \articulate <<
    … music …
  >>
  \midi { }
}

The \articulate command enables abbreviatures (such as trills and turns) to be processed. A full list of supported items can be found in the script itself. See ‘ly/articulate.ly’.

See also

Learning Manual: Other sources of information.

Notation Reference: Score layout.

Installed Files: ‘ly/articulate.ly’.

Note: The ‘articulate’ script may shorten chords, which might not be appropriate for some types of instrument, such as organ music. Notes that do not have any articulations attached to them may also be shortened; so to allow for this, restrict the use of the \articulate function to shorter segments of music, or modify the values of the variables defined in the ‘articulate’ script to compensate for the note-shortening behavior.


The ‘swing’ script

The ‘swing’ script provides additional functions allowing for regular durations to be played with an inequal rhythm. The most obvious example is ‘swing’ intepretation commonly found in jazz music where binary eighth notes should be played in a ternary fashion; however additional interpretations are also supported.

This script has to be \include-d at the beginning of the input file:

\include "swing.ly"

Three commands are provided:

Note: As with the ‘articulate’ script, all swing commands are also rendered in the engraved output, which results in irregular note spacing. This can be avoided by using them only in a \score block dedicated to MIDI output, rather than to printed music.

Additional help and information is included in the script file: see ‘ly/swing.ly’.

See also

Learning Manual: Other sources of information.

Notation Reference: Rhythms.

Installed Files: ‘ly/swing.ly’.

Known issues and warnings


3.7 Extracting musical information

In addition to creating graphical output and MIDI, LilyPond can display musical information as text.


3.7.1 Displaying LilyPond notation

Displaying a music expression in LilyPond notation can be done with the music function \displayLilyMusic. To see the output, you will typically want to call LilyPond using the command line. For example,

{
  \displayLilyMusic \transpose c a, { c4 e g a bes }
}

will display

{ a,4 cis4 e4 fis4 g4 }

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 \displayLilyMusic, redirect the output to a file.

lilypond file.ly >display.txt

Note that LilyPond does not just display the music expression, but also interprets it (since \displayLilyMusic returns it in addition to displaying it). Just insert \displayLilyMusic into the existing music in order to get information about it.

To interpret and display a music section in the console but, at the same time, remove it from the output file use the \void command.

{
  \void \displayLilyMusic \transpose c a, { c4 e g a bes }
  c1
}

3.7.2 Displaying scheme music expressions

See Displaying music expressions.


3.7.3 Saving music events to a file

Music events can be saved to a file on a per-staff basis by including a file in your main score.

\include "event-listener.ly"

This creates file(s) called ‘FILENAME-STAFFNAME.notes’ or ‘FILENAME-unnamed-staff.notes’ for each staff. Note that if you have multiple unnamed staves, the events for all staves are mixed together in the same file. The output looks like this:

0.000   note     57       4   p-c 2 12
0.000   dynamic  f
0.250   note     62       4   p-c 7 12
0.500   note     66       8   p-c 9 12
0.625   note     69       8   p-c 14 12
0.750   rest     4
0.750   breathe

The syntax is a tab-delimited line, with two fixed fields on each line followed by optional parameters.

time  type  …params…

This information can easily be read into other programs such as python scripts, and can be very useful for researchers wishing to perform musical analysis or playback experiments with LilyPond.

Known issues and warnings

Not all lilypond music events are supported by ‘event-listener.ly’. It is intended to be a well-crafted “proof of concept”. If some events that you want to see are not included, copy ‘event-listener.ly’ into your lilypond directory and modify the file so that it outputs the information you want.


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

\paper blocks may be placed in three different places to form a descending hierarchy of \paper blocks:

A \paper block cannot be placed within a \score block.

The values of the fields filter down this hierarchy, with the values set higher in the hierarchy persisting unless they are overridden by a value set lower in the hierarchy.

Several \paper blocks can appear at each of the levels, for example as parts of several \included files. If so, the fields at each level are merged, with values encountered last taking precedence if duplicated fields appear.

Settings that can appear in a \paper block include:

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 titles headers and footers.

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, \pt, and \bp. 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 titles headers and footers, The \layout block.

Installed Files: ‘ly/paper-defaults-init.ly’.


4.1.2 Paper size and automatic scaling


Setting the paper size

‘A4’ is the default value when no explicit paper size is set. However, there are two functions that can be used to change it:

set-default-paper-size
#(set-default-paper-size "quarto")

which must always be placed at the toplevel scope, and

set-paper-size
\paper {
  #(set-paper-size "tabloid")
}

which must always be placed in a \paper block.

If the set-default-paper-size function is used in the toplevel scope, it must come before any \paper block. set-default-paper-size sets the paper size for all pages, whereas set-paper-size only sets the paper size for the pages that the \paper block applies to. For example, if the \paper block is at the top of the file, then it applies the paper size to all pages. If the \paper block is inside a \book, then the paper size applies only to that book.

When the set-paper-size function is used, it must be placed before any other functions used within the same \paper block. See Automatic scaling to paper size.

Paper sizes are defined in file ‘scm/paper.scm’; see Predefined paper sizes for a complete list.

Both set-default-paper-size and set-paper-size also accept a quoted number pair as its argument to set a custom paper size. For example,

#(set-default-paper-size '(cons (* 100 mm) (* 50 mm)))

sets the paper width and height to 100mm and 50mm, respectively.

Possible units are in (inches), cm (centimeters), mm (millimeters), pt (points), and bp (big points).

If the symbol 'landscape is added to the paper size function as a second argument, pages are rotated by 90 degrees, and wider line widths are set accordingly.

#(set-default-paper-size "a6" 'landscape)

Swapping the paper dimensions without having the print rotated (like when printing to postcard size, or creating graphics for inclusion rather than a stand-alone document) can be achieved by appending ‘landscape’ to the name of the paper size itself:

#(set-default-paper-size "a6landscape")

When the paper size ends with an explicit ‘landscape’ or ‘portrait’, the presence of a 'landscape symbol only affects print orientation, not the paper dimensions used for layout.

See also

Notation Reference: Automatic scaling to paper size, Predefined paper sizes.

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 the 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 file ‘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 this is set to true, systems will be set at their natural spacing, neither compressed nor stretched vertically to fit the page.

ragged-last-bottom

If this is set to false, then the last page, and the last page in each section created with a \bookpart block, will be vertically justified in the same way as the earlier pages.

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.

Explicitly defined paper sizes will override any user-defined top or bottom margin settings.


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:

If a page has a ragged bottom, the resulting distance is the largest of:

For multi-page scores with a ragged bottom on the last page, the last page uses the same spacing as the preceding page, provided there is enough space for that.

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

When specified in a \paper block this defines the horizontal extent available for the staff lines in un-indented systems. If left unspecified, the paper’s line-width is determined from (paper-width - left-margin - right-margin). If the paper’s line-width is specified, and both left-margin and right-margin are not, then the margins will be updated to center the systems on the page automatically. Also see check-consistency.

line-widths for individual scores can be specified in the scores’ \layout blocks. These values control the width of the lines produced on a score-by-score basis. If line-width is not specified for a score, it defaults to the paper’s line-width. Setting a score’s line-width has no effect on the paper margins. Staff lines, of a length determined by the score’s line-width, are left-aligned within the paper area defined by the paper’s line-width. If the score and paper line-widths are equal, the staff lines will extend exactly from the left margin to the right margin, but if the score’s line-width is greater than the paper’s line-width the staff lines will run over into the right margin.

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 this is true (the default value), 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 their default values (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’.

Known issues and warnings

Explicitly defined paper sizes will override any user-defined left or right margin settings.


\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. The space within line-width available for the first system is reduced by this amount. indent may also be specified in \layout blocks to set indents on a score-by-score basis.

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. The space within line-width available for systems other than the first is reduced by this amount. short-indent may also be specified in \layout blocks to set short indents on a score-by-score basis.

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

page-breaking

The page breaking algorithm to use. Choices are ly:minimal-breaking, ly:page-turn-breaking, ly:one-page-breaking, ly:one-line-breaking, ly:one-line-auto-height-breaking, and ly:optimal-breaking. Default: 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. Default: unset.

page-spacing-weight

When using the ly:optimal-breaking algorithm for page breaking, LilyPond has to make trade-offs between horizontal and vertical stretching so that the overall spacing is more acceptable. This parameter controls the relative importance of page (vertical) spacing and line (horizontal) spacing. High values will make page spacing more important. Default: 10.

The following variables are effective only when page-breaking is set to ly:page-turn-breaking. Page breaks are then chosen to minimize the number of page turns. Since page turns are required on moving from an odd-numbered page to an even-numbered one, a layout in which the last page is odd-numbered will usually be favoured. Places where page turns are preferred can be indicated manually by inserting \allowPageTurn or automatically by including the Page_turn_engraver (see Optimal page turning).

If there are insufficient choices available for making suitable page turns, LilyPond may insert a blank page either within a score, between scores (if there are two or more scores), or by ending a score on an even-numbered page. The values of the following three variables may be increased to make these actions less likely.

The values are penalties, i.e., the higher the value the less likely will be the associated action relative to other choices.

blank-page-penalty

The penalty for having a blank page in the middle of a score. If blank-page-penalty is large and ly:page-turn-breaking is selected, then LilyPond will be less likely to insert a page in the middle of a score. Instead, it will space out the music further to fill the blank page and the following one. Default: 5.

blank-last-page-penalty

The penalty for ending the score on an even-numbered page. If blank-last-page-penalty is large and ly:page-turn-breaking is selected, then LilyPond will be less likely to produce a score in which the last page is even-numbered. Instead, it will adjust the spacing in order to use one page more or one page less. Default: 0.

blank-after-score-page-penalty

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-penalty, so that blank pages after scores are inserted in preference to blank pages within a score. Default: 2.

See also

Notation Reference: Page breaking, Optimal page breaking, Optimal page turning, Minimal page breaking, One-page page breaking, One-line page breaking, One-line-auto-height 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.

page-number-type

The type of numerals used for page numbers. Choices include 'arabic, 'roman-ij-lower, 'roman-ij-upper, 'roman-lower, and 'roman-upper. Default: 'arabic.

bookpart-level-page-numbering

If set to true, each bookpart has its indepdendent sequence of page numbers, starting at first-page-number (1 by default).

This may also be used for one bookpart only. The typical use case is numbering pages of the first bookpart independently and in roman numerals, as may be wished for an analytical introduction to the work being published.

\book {
  \bookpart {
    \paper {
      bookpart-level-page-numbering = ##t
      page-number-type = #'roman-lower
    }
    \markuplist \wordwrap-lines {
      Lorem ipsum dolor sit amet.
    }
  }
  \bookpart {
    …
  }
}

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.


\paper variables concerning headers and markups

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. For use cases see Titles and headers. Default: #f.

reset-footnotes-on-new-page

If set to true, footnote numbers are reset on each page break. For footnotes numbered consecutively across page breaks, set to #f. Default: #t.

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''1 \break c1 \break c1 }
  }
}

[image of music]

footnote-separator-markup

A markup object that is inserted above the footnote texts at the bottom of the page. Default: a centered horizontal line, defined in ‘ly/paper-defaults-init.ly’.

See also

Installed Files: ‘ly/titling-init.ly’, ‘ly/paper-defaults-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.


\paper variables for debugging

The variables debug-beam-scoring, debug-slur-scoring and debug-tie-scoring allow to print debugging output for beam, slur and tie scoring. See Debugging scoring algorithms for a detailed explanation, what these variables do.


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 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, with default values taken from the \paper block are:

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

Multiple \layout blocks can be entered as toplevel expressions. This can, for example, be useful if different settings are stored in separate files and included optionally. Internally, when a \layout block is evaluated, a copy of the current \layout configuration is made, then any changes defined within the block are applied and the result is saved as the new current configuration. From the user’s perspective the \layout blocks are combined, but in conflicting situations (when the same property is changed in different blocks) the later definitions take precedence.

For example, if this block:

\layout {
  \context {
    \Voice
    \override TextScript.color = #magenta
    \override Glissando.thickness = #1.5
  }
}

is placed after the one from the preceding example the padding and color overrides for TextScript are combined, but the later thickness override for Glissando replaces (or hides) the earlier one.

\layout blocks may be assigned to variables for reuse later, but the way this works is slightly but significantly different from writing them literally.

If a variable is defined like this:

layoutVariable = \layout {
  \context {
    \Voice
    \override NoteHead.font-size = #4
  }
}

it will hold the current \layout configuration with the NoteHead.font-size override added, but this combination is not saved as the new current configuration. Be aware that the ‘current configuration’ is read when the variable is defined and not when it is used, so the content of the variable is dependent on its position in the source.

The variable can then be used inside another \layout block, for example:

\layout {
  \layoutVariable
  \context {
    \Voice
    \override NoteHead.color = #red
  }
}

A \layout block containing a variable, as in the example above, does not copy the current configuration but instead uses the content of \layoutVariable as the base configuration for the further additions. This means that any changes defined between the definition and the use of the variable are lost.

If layoutVariable is defined (or \included) immediately before being used, its content is just the current configuration plus the overrides defined within it. So in the example above showing the use of \layoutVariable the final \layout block would consist of:

  TextScript.padding = #1
  TextScript.color = #magenta
  Glissando.thickness = #1.5
  NoteHead.font-size = #4
  NoteHead.color = #red

plus the indent and the StaffGrouper overrides.

But if the variable had already been defined before the first \layout block the current configuration would now contain only

  NoteHead.font-size = #4 % (written in the variable definition)
  NoteHead.color = #red % (added after the use of the variable)

If carefully planned, \layout variables can be a valuable tool to structure the layout design of sources, and also to reset the \layout configuration to a known state.

See also

Notation Reference: Changing context default settings.

Snippets: Spacing.


4.2.2 Setting the staff size

The default staff size is 20 points, which corresponds to a staff height of 7.03mm (one point is equal to 100/7227 of an inch, or 2540/7227 mm). The staff size may be changed in three ways:

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

    The above example sets the global default staff size to 14pt (4.92mm) and scales all fonts accordingly.

  2. To set the staff size for a single score within a book, use layout-set-staff-size inside that score’s \layout block:
    \score {
      …
      \layout {
        #(layout-set-staff-size 14)
      }
    }
    
  3. To set the staff size for a single staff within a system, use the \magnifyStaff command. For example, traditionally engraved chamber music scores with piano often used 7mm piano staves while the other staves were typically between 3/5 and 5/7 as large (between 60% and 71%). To achieve the 5/7 proportion, use:
    \score {
      <<
        \new Staff \with {
          \magnifyStaff #5/7
        } { … }
        \new PianoStaff { … }
      >>
    }
    

    If you happen to know which fontSize you wish to use, you could use the following form:

    \score {
      <<
        \new Staff \with {
          \magnifyStaff #(magstep -3)
        } { … }
        \new PianoStaff { … }
      >>
    }
    

    To emulate the look of traditional engraving, it is best to avoid reducing the thickness of the staff lines.

Automatic font weight at different sizes

The Emmentaler font provides the set of Feta musical glyphs in eight different sizes; each one tuned for a different staff size. The smaller the glyph size, the “heavier” it becomes, so as to match the relatively thicker staff lines. Recommended glyphs sizes are listed in the following table:

font namestaff height (pt)staff height (mm)use
feta1111.223.9pocket scores
feta1312.604.4
feta1414.145.0
feta1615.875.6
feta1817.826.3song books
feta20207.0standard parts
feta2322.457.9
feta2625.28.9

See also

Notation Reference: Selecting notation font size, The Emmentaler font.

Snippets: Spacing.

Known issues and warnings

When using \magnifyStaff only for some staves in a StaffGroup, BarLine grobs do not align any more, due to the changed BarLine properties thick-thickness, hair-thickness and kern.

\new StaffGroup
  <<
    \new Staff \with { \magnifyStaff #1/2 } { b1 \bar "|." }
    \new Staff { b }
  >>

[image of music]

You may want to cancel magnifying BarLine grobs, mimick them on the other staves or apply intermediate values for every Staff.

#(define bar-line-props
  '((BarLine thick-thickness)
    (BarLine hair-thickness)
    (BarLine kern)))

mus = { b1 \bar "|."}

\markup "Cancel \\magnifyStaff for bar lines:"
\new StaffGroup
  <<
    \new Staff
      \with {
        \magnifyStaff
        #1/2 #(revert-props 'magnifyStaff 0 bar-line-props)
      }
      \mus
    \new Staff
      \mus
  >>

\markup "Mimick \\magnifyStaff on other staves:"
\new StaffGroup
  <<
    \new Staff
      \with { \magnifyStaff #1/2 }
      \mus
    \new Staff
      \with {
        #(scale-props 'magnifyStaff 1/2 #t bar-line-props)
      }
      \mus
  >>

\markup "Apply an intermediate value to all staves:"
\new StaffGroup
  <<
    \new Staff
      \with {
        \magnifyStaff #1/2
        #(scale-props 'magnifyStaff 3/2 #t bar-line-props)
      }
      \mus
    \new Staff
      \with {
        #(scale-props 'magnifyStaff 3/4 #t bar-line-props)
      }
      \mus
  >>

[image of music]


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:

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

[image of music]

By default, breaks are only allowed at bar lines. There are also a few other factors that can prevent a break from being allowed at a certain bar line:

The \break command forces a break in all cases, regardless of the presence of a bar line or any other factor. It is also possible to bypass all these factors using the \allowBreak command. In the following example, breaks are allowed everywhere, even in the middle of a measure, and despite the presence of beams.

\repeat unfold 56 { c'8 \allowBreak }

[image of music]

If you find yourself using \allowBreak often, you may want to prevent some of the factors mentioned above from disabling breaks.

The \noBreak command will prevent a line break at the bar line where it is inserted.

Within a score, automatic line breaking is prevented within music lying between \autoLineBreaksOff and \autoLineBreaksOn commands. If automatic page breaks should also be prevented, the commands \autoBreaksOff and \autoBreaksOn should be used. Manual breaks are unaffected by these commands. Note that inhibiting automatic line breaks may cause music to run over the right margin if it cannot all be contained within one line.

Automatic line breaks (but not page breaks) may be enabled at single bar lines by using \once \autoLineBreaksOn at a bar line. This identifies a permitted rather than a forced line break.

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

Predefined commands

\break, \allowBreak, \noBreak, \autoBreaksOff, \autoBreaksOn, \autoLineBreaksOff, \autoLineBreaksOn.

Selected Snippets

Using an extra voice for breaks

Often it is easier to manage line and page-breaking information by keeping it separate from the music by introducing an extra voice containing only skips along with the \break, pageBreak and other layout information.

This pattern becomes especially helpful when overriding line-break-system-details and the other useful but long properties of NonMusicalPaperColumnGrob.

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

[image of music]

See also

Notation Reference: \paper variables for line breaking The \layout block.

Snippets: Spacing.

Internals Reference: LineBreakEvent.

Known issues and warnings

Placing \autoLineBreaksOff or \autoBreaksOff before any music will cause error messages to appear. Always place these commands after some music.


4.3.2 Page breaking

This section describes the different page breaking methods, and how to modify them.


Manual 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 at that bar line. 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.

Within a score, automatic page breaks are prevented within music lying between \autoPageBreaksOff and \autoPageBreaksOn commands. Manual page breaks are unaffected by these commands.

There are also analogous settings to ragged-right and ragged-last which have the same effect on vertical spacing. If ragged-bottom is set to #t the systems will not be justified vertically. When ragged-last-bottom is set to #t, as it is by default, empty space is allowed at the bottom of the final page (or the final page in each \bookpart). See Fixed vertical spacing \paper variables.

Page breaks are computed by the page-breaking function. LilyPond provides several algorithms for computing page breaks, including 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, \autoPageBreaksOn, \autoPageBreaksOff.

See also

Notation Reference: \paper variables for page breaking.

Snippets: Spacing.

Known issues and warnings

The \once prefix is ineffective with \autoPageBreaksOn and \autoPageBreaksOff. If auto page breaking is off and is then turned on to permit a page break, it must remain on for a few bars (the precise number of bars depends on the score) before being turned off, else the opportunity to break the page will not be taken.


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.


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.


One-page page breaking

The ly:one-page-breaking function is a special-purpose page breaking algorithm that automatically adjusts the page height to fit the music, so that everything fits on a single page. The paper-height variable in the paper block is ignored, but other settings work as usual. In particular, the spacing between the last system (or top level markup) and the footer can be customized with last-bottom-spacing in the paper block. The width of the page is left unmodified by default but can be set with paper-width in the paper block.

Known issues and warnings

ly:one-page-breaking is not currently compatible with \bookpart.


One-line page breaking

The ly:one-line-breaking function is a special-purpose page breaking algorithm that puts each score on its own page, and on a single line. No titles or margins are typeset; only the score is displayed.

The page width is adjusted so that the longest score fits on one line. In particular, paper-width, line-width and indent variables in the \paper block are ignored, although left-margin and right-margin are still honored. The height of the page is left unmodified.


One-line-auto-height page breaking

The ly:one-line-auto-height-breaking function works just like ly:one-line-breaking except the page height is automatically modified to fit the height of the music. Specifically, the paper-height variable in the \paper block is set so that it spans the height of the tallest score plus the top-margin and bottom-margin.

Note that the top-system-spacing setting will affect the vertical position of the music. Set it to #f in a paper block to simply place the music between the top and bottom margins.


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

When using volta repeats, the Page_turn_engraver 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. If the repeat is too short then the Page_turn_engraver can be used to disable page turns by setting an appropriate value for the context property minimumRepeatLengthForPageTurn. In this case the Page_turn_engraver will only allows turns in repeats whose duration is longer than the value specified.

The page turning commands, \pageTurn, \noPageTurn and \allowPageTurn, may also be used at top-level, in top-level markups and between scores.

Predefined commands

\pageTurn, \noPageTurn, \allowPageTurn.

See also

Notation Reference: \paper variables for line breaking.

Snippets: Spacing.

Known issues and warnings

Use only one Page_turn_engraver per score. If there are more, they will interfere with each other.

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:

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 lineReference point
ChordNamesbaseline
NoteNamesbaseline
Lyricsbaseline
Dynamicsmid-height of ‘m’
FiguredBasshighest point
FretBoardstop line

In the following image, horizontal lines indicate the positions of these reference points:

[image of music]

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 redefines 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. If only some values are specified in an override, missing values will be taken from default-staff-staff-spacing (if it has values for them).

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.

Installed Files: ‘ly/engraver-init.ly’, ‘scm/define-grobs.scm’.

Internals Reference: Contexts, VerticalAxisGroup, StaffGrouper.


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:

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

[image of music]

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:

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

[image of music]

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 contain the Axis_group_engraver.

The following properties affect the spacing of non-staff lines:

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

[image of music]

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 property 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 four different settings:

\once \override NonMusicalPaperColumn.line-break-system-details =
  #'((X-offset . 20))

\once \override NonMusicalPaperColumn.line-break-system-details =
  #'((Y-offset . 40))

\once \override NonMusicalPaperColumn.line-break-system-details =
  #'((X-offset . 20)
     (Y-offset . 40))

\once \override NonMusicalPaperColumn.line-break-system-details =
  #'((alignment-distances . (15)))

\once \override 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' }
      }
    >>
  }
}

[image of music]

This score isolates both line breaking 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. Also see Breaks.

By using explicit \break commands, the music is divided into five measures per line. Vertical spacing is from LilyPond’s own defaults but the vertical startpoint of each system is set explicitly using 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 {
          \once \override
            Score.NonMusicalPaperColumn
                 .line-break-system-details = #'((Y-offset . 0))
          s1*5 \break
          \once \override
            Score.NonMusicalPaperColumn
                 .line-break-system-details = #'((Y-offset . 40))
          s1*5 \break
          \once \override
            Score.NonMusicalPaperColumn
                 .line-break-system-details = #'((Y-offset . 60))
          s1*5 \break
        }
        \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
      >>
      \new Staff {
        \repeat unfold 15 { d'4 d' d' d' }
      }
    >>
  }
}

[image of music]

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.

In contrast to the absolute positioning available through Y-offset and X-offset, relative positioning is possible with the extra-offset property of line-break-system-details. Placement is relative to the default layout or to the absolute positioning created by setting X-offset and Y-offset. The property extra-offset accepts a pair consisting of displacements along the X-axis and Y-axis.

\header { tagline = ##f }
\paper { left-margin = 0\mm }
\book {
  \score {
    <<
      \new Staff <<
        \new Voice {
          s1*5 \break
          \once \override
            Score
            .NonMusicalPaperColumn
            .line-break-system-details = #'((extra-offset . (0 . 10)))
          s1*5 \break
          \once \override
            Score
            .NonMusicalPaperColumn
            .line-break-system-details = #'((extra-offset . (0 . 10)))
          s1*5 \break
        }
        \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
      >>
      \new Staff {
        \repeat unfold 15 { d'4 d' d' d' }
      }
    >>
  }
}

[image of music]

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 {
          \once \override
            Score
            .NonMusicalPaperColumn
            .line-break-system-details
            = #'((Y-offset . 20)
                 (alignment-distances . (10)))
          s1*5 \break
          \once \override
            Score
            .NonMusicalPaperColumn
            .line-break-system-details
            = #'((Y-offset . 60)
                 (alignment-distances . (15)))
          s1*5 \break
          \once \override
            Score
            .NonMusicalPaperColumn
            .line-break-system-details
            = #'((Y-offset . 85)
                 (alignment-distances . (20)))
          s1*5 \break
        }
        \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
      >>
      \new Staff {
        \repeat unfold 15 { d'4 d' d' d' }
      }
    >>
  }
}

[image of music]

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 {
          \once \override
            Score
            .NonMusicalPaperColumn
            .line-break-system-details
            = #'((Y-offset . 0)
                 (alignment-distances . (30 10)))
          s1*5 \break
          \once \override
            Score
            .NonMusicalPaperColumn
            .line-break-system-details
            = #'((Y-offset . 60)
                 (alignment-distances . (10 10)))
          s1*5 \break
          \once \override
            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' } }
      >>
    >>
  }
}

[image of music]

Some points to consider:

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.

A listing of defaults for outside-staff-priority may be found in Default values for outside-staff-priority.

\relative c'' {
  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
}

[image of music]

The vertical padding around outside-staff objects can be controlled with property outside-staff-padding.

\relative {
  \once \override TextScript.outside-staff-padding = #0
  a'4-"outside-staff-padding = #0"
  \once \override TextScript.outside-staff-padding = #3
  d-"outside-staff-padding = #3"
  c-"default outside-staff-padding"
  b-"default outside-staff-padding"
  R1
}

[image of music]

By default, outside-staff objects are placed so they avoid a horizontal collision with previously-positioned grobs. This can lead to situations in which objects are placed close to each other horizontally. As shown in the example below, setting outside-staff-horizontal-padding increases the horizontal spacing required, and in this case moves the text up to prevent it from getting too close to the ledger lines.

\relative {
  c''4^"Word" c c''2
  R1
  \once \override TextScript.outside-staff-horizontal-padding = #1
  c,,4^"Word" c c''2
}

[image of music]

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

\relative c' {
  c2 c4. c8
  c4. c8 c4. c8
  c8 c c4 c c
}

[image of music]

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.

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:

\relative { c''2 c4. c8 | c4. c16[ c] c4. c8 | c8 c c4 c c }

[image of music]

As explained in the Essay on automated music engraving, stem directions will influence spacing (see Optical spacing) and can be adjusted using the stem-spacing-correction property of the NoteSpacing object (which 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 this; once with the default settings and once with an exaggerated adjustment:

[image of music]

Proportional notation is supported; see Proportional notation.

See also

Essay on automated music engraving: Optical spacing.

Snippets: Spacing.

Internals Reference: SpacingSpanner, NoteSpacing, StaffSpacing, NonMusicalPaperColumn.

Known issues and warnings

There is no convenient mechanism to manually override spacing. The following workaround may be used to insert extra space into a score, adjusting the padding value as necessary.

 \override Score.NonMusicalPaperColumn.padding = #10

No workaround exists for decreasing the amount of space.


4.5.2 New spacing section

New sections with different spacing parameters can be started with the newSpacingSection command. This is useful for sections with different notions of ‘long’ and ‘short’ notes. The \newSpacingSection command creates a new SpacingSpanner object at that musical moment.

In the following example the time signature change introduces a new section, and the 16ths notes are automatically spaced slightly wider apart.

\relative c' {
  \time 2/4
  c4 c8 c
  c8 c c4 c16[ c c8] c4
  \newSpacingSection
  \time 4/16
  c16[ c c8]
}

[image of music]

If the automatic spacing adjustments do not give the required spacing, manual \overrides may be applied to its properties. These must be applied at the same musical moment as the \newSpacingSection command itself and will then affect the spacing of all the following music until the properties are changed in a new spacing section, for example:

\relative c' {
  \time 4/16
  c16[ c c8]
  \newSpacingSection
  \override Score.SpacingSpanner.spacing-increment = #2
  c16[ c c8]
  \newSpacingSection
  \revert Score.SpacingSpanner.spacing-increment
  c16[ c c8]
}

[image of music]

See also

Snippets: Spacing.

Internals Reference: SpacingSpanner.


4.5.3 Changing horizontal spacing globally

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 {
    g'4 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 |
  }
}

[image of music]

\score {
  \relative {
    g'4 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)
    }
  }
}

[image of music]


Uniform stretching of tuplets

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 \relative c' {
      \tuplet 5/4 { c8 c c c c } c8 c c c
    }
    \new Staff \relative c' {
      c8 c c c \tuplet 5/4 { c8 c c c c }
    }
  >>
  \layout {
    \context {
      \Score
      \override SpacingSpanner.uniform-stretching = ##t
    }
  }
}

[image of music]


Strict note spacing

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 \relative {
  c''8[ c \clef alto c \grace { c16 c } c8 c c]  c32[ c] }

[image of music]

See also

Snippets: Spacing.


4.5.4 Adjusting horizontal spacing for specific layout objects

In addition to the general-purpose parameters of the default spacing algorithm that apply to all elements of the score or spacing section, several properties serve to operate adjustments on a per-object-type-basis. Examples include adjusting the distance from clefs to time signatures, but not from clefs to notes when there is no time signature, or stretching notes further apart in the presence of a printed text so that it does not overlap with the next note. Tweaking these first requires identifying the type of spacing at play.


4.5.4.1 Overview of object-specific horizontal spacing tweaks

Layout objects that have a horizontally fixed position are called items, as opposed to spanners, and for the purpose of horizontal spacing, are grouped into columns. Note heads and rests, forming the main musical material, together with those objects that are logically linked to them – accidentals, articulations, stems, dots, etc. – are all part of ‘musical column’. Prefatory items, such as clefs, time signatures and bar lines, are grouped into ‘non-musical columns’. In the following example, musical items are colored red, while non-musical items are blue.

[image of music]

This example shows that there is an alternation between musical and non-musical columns. The first non-musical column contains a clef and a time signature. The first musical column has a note head with its stem and articulation. The second non-musical column is empty and thus is removed during the layout process. The second musical column has a note again. The third non-musical column contains a clef, a bar line and a rehearsal mark, etc.

Within one column, spacing is fixed. On the other hand, the amount of space between consecutive columns is flexible. As we shall see, the methods to adjust spacing within a column and between columns are different.


4.5.4.2 Spacing between adjacent non-musical items

Within a non-musical column, items are laid out in a specific order. For instance, with the set of items in the picture below, the default order places the breathing sign first, then the clef, then the bar line, the key cancellation and key signature, and finally the time signature (this is controlled by the BreakAlignment.break-align-orders property).

\relative {
  \key g \minor
  g'1
  \breathe
  \clef alto
  \time 6/8
  \key a \major
  aes4.
}

[image of music]

The distance between two adjacent items from the same non-musical column is controlled by the value of the space-alist property of the leftmost one of the two. space-alist has the form of an associative list mapping break align symbols to (spacing-style . value) pairs. A breakable item’s break align symbol is given by the value of its break-align-symbol property; standard choices are listed in break-alignment-interface. Spacing styles are listed in break-aligned-interface. Among the available options, only extra-space and minimum-space are relevant for tweaking the space between non-musical items. The difference is that extra-space measures the padding from the right of the first object to the left of the second object while minimum-space counts from the left of the first object. Thus, a way to move the bar line farther from the clef is:

\relative {
  \key g \minor
  g'1
  \override Staff.Clef.space-alist.staff-bar = #'(extra-space . 4)
  \breathe
  \clef alto
  \time 6/8
  \key a \major
  aes4.
}

[image of music]

space-alist settings, not limited to the two spacing styles described above, are also possible to override the spacing between different columns. However, this kind of spacing is flexible, and does not merely depend on the types of object involved but also their shapes. Methods specific to it are documented in the next section.

See also

Notation Reference: Using the break-alignable-interface.

Extending LilyPond: Association lists (alists).

Internals Reference: Break_align_engraver, BreakAlignGroup, BreakAlignment, break-alignable-interface, break-aligned-interface, break-alignment-interface.


4.5.4.3 Spacing between adjacent columns

Contrary to spacing within one column, spacing between adjacent columns is flexible and stretches or compresses according to the density of music on the line. By default, columns may even overlap in some situations. The following example shows three cases. The second accidental slides behind the bar line, while the third one overlaps with the clef. Also, the tempo marking Presto spans several columns. Observe how the first accidental, which remains within the vertical extent of the bar line on its left, is placed further apart.

[image of music]

These spacing rules can be overridden. This is done by modifying the width and height that an object takes in horizontal spacing. The relevant properties are extra-spacing-width and extra-spacing-height. When unset, an object takes as much space in horizontal spacing as its X-extent and Y-extent properties allow. These are accurate values of its dimensions. The extra-spacing-width and extra-spacing-height properties make an object larger or smaller for computation of horizontal spacing between columns only, but preserve its dimensions for other spacing types.

{
  \textMark "Default"
  c'2 2 cis'2 2
}

{
  \textMark "Modified X-extent"
  \override NoteHead.X-extent = #'(-2 . 2)
  c'2 2 cis'2 2
}

{
  \textMark "Modified extra-spacing-width"
  \override NoteHead.extra-spacing-width = #'(-2 . 2)
  c'2 2 cis'2 2
}

[image of music]

extra-spacing-width and extra-spacing-height are pairs of numbers, which are added to the dimensions on each axis. For instance, setting extra-spacing-height to '(-2 . 3) makes the object three units larger on the top, and two units larger on the bottom (limit lowered by 2). The following example shows how to use extra-spacing-height to change the limit after which accidentals no longer overlap with bar lines.

music = \relative {
  \time 1/4
  cis8 8 | dis8 8 | eis8 8 | fis8 8 |
  gis8 8 | ais8 8 | bis8 8 | cis8 8 |
}

{
  \music
}

{
  \override Accidental.extra-spacing-height = #'(0 . 1.0)
  \music
}

[image of music]

The value '(+inf.0 . -inf.0) for extra-spacing-width or extra-spacing-height removes the object’s presence.

music = \relative {
  \time 1/4
  cis8 8 | dis8 8 | eis8 8 | fis8 8 |
  gis8 8 | ais8 8 | bis8 8 | cis8 8 |
}

{
  \override Accidental.extra-spacing-height = #'(+inf.0 . -inf.0)
  \music
}

[image of music]

Conversely, an extra-spacing-height of '(-inf.0 . +inf.0) makes the object infinitely high, preventing overlap with another column completely. The below example demonstrates this technique on Accidental and MetronomeMark. In the case of MetronomeMark, it is necessary to set extra-spacing-width to '(0 . 0) because the default is '(+inf.0 . -inf.0), and even an infinitely high object does not take space if it has no width.

{
  \override Score.MetronomeMark.extra-spacing-width =
    #'(0 . 0)
  \override Score.MetronomeMark.extra-spacing-height =
    #'(-inf.0 . +inf.0)
  \override Accidental.extra-spacing-height =
    #'(-inf.0 . +inf.0)
  cis'4 r2.
  \tempo Presto
  fis16 8 16 4 \clef alto cis4 fis4
}

[image of music]

See also

Internals Reference: item-interface, separation-item-interface.


4.5.5 Line width

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

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 {
      c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
    }
  >>
}

[image of music]

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 {
      c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
    }
  >>
 \layout {
    \context {
      \Score
      proportionalNotationDuration = #(ly:make-moment 1/20)
    }
  }
}

[image of music]

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 {
      c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
    }
  >>
  \layout {
    \context {
      \Score
      proportionalNotationDuration = #(ly:make-moment 1/8)
    }
  }
}

\score {
  <<
    \new RhythmicStaff {
      c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
    }
  >>
  \layout {
    \context {
      \Score
      proportionalNotationDuration = #(ly:make-moment 1/16)
    }
  }
}

\score {
  <<
    \new RhythmicStaff {
      c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
    }
  >>
  \layout {
    \context {
      \Score
      proportionalNotationDuration = #(ly:make-moment 1/32)
    }
  }
}

[image of music]

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 {
      c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
    }
    \new RhythmicStaff {
      \tuplet 9/8 { c8 8 8 8 8 8 8 8 8 }
    }
  >>
}

[image of music]

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 {
      c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
    }
    \new RhythmicStaff {
      \tuplet 9/8 { c8 8 8 8 8 8 8 8 8 }
    }
  >>
  \layout {
    \context {
      \Score
      proportionalNotationDuration = #(ly:make-moment 1/20)
    }
  }
}

[image of music]

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 {
      c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
    }
    \new RhythmicStaff {
      \tuplet 9/8 { c8 8 8 8 8 8 8 8 8 }
    }
  >>
  \layout {
    \context {
      \Score
      proportionalNotationDuration = #(ly:make-moment 1/20)
      \override SpacingSpanner.uniform-stretching = ##t
    }
  }
}

[image of music]

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’s \with block, in a Score’s \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 section, 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
}

[image of music]

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
}

[image of music]

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 8 8 \clef alto d'2 2
}

\new Staff {
  \set Score.proportionalNotationDuration = #(ly:make-moment 1/16)
  \override Score.SpacingSpanner.strict-note-spacing = ##t
  c''8 8 8 \clef alto d'2 2
}

[image of music]

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:

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

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:

\book {
  \score { { c4 } }
  \paper { annotate-spacing = ##t }
}

[image of music]

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:

See also

Notation Reference: Page layout, Changing horizontal spacing globally.

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


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:


Output definitions – blueprints for contexts

This section explains the relevance of output definitions when working with contexts. Examples for actual output definitions are given later (see Changing all contexts of the same type).

While music written in a file may refer to context types and names, contexts are created only when the music is actually being interpreted. LilyPond interprets music under control of an ‘output definition’ and may do so for several different output definitions, resulting in different output. The output definition relevant for printing music is specified using \layout.

A much simpler output definition used for producing Midi output is specified using \midi. Several other output definitions are used by LilyPond internally, like when using the part combiner (Automatic part combining) or creating music quotes (Quoting other voices).

Output definitions define the relation between contexts as well as their respective default settings. While most changes will usually be made inside of a \layout block, Midi-related settings will only have an effect when made within a \midi block.

Some settings affect several outputs: for example, if autoBeaming is turned off in some context, beams count as melismata for the purpose of matching music to lyrics as described in Automatic syllable durations. This matching is done both for printed output as well as for Midi. If changes made to autoBeaming within a context definition of a \layout block are not repeated in the corresponding \midi block, lyrics and music will get out of sync in Midi.

See also

Installed Files: ‘ly/engraver-init.ly’. ‘ly/performer-init.ly’.


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 {…} 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 when engraving; the notes are printed on one line. The MIDI rendition retains pitches unchanged.

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. A bottom-level context is one without defaultchild. While it is possible to let it accept/contain subcontexts, they can only be created and entered explicitly.

Voice

Corresponds to a voice on a staff. This context handles the conversion of dynamic signs, stems, beams, super- and subscripts, 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 and referencing contexts

LilyPond will create lower-level contexts automatically if a music expression is encountered before a suitable context exists, but this is usually successful only for simple scores or music fragments like the ones in the documentation. For more complex scores it is advisable to specify all contexts explicitly with either the \new or \context command. The syntax of these two commands is very similar:

[\new | \context] Context [ = name] [music-expression]

where either \new or \context may be specified. Context is the type of context which is to be created, name is an optional name to be given to the particular context being created and music-expression is a single music expression that is to be interpreted by the engravers and performers in this context.

The \new prefix without a name is commonly used to create scores with many staves:

<<
  \new Staff \relative {
    % leave the Voice context to be created implicitly
    c''4 c
  }
  \new Staff \relative {
    d''4 d
  }
>>

[image of music]

and to place several voices into one staff:

\new Staff <<
  \new Voice \relative {
    \voiceOne
    c''8 c c4 c c
  }
  \new Voice \relative {
    \voiceTwo
    g'4 g g g
  }
>>

[image of music]

\new should always be used to specify unnamed contexts.

The difference between \new and \context is in the action taken:

A context must be named if it is to be referenced later, for example when lyrics are associated with music:

\new Voice = "tenor" music
…
\new Lyrics \lyricsto "tenor" lyrics

For details of associating lyrics with music see Automatic syllable durations.

The properties of all contexts of a particular type can be modified in a \layout block (with a different syntax), see Changing all contexts of the same type. This construct also provides a means of keeping layout instructions separate from the musical content. If a single context is to be modified, a \with block must be used, see Changing just one specific context.

See also

Learning Manual: Organizing pieces with variables.

Notation Reference: Changing just one specific context, Automatic syllable durations.


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: inside of an {…} construct (sequential music), the construct’s notion of the “current context” will descend whenever an element of the sequence ends in a subcontext of the previous current context. This avoids spurious creation of implicit contexts in a number of situations but means that the first context descended into will be kept alive until the end of the expression.

In contrast, the contexts of a <<…>> construct’s (simultaneous music) expression are not carried forth, so enclosing a context creating command in an extra pair of <<…>> will keep the context from persisting through all of the enclosing {…} sequence.

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 { d''4 d d d }
musicB = \relative { g'4 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
  >>
}

[image of 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 { a'4 a a a }
accompaniment = \relative { d'4 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 }
  >>
}

[image of music]

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 {
  s1  % skip a bar
  a'4 a a a
  s1  % skip a bar
  a4 a a a
}
accompaniment = \relative {
  d'4 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 }
  >>
}

[image of music]


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_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 each … 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 \relative {
    f'2 g
  }
  \new Staff \with {
     \remove Time_signature_engraver
     \remove Clef_engraver
  } \relative {
    f'2 g2
  }
>>

[image of music]

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.

Known issues and warnings

The order in which the engravers are specified is the order in which they are called to carry out their processing. 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 following orderings are important:

See also

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


5.1.5 Changing context default settings

Context and grob properties can be changed with \set and \override commands, as described in Modifying properties. These commands create music events, making the changes take effect at the point in time the music is being processed.

In contrast, this section explains how to change the default values of context and grob properties at the time the context is created. There are two ways of doing this. One modifies the default values in all contexts of a particular type, the other modifies the default values in just one particular instance of a context.


Changing all contexts of the same type

The default context settings which are to be used for typesetting in Score, Staff, Voice and other contexts may be specified in a \context block within any \layout block.

Settings for Midi output as opposed to typesetting will have to be separately specified in \midi blocks (see Output definitions – blueprints for contexts).

The \layout block should be placed within the \score block to which it is to apply, after the music.

\layout {
  \context {
    \Voice
    [context settings for all Voice contexts]
  }
  \context {
    \Staff
    [context settings for all Staff contexts]
  }
}

The following types of settings may be specified:

Property-setting commands can be placed in a \layout block without being enclosed in a \context block. Such settings are equivalent to including the same property-setting commands at the start of every context of the type specified. If no context is specified every bottom-level context is affected (see Bottom-level contexts – voices). The syntax of a property-setting command in a \layout block is the same as the same command written in the music stream.

\score {
  \new Staff {
    \relative {
      a'4^"Smaller font" a a a
      a4 a a a
    }
  }
  \layout {
    \accidentalStyle dodecaphonic
    \set fontSize = #-4
    \override Voice.Stem.thickness = #4.0
  }
}

[image of music]


Changing just one specific context

The context properties of just one specific context instance can be changed in a \with block. All other context instances of the same type retain the default settings built into LilyPond and modified by any \layout block within scope. The \with block must be placed immediately after the \new context-type command:

\new Staff \with {
  [context settings for this context instance only]
} {
  …
}

Alternatively, if the music is being entered using the short form of the input mode-specifying commands, e.g. \chords rather than \chordmode, the \with command must be placed immediately after the mode-specifying command:

\chords \with {
  [context settings for this (implicit) context instance only]
} {
  …
}

as it is the implicit context created by these short forms which should be modified. The same consideration applies to the other input mode-specifying short forms (\drums, \figures), see Input modes.

Since context modifications specified in \with blocks are inside music, they will affect all outputs (typesetting and Midi) as opposed to changes within an output definition.

The following types of settings may be specified:

See also

Notation Reference: Input modes.


Order of precedence

The value of a property which applies at a particular time is determined as follows:

See also

Learning Manual: Modifying context properties.

Notation Reference: Contexts explained, Bottom-level contexts – voices, The \set command, The \override command, The \layout block.


5.1.6 Defining new contexts


Context definition overview

Specific contexts, like Staff and Voice, are made from 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,

[image of music]

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 context, we want commands that work in (existing) Voice contexts to continue working. This is achieved by giving the new context an alias of Voice,

\alias Voice

The context will print notes and instructive texts, so we need to add the engravers which provide this functionality, plus the engraver which groups notes, stems and rests which occur at the same musical moment into columns,

\consists Note_heads_engraver
\consists Text_engraver
\consists Rhythmic_column_engraver

The note heads should all be placed on the center line,

\consists Pitch_squash_engraver
squashedPosition = #0

The Pitch_squash_engraver modifies note heads (created by the 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
\hide Stem

All these plug-ins have to communicate under the control of the context. The mechanisms with which contexts communicate are established by declaring the context \type. Within a \layout block, most contexts will be of type Engraver_group. Some special contexts use other context types. Copying and modifying an existing context definition will also fill in the type. Since this example creates a definition from scratch, it needs to be specified explicitly.

\type Engraver_group

Put together, we get

\context {
  \name ImproVoice
  \type Engraver_group
  \consists Note_heads_engraver
  \consists Text_engraver
  \consists Rhythmic_column_engraver
  \consists Pitch_squash_engraver
  squashedPosition = #0
  \override NoteHead.style = #'slash
  \hide Stem
  \alias Voice
}

Contexts form hierarchies. We want to place the ImproVoice context within the Staff context, just like normal Voice contexts. Therefore, we modify the Staff definition with the \accepts command,

\context {
  \Staff
  \accepts ImproVoice
}

Often when reusing an existing context definition, the resulting context can be used anywhere where the original context would have been useful.

\layout {
  …
  \inherit-acceptability to from
}

will arrange to have contexts of type to accepted by all contexts also accepting from. For example, using

\layout {
  …
  \inherit-acceptability ImproVoice Voice
}

will add an \accepts for ImproVoice to both Staff and RhythmicStaff definitions.

The opposite of \accepts is \denies, which is sometimes needed when reusing existing context definitions.

Arranging the required pieces into a \layout block leaves us with

\layout {
  \context {
    \name ImproVoice
    …
  }
  \inherit-acceptability ImproVoice Voice
}

Then the output at the start of this subsection can be entered as

\relative {
  a'4 d8 bes8
  \new ImproVoice {
    c4^"ad lib" c
    c4 c^"undress"
    c c_"while playing :)"
  }
  a1
}

See also

Internals Reference: Contexts, Engravers and Performers.


New contexts in MIDI

In MIDI output, the syntax for defining new context types is the same, except that the \context block should be placed inside a \midi block, and the \type should normally be Performer_group rather than Engraver_group. The term “engraver” refers to a context plug-in that creates visual output. A “performer”, on the other hand, is relevant in MIDI output only. When plug-ins have “translator” in their name rather than “engraver” or “performer”, they are relevant for both graphical and audio output. Thus, when adapting a context definition for the \midi block, you need to

Please note that, in order to maintain consistent interpretation between graphical and MIDI output, it is recommended to copy any custom context definition in a \midi block. It should at the minimum include those commands that specify the context hierarchy, such as \accepts, \defaultchild and \inherit-acceptability. Copying aliases is advised as well.

Thus, to complete the example above, the following can be added:

\midi {
  \context {
    \name ImproVoice
    \type Performer_group
    \alias Voice
    \consists Note_performer
    \consists Beam_performer
    \consists Dynamic_performer
    \consists Tie_performer
    \consists Slur_performer
  }
  \context {
    \Staff
    \accepts ImproVoice
  }
}

This makes the ImproVoice context also work in MIDI output.


Replacing the Score context

In order to write a context MyScore that acts as the topmost context, as the Score context usually does, use \inherit-acceptability MyScore Score. The following example defines a ProportionalScore context where proportional notation is enabled (see Proportional notation).

\layout {
  \context {
    \Score
    \name ProportionalScore
    \alias Score
    proportionalNotationDuration = #(ly:make-moment 1/4)
  }
  \inherit-acceptability ProportionalScore Score
}

\new ProportionalScore { c'1 2 4 8 16 32 64 64 }

[image of music]

Since the topmost context needs to contain a number of fundamental engravers, inheriting settings with \Score is easiest in most cases. If you nevertheless define a score-level context from scratch without inheriting the Score definition, the argument to \type should be Score_engraver (or Score_performer in \midi) rather than Engraver_group. Furthermore, giving the topmost context the Score alias is strongly recommended given that a number of engravers need to access the topmost context using its alias.


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

The “accepts” list of a context can be changed with the \accepts or \denies commands. \accepts adds a context to the “accepts” list and \denies removes a context from the list.

For example, a TabStaff by default \accepts TabVoice contexts and \denies Voice contexts. If a Voice context is written within the TabStaff, it would be set on a separate staff.

\score {
  \new TabStaff <<
    \new TabVoice { c'1 }
    \new Voice { d'1 }
    >>
}

[image of music]

However, by using the \accepts command, the Voice context can be forced onto the TabStaff

\score {
  \new TabStaff <<
    \new TabVoice { c'1 }
    \new Voice { d'1 }
    >>
    \layout {
      \context {
        \TabStaff
        \accepts Voice
      }
    }
}

[image of music]

\denies is mainly used when a new context is being based on another, but the required nesting differs. For example, the VaticanaStaff context is based on the Staff context, but with the VaticanaVoice context substituted for the Voice context in the “accepts” list.

Note that a context will be silently created implicitly if a command is encountered when there is no suitable context available to contain it.

Within a context definition, the type of subcontext to be implicitly created is specified using \defaultchild. A number of music events require a ‘Bottom’ context: when such an event is encountered, subcontexts are created recursively until reaching a context with no ‘defaultchild’ setting.

Implicit context creation can at times give rise to unexpected new staves or scores. Using \new to create contexts explicitly avoids those problems.

Sometimes a context is required to exist for just a brief period, a good example being the staff context for an ossia. This is usually achieved by introducing the context definition at the appropriate place in parallel with corresponding section of the main music. By default, the temporary context will be placed below all the existing contexts. To reposition it above the context called “main”, it should be defined like this:

\new Staff \with { alignAboveContext = "main" }

A similar situation arises when positioning a temporary lyrics context within a multi-staff layout such as a ChoirStaff, for example, when adding a second verse to a repeated section. By default the temporary lyrics context will be placed beneath the lower staves. By defining the temporary lyrics context with alignBelowContext it can be positioned correctly beneath the (named) lyrics context containing the first verse.

Examples showing this repositioning of temporary contexts can be found elsewhere – see Nesting music expressions, Modifying single staves and Techniques specific to lyrics.

See also

Learning Manual: Nesting music expressions.

Notation Reference: Modifying single staves, Techniques specific to lyrics.

Application Usage: An extra staff appears.

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


5.2 Explaining the Internals Reference

See also

Notation Reference: Naming conventions.


5.2.1 Navigating the program reference

Suppose we want to move the fingering indication in the fragment below:

c''-2

[image of music]

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:

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

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

[image of music]

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 will insert “three staff spaces” worth of distance between the note and a fingering mark:

\once \override Voice.Fingering.padding = #3

Inserting the padding before the fingering object is created results in the following:

\once \override Voice.Fingering.padding = #3
c''-2

[image of music]

In this case, the context for this tweak is Voice. See Fingering_engraver plug-in, which says:

Fingering_engraver is part of contexts: … Voice


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 Reference: Backend, All layout objects, OverrideProperty, RevertProperty, PropertySet.


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., localAlterations (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, multi-measure rests will be combined into a single bar (as explained in Compressing empty measures) if the context property skipBars is set to #t:

R1*2
\set Score.skipBars = ##t
R1*2

[image of music]

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
\relative {
  e''8 e e e
  \set autoBeaming = ##t
  e8 e e e
} \\
\relative {
  c''8 c c c c8 c c c
}

[image of music]

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

[image of music]

Contexts are hierarchical, so if an enclosing context was specified, for example Staff, then the change would also apply to all Voices 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
\relative {
  \unset autoBeaming
  e''8 e e e
  \unset Score.autoBeaming
  e8 e e e
} \\
\relative {
  c''8 c c c c8 c c c
}

[image of music]

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 or \unset command by \once makes the setting apply to only a single time step:

c''4
\once \set fontSize = #4.7
c''4
c''4

[image of music]

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.

The syntax for the \override command is

\override [context.]GrobName.property = #value

For example, we can increase the thickness of a note stem by overriding the thickness property of the Stem object:

c''4 c''
\override Voice.Stem.thickness = #3.0
c''4 c''

[image of music]

If no context is specified in an \override, the bottom context is used:

\override Staff.Stem.thickness = #3.0
<<
  \relative {
    e''4 e
    \override Stem.thickness = #0.5
    e4 e
  } \\
  \relative {
    c''4 c c c
  }
>>

[image of music]

Some tweakable options are called ‘subproperties’ and reside inside properties. To tweak those, use commands in the form

\override Stem.details.beamed-lengths = #'(4 4 3)

or to modify the ends of spanners, use a form like these

\override TextSpanner.bound-details.left.text = "left text"
\override TextSpanner.bound-details.right.text = "right text"

The effects of \override can be undone by \revert.

The syntax for the \revert command is

\revert [context.]GrobName.property

For example,

\relative {
  c''4
  \override Voice.Stem.thickness = #3.0
  c4 c
  \revert Voice.Stem.thickness
  c4
}

[image of music]

The effects of \override and \revert apply to all grobs in the affected context from the current time forward:

<<
  \relative {
    e''4
    \override Staff.Stem.thickness = #3.0
    e4 e e
  } \\
  \relative {
    c''4 c c
    \revert Staff.Stem.thickness
    c4
  }
>>

[image of music]

\once can be used with \override or \revert to affect only the current time step:

<<
  \relative c {
    \override Stem.thickness = #3.0
    e''4 e e e
  } \\
  \relative {
    c''4
    \once \override Stem.thickness = #3.0
    c4 c c
  }
>>

[image of music]

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 [layout-object.]grob-property value

Specifying layout-object is optional. The \tweak command applies to the music 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:

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

[image of music]

\tweak can be used to modify slurs:

\relative { c'-\tweak thickness #5 ( d e f) }

[image of music]

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. Tweaking a whole chord does not do anything since its music event only acts as a container, and all layout objects are created from events inside of the EventChord:

\tweak color #red c''4
\tweak color #red <c'' e''>4
<\tweak color #red c'' e''>4

[image of music]

The simple \tweak command cannot be used to modify any object that is not directly created from the input. In particular it will not affect stems, automatic beams or accidentals, since these are generated later by NoteHead layout objects rather than by music elements in the input stream.

Such indirectly created layout objects can be tweaked using the form of the \tweak command in which the grob name is specified explicitly:

\tweak Stem.color #(universal-color 'orange)
\tweak Beam.color #(universal-color 'skyblue) c''8 e''
<c'' e'' \tweak Accidental.font-size #-3 ges''>4

[image of music]

\tweak cannot 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''

[image of music]

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 LilyPond: Displaying music expressions.

Known issues and warnings

The \tweak command cannot be used to modify the control points of just one of several ties in a chord, other than the first one encountered in the input file.


5.3.5 \set vs. \override

The \set and \override commands manipulate properties associated with contexts. In both cases, the properties follow a hierarchy of contexts; properties that are not set themselves in a context will still show the values of their respective parent’s context.

The lifetime and value of a context property is dynamic and only available when music is being interpreted (i.e., ‘iterated’). At the time of the context’s creation, properties are initialized from its corresponding definitions (along with any other modifications) of that context. Any subsequent changes are achieved with any ‘property-setting’ commands that are within the music itself.

Graphical Object (or “grob”) definitions are a special category of context properties as their structure and use is different from that of normal context properties. Unlike normal context properties, grob definitions are subdivided into grob properties.

Also, in contrast to normal context properties, grob definitions have their own internal ‘bookkeeping’ used to keep track of their own individual grob properties and any subproperties. This means that it is possible to define those parts within different contexts and yet still have the overall grob definition at the time of grob creation from all the pieces provided amongst the current context and its parent(s).

A grob is usually created by an engraver at the time of interpreting a music expression and receives its initial properties from the current grob definition of the engraver’s context. The engraver (or other ‘backend’ parts of LilyPond) can then change (or add to) the grob’s initial properties. However, this does not affect the context’s own grob definition.

What LilyPond calls grob properties in the context of ‘user-level’ tweaks are really the properties of a context’s own grob definition.

Grob definitions are accessed with a different set of commands and are manipulated using \override and \revert and have a name starting with a capital letter (e.g., ‘NoteHead’); whereas normal context properties are manipulated using \set and \unset and are named starting with a lowercase letter.

The commands \tweak and \overrideProperty change grob properties by bypassing all context properties completely and, instead, catch grobs as they are being created, setting properties on them for a music event (\tweak) or, in the case of \overrideProperty for a specific override.


5.3.6 The \offset command

While it is possible to set grob properties to new values with the \override, \tweak, and \overrideProperty commands, it is often more convenient to modify such properties relative to a default value. The \offset command is available for this purpose.

The syntax for \offset is

[-]\offset property offsets item

The command works by adding the contents of offsets to the default setting of the property property of the grob indicated by item.

Depending on the formulation of the command, \offset may act as either a \tweak or \override. The variations in usage are discussed after consideration is given to grob properties that may be used with \offset.

Properties which may be offset

Many, but not all, grob properties may be offset. If property cannot be offset, the object will remain unchanged and a warning will be issued. In such cases, \override or \tweak should be used to modify the object instead.

One can work by trial and error and let the warnings be the guide to what may or may not be offset. A more systematic approach is possible, however.

The following criteria determine whether a property can be modified with \offset:

The following examples consider several grob properties against the criteria outlined above.

\offset as an override

If item is a grob name like Arpeggio or Staff.OttavaBracket, the result is an \override of the specified grob type.

\offset property offsets [context.]GrobName

Note that the leading hyphen is never used with the ‘override’ form, just as it is never used with the \override command itself.

The following example uses the ‘override’ form to lengthen the default arpeggios shown in the first measure to cover the extent of the chords more fully. The arpeggios are stretched by a half staff space to top and bottom. Also shown is the same operation done on the first chord with an ordinary override of the positions property. This method is not at all expressive of the task of ‘stretching by a half staff space’, as the endpoints must be specified with absolute rather than relative coordinates. Furthermore, individual overrides would be needed for the other chords, as they vary in size and position.

arpeggioMusic = {
  <c' e' g'>\arpeggio <a' c'' e''>\arpeggio
  <d' f' a' c''>\arpeggio <c' e' g' b' d'' f'' a''>\arpeggio
}

{
  \arpeggioMusic
  \bar "||"
  \offset positions #'(-0.5 . 0.5) Arpeggio
  \arpeggioMusic
  \bar "||"
  \once \override Arpeggio.positions = #'(-3.5 . -0.5)
  <c' e' g'>1\arpeggio
  \bar "||"
}

[image of music]

In its ‘override’ usage, \offset may be prefaced with \once or \temporary and reverted using \revert with property (see functions Intermediate substitution functions). This follows from the fact that \offset actually creates an \override of property.

music = { c'8\< d' e' f'\! }

{
  \music
  \offset height 1 Hairpin
  \music
  \music
  \revert Hairpin.height
  \music
  \bar "||"
  \once \offset height 1 Hairpin
  \music \music
  \bar "||"
  \override Hairpin.height = 0.2
  \music
  \temporary \offset height 2 Hairpin
  \music
  \music
  \revert Hairpin.height
  \music
  \bar "||"
}

[image of music]

Also like \override, the ‘override’ form of \offset may be used with \undo and \single.

longStem = \offset length 6 Stem

{
 \longStem c'4 c''' c' c''
 \bar "||"
 \undo \longStem c'4 c''' c' c''
 \bar "||"
 \single \longStem c'4 c''' c' c''
 \bar "||"
}

[image of music]

\offset as a tweak

If item is a music expression such as ( or \arpeggio, the result is the same music expression with a tweak applied.

[-]\offset [GrobName.]property offsets music-expression

The syntax of \offset in its ‘tweak’ form is analogous to the \tweak command itself, both in ordering and in the presence or absence of the leading hyphen.

The following example uses the ‘tweak’ form to adjust the vertical position of the BreathingSign object. Compare this with the ordinary \tweak command also demonstrated. The syntax is equivalent; however, the output of \tweak is less intuitive, since BreathingSign.Y-offset is calculated from the middle staff line. It is not necessary to know how Y-offset is calculated when using \offset.

{
  c''4
  \breathe
  c''4
  \offset Y-offset 2 \breathe
  c''2
  \tweak Y-offset 3 \breathe
}

[image of music]

In the previous example, the tweaked objects were created directly from the user input: the \breathe command was an explicit instruction to return a BreathingSign object. Since the focus of the command was unambiguous, there was no need to specify the object’s name. When an object is indirectly created, however, it is necessary to include the grob’s name. This is the same as for the \tweak command.

In the following example, the Beam object is lowered two staff spaces by applying \offset to the positions property.

The first application of \offset requires that the grob’s name be included, because nothing in the input explicitly creates the beam. In the second application, the beam is created manually with the music expression [; therefore, the grob’s name is not needed. (Also illustrated is a shorthand: a single number will be applied to both members of a number-pair.)

{
  c''8 g'' e'' d''
  \offset Beam.positions #'(-2 . -2)
  c''8 g'' e'' d''
  c''8 g'' e'' d''
  c''8-\offset positions #-2 [ g'' e'' d'']
}

[image of music]

\offset with broken spanners

Independently modifying segments of a spanner extending over a line break or breaks is also possible. In this case, offsets takes a list of values of the property’s required data type.

The \offset command used in this manner is similar to the \alterBroken command. (See Modifying broken spanners.) In contrast with \alterBroken, however, the values given to \offset are relative, not absolute.

The following example displaces the ‘broken’ OttavaBracket object through its staff-padding property. Since the property takes a number, offsets is provided with a list of numbers to account for the two segments created by the line break. The bracket piece on the first line is effectively untouched since 0 is added to its default value of staff-padding. The segment on the second line is raised three staff spaces from its default height. The default height happens to be 2, though it is not necessary to know this to achieve the desired positioning.

{
  \offset staff-padding #'(0 3) Staff.OttavaBracket
  \ottava #1
  c'''2 c'''
  \break
  c'''2 c'''
}

[image of music]

The following example mimics the effect of the \shape command by offsetting the control-points property of the Slur object. Here, offsets is a list of number-pair-lists, one for each slur segment. This example achieves a result identical to the corresponding illustration at Modifying shapes.

{
  c'4-\offset control-points #'(
               ((0 . 0) (0 . 0) (0 . 0) (0 . 1))
               ((0.5 . 1.5) (1 . 0) (0 . 0) (0 . -1.5))
              ) ( f'4 g' c''
  \break
  d'4 c'' f' c')
}

[image of music]


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

[image of music]

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

[image of music]

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, keyAlterations, timeSignatureSettings, etc.). These properties can only be modified by completely redefining them as alists.


5.4 Useful concepts and properties

This section discusses various common layout issues and the tweaking methods related to them.

See also

Learning Manual: Tweaking output, Other sources of information.

Notation Reference: Explaining the Internals Reference, Modifying properties.

Extending LilyPond: Interfaces for programmers.

Installed Files: ‘scm/define-grobs.scm’.

Snippets: Tweaks and overrides.

Internals Reference: All layout objects.


5.4.1 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

Direction indicators affect only the next note:

\relative {
  c''2( c)
  c2_( c)
  c2( c)
  c2^( c)
}

[image of music]


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 of the form

\xxxUp, \xxxDown or \xxxNeutral

where \xxxNeutral means “use the default” direction. See Within-staff objects.

In a few cases, arpeggio for example, the value of the direction property can specify whether the object is to be placed to the right or left of the parent. 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.

These indications affect all notes until they are canceled.

\relative {
  c''2( c)
  \slurDown
  c2( c)
  c2( c)
  \slurNeutral
  c2( c)
}

[image of music]

In polyphonic music, it is generally better to specify an explicit voice than change an object’s direction. For more information, see Multiple voices.

See also

Learning Manual: Within-staff objects.

Notation Reference: Multiple voices.


5.4.2 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. In general, distance units may be specified by appending \mm (millimeter), \cm (centimeter), \in (inches), \pt (points), or \bp (big points).

mmcminptbp
mm10.10.03942.84532.8346
cm1010.393728.452828.3465
in25.42.54172.2772
pt0.35150.03510.013810.996
bp0.35380.03540.01391.00381

Page layout distances can also be specified in scalable units (see the following paragraph) by appending \staff-space to the quantity. See Page layout for a detailed description of LilyPond’s 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.3 Dimensions

The dimensions of a graphical object specify the positions of the left and right edges and the bottom and top edges of the objects’ bounding box as distances from the objects’ reference point in units of staff spaces. These positions are usually coded as two Scheme pairs. For example, the text markup command \with-dimensions takes three arguments, the first two of which are a Scheme pair giving the left and right edge positions and a Scheme pair giving the bottom and top edge positions:

\with-dimensions #'(-5 . 10) #'(-3 . 15) arg

This specifies a bounding box for arg with its left edge at -5, its right edge at 10, its bottom edge at -3 and its top edge at 15, all measured from the objects’ reference point in units of staff spaces.

See also

Notation Reference: Distances and measurements.


5.4.4 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 behavior, as well as special tweaking methods related to the fact that they can be broken across systems.


Modifying broken spanners

When a spanner crosses a line break or breaks, each piece inherits the attributes of the original spanner. Thus, ordinary tweaking of a broken spanner applies the same modifications to each of its segments. In the example below, overriding thickness affects the slur on either side of the line break.

\relative c'' {
  r2
  \once\override Slur.thickness = 10
  c8( d e f
  \break
  g8 f e d) r2
}

[image of music]

Independently modifying the appearance of individual pieces of a broken spanner is possible with the \alterBroken command. This command can produce either an \override or a \tweak of a spanner property.

The syntax for \alterBroken is

[-]\alterBroken property values target

The argument values is a list of values, one for each broken piece. If target is a grob name like Slur or Staff.PianoPedalBracket, the result is an \override of the specified grob type. If target is a music expression such as ‘(’ or ‘[’ the result is the same music expression with an appropriate tweak applied.

The leading hyphen must be used with the \tweak form. Do not add it when \alterBroken is used as an \override.

In its \override usage, \alterBroken may be prefaced by \once or \temporary and reverted by using \revert with property (see substitution functions Intermediate substitution functions).

The following code applies an independent \override to each of the slur segments in the previous example:

\relative c'' {
  r2
  \alterBroken thickness #'(10 1) Slur
  c8( d e f
  \break
  g8 f e d) r2
}

[image of music]

The \alterBroken command may be used with any spanner object, including Tie, PhrasingSlur, Beam and TextSpanner. For example, an editor preparing a scholarly edition may wish to indicate the absence of part of a phrasing slur in a source by dashing only the segment which has been added. The following example illustrates how this can be done, in this case using the \tweak form of the command:

% The empty list is conveniently used below, because it is the
% default setting of dash-definition, resulting in a solid curve.
\relative {
  c''2-\alterBroken dash-definition #'(() ((0 1.0 0.4 0.75))) \(e
  \break
  g2 e\)
}

[image of music]

It is important to understand that \alterBroken sets each piece of a broken spanner to the corresponding value in values. When there are fewer values than pieces, any additional piece will be assigned the empty list. This may lead to undesired results if the layout property is not set to the empty list by default. In such cases, each segment should be assigned an appropriate value.

Known issues and warnings

Line breaks may occur in different places following changes in layout. Settings chosen for \alterBroken may be unsuitable for a spanner that is no longer broken or is split into more segments than before. Explicit use of \break can guard against this situation.

The \alterBroken command is ineffective for spanner properties accessed before line breaking such as direction.

See also

Extending LilyPond: Difficult tweaks.


Setting minimum lengths for spanners

The spanner-interface interface provides three 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'

[image of music]

\relative \compressMMRests {
  a'1
  R1*23
  % increase the length of the rest bar
  \once \override MultiMeasureRest.minimum-length = #20
  R1*23
  a1
}

[image of music]

\relative {
  a' \< a a a \!
  % increase the length of the hairpin
  \override Hairpin.minimum-length = #20
  a \< a a a \!
}

[image of music]

This override can also be used to increase the length of slurs and phrasing slurs:

\relative {
  a'( g)
  a
  -\tweak minimum-length #5
  ( g)

  a\( g\)
  a
  -\tweak minimum-length #5
  \( g\)
}

[image of music]

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

[image of music]

The same is true of the Beam object:

% not effective alone
\once \override Beam.minimum-length = #20
e'8 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
e'8 e' e' e'

[image of music]

The minimum-length-after-break property

The property minimum-length-after-break can be used to stretch broken spanners starting after a line break. As for the minimum-length property, it is often needed to set the springs-and-rods property to ly:spanner::set-spacing-rods.

{
  \once \override Tie.minimum-length-after-break = 20
  a1~
  \break
  a1

  \once \override Slur.minimum-length-after-break = 20
  a1(
  \break
  d'1)

  \once \override TextSpanner.springs-and-rods =
    #ly:spanner::set-spacing-rods
  \once \override TextSpanner.minimum-length-after-break = 20
  a1\startTextSpan
  \break
  a1\stopTextSpan

  \once \override Hairpin.after-line-breaking = ##t
  \once \override Hairpin.to-barline = ##f
  \once \override Hairpin.minimum-length-after-break = 20
  a1\<
  \break
  a1\!

  \once \override Glissando.springs-and-rods =
    #ly:spanner::set-spacing-rods
  \once \override Glissando.breakable = ##t
  \once \override Glissando.after-line-breaking = ##t
  \once \override Glissando.minimum-length-after-break = 20
  a1\glissando
  \break
  d'1
}

[image of music]


Controlling spanner end points

The to-barline property of the spanner-interface, usually defaulting to true, causes hairpins and other spanners that are terminated on the first note of a measure to end instead on the immediately preceding bar line. If set to false, the spanner extends beyond the bar line and end on the note itself:

\relative {
  a' \< a a a a \! a a a \break
  \override Hairpin.to-barline = ##f
  a \< a a a a \! a a a
}

[image of music]

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.


5.4.5 Line styles

The line-interface groups all objects printing lines. All objects supporting these interfaces can be printed using different line styles. Here is an example showing the available values.

\relative {
  d''2 \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
}

[image of music]

Some objects may support specific additional styles.


5.4.6 Line spanners

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.

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 that need to be specified are nested two levels down within the property hierarchy, but the syntax of the \override command is quite simple:

e''2 \glissando b'
\once \override Glissando.bound-details.left.Y = #3
\once \override Glissando.bound-details.right.Y = #-2
e''2 \glissando b'

[image of music]

The units for the Y property are staff spaces, 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 sublists of bound-details. For example:

\override Glissando.breakable = ##t
\override Glissando.bound-details.right-broken.Y = #-3
c''1 \glissando \break
f''1

[image of music]

A number of further properties of the left and right sublists of the bound-details property may be modified in the same way as Y:

Y

This sets the Y-coordinate of the end point, measured in staff spaces 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 subproperty. 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 }
\relative { c''2\startTextSpan b c a\stopTextSpan }

[image of music]

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

\relative { c'4^\startTextSpan c c c \stopTextSpan }

[image of music]

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 subproperty to #t produces an arrowhead at the end points of the line.

padding

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

\relative c'' {
  \endSpanners
  c2 \startTextSpan c2 c2
  \endSpanners
  c2 \< c2 c2
}

[image of music]

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

[image of music]

This rather common operation has a shortcut \omit:

a1 a
\omit Score.BarLine
a a
\undo \omit Score.BarLine
a a a

[image of music]


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.

a'4 a'
\once \override NoteHead.transparent = ##t
a' a'

[image of music]

This rather common operation has a shortcut \hide:

a'4 a'
\once \hide NoteHead
a' a'

[image of music]


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
a'1

[image of music]

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
a'1

[image of music]

Selected Snippets

Using the whiteout property

Any graphical object can be printed over a white background to mask parts of objects that lie beneath. This can be useful to improve the appearance of collisions in complex situations when repositioning objects is impractical. It is necessary to explicitly set the layer property to control which objects are masked by the white background. In this example the collision of the tie with the time signature is improved by masking out the part of the tie that crosses the time signature by setting the whiteout property of TimeSignature. To do this TimeSignature is moved to a layer above Tie, which is left in the default layer of 1, and StaffSymbol is moved to a layer above TimeSignature so it is not masked.

{
  \override Score.StaffSymbol.layer = #4
  \override Staff.TimeSignature.layer = #3
  b'2 b'~
  \once \override Staff.TimeSignature.whiteout = ##t
  \time 3/4
  b' r4
}

[image of music]


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

FunctionVectorBeforeAt noAfter
formformbreakbreakbreak
all-visible#(#t #t #t)yesyesyes
begin-of-line-visible#(#f #f #t)nonoyes
center-visible#(#f #t #f)noyesno
end-of-line-visible#(#t #f #f)yesnono
begin-of-line-invisible#(#t #t #f)yesyesno
center-invisible#(#t #f #t)yesnoyes
end-of-line-invisible#(#f #t #t)noyesyes
all-invisible#(#f #f #f)nonono

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 objectUsual contextDefault setting
BarLineScorecalculated
BarNumberScorebegin-of-line-visible
BreathingSignVoicebegin-of-line-invisible
ClefStaffbegin-of-line-visible
CustosStaffend-of-line-visible
DivisioStaffbegin-of-line-invisible
DoublePercentRepeatVoicebegin-of-line-invisible
KeyCancellationStaffbegin-of-line-invisible
KeySignatureStaffbegin-of-line-visible
ClefModifierStaffbegin-of-line-visible
RehearsalMarkScoreend-of-line-invisible
TimeSignatureStaffall-visible

The example below shows the use of the vector form to control the visibility of bar lines:

\relative {
  f'4 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
}

[image of music]

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:


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.

\relative {
  \key g \major
  f'4 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
}

[image of music]

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.

\relative {
  \key g \major
  f'4 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
}

[image of music]

Visibility of cancelling accidentals

To remove the cancelling accidentals printed at an explicit key change, set the Staff context property printKeyCancellation to #f:

\relative {
  \key g \major
  f'4 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
}

[image of music]

With these overrides only the accidentals before the notes remain to indicate the change of key.

Note that when changing the key to C major or A minor the cancelling accidentals would be the only indication of the key change. In this case setting printKeyCancellation to #f has no effect:

\relative {
  \key g \major
  f'4 g a b
  \set Staff.explicitKeySignatureVisibility = #all-invisible
  \set Staff.printKeyCancellation = ##f
  \key c \major
  f4 g a b \break
  f4 g a b
  f4 g a b
}

[image of music]

To suppress the cancelling accidentals even when the key is changed to C major or A minor, override the visibility of the KeyCancellation grob instead:

\relative {
  \key g \major
  f'4 g a b
  \set Staff.explicitKeySignatureVisibility = #all-invisible
  \override Staff.KeyCancellation.break-visibility = #all-invisible
  \key c \major
  f4 g a b \break
  f4 g a b
  f4 g a b
}

[image of music]

Transposed clefs

The small transposition symbol on transposed clefs is produced by the ClefModifier 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 ClefModifier layout objects to suppress transposition symbols for invisible clefs.

For explicit clef changes, the explicitClefVisibility property controls both the clef symbol and any transposition symbol associated with it.

See also

Learning Manual: Visibility and color of objects.


5.4.8 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 = #'(15 -1 0)
g4\< e' d'' f''\!

[image of music]


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

[image of music]


5.4.9 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

Notation Reference: Using the break-alignable-interface.

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

[image of music]


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 propertydirection propertyPlacement
0-1left
01right
1-1below
11above

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

[image of music]

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, and UP may be substituted for -1, 0, and 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

[image of music]


Using the break-alignable-interface

Rehearsal marks, text marks, bar numbers, and more generally all objects with break-alignable-interface, collectively referred to as “break-alignable objects”, may be aligned with notation objects such as bar lines, key signatures, time signatures, and generally any object with break-aligned-interface. To be more precise, break-aligned items have a break-align-symbol property, providing symbols that can be used as ‘anchor points’ for other objects via the break-align-symbols property. See break-alignment-interface, for a complete list of available symbols.

Each type of object has its own default reference point, to which break-alignable items are aligned:

\override Score.TextMark.self-alignment-X = #CENTER
% The text mark will be aligned
% to the right edge of the clef
\override Score.TextMark.break-align-symbols =
            #'(clef)
\key a \major
\clef treble
\textMark "↓"
e'1
% The text mark will be aligned
% to the left edge of the time signature
\override Score.TextMark.break-align-symbols =
            #'(time-signature)
\key a \major
\clef treble
\time 3/4
\textMark "↓"
e'2.
% The text mark will be centered
% above the breathing mark
\override Score.TextMark.break-align-symbols =
            #'(breathing-sign)
\key a \major
\clef treble
\time 4/4
e'1
\breathe
\textEndMark "↓"

[image of music]

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.

\override Score.TextMark.self-alignment-X = #CENTER
% The text mark will be aligned
% to the right edge of the key signature
\override Score.TextMark.break-align-symbols =
            #'(key-signature clef)
\key a \major
\clef treble
\textMark "↓"
e'1
% The text mark will be aligned
% to the right edge of the clef
\set Staff.explicitKeySignatureVisibility = #all-invisible
\override Score.TextMark.break-align-symbols =
            #'(key-signature clef)
\key a \major
\clef bass
\textMark "↓"
gis,1
% The text mark will be centered
% above the bar line
\set Staff.explicitKeySignatureVisibility = #all-invisible
\set Staff.explicitClefVisibility = #all-invisible
\override Score.TextMark.break-align-symbols =
            #'(key-signature clef)
\key a \major
\clef treble
\textMark "↓"
e'1

[image of music]

The alignment of the break-alignable item 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.

\override Score.TextMark.self-alignment-X = #CENTER
% The text mark will be aligned
% with the right edge of the key signature
\override Score.TextMark.break-align-symbols =
            #'(key-signature)
\key a \major
\clef treble
\time 4/4
\textMark "↓"
e'1
% The text mark will be centered
% above the key signature
\once \override Score.KeySignature.break-align-anchor-alignment =
                  #CENTER
\textMark "↓"
\key a \major
e'1
% The text mark will be aligned
% with the left edge of the key signature
\once \override Score.KeySignature.break-align-anchor-alignment =
                  #LEFT
\key a \major
\textMark "↓"
e'1

[image of music]

The break-alignable item can also be offset to the right or left of the left edge by an arbitrary amount. The units are staff spaces:

\override Score.TextMark.self-alignment-X = #CENTER
% The text mark will be aligned
% with the left edge of the key signature
% and then shifted right by 3.5 staff spaces
\override Score.TextMark.break-align-symbols =
            #'(key-signature)
\once \override Score.KeySignature.break-align-anchor = #3.5
\key a \major
\textMark "↓"
e'1
% The text mark 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
\textMark "↓"
e'1

[image of music]


5.4.10 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 {
  a' a \XinO a a
}

[image of music]

Any of the Feta glyphs used in the Emmentaler font can be supplied to the \musicglyph markup command – see The Emmentaler font.

EPS’ files and Postscript commands can both be inserted inline using the \epsfile and \postscript markup commands respectively – see Graphic.

See also

Notation Reference: Graphic notation inside markup, Formatting text, Text markup commands, The Emmentaler font, Graphic.


5.4.11 Modifying shapes


Modifying ties and slurs

Ties, Slurs, PhrasingSlurs, LaissezVibrerTies and RepeatTies are all 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 in two ways:

  1. by specifying the displacements to be made to the control points of the automatically calculated Bézier curve, or
  2. by explicitly specifying the positions of the four control points required to define the wanted curve.

Both methods are explained below. The first method is more suitable if only slight adjustments to the curve are required; the second may be better for creating curves which are related to just a single note.

Cubic Bézier curves

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

[image of music]

Translations, rotations and scaling of the control points all result in exactly the same operations on the curve.

Specifying displacements from current control points

In this example the automatic placement of the tie is not optimum, and \tieDown would not help.

<<
  { e'1~ 1 }
\\
  \relative { r4 <g' c,> <g c,> <g c,> }
>>

[image of music]

Adjusting the control points of the tie with \shape allows the collisions to be avoided.

The syntax of \shape is

[-]\shape displacements item

This will reposition the control points of item by the amounts given by displacements. The displacements argument is a list of number pairs or a list of such lists. Each element of a pair represents the displacement of one of the coordinates of a control point. If item is a string, the result is \once\override for the specified grob type. If item is a music expression, the result is the same music expression with an appropriate tweak applied.

In other words, the \shape function can act as either a \once\override command or a \tweak command depending on whether the item argument is a grob name, like “Slur”, or a music expression, like “(”. The displacements argument specifies the displacements of the four control points as a list of four pairs of (dx . dy) values in units of staff spaces (or a list of such lists if the curve has more than one segment).

The leading hyphen is required if and only if the \tweak form is being used.

So, using the same example as above and the \once\override form of \shape, this will raise the tie by half a staff space:

<<
  {
    \shape #'((0 . 0.5) (0 . 0.5) (0 . 0.5) (0 . 0.5)) Tie
    e'1~ 1
  }
\\
  \relative { r4 <g' c,> <g c,> <g c,> }
>>

[image of music]

This positioning of the tie is better, but maybe it should be raised more in the center. The following example does this, this time using the alternative \tweak form:

<<
  {
    e'1-\shape #'((0 . 0.5) (0 . 1) (0 . 1) (0 . 0.5)) ~ e'
  }
\\
  \relative { r4 <g' c,> <g c,> <g c,> }
>>

[image of music]

To aid the tweaking process, the \vshape function is provided. Its name means visual shape: it acts exactly like \shape, except that the control points and polygon are additionally displayed.

\relative {
  c''8(\( a) e4 gis a\)
  \vshape #'((0 . -0.3) (0.5 . -0.2)
             (0.5 . -0.3) (0 . -0.7)) PhrasingSlur
  c8(\( a) e4 gis a\)
}

[image of music]

It is advisable to start with \vshape and adjust until a satisfactory curve is obtained, then simply remove the “v” letter in \vshape.

Two different curves starting at the same musical moment may also be shaped:

\relative {
  c''8(\( a) a'4 e c\)
  \shape #'((0.7 . -0.4) (0.5 . -0.4)
            (0.3 . -0.3) (0 . -0.2)) Slur
  \shape #'((0 . 0) (0 . 0.5)
            (0 . 0.5) (0 . 0)) PhrasingSlur
  c8(\( a) a'4 e c\)
}

[image of music]

The \shape function can also displace the control points of curves which stretch across line breaks. Each piece of the broken curve can be given its own list of offsets. If changes to a particular segment are not needed, the empty list can serve as a placeholder. In this example the line break makes the single slur look like two:

\relative {
  c'4( f g c
  \break
  d,4 c' f, c)
}

[image of music]

Changing the shapes of the two halves of the slur makes it clearer that the slur continues over the line break:

% () may be used as a shorthand for ((0 . 0) (0 . 0) (0 . 0) (0 . 0))
% if any of the segments does not need to be changed
\relative c' {
  \shape #'(
             (( 0 . 0) (0 . 0) (0 . 0) (0 . 1))
             ((0.5 . 1.5) (1 . 0) (0 . 0) (0 . -1.5))
           ) Slur
  c4( f g c
  \break
  d,4 c' f, c)
}

[image of music]

If an S-shaped curve is required the control points must always be adjusted manually – LilyPond will never select such shapes automatically.

\relative c'' {
  c8( e b-> f d' a e-> g)
  \shape #'((0 . -1) (5.5 . -0.5) (-5.5 . -10.5) (0 . -5.5))
         PhrasingSlur
  c8\( e b-> f d' a e-> g\)
}

[image of music]

Specifying control points explicitly

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 specified 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. Be aware that these values may need to be manually adjusted if any further changes are made to the music or the layout.

One situation where specifying the control points explicitly is preferable to specifying displacements is when they need to be specified relative to a single note. Here is an example of this. It shows one way of indicating a slur extending into alternative sections of a volta repeat.

\relative {
  c''1
  \repeat volta 3 { c4 d( e f }
  \alternative {
    \volta 1 { g2) d }
    \volta 2 {
      g2
        % create a slur and move it to a new position
        % the <> is just an empty chord to carry the slur termination
        -\tweak control-points
                  #'((-2 . 3.8) (-1 . 3.9) (0 . 4) (1 . 3.4)) ( <> )
      f,
    }
    \volta 3 {
      e'2
        % create a slur and move it to a new position
        -\tweak control-points
                  #'((-2 . 3) (-1 . 3.1) (0 . 3.2) (1 . 2.4)) ( <> )
      f,
    }
  }
}

[image of music]

Known issues and warnings

It is not possible to modify shapes of ties or slurs by changing the control-points property if there are multiple ties or slurs at the same musical moment – the \tweak command will also not work in this case. However, the tie-configuration property of TieColumn can be overridden to set start line and direction as required.

See also

Internals Reference: TieColumn.


A. Notation manual tables


A.1 Chord name chart

The following chart shows LilyPond’s standard system for printing chord names, along with the pitches they represent. Additional (unsupported) naming systems are also demonstrated in the “Chord names alternative” snippet in Chords, including the notation inspired by Harald Banter (1982) that was used by default in early LilyPond releases (up to version 1.7).

[image of music]


A.2 Common chord modifiers

The following table shows chord modifiers that can be used to generate standard chord structures.

TypeIntervalModifierExampleOutput
MajorMajor third,
perfect fifth
5 or nothingc1:5 [image of music]
MinorMinor third,
perfect fifth
m or m5c1:m [image of music]
AugmentedMajor third,
augmented fifth
augc1:aug [image of music]
DiminishedMinor third,
diminished fifth
dimc1:dim [image of music]
Dominant seventhMajor triad,
minor seventh
7c1:7 [image of music]
Major seventhMajor triad,
major seventh
maj7 or majc1:maj7 [image of music]
Minor seventhMinor triad,
minor seventh
m7c1:m7 [image of music]
Diminished
seventh
Diminished triad,
diminished seventh
dim7c1:dim7 [image of music]
Augmented
seventh
Augmented triad,
minor seventh
aug7c1:aug7 [image of music]
Half-diminished
seventh
Diminished triad,
minor seventh
m7.5-c1:m7.5- [image of music]
Minor-major
seventh
Minor triad,
major seventh
m7+c1:m7+ [image of music]
Major sixthMajor triad,
sixth
6c1:6 [image of music]
Minor sixthMinor triad,
sixth
m6c1:m6 [image of music]
Dominant ninthDominant seventh,
major ninth
9c1:9 [image of music]
Major ninthMajor seventh,
major ninth
maj9c1:maj9 [image of music]
Minor ninthMinor seventh,
major ninth
m9c1:m9 [image of music]
Dominant eleventhDominant ninth,
perfect eleventh
11c1:11 [image of music]
Major eleventhMajor ninth,
perfect eleventh
maj11c1:maj11 [image of music]
Minor eleventhMinor ninth,
perfect eleventh
m11c1:m11 [image of music]
Dominant
thirteenth
Dominant ninth,
major thirteenth
13c1:13 [image of music]
Dominant
thirteenth
Dominant eleventh,
major thirteenth
13.11c1:13.11 [image of music]
Major thirteenthMajor eleventh,
major thirteenth
maj13.11c1:maj13.11 [image of music]
Minor thirteenthMinor eleventh,
major thirteenth
m13.11c1:m13.11 [image of music]
Suspended secondMajor second,
perfect fifth
sus2c1:sus2 [image of music]
Suspended fourthPerfect fourth,
perfect fifth
sus4c1:sus4 [image of music]
Power chord
(two-voiced)
Perfect fifth1.5c1:5 [image of music]
Power chord
(three-voiced)
Perfect fifth,
octave
1.5.8c1:5.8 [image of music]

A.3 Predefined string tunings

The chart below shows the predefined string tunings.

[image of music]


A.4 Predefined fretboard diagrams


Diagrams for Guitar

[image of music]


Diagrams for Ukulele

[image of music]


Diagrams for Mandolin

[image of music]


A.5 Predefined paper sizes

Paper sizes are defined in file ‘scm/paper.scm’.

ISO 216, A series

"a10"26mm x 37mm (1.02in x 1.46in)
"a9"37mm x 52mm (1.46in x 2.05in)
"a8"52mm x 74mm (2.05in x 2.91in)
"a7"74mm x 105mm (2.91in x 4.13in)
"a6"105mm x 148mm (4.13in x 5.83in)
"a5"148mm x 210mm (5.83in x 8.27in)
"a4"210mm x 297mm (8.27in x 11.69in)
"a3"297mm x 420mm (11.69in x 16.54in)
"a2"420mm x 594mm (16.54in x 23.39in)
"a1"594mm x 841mm (23.39in x 33.11in)
"a0"841mm x 1189mm (33.11in x 46.81in)

Two extended sizes as defined in DIN 476

"2a0"1189mm x 1682mm (46.81in x 66.22in)
"4a0"1682mm x 2378mm (66.22in x 93.62in)

ISO 216, B series

"b10"31mm x 44mm (1.22in x 1.73in)
"b9"44mm x 62mm (1.73in x 2.44in)
"b8"62mm x 88mm (2.44in x 3.46in)
"b7"88mm x 125mm (3.46in x 4.92in)
"b6"125mm x 176mm (4.92in x 6.93in)
"b5"176mm x 250mm (6.93in x 9.84in)
"b4"250mm x 353mm (9.84in x 13.90in)
"b3"353mm x 500mm (13.90in x 19.69in)
"b2"500mm x 707mm (19.69in x 27.83in)
"b1"707mm x 1000mm (27.83in x 39.37in)
"b0"1000mm x 1414mm (39.37in x 55.67in)

ISO 269, C series

"c10"28mm x 40mm (1.10in x 1.57in)
"c9"40mm x 57mm (1.57in x 2.24in)
"c8"57mm x 81mm (2.24in x 3.19in)
"c7"81mm x 114mm (3.19in x 4.49in)
"c6"114mm x 162mm (4.49in x 6.38in)
"c5"162mm x 229mm (6.38in x 9.02in)
"c4"229mm x 324mm (9.02in x 12.76in)
"c3"324mm x 458mm (12.76in x 18.03in)
"c2"458mm x 648mm (18.03in x 25.51in)
"c1"648mm x 917mm (25.51in x 36.10in)
"c0"917mm x 1297mm (36.10in x 51.06in)

North American paper sizes

"junior-legal"5.0in x 8.0in (127mm x 203mm)
"legal"8.5in x 14.0in (216mm x 356mm)
"ledger"17.0in x 11.0in (432mm x 279mm)
"17x11"17.0in x 11.0in (432mm x 279mm)
"letter"8.5in x 11.0in (216mm x 279mm)
"tabloid"11.0in x 17.0in (279mm x 432mm)
"11x17"11.0in x 17.0in (279mm x 432mm)

Sizes by IEEE Printer Working Group, for children’s writing

"government-letter"8.0in x 10.5in (203mm x 267mm)
"government-legal"8.5in x 13.0in (216mm x 330mm)
"philippine-legal"8.5in x 13.0in (216mm x 330mm)

ANSI sizes

"ansi a"8.5in x 11.0in (216mm x 279mm)
"ansi b"11.0in x 17.0in (279mm x 432mm)
"ansi c"17.0in x 22.0in (432mm x 559mm)
"ansi d"22.0in x 34.0in (559mm x 864mm)
"ansi e"34.0in x 44.0in (864mm x 1118mm)
"engineering f"28.0in x 40.0in (711mm x 1016mm)

North American architectural sizes

"arch a"9.0in x 12.0in (229mm x 305mm)
"arch b"12.0in x 18.0in (305mm x 457mm)
"arch c"18.0in x 24.0in (457mm x 610mm)
"arch d"24.0in x 36.0in (610mm x 914mm)
"arch e"36.0in x 48.0in (914mm x 1219mm)
"arch e1"30.0in x 42.0in (762mm x 1067mm)

Other sizes, including antique sizes still used in the United Kingdom

"statement"5.5in x 8.5in (140mm x 216mm)
"half letter"5.5in x 8.5in (140mm x 216mm)
"quarto"8.0in x 10.0in (203mm x 254mm)
"octavo"6.75in x 10.5in (171mm x 267mm)
"executive"7.25in x 10.5in (184mm x 267mm)
"monarch"7.25in x 10.5in (184mm x 267mm)
"foolscap"8.27in x 13.0in (210mm x 330mm)
"folio"8.27in x 13.0in (210mm x 330mm)
"super-b"13.0in x 19.0in (330mm x 483mm)
"post"15.5in x 19.5in (394mm x 495mm)
"crown"15.0in x 20.0in (381mm x 508mm)
"large post"16.5in x 21.0in (419mm x 533mm)
"demy"17.5in x 22.5in (445mm x 572mm)
"medium"18.0in x 23.0in (457mm x 584mm)
"broadsheet"18.0in x 24.0in (457mm x 610mm)
"royal"20.0in x 25.0in (508mm x 635mm)
"elephant"23.0in x 28.0in (584mm x 711mm)
"double demy"22.5in x 35.0in (572mm x 889mm)
"quad demy"35.0in x 45.0in (889mm x 1143mm)
"atlas"26.0in x 34.0in (660mm x 864mm)
"imperial"22.0in x 30.0in (559mm x 762mm)
"antiquarian"31.0in x 53.0in (787mm x 1346mm)

PA4-based sizes

"pa10"26mm x 35mm (1.02in x 1.38in)
"pa9"35mm x 52mm (1.38in x 2.05in)
"pa8"52mm x 70mm (2.05in x 2.76in)
"pa7"70mm x 105mm (2.76in x 4.13in)
"pa6"105mm x 140mm (4.13in x 5.51in)
"pa5"140mm x 210mm (5.51in x 8.27in)
"pa4"210mm x 280mm (8.27in x 11.02in)
"pa3"280mm x 420mm (11.02in x 16.54in)
"pa2"420mm x 560mm (16.54in x 22.05in)
"pa1"560mm x 840mm (22.05in x 33.07in)
"pa0"840mm x 1120mm (33.07in x 44.09in)

Additional format for use in Southeast Asia and Australia

"f4"210mm x 330mm (8.27in x 12.99in)

A.6 MIDI instruments

The following is a list of names that can be used for the midiInstrument property. Each is presented with its number among the General MIDI Standard’s 128 Program Numbers.

1   acoustic grand2   bright acoustic3   electric grand
4   honky-tonk5   electric piano 16   electric piano 2
7   harpsichord8   clav9   celesta
10   glockenspiel11   music box12   vibraphone
13   marimba14   xylophone15   tubular bells
16   dulcimer17   drawbar organ18   percussive organ
19   rock organ20   church organ21   reed organ
22   accordion23   harmonica24   concertina
25   acoustic guitar (nylon)26   acoustic guitar (steel)27   electric guitar (jazz)
28   electric guitar (clean)29   electric guitar (muted)30   overdriven guitar
31   distorted guitar32   guitar harmonics33   acoustic bass
34   electric bass (finger)35   electric bass (pick)36   fretless bass
37   slap bass 138   slap bass 239   synth bass 1
40   synth bass 241   violin42   viola
43   cello44   contrabass45   tremolo strings
46   pizzicato strings47   orchestral harp48   timpani
49   string ensemble 150   string ensemble 251   synthstrings 1
52   synthstrings 253   choir aahs54   voice oohs
55   synth voice56   orchestra hit57   trumpet
58   trombone59   tuba60   muted trumpet
61   french horn62   brass section63   synthbrass 1
64   synthbrass 265   soprano sax66   alto sax
67   tenor sax68   baritone sax69   oboe
70   english horn71   bassoon72   clarinet
73   piccolo74   flute75   recorder
76   pan flute77   blown bottle78   shakuhachi
79   whistle80   ocarina81   lead 1 (square)
82   lead 2 (sawtooth)83   lead 3 (calliope)84   lead 4 (chiff)
85   lead 5 (charang)86   lead 6 (voice)87   lead 7 (fifths)
88   lead 8 (bass+lead)89   pad 1 (new age)90   pad 2 (warm)
91   pad 3 (polysynth)92   pad 4 (choir)93   pad 5 (bowed)
94   pad 6 (metallic)95   pad 7 (halo)96   pad 8 (sweep)
97   fx 1 (rain)98   fx 2 (soundtrack)99   fx 3 (crystal)
100   fx 4 (atmosphere)101   fx 5 (brightness)102   fx 6 (goblins)
103   fx 7 (echoes)104   fx 8 (sci-fi)105   sitar
106   banjo107   shamisen108   koto
109   kalimba110   bagpipe111   fiddle
112   shanai113   tinkle bell114   agogo
115   steel drums116   woodblock117   taiko drum
118   melodic tom119   synth drum120   reverse cymbal
121   guitar fret noise122   breath noise123   seashore
124   bird tweet125   telephone ring126   helicopter
127   applause128   gunshot

The drum kits listed below are also possible.

1   standard kit9   room kit17   power kit
25   electronic kit26   tr-808 kit33   jazz kit
41   brush kit49   orchestra kit57   sfx kit
128   mt-32 kit/cm-64 kit

A.7 List of colors

Normal colors

Usage syntax is detailed in Coloring objects.

blackwhiteredgreen
bluecyanmagentayellow
greydarkreddarkgreendarkblue
darkcyandarkmagentadarkyellow

CSS color names

CSS color names may be used as-is in string arguments.

alicebluedarkturquoiselightsalmonpapayawhip
antiquewhitedarkvioletlightseagreenpeachpuff
aquadeeppinklightskyblueperu
aquamarinedeepskybluelightslategraypink
azuredimgraylightslategreyplum
beigedimgreylightsteelbluepowderblue
bisquedodgerbluelightyellowpurple
blackfirebricklimerebeccapurple
blanchedalmondfloralwhitelimegreenred
blueforestgreenlinenrosybrown
bluevioletfuchsiamagentaroyalblue
browngainsboromaroonsaddlebrown
burlywoodghostwhitemediumaquamarinesalmon
cadetbluegoldmediumbluesandybrown
chartreusegoldenrodmediumorchidseagreen
chocolategraymediumpurpleseashell
coralgreenmediumseagreensienna
cornflowerbluegreenyellowmediumslatebluesilver
cornsilkgreymediumspringgreenskyblue
crimsonhoneydewmediumturquoiseslateblue
cyanhotpinkmediumvioletredslategray
darkblueindianredmidnightblueslategrey
darkcyanindigomintcreamsnow
darkgoldenrodivorymistyrosespringgreen
darkgraykhakimoccasinsteelblue
darkgreenlavendernavajowhitetan
darkgreylavenderblushnavyteal
darkkhakilawngreenoldlacethistle
darkmagentalemonchiffonolivetomato
darkolivegreenlightblueolivedrabturquoise
darkorangelightcoralorangeviolet
darkorchidlightcyanorangeredwheat
darkredlightgoldenrodyelloworchidwhite
darksalmonlightgraypalegoldenrodwhitesmoke
darkseagreenlightgreenpalegreenyellow
darkslatebluelightgreypaleturquoiseyellowgreen
darkslategraylightpinkpalevioletred
darkslategrey

CSS color definitions differ from X color names for the following colors: green, grey, maroon, purple.

X color names

X11 color names offer a wider choice than CSS names. They come in several variants:

Use the Scheme function x11-color to access them.

The following tables present all color names that may be used without a numerical suffix, and then the subset of these that may be used with such a suffix.

Color Names without a numerical suffix

AliceBlueLawnGreenOrangeRedfirebrick
AntiqueWhiteLemonChiffonPaleGoldenrodgainsboro
BlanchedAlmondLightBluePaleGreengold
BlueVioletLightCoralPaleTurquoisegoldenrod
CadetBlueLightCyanPaleVioletRedgreen
CornflowerBlueLightGoldenrodPapayaWhipgrey
DarkBlueLightGoldenrodYellowPeachPuffhoneydew
DarkCyanLightGreenPowderBlueivory
DarkGoldenrodLightGreyRosyBrownkhaki
DarkGreenLightPinkRoyalBluelavender
DarkGreyLightSalmonSaddleBrownlinen
DarkKhakiLightSeaGreenSandyBrownmagenta
DarkMagentaLightSkyBlueSeaGreenmaroon
DarkOliveGreenLightSlateBlueSkyBluemoccasin
DarkOrangeLightSlateGreySlateBluenavy
DarkOrchidLightSteelBlueSlateGreyorange
DarkRedLightYellowSpringGreenorchid
DarkSalmonLimeGreenSteelBlueperu
DarkSeaGreenMediumAquamarineVioletRedpink
DarkSlateBlueMediumBlueWhiteSmokeplum
DarkSlateGreyMediumOrchidYellowGreenpurple
DarkTurquoiseMediumPurpleaquamarinered
DarkVioletMediumSeaGreenazuresalmon
DeepPinkMediumSlateBluebeigeseashell
DeepSkyBlueMediumSpringGreenbisquesienna
DimGreyMediumTurquoiseblacksnow
DodgerBlueMediumVioletRedbluetan
FloralWhiteMidnightBluebrownthistle
ForestGreenMintCreamburlywoodtomato
GhostWhiteMistyRosechartreuseturquoise
GreenYellowNavajoWhitechocolateviolet
HotPinkNavyBluecoralwheat
IndianRedOldLacecornsilkwhite
LavenderBlushOliveDrabcyanyellow

Color names with a numerical suffix

In the following names the suffix N must be an integer between 1 and 4, from lighter to darker shades:

AntiqueWhiteNLightSkyBlueNSteelBlueNkhakiN
CadetBlueNLightSteelBlueNVioletRedNmagentaN
DarkGoldenrodNLightYellowNaquamarineNmaroonN
DarkOliveGreenNMediumOrchidNazureNorangeN
DarkOrangeNMediumPurpleNbisqueNorchidN
DarkOrchidNMistyRoseNblueNpinkN
DarkSeaGreenNNavajoWhiteNbrownNplumN
DeepPinkNOliveDrabNburlywoodNpurpleN
DeepSkyBlueNOrangeRedNchartreuseNredN
DodgerBlueNPaleGreenNchocolateNsalmonN
HotPinkNPaleTurquoiseNcoralNseashellN
IndianRedNPaleVioletRedNcornsilkNsiennaN
LavenderBlushNPeachPuffNcyanNsnowN
LemonChiffonNRosyBrownNfirebrickNtanN
LightBlueNRoyalBlueNgoldNthistleN
LightCyanNSeaGreenNgoldenrodNtomatoN
LightGoldenrodNSkyBlueNgreenNturquoiseN
LightPinkNSlateBlueNhoneydewNwheatN
LightSalmonNSpringGreenNivoryNyellowN

Grey Scale

A grey scale can be obtained using:

 
greyN

Where N is in the range 0–100.

Color-blind-safe colors

The Scheme function universal-color provides a set of eight colors designed to be unambiguous to people with dichromatism.

blackorangeskybluebluegreen
yellowbluevermillionredpurple

A.8 The Emmentaler font

The Emmentaler font consists of two subsets of glyphs. “Feta”, used for classical notation and “Parmesan”, used for Ancient notation.

Any glyph within the Emmentaler font can be accessed directly by using text markup along with the name of the glyph (as shown in the tables below). For example;

g^\markup {\musicglyph "scripts.segno" }

or

\markup {\musicglyph "five"}

For more information see Formatting text.


Clef glyphs

[image of music]


Time Signature glyphs

[image of music]


Number glyphs

[image of music]


Figured bass symbol glyphs

[image of music]


Accidental glyphs

[image of music]


Default note head glyphs

[image of music]


Special note head glyphs

[image of music]


Note head glyphs for shape notes

[image of music]


Rest glyphs

[image of music]


Flag glyphs

[image of music]


Dot glyphs

[image of music]


Dynamic glyphs

[image of music]


Script glyphs

[image of music]


Arrowhead glyphs

[image of music]


Bracket-tip glyphs

[image of music]


Pedal glyphs

[image of music]


Accordion glyphs

[image of music]


Tie glyphs

[image of music]


Vaticana glyphs

[image of music]


Medicaea glyphs

[image of music]


Hufnagel glyphs

[image of music]


Mensural glyphs

[image of music]


Neomensural glyphs

[image of music]


Petrucci glyphs

[image of music]


Solesmes glyphs

[image of music]


Kievan Notation glyphs

[image of music]


A.9 Note head styles

The following styles may be used for note heads.

[image of music]


A.10 Accidental glyph sets

The following sets of accidental glyphs are available.

[image of music]


A.11 Clef styles

The following table shows all the clef styles possible (including where middle C sits relative to the clef).


Standard clefs

ExampleOutputExampleOutput
\clef G [image of music]\clef "G2" [image of music]
\clef treble [image of music]\clef violin [image of music]
\clef french [image of music]\clef GG [image of music]
\clef tenorG [image of music]
\clef soprano [image of music]\clef mezzosoprano [image of music]
\clef C [image of music]\clef alto [image of music]
\clef tenor [image of music]\clef baritone [image of music]
\clef varC [image of music]\clef altovarC [image of music]
\clef tenorvarC [image of music]\clef baritonevarC [image of music]
\clef varbaritone [image of music]\clef baritonevarF [image of music]
\clef F [image of music]\clef bass [image of music]
\clef subbass [image of music]

Percussion staff clef

ExampleOutputExampleOutput
\clef percussion [image of music]\clef varpercussion [image of music]

Tab staff clefs

ExampleOutputExampleOutput
\new TabStaff {
  \clef tab
}
[image of music] \new TabStaff {
  \clef moderntab
}
[image of music]

Ancient music clefs


Gregorian

ExampleOutputExampleOutput
\clef "vaticana-do1" [image of music]\clef "vaticana-do2" [image of music]
\clef "vaticana-do3" [image of music]\clef "vaticana-fa1" [image of music]
\clef "vaticana-fa2" [image of music]
\clef "medicaea-do1" [image of music]\clef "medicaea-do2" [image of music]
\clef "medicaea-do3" [image of music]\clef "medicaea-fa1" [image of music]
\clef "medicaea-fa2" [image of music]
\clef "hufnagel-do1" [image of music]\clef "hufnagel-do2" [image of music]
\clef "hufnagel-do3" [image of music]\clef "hufnagel-fa1" [image of music]
\clef "hufnagel-fa2" [image of music]\clef "hufnagel-do-fa" [image of music]

Mensural

ExampleOutputExampleOutput
\clef "mensural-c1" [image of music]\clef "mensural-c2" [image of music]
\clef "mensural-c3" [image of music]\clef "mensural-c4" [image of music]
\clef "mensural-c5" [image of music]
\clef "mensural-f" [image of music]\clef "mensural-g" [image of music]
\clef "blackmensural-c1" [image of music]\clef "blackmensural-c2" [image of music]
\clef "blackmensural-c3" [image of music]\clef "blackmensural-c4" [image of music]
\clef "blackmensural-c5" [image of music]
\clef "neomensural-c1" [image of music]\clef "neomensural-c2" [image of music]
\clef "neomensural-c3" [image of music]\clef "neomensural-c4" [image of music]
\clef "neomensural-c5" [image of music]
\clef "petrucci-c1" [image of music]\clef "petrucci-c2" [image of music]
\clef "petrucci-c3" [image of music]\clef "petrucci-c4" [image of music]
\clef "petrucci-c5" [image of music]
\clef "petrucci-f" [image of music]\clef "petrucci-f2" [image of music]
\clef "petrucci-f3" [image of music]\clef "petrucci-f4" [image of music]
\clef "petrucci-f5" [image of music]
\clef "petrucci-g1" [image of music]\clef "petrucci-g2" [image of music]
\clef "petrucci-g" [image of music]

Kievan

ExampleOutput
\clef "kievan-do" [image of music]

A.12 Text markup commands

The following commands can all be used inside \markup { }.


A.12.1 Font

\abs-fontsize size (number) arg (markup)

Use size as the absolute font size (in points) 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 }
}

[image of music]

Used properties:

  • baseline-skip (3)
  • word-space (0.6)
\bold arg (markup)

Switch to bold font-series.

\markup {
  default
  \hspace #2
  \bold
  bold
}

[image of music]

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

[image of music]

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

[image of music]

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

[image of music]

\figured-bass arg (markup)

Set arg as small numbers for figured bass. Specially slashed digits can be achieved with a trailing backslashes (for numbers 6, 7, and 9) or a trailing plus (for numbers 2, 4, and 5).11

The use of a backslash is in analogy to \figuremode (see Entering figured bass). Note that to get a backslash character in markup it must be escaped by doubling it. Additionally, it must be put into double quotes.

\markup {
  \figured-bass {
    2 3 4+ 7 "9\\"
  }
}

[image of music]

\finger arg (markup)

Set arg as small numbers for fingering instructions.

\markup {
  \finger {
    1 2 3 4 5
  }
}

[image of music]

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

[image of music]

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
}

[image of music]

\italic arg (markup)

Use italic font-shape for arg.

\markup {
  default
  \hspace #2
  \italic
  italic
}

[image of music]

\large arg (markup)

Set font size to +1.

\markup {
  default
  \hspace #2
  \large
  large
}

[image of music]

\larger arg (markup)

Increase the font size relative to the current setting.

\markup {
  default
  \hspace #2
  \larger
  larger
}

[image of music]

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

[image of music]

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

[image of music]

\normal-size-sub arg (markup)

Set arg in subscript with a normal font size.

\markup {
  default
  \normal-size-sub {
    subscript in standard size
  }
}

[image of music]

Used properties:

  • font-size (0)
\normal-size-super arg (markup)

Set arg in superscript with a normal font size.

\markup {
  default
  \normal-size-super {
    superscript in standard size
  }
}

[image of music]

Used properties:

  • font-size (0)
\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 {
    huge bold sans caps
    \hspace #2
    \normal-text {
      huge normal
    }
    \hspace #2
    as before
  }
}

[image of music]

\normalsize arg (markup)

Set font size to default.

\markup {
  \teeny {
    this is very small
    \hspace #2
    \normalsize {
      normal size
    }
    \hspace #2
    teeny again
  }
}

[image of music]

\number arg (markup)

Set font family to number, which yields the font used for digits. This font also contains some punctuation; it has no letters.

The appearance of digits in the Emmentaler font can be controlled with four OpenType features: ‘tnum’, ‘cv47’, ‘ss01’, and ‘kern’, which can be arbitrarily combined.

tnum

If off (which is the default), glyphs ‘zero’ to ‘nine’ have no left and right side bearings. If on, the glyphs all have the same advance width by making the bearings non-zero.

cv47

If on, glyphs ‘four’ and ‘seven’ have shorter vertical strokes. Default is off.

ss01

If on, glyphs ‘zero’ to ‘nine’ have a fatter design, making them more readable at small sizes. Default is off.

kern

If on (which is the default), provide pairwise kerning between (most) glyphs.

\markuplist
  \number
  \fontsize #5
  \override #'((padding . 2)
               (baseline-skip . 4)
               (box-padding . 0)
               (thickness . 0.1))
  \table #'(-1 -1 -1 -1) {
      0123456789 \box 147 \concat { \box 1 \box 4 \box 7 }
    \normal-text \normalsize "(time signatures)"
    \override #'(font-features .("cv47")) {
      0123456789 \box 147 \concat { \box 1 \box 4 \box 7 } }
    \normal-text \normalsize "(alternatives)"
    \override #'(font-features .("tnum" "cv47" "-kern")) {
      0123456789 \box 147 \concat { \box 1 \box 4 \box 7 } }
    \normal-text \normalsize "(fixed-width)"
    \override #'(font-features . ("tnum" "cv47" "ss01")) {
      0123456789 \box 147 \concat { \box 1 \box 4 \box 7 } }
    \normal-text \normalsize "(figured bass)"
    \override #'(font-features . ("cv47" "ss01")) {
      0123456789 \box 147 \concat { \box 1 \box 4 \box 7 } }
    \normal-text \normalsize "(fingering)"
  }

[image of music]

See also the markup commands \figured-bass and \finger, which set the font features accordingly.

\overtie arg (markup)

Overtie arg.

\markup \line {
  \overtie "overtied"
  \override #'((offset . 5) (thickness . 1))
  \overtie "overtied"
  \override #'((offset . 1) (thickness . 5))
  \overtie "overtied"
}

[image of music]

Used properties:

  • shorten-pair ((0 . 0))
  • height-limit (0.7)
  • direction (1)
  • offset (2)
  • thickness (1)
\replace replacements (list) arg (markup)

Used to automatically replace a string by another in the markup arg. Each pair of the alist replacements specifies what should be replaced. The key is the string to be replaced by the value markup. Note the quasiquoting syntax with a backquote in the second example.

\markup \replace #'(("2nd" . "Second"))
  "2nd time"
\markup \replace
  #`(("2nd" . ,#{ \markup \concat { 2 \super nd } #}))
  \center-column {
    \line { Play only }
    \line { the 2nd time }
  }

[image of music]

Used properties:

  • replacement-alist
\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
  }
}

[image of music]

\sans arg (markup)

Switch to the sans serif font family.

\markup {
  default
  \hspace #2
  \sans {
    sans serif
  }
}

[image of music]

\simple str (string)

\markup \simple "x" is equivalent to \markup "x". This command was previously used internally, but no longer is, and is being kept for backwards compatibility only.

\small arg (markup)

Set font size to -1.

\markup {
  default
  \hspace #2
  \small
  small
}

[image of music]

\smallCaps arg (markup)

Emit arg as small caps.

\markup {
  default
  \hspace #2
  \smallCaps {
    Text in small caps
  }
}

[image of music]

\smaller arg (markup)

Decrease the font size relative to the current setting.

\markup {
  \fontsize #3.5 {
    large text
    \hspace #2
    \smaller { smaller text }
    \hspace #2
    large text
  }
}

[image of music]

\sub arg (markup)

Set arg in subscript.

\markup {
  \concat {
    H
    \sub {
      2
    }
    O
  }
}

[image of music]

Used properties:

  • font-size (0)
\super arg (markup)

Set arg in superscript.

\markup {
  E =
  \concat {
    mc
    \super
    2
  }
}

[image of music]

Used properties:

  • font-size (0)
\teeny arg (markup)

Set font size to -3.

\markup {
  default
  \hspace #2
  \teeny
  teeny
}

[image of music]

\text arg (markup)

Use a text font instead of music symbol or music alphabet font.

\markup {
  \number {
    1, 2,
    \text {
      three, four,
    }
    5
  }
}

[image of music]

\tie arg (markup)

Adds a horizontal bow created with make-tie-stencil at bottom or top of arg. Looks at thickness to determine line thickness, and offset to determine y-offset. The added bow fits the extent of arg, shorten-pair may be used to modify this. direction may be set using an override or direction-modifiers or voiceOne, etc.

\markup {
  \override #'(direction . 1)
  \tie "above"
  \override #'(direction . -1)
  \tie "below"
}

[image of music]

Used properties:

  • shorten-pair ((0 . 0))
  • height-limit (0.7)
  • direction (1)
  • offset (2)
  • thickness (1)
\tiny arg (markup)

Set font size to -2.

\markup {
  default
  \hspace #2
  \tiny
  tiny
}

[image of music]

\typewriter arg (markup)

Use font-family typewriter for arg.

\markup {
  default
  \hspace #2
  \typewriter
  typewriter
}

[image of music]

\underline arg (markup)

Underline arg. Looks at thickness to determine line thickness, offset to determine line y-offset from arg and underline-skip to determine the distance of additional lines from the others. underline-shift is used to get subsequent calls correct. Overriding it makes little sense, it would end up adding the provided value to the one of offset.

\markup \justify-line {
  \underline "underlined"
  \override #'(offset . 5)
  \override #'(thickness . 1)
  \underline "underlined"
  \override #'(offset . 1)
  \override #'(thickness . 5)
  \underline "underlined"
  \override #'(offset . 5)
  \override #'(underline-skip . 4)
  \underline \underline \underline "multiple underlined"
}

[image of music]

Used properties:

  • underline-skip (2)
  • underline-shift (0)
  • offset (2)
  • thickness (1)
\undertie arg (markup)
\markup \line {
  \undertie "undertied"
  \override #'((offset . 5) (thickness . 1))
  \undertie "undertied"
  \override #'((offset . 1) (thickness . 5))
  \undertie "undertied"
}

[image of music]

Used properties:

  • shorten-pair ((0 . 0))
  • height-limit (0.7)
  • direction (1)
  • 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
  }
}

[image of music]

\with-string-transformer transformer (procedure) arg (markup)

Interpret the markup arg with a string transformer installed. Whenever a string is interpreted inside arg, the transformer is first called, and it is the result that is interpreted. The arguments passed to the transformer are the output definition, the property alist chain, and the string. See New markup command definition about the two first arguments.

\markup \with-string-transformer
  #(lambda (layout props str)
     (string-upcase str))
  "abc"

[image of music]


A.12.2 Align

\align-on-other axis (non-negative, exact integer) other-dir (number) other (markup) self-dir (number) self (markup)

Align markup self on markup other along axis axis, using self-dir and other-dir for mutual alignment of self and other, respectively. This command translates self as requested relative to its surroundings; other is not printed.

\markup \column {
  1
  12
  \align-on-other #X #RIGHT 12
                     #LEFT 12345
  123
}

[image of music]

\center-align arg (markup)

Align arg to its X center.

\markup {
  \column {
    one
    \center-align
    two
    three
  }
}

[image of music]

\center-column args (markup list)

Put args in a centered column.

\markup {
  \center-column {
    one
    two
    three
  }
}

[image of music]

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

[image of music]

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; for this purpose use \overlay instead.

\markup {
  \fontsize #5
  \override #'(thickness . 2)
  \combine
    \draw-line #'(0 . 4)
    \arrow-head #Y #DOWN ##f
}

[image of music]

\concat args (markup list)

Concatenate args in a horizontal line, without spaces in between. Strings are concatenated on the input level, allowing ligatures. For example, \concat { "f" "i" } is equivalent to "fi".

\markup {
  \concat {
    one
    two
    three
  }
}

[image of music]

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

[image of music]

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 }
    }
    \null
    \override #'(line-width . 50)
    \fill-line {
      Width explicitly specified
    }
  }
}

[image of music]

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
}

[image of music]

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

[image of music]

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

[image of music]

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

[image of music]

\hspace amount (number)

Create an invisible object taking up horizontal space amount.

\markup {
  one
  \hspace #2
  two
  \hspace #8
  three
}

[image of music]

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

[image of music]

Used properties:

  • text-direction (1)
  • word-space
  • line-width (#f)
  • baseline-skip
\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
}

[image of music]

\justify-line args (markup list)

Put markups in a horizontal line of width line-width. The markups are spread to fill the entire line and separated by equal space. If there are no arguments, return an empty stencil.

\markup {
  \justify-line {
    Constant space between neighboring words
  }
}

[image of music]

Used properties:

  • line-width (#f)
  • word-space (0.6)
  • text-direction (1)
\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"
}

[image of music]

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

[image of music]

\left-column args (markup list)

Put args in a left-aligned column.

\markup {
  \left-column {
    one
    two
    three
  }
}

[image of music]

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

[image of music]

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
}

[image of music]

\overlay args (markup list)

Takes a list of markups combining them.

\markup {
  \fontsize #5
  \override #'(thickness . 2)
  \overlay {
    \draw-line #'(0 . 4)
    \arrow-head #Y #DOWN ##f
    \translate #'(0 . 4)\arrow-head #Y #UP ##f
  }
}

[image of music]

\pad amount (number) arg (markup)

Add space around a markup object. Identical to pad-around.

\markup {
  \box {
    default
  }
  \hspace #2
  \box {
    \pad-markup #1 {
      padded
    }
  }
}

[image of music]

\pad-around amount (number) arg (markup)

Add padding amount all around arg.

\markup {
  \box {
    default
  }
  \hspace #2
  \box {
    \pad-around #0.5 {
      padded
    }
  }
}

[image of music]

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

[image of music]

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

[image of music]

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

[image of music]

\right-align arg (markup)

Align arg on its right edge.

\markup {
  \column {
    one
    \right-align
    two
    three
  }
}

[image of music]

\right-column args (markup list)

Put args in a right-aligned column.

\markup {
  \right-column {
    one
    two
    three
  }
}

[image of music]

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

[image of music]

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

[image of music]

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

[image of music]

Used properties:

  • font-size (0)
\vcenter arg (markup)

Align arg to its Y center.

\markup {
  one
  \vcenter
  two
  three
}

[image of music]

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

[image of music]

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

[image of music]

Used properties:

  • text-direction (1)
  • word-space
  • line-width (#f)
  • baseline-skip
\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
}

[image of music]

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

[image of music]

Used properties:

  • text-direction (1)
  • word-space
  • line-width
  • baseline-skip

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

[image of music]

\beam width (number) slope (number) thickness (number)

Create a beam with the specified parameters.

\markup {
  \beam #5 #1 #2
}

[image of music]

\bracket arg (markup)

Draw vertical brackets around arg.

\markup {
  \bracket {
    \note {2.} #UP
  }
}

[image of music]

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

[image of music]

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
}

[image of music]

\draw-dashed-line dest (pair of numbers)

A dashed line.

If full-length is set to #t (default) the dashed-line extends to the whole length given by dest, without white space at beginning or end. off will then be altered to fit. To insist on the given (or default) values of on, off use \override #'(full-length . #f) Manual settings for on,off and phase are possible.

\markup {
  \draw-dashed-line #'(5.1 . 2.3)
  \override #'((on . 0.3) (off . 0.5))
  \draw-dashed-line #'(5.1 . 2.3)
}

[image of music]

Used properties:

  • full-length (#t)
  • phase (0)
  • off (1)
  • on (1)
  • thickness (1)
\draw-dotted-line dest (pair of numbers)

A dotted line.

The dotted-line always extends to the whole length given by dest, without white space at beginning or end. Manual settings for off are possible to get larger or smaller space between the dots. The given (or default) value of off will be altered to fit the line-length.

\markup {
  \draw-dotted-line #'(5.1 . 2.3)
  \override #'((thickness . 2) (off . 0.2))
  \draw-dotted-line #'(5.1 . 2.3)
}

[image of music]

Used properties:

  • phase (0)
  • off (1)
  • thickness (1)
\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
  }
}

[image of music]

Used properties:

  • span-factor (1)
  • line-width
  • thickness (1)
\draw-line dest (pair of numbers)

A simple line.

\markup {
  \draw-line #'(4 . 4)
  \override #'(thickness . 5)
  \draw-line #'(-3 . 0)
}

[image of music]

Used properties:

  • thickness (1)
\draw-squiggle-line sq-length (number) dest (pair of numbers) eq-end? (boolean)

A squiggled line.

If eq-end? is set to #t, it is ensured the squiggled line ends with a bow in same direction as the starting one. sq-length is the length of the first bow. dest is the end point of the squiggled line. To match dest the squiggled line is scaled accordingly. Its appearance may be customized by overrides for thickness, angularity, height and orientation.

\markup
  \column {
    \draw-squiggle-line #0.5 #'(6 . 0) ##t
    \override #'(orientation . -1)
    \draw-squiggle-line #0.5 #'(6 . 0) ##t
    \draw-squiggle-line #0.5 #'(6 . 0) ##f
    \override #'(height . 1)
    \draw-squiggle-line #0.5 #'(6 . 0) ##t
    \override #'(thickness . 5)
    \draw-squiggle-line #0.5 #'(6 . 0) ##t
    \override #'(angularity . 2)
    \draw-squiggle-line #0.5 #'(6 . 0) ##t
  }

[image of music]

Used properties:

  • orientation (1)
  • height (0.5)
  • angularity (0)
  • thickness (0.5)
\ellipse arg (markup)

Draw an ellipse around arg. Use thickness, x-padding, y-padding and font-size properties to determine line thickness and padding around the markup.

\markup {
  \ellipse {
    Hi
  }
}

[image of music]

Used properties:

  • y-padding (0.2)
  • x-padding (0.2)
  • font-size (0)
  • 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"
  }
}

[image of music]

\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
  \combine
  \filled-box #'(1 . 8) #'(0 . 7) #0.2
  \with-color #white
  \filled-box #'(3.6 . 5.6) #'(3.5 . 5.5) #0.7
}

[image of music]

\hbracket arg (markup)

Draw horizontal brackets around arg.

\markup {
  \hbracket {
    \line {
      one two three
    }
  }
}

[image of music]

\oval arg (markup)

Draw an oval around arg. Use thickness, x-padding, y-padding and font-size properties to determine line thickness and padding around the markup.

\markup {
  \oval {
    Hi
  }
}

[image of music]

Used properties:

  • y-padding (0.75)
  • x-padding (0.75)
  • font-size (0)
  • thickness (1)
\parenthesize arg (markup)

Draw parentheses around arg. This is useful for parenthesizing a column containing several lines of text.

\markup {
  \parenthesize
  \column {
    foo
    bar
  }
  \override #'(angularity . 2)
  \parenthesize
  \column {
    bah
    baz
  }
}

[image of music]

Used properties:

  • width (0.25)
  • line-thickness (0.1)
  • thickness (1)
  • size (1)
  • padding
  • angularity (0)
\path thickness (number) commands (list)

Draws a path with line 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.

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. You may also use the standard SVG single-letter equivalents: moveto = M, lineto = L, curveto = C, closepath = Z. The relative commands are written lowercase: rmoveto = r, rlineto = l, rcurveto = c.

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.

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.

samplePath =
  #'((lineto -1 1)
     (lineto 1 1)
     (lineto 1 -1)
     (curveto -5 -5 -5 5 -1 0)
     (closepath))

\markup {
  \path #0.25 #samplePath

  \override #'(line-join-style . miter)
  \path #0.25 #samplePath

  \override #'(filled . #t)
  \path #0.25 #samplePath
}

[image of music]

Used properties:

  • filled (#f)
  • line-join-style (round)
  • line-cap-style (round)
\polygon points (list of number pairs)

A polygon delimited by the list of points. extroversion defines how the shape of the polygon is adapted to its thickness. If it is 0, the polygon is traced as-is. If -1, the outer side of the line is just on the given points. If 1, the line has its inner side on the points. The thickness property controls the thickness of the line; for filled polygons, this means the diameter of the blot.

regularPentagon =
  #'((1 . 0) (0.31 . 0.95) (-0.81 . 0.59)
     (-0.81 . -0.59) (0.31 . -0.95))

\markup {
  \polygon #'((-1 . -1) (0 . -3) (2 . 2) (1 . 2))
  \override #'(filled . #f)
    \override #'(thickness . 2)
      \combine
        \with-color #(universal-color 'blue)
          \polygon #regularPentagon
        \with-color #(universal-color 'vermillion)
          \override #'(extroversion . 1)
            \polygon #regularPentagon
}

[image of music]

Used properties:

  • thickness (1)
  • filled (#t)
  • extroversion (0)
\postscript str (string)

Insert str directly into the output as a PostScript command string.

This command is meant as a last resort. Almost all needs are better fulfilled by other markup commands (see, for example, \path and \draw-line). If you do use this command, keep the following points in mind:

  • \postscript does not work in SVG output.
  • There are no stability guarantees on the details of how LilyPond produces its own output (i.e., the context into which the PostScript code is inserted). They may change substantially across versions.
  • LilyPond cannot understand the shape of the drawing, leading to suboptimal spacing.
  • Depending on how you install LilyPond, the version of the PostScript interpreter (GhostScript) can vary, and some of its features may be disabled.
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
}

[image of music]

\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

[image of music]

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

[image of music]

\triangle filled (boolean)

A triangle, either filled or empty.

\markup {
  \triangle ##t
  \hspace #2
  \triangle ##f
}

[image of music]

Used properties:

  • thickness (1)
  • font-size (0)
  • extroversion (0)
\with-url url (string) arg (markup)

Add a link to URL url around arg. This only works in the PDF backend.

\markup {
  \with-url #"https://lilypond.org/" {
    LilyPond ... \italic {
      music notation for everyone
    }
  }
}

[image of music]


A.12.4 Music

\accidental alteration (an exact rational number)

Select an accidental glyph from an alteration, given as rational number.

\markup \accidental #1/2

[image of music]

Used properties:

  • alteration-glyph-name-alist
\coda

Draw a coda sign.

\markup {
  \coda
}

[image of music]

\compound-meter time-sig (number or pair)

Draw a numeric time signature.

\markup {
  \column {
    \line { Single number:
               \compound-meter #3 }
    \line { Conventional:
               \compound-meter #'(4 . 4) or
               \compound-meter #'(4 4) }
    \line { Compound:
               \compound-meter #'(2 3 8) }
    \line { Single-number compound:
               \compound-meter #'((2) (3)) }
    \line { Complex compound:
               \compound-meter #'((2 3 8) (3 4)) }
  }
}

[image of music]

\customTabClef num-strings (integer) staff-space (number)

Draw a tab clef sans-serif style.

\doubleflat

Draw a double flat symbol.

\markup {
  \doubleflat
}

[image of music]

\doublesharp

Draw a double sharp symbol.

\markup {
  \doublesharp
}

[image of music]

\fermata

Create a fermata glyph. When direction is DOWN, use an inverted glyph. Note that within music, one would usually use the \fermata articulation instead of a markup.

 { c''1^\markup \fermata d''1_\markup \fermata }

\markup { \fermata \override #`(direction . ,DOWN) \fermata }

[image of music]

Used properties:

  • direction (1)
\flat

Draw a flat symbol.

\markup {
  \flat
}

[image of music]

\multi-measure-rest-by-number duration-scale (non-negative, exact integer)

Returns a multi-measure rest symbol.

If the number of measures is greater than the number given by expand-limit a horizontal line is printed. For every multi-measure rest lasting more than one measure a number is printed on top.

\markup {
  Multi-measure rests may look like
  \multi-measure-rest-by-number #12
  or
  \multi-measure-rest-by-number #7
  (church rests)
}

[image of music]

Used properties:

  • multi-measure-rest-number (#t)
  • width (8)
  • expand-limit (10)
  • hair-thickness (2.0)
  • thick-thickness (6.6)
  • word-space
  • style (())
  • font-size (0)
\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 Emmentaler font for a complete listing of the possible glyphs.

\markup {
  \musicglyph #"f"
  \musicglyph #"rests.2"
  \musicglyph #"clefs.G_change"
}

[image of music]

\natural

Draw a natural symbol.

\markup {
  \natural
}

[image of music]

\note duration (duration) 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
}

[image of music]

Used properties:

  • style (())
  • dots-direction (0)
  • flag-style (())
  • font-size (0)
\note-by-number log (number) dot-count (number) dir (number)

Construct a note symbol, with stem and flag. By using fractional values for dir, longer or shorter stems can be obtained. Supports all note-head-styles. Ancient note-head-styles will get mensural-style-flags. flag-style may be overridden independently. Supported flag-styles are default, old-straight-flag, modern-straight-flag, flat-flag, mensural and neomensural. The latter two flag-styles will both result in mensural-flags. Both are supplied for convenience.

\markup {
  \note-by-number #3 #0 #DOWN
  \hspace #2
  \note-by-number #1 #2 #0.8
}

[image of music]

Used properties:

  • style (())
  • dots-direction (0)
  • flag-style (())
  • font-size (0)
\rest duration (duration)

Returns a rest symbol.

If multi-measure-rest is set to true, a multi-measure rest symbol my be returned. In this case the duration needs to be entered as { 1*2 }to get a multi-measure rest for two bars. Actually, it’s only the scaling factor that determines the length, the basic duration is disregarded.

\markup {
  Rests:
  \hspace #2
  \rest { 4.. }
  \hspace #2
  \rest { \breve }
  \hspace #2
  Multi-measure rests:
  \override #'(multi-measure-rest . #t)
  {
  \hspace #2
  \override #'(multi-measure-rest-number . #f)
  \rest { 1*7 }
  \hspace #2
  \rest { 1*12 }
  }
}

[image of music]

Used properties:

  • multi-measure-rest-number (#t)
  • width (8)
  • expand-limit (10)
  • hair-thickness (2.0)
  • thick-thickness (6.6)
  • word-space
  • style (())
  • font-size (0)
  • style (())
  • ledgers ((-1 0 1))
  • font-size (0)
\rest-by-number log (integer) dot-count (integer)

A rest symbol.

For duration logs specified with property ledgers, rest symbols with ledger lines are selected.

\markup {
  \rest-by-number #3 #2
  \hspace #2
  \rest-by-number #0 #1
}

[image of music]

Used properties:

  • style (())
  • ledgers ((-1 0 1))
  • font-size (0)
\rhythm music (music)

An embedded rhythmic pattern.

\relative {
  \tempo \markup {
    Swing
    \hspace #0.4
    \rhythm { 8[ 8] } = \rhythm { \tuplet 3/2 { 4 8 } }
  }
  b8 g' c, d ees d16 ees d c r8
}

[image of music]

Within \rhythm, there is no time signature and no division in measures (as with \cadenzaOn, see Unmetered music). Beaming must be added explicitly with the syntax explained in Manual beams.

\markup {
  The rhythmic pattern \rhythm { 16[ 8 16] } is
  a type of syncopation.
}

[image of music]

\stemDown can be used to flip the stems.

\markup \rhythm { \stemDown 8 16 8 }

[image of music]

\rhythm works by creating a StandaloneRhythmVoice context. The parents of this context are StandaloneRhythmStaff and StandaloneRhythmScore. It is possible to apply global tweaks to the output by using a \layout block.

\layout {
  \context {
    \StandaloneRhythmVoice
    \xNotesOn
  }
}

\markup \rhythm { 8 16 8 }

[image of music]

Note: rhythm does not work when its argument is a single duration, e.g., rhythm { 8 }. Use extra braces: rhythm { { 8 } }.

Used properties:

  • font-size (-2)
\score score (score)

Inline an image of music. The reference point (usually the middle staff line) of the lowest staff in the top system is placed on the baseline.

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

[image of music]

Used properties:

  • baseline-skip
\segno

Draw a segno symbol.

\markup {
  \segno
}

[image of music]

\semiflat

Draw a semiflat symbol.

\markup {
  \semiflat
}

[image of music]

\semisharp

Draw a semisharp symbol.

\markup {
  \semisharp
}

[image of music]

\sesquiflat

Draw a 3/2 flat symbol.

\markup {
  \sesquiflat
}

[image of music]

\sesquisharp

Draw a 3/2 sharp symbol.

\markup {
  \sesquisharp
}

[image of music]

\sharp

Draw a sharp symbol.

\markup {
  \sharp
}

[image of music]

\tied-lyric str (string)

Replace ‘~’ tilde symbols with tie characters in the argument.

\markup \column {
  \tied-lyric
    #"Siam navi~all'onde~algenti Lasciate~in abbandono"
  \tied-lyric
    #"Impetuosi venti I nostri~affetti sono"
  \tied-lyric
    #"Ogni diletto~e scoglio Tutta la vita~e~un mar."
}

[image of music]

Used properties:

  • word-space
\varcoda

Draw a varcoda sign.

\markup {
  \varcoda
}

[image of music]


A.12.5 Conditionals

\if condition? (procedure) argument (markup)

Test condition, and only insert argument if it is true. The condition is provided as a procedure taking an output definition and a property alist chain. The procedure is applied, and its result determines whether to print the markup. This command is most useful inside oddHeaderMarkup or similar. Here is an example printing page numbers in bold:

\paper {
  oddHeaderMarkup =
    \markup \fill-line {
      ""
      \if #print-page-number
           \bold \fromproperty #'page:page-number-string
    }
  evenHeaderMarkup =
    \markup \fill-line {
      \if #print-page-number
           \bold \fromproperty #'page:page-number-string
      ""
    }
}
\unless condition? (procedure) argument (markup)

Similar to \if, printing the argument if the condition is false.

The following example shows how to print the copyright notice on all pages but the last instead of just the first page.

\paper {
  oddFooterMarkup = \markup {
    \unless #on-last-page-of-part \fill-line {
      \fromproperty #'header:copyright
    }
  }
}

\header {
  copyright = "© LilyPond Authors. License: GFDL."
  tagline = "© LilyPond Authors.  Documentation placed
under the GNU Free Documentation License
version 1.3."
}

A.12.6 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:

  • - Diagram items are separated by semicolons.
  • - Possible items:
    • s:number – Set the fret spacing of the diagram (in staff spaces). Default: 1.
    • t:number – Set the line thickness (relative to normal line thickness). Default: 0.5.
    • h:number – Set the height of the diagram in frets. Default: 4.
    • w:number – Set the width of the diagram in strings. Default: 6.
    • f:number – Set fingering label type (0 = none, 1 = in circle on string, 2 = below string). Default: 0.
    • d:number – Set radius of dot, in terms of fret spacing. Default: 0.25.
    • p:number – Set the position of the dot in the fret space. 0.5 is centered; 1 is on lower fret bar, 0 is on upper fret bar. Default: 0.6.
    • c:string1-string2-fret – Include a barre mark from string1 to string2 on fret.
    • string-fret – Place a dot on string at fret. If fret is ‘o’, string is identified as open. If fret is ‘x’, string is identified as muted.
    • string-fret-fingering – Place a dot on string at fret, and label with fingering as defined by the f: code.
  • - Note: 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)
\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] [color] ['parenthesized ['default-paren-color]])

Place a fret playing indication on string string-number at fret fret-number with an optional fingering label finger-value, an optional color modifier color-modifier, an optional color color, an optional parenthesis 'parenthesized and an optional paranthesis color 'default-paren-color. By default, the fret playing indicator is a solid dot. This can be globally changed by setting the value of the variable dot-color or for a single dot by setting the value of color. The dot can be parenthesized by adding 'parenthesized. By default the color for the parenthesis is taken from the dot. Adding 'default-paren-color will take the parenthesis-color from the global dot-color, as a fall-back black will be used. Setting color-modifier to inverted inverts the dot color for a specific fingering. The values for string-number, fret-number, and the optional finger should be entered first in that order. The order of the other optional arguments does not matter. 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^"

[image of music]

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:

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

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:

  • - 1q (1/4 covered)
  • - 1h (1/2 covered)
  • - 3q (3/4 covered)
  • - R (ring depressed)
  • - F (fully covered; the default if no state put)

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:

  • woodwind-diagram-details (())
  • font-size (0)
  • graphical (#t)
  • thickness (0.1)
  • size (1)

A.12.7 Accordion Registers

\discant name (string)

\discant name generates a discant accordion register symbol.

To make it available,

#(use-modules (lily accreg))

is required near the top of your input file.

The register names in the default \discant register set have modeled after numeric Swiss notation like depicted in http://de.wikipedia.org/wiki/Register_%28Akkordeon%29, omitting the slashes and dropping leading zeros.

The string name is basically a three-digit number with the lowest digit specifying the number of 16’ reeds, the tens the number of 8’ reeds, and the hundreds specifying the number of 4’ reeds. Without modification, the specified number of reeds in 8’ is centered in the symbol. Newer instruments may have registrations where 8’ can be used either within or without a tone chamber, ‘cassotto’. Notationally, the central dot then indicates use of cassotto. One can suffix the tens’ digits ‘1’ and ‘2’ with ‘+’ or ‘-’ to indicate clustering the dots at the right or left respectively rather than centered.

Some examples are

[image of music]

Used properties:

  • font-size (0)
\freeBass name (string)

\freeBass name generates a free bass/converter accordion register symbol for the usual two-reed layout.

To make it available,

#(use-modules (lily accreg))

is required near the top of your input file.

Available registrations are

[image of music]

Used properties:

  • font-size (0)
\stdBass name (string)

\stdBass name generates a standard bass accordion register symbol.

To make it available,

#(use-modules (lily accreg))

is required near the top of your input file.

The default bass register definitions have been modeled after the article http://www.accordions.com/index/art/stradella.shtml originally appearing in Accord Magazine.

The underlying register model is

[image of music]

This kind of overlapping arrangement is common for Italian instruments though the exact location of the octave breaks differ.

When not composing for a particular target instrument, using the five reed definitions makes more sense than using a four reed layout: in that manner, the ‘Master’ register is unambiguous. This is rather the rule in literature bothering about bass registrations at all.

Available registrations are

[image of music]

Used properties:

  • font-size (0)
\stdBassIV name (string)

\stdBassIV name generates a standard bass accordion register symbol.

To make it available,

#(use-modules (lily accreg))

is required near the top of your input file.

The main use is for four-reed standard bass instruments with reedbank layout

[image of music]

Notable instruments are Morino models with MIII (the others are five-reed instead) and the Atlantic IV. Most of those models have three register switches. Some newer Morinos with MIII might have five or even seven.

The prevalent three-register layout uses the middle three switches ‘Tenor’, ‘Master’, ‘Soft Bass’. Note that the sound is quite darker than the same registrations of ‘c,’-based instruments.

Available registrations are

[image of music]

Used properties:

  • font-size (0)
\stdBassV name (string)

\stdBassV name generates a standard bass accordion register symbol.

To make it available,

#(use-modules (lily accreg))

is required near the top of your input file.

The main use is for five-reed standard bass instruments with reedbank layout

[image of music]

This tends to be the bass layout for Hohner’s Morino series without convertor or MIII manual.

With the exception of the rather new 7-register layout, the highest two chord reeds are usually sounded together. The Older instruments offer 5 or 3 bass registers. The Tango VM offers an additional ‘Solo Bass’ setting that mutes the chord reeds. The symbol on the register buttons of the Tango VM would actually match the physical five-octave layout reflected here, but it is not used in literature.

Composers should likely prefer the five-reed versions of these symbols. The mismatch of a four-reed instrument with five-reed symbols is easier to resolve for the player than the other way round.

Available registrations are

[image of music]

Used properties:

  • font-size (0)
\stdBassVI name (string)

\stdBassVI name generates a standard bass accordion register symbol for six reed basses.

To make it available,

#(use-modules (lily accreg))

is required near the top of your input file.

This is primarily the register layout for the Hohner “Gola” model. The layout is

[image of music]

The registers are effectively quite similar to that of \stdBass. An additional bass reed at alto pitch is omitted for esthetical reasons from the ‘Master’ setting, so the symbols are almost the same except for the ‘Alto/Soprano’ register with bass notes at Alto pitch and chords at Soprano pitch.

Available registrations are

[image of music]

Used properties:

  • font-size (0)

A.12.8 Other

\auto-footnote mkup (markup) note (markup)

Have footnote note act as an annotation to the markup mkup.

\markup {
  \auto-footnote a b
  \override #'(padding . 0.2)
  \auto-footnote c d
}

[image of music]

The footnote will be annotated automatically.

Used properties:

  • padding (0.0)
  • raise (0.5)
\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
}

[image of music]

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
}

[image of music]

\eyeglasses

Prints out eyeglasses, indicating strongly to look at the conductor.

\markup { \eyeglasses }

[image of music]

\first-visible args (markup list)

Use the first markup in args that yields a non-empty stencil and ignore the rest.

\markup {
  \first-visible {
    \fromproperty #'header:composer
    \italic Unknown
  }
}

[image of music]

\footnote mkup (markup) note (markup)

Have footnote note act as an annotation to the markup mkup.

\markup {
  \footnote a b
  \override #'(padding . 0.2)
  \footnote c d
}

[image of music]

The footnote will not be annotated automatically.

\fraction arg1 (markup) arg2 (markup)

Make a fraction of two markups.

\markup {
  π 
  \fraction 355 113
}

[image of music]

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
}

[image of music]

\left-brace size (number)

A feta brace in point size size.

\markup {
  \left-brace #35
  \hspace #2
  \left-brace #45
}

[image of music]

\lookup glyph-name (string)

Lookup a glyph by name.

\markup {
  \override #'(font-encoding . fetaBraces) {
    \lookup #"brace200"
    \hspace #2
    \rotate #180
    \lookup #"brace180"
  }
}

[image of music]

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

[image of music]

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

[image of music]

\null

An empty markup with extents of a single point.

\markup {
  \null
}

[image of music]

\on-the-fly procedure (procedure) arg (markup)

Apply the procedure markup command to arg. procedure takes the same arguments as interpret-markup and returns a stencil.

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

new-prop may be either a single alist pair, or non-empty alist of its own.

\markup {
  \undertie "undertied"
  \override #'(offset . 15)
  \undertie "offset undertied"
  \override #'((offset . 15)(thickness . 3))
  \undertie "offset thick undertied"
}

[image of music]

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

[image of music]

\page-ref label (symbol) gauge (markup) default (markup)

Reference to a page number. label is the label set on the referenced page (using \label or \tocItem), gauge a markup used to estimate the maximum width of the page number, and default the value to display when label is not found.

(If the current book or bookpart is set to use roman numerals for page numbers, the reference will be formatted accordingly – in which case the gauge’s width may require additional tweaking.)

\pattern count (non-negative, exact integer) axis (non-negative, exact integer) space (number) pattern (markup)

Prints count times a pattern markup. Patterns are spaced apart by space (defined as for \hspace or \vspace, respectively). Patterns are distributed on axis.

\markup \column {
  "Horizontally repeated :"
  \pattern #7 #X #2 \flat
  \null
  "Vertically repeated :"
  \pattern #3 #Y #0.5 \flat
}

[image of music]

\property-recursive symbol (symbol)

Print out a warning when a header field markup contains some recursive markup definition.

\right-brace size (number)

A feta brace in point size size, rotated 180 degrees.

\markup {
  \right-brace #45
  \hspace #2
  \right-brace #35
}

[image of music]

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

[image of music]

Used properties:

  • thickness (1.6)
  • font-size (0)
\stencil stil (stencil)

Use a stencil as markup.

\markup {
  \stencil #(make-circle-stencil 2 0 #t)
}

[image of music]

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

[image of music]

\verbatim-file name (string)

Read the contents of file name, and include it verbatim.

\markup {
  \verbatim-file #"en/included/simple.ly"
}

[image of music]

\whiteout arg (markup)

Provide a white background for arg. The shape of the white background is determined by style. The default is box which produces a rectangle. rounded-box produces a rounded rectangle. outline approximates the outline of the markup.

\markup {
  \combine
    \filled-box #'(-1 . 15) #'(-3 . 4) #1
    \override #'(thickness . 1.5)
    \whiteout whiteout-box
}
\markup {
  \combine
    \filled-box #'(-1 . 24) #'(-3 . 4) #1
    \override #'((style . rounded-box) (thickness . 3))
    \whiteout whiteout-rounded-box
}
\markup {
  \combine
    \filled-box #'(-1 . 18) #'(-3 . 4) #1
    \override #'((style . outline) (thickness . 3))
    \whiteout whiteout-outline
}

[image of music]

Used properties:

  • thickness (())
  • style (box)
\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 "#0000ff"
  blue
}

[image of music]

\with-dimension axis (integer) val (pair of numbers) arg (markup)

Set the horizontal dimension of arg to val if axis is equal to X. If axis is equal to Y, set the vertical dimension of arg to val instead.

\with-dimension-from axis (integer) arg1 (markup) arg2 (markup)

Print arg2 but replace the horizontal dimension with the one from arg1 if axis is set to X. If axis is set to Y, replace the vertical dimension with the one from arg1 instead.

\with-dimensions x (pair of numbers) y (pair of numbers) arg (markup)

Set the horizontal and vertical dimensions of arg to x and y.

\with-dimensions-from arg1 (markup) arg2 (markup)

Print arg2 with the horizontal and vertical dimensions of arg1.

\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... }
  }
}
\with-outline outline (markup) arg (markup)

Print arg with the outline and dimensions of outline. The outline is used by skylines to resolve collisions (not for whiteout).

\with-true-dimension axis (integer) arg (markup)

Give arg its actual dimension (extent) on axis. Sometimes, the extents of a markup’s printed ink differs from the default extents. The main case is if glyphs are involved. By default, the extents of a glyph are based on the glyph’s metrics (i.e., a default vertical and horizontal size for the glyph), which, for various reasons, are often not identical to its bounding box (i.e., the smallest rectangle that completely encompasses the glyph’s outline) – in most cases, the outline protrudes the box spanned up by the metrics.

\markup
  \fontsize #10
  \override #'((box-padding . 0) (thickness . 0.2))
  \box
  \musicglyph "scripts.trill"

[image of music]

For purposes other than setting text, this behavior may not be wanted. You can use \with-true-dimension in order to give the markup its actual printed extent.

\markup
  \fontsize #10
  \override #'((box-padding . 0) (thickness . 0.2))
  \box
  \with-true-dimension #X
  \musicglyph "scripts.trill"

[image of music]

\with-true-dimensions arg (markup)

\markup \with-true-dimensions arg is short for \markup \with-true-dimension #X \with-true-dimension #Y arg, i.e., \with-true-dimensions has the effect of \with-true-dimension on both axes.


A.13 Text markup list commands

The following commands can all be used with \markuplist:

\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
\map-commands compose (procedure) args (markup list)

This applies the function compose to every markup in args (including elements of markup list command calls) in order to produce a new markup list. Since the return value from a markup list command call is not a markup list but rather a list of stencils, this requires passing those stencils off as the results of individual markup calls. That way, the results should work out as long as no markups rely on side effects.

\override-lines new-prop (pair) args (markup list)

Like \override, for markup lists.

\score-lines score (score)

This is the same as the \score markup but delivers its systems as a list of lines. Its score argument is entered in braces like it would be for \score.

\string-lines strg (string)

Takes the string strg and splits it at the character provided by the property split-char, defaulting to #\newline. Surrounding whitespace is removed from every resulting string. The returned list of markups is ready to be formatted by other markup or markup list commands like \column, \line, etc.

\markup {
  \column
    \string-lines
     "foo, foo,
     bar, bar,
     buzz, buzz!"
}

[image of music]

Used properties:

  • split-char (#\newline)
\table column-align (number list) lst (markup list)

Returns a table.

column-align specifies how each column is aligned, possible values are -1, 0, 1. The number of elements in column-align determines how many columns will be printed. The entries to print are given by lst, a markup-list. If needed, the last row is filled up with point-stencils. Overriding padding may be used to increase columns horizontal distance. Overriding baseline-skip to increase rows vertical distance.

% A markup command to print a fixed-width number.
\markup fwnum =
  \markup \override #'(font-features . ("ss01" "-kern"))
    \number \etc

\markuplist {
  \override #'(padding . 2)
  \table
    #'(0 1 0 -1)
    {
      \underline { center-aligned right-aligned
                    center-aligned left-aligned }
      one      \fwnum    1 thousandth \fwnum 0.001
      eleven   \fwnum   11 hundredth  \fwnum 0.01
      twenty   \fwnum   20 tenth      \fwnum 0.1
      thousand \fwnum 1000 one        \fwnum 1.0
    }
}

[image of music]

Used properties:

  • baseline-skip
  • padding (0)
\table-of-contents

Used properties:

  • baseline-skip
\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 that is used to define \justify-string and \wordwrap-string.

Used properties:

  • text-direction (1)
  • word-space
  • line-width

A.14 List of special characters

The following special characters references can be used; for more details, see ASCII aliases.

The HTML syntax is used and most of these references are the same as HTML. The rest of them are inspired by LaTeX.

The characters are boxed so that you can see their size. A small padding has been added between the character and the box for more readability.

[image of music]


A.15 List of articulations

In LilyPond’s internal logic, an ‘articulation’ is any object (other than dynamics) that may be attached directly after a rhythmic event: notes, chords; even silences and skips, or the empty chord construct <> (see Structure of a note entry). Even slurs, fingerings and text scripts are technically articulations, although these are not shown here.

Therefore, the following lists include not only articulation marks, but also all other scripts in the Emmentaler font that may be attached to notes (the way an accent is entered as ‘c'\accent’ or ‘c'->’). Each example shows the script in its two possible vertical positions: respectively up and down, as well as its default (neutral) position. See also Script glyphs for a more extensive list of glyphs, for use with the \musicglyph markup command as explained in Music notation inside markup.


Articulation scripts

\accent or ->

[image of music]

\espressivo

[image of music]

\marcato or -^

[image of music]

\portato or -_

[image of music]

\staccatissimo or -!

[image of music]

\staccato or -.

[image of music]

\tenuto or --

[image of music]


Ornament scripts

\prall

[image of music]

\prallup

[image of music]

\pralldown

[image of music]

\upprall

[image of music]

\downprall

[image of music]

\prallprall

[image of music]

\lineprall

[image of music]

\prallmordent

[image of music]

\mordent

[image of music]

\upmordent

[image of music]

\downmordent

[image of music]

\trill

[image of music]

\turn

[image of music]

\reverseturn

[image of music]

\slashturn

[image of music]

\haydnturn

[image of music]


Fermata scripts

\veryshortfermata

[image of music]

\shortfermata

[image of music]

\fermata

[image of music]

\longfermata

[image of music]

\verylongfermata

[image of music]

\henzeshortfermata

[image of music]

\henzelongfermata

[image of music]


Instrument-specific scripts

\upbow

[image of music]

\downbow

[image of music]

\flageolet

[image of music]

\open

[image of music]

\halfopen

[image of music]

\lheel

[image of music]

\rheel

[image of music]

\ltoe

[image of music]

\rtoe

[image of music]

\snappizzicato

[image of music]

\stopped or -+

[image of music]

\thumb

[image of music]


Repeat sign scripts

\segno

[image of music]

\coda

[image of music]

\varcoda

[image of music]


Ancient scripts

\accentus

[image of music]

\circulus

[image of music]

\ictus

[image of music]

\semicirculus

[image of music]

\signumcongruentiae

[image of music]


A.16 List of breath marks

'chantquarterbar

[image of music]

'chanthalfbar

[image of music]

'chantfullbar

[image of music]

'chantdoublebar

[image of music]

'comma

[image of music]

'varcomma

[image of music]

'tickmark

[image of music]

'upbow

[image of music]

'outsidecomma

[image of music]

'caesura

[image of music]

'curvedcaesura

[image of music]

'spacer

[image of music]


A.17 Percussion notes

bassdrum
bd

[image of music]

acousticbassdrum
bda

[image of music]

snare
sn

[image of music]

acousticsnare
sna

[image of music]

electricsnare
sne

[image of music]

lowfloortom
tomfl

[image of music]

highfloortom
tomfh

[image of music]

lowtom
toml

[image of music]

hightom
tomh

[image of music]

lowmidtom
tomml

[image of music]

himidtom
tommh

[image of music]

hihat
hh

[image of music]

closedhihat
hhc

[image of music]

openhihat
hho

[image of music]

halfopenhihat
hhho

[image of music]

pedalhihat
hhp

[image of music]

crashcymbal
cymc

[image of music]

crashcymbala
cymca

[image of music]

crashcymbalb
cymcb

[image of music]

ridecymbal
cymr

[image of music]

ridecymbala
cymra

[image of music]

ridecymbalb
cymrb

[image of music]

chinesecymbal
cymch

[image of music]

splashcymbal
cyms

[image of music]

ridebell
rb

[image of music]

cowbell
cb

[image of music]

hibongo
boh

[image of music]

openhibongo
boho

[image of music]

mutehibongo
bohm

[image of music]

lobongo
bol

[image of music]

openlobongo
bolo

[image of music]

mutelobongo
bolm

[image of music]

hiconga
cgh

[image of music]

openhiconga
cgho

[image of music]

mutehiconga
cghm

[image of music]

loconga
cgl

[image of music]

openloconga
cglo

[image of music]

muteloconga
cglm

[image of music]

hitimbale
timh

[image of music]

lotimbale
timl

[image of music]

hiagogo
agh

[image of music]

loagogo
agl

[image of music]

sidestick
ss

[image of music]

hisidestick
ssh

[image of music]

losidestick
ssl

[image of music]

guiro
gui

[image of music]

shortguiro
guis

[image of music]

longguiro
guil

[image of music]

cabasa
cab

[image of music]

maracas
mar

[image of music]

shortwhistle
whs

[image of music]

longwhistle
whl

[image of music]

handclap
hc

[image of music]

tambourine
tamb

[image of music]

vibraslap
vibs

[image of music]

tamtam
tt

[image of music]

claves
cl

[image of music]

hiwoodblock
wbh

[image of music]

lowoodblock
wbl

[image of music]

opencuica
cuio

[image of music]

mutecuica
cuim

[image of music]

triangle
tri

[image of music]

opentriangle
trio

[image of music]

mutetriangle
trim

[image of music]


A.18 List of bar lines

Each system following shows the appearance of a particular bar type at the beginning, middle, and end of a line.

For more information, see Bar lines and Automatic bar lines.

[image of music]


A.19 Default values for outside-staff-priority

The following table shows the default outside-staff-priority of all outside-staff grobs. Objects with smaller values are placed closer to the staff.

GrobPriority
AccidentalSuggestion0
MultiMeasureRestScript40
TrillSpanner50
BarNumber100
DynamicLineSpanner250
TextSpanner350
OttavaBracket400
CombineTextScript450
MultiMeasureRestText450
TextScript450
InstrumentSwitch500
VoltaBracketSpanner600
MeasureCounter750
MeasureSpanner750
SostenutoPedalLineSpanner1000
SustainPedalLineSpanner1000
UnaCordaPedalLineSpanner1000
CenteredBarNumberLineSpanner1200
TextMark1250
MetronomeMark1300
JumpScript1350
CodaMark1400
SegnoMark1400
SectionLabel1450
RehearsalMark1500

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


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, Special characters.


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, Properties of layout objects.

Notation Reference: Naming conventions.

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, Properties found in interfaces.

Notation Reference: Naming conventions, Layout interfaces.

Internals Reference: Graphical Object Interfaces.


lexer

A lexer is a program that 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 (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:


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.


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


spanner

Spanners are a class of grobs that are not horizontally fixed on one point of the score but extend from one point to another. Examples include beams, ties, and slurs, as well as hairpins and staff lines. Whereas non-spanners can only be broken into at most two visible pieces (for example, a clef duplicated at the end of the line and the beginning of the next line), spanners are broken into as many pieces as required by their start and end points (such as a long crescendo extending on three systems, or staff lines, which always span the whole score).

Technically, spanners are defined as grobs having the spanner-interface; on the C++ side of LilyPond, they are instances of the Spanner subclass of Grob. The left and right bounds of a spanner can be retrieved and set using ly:spanner-bound and ly:spanner-set-bound!, respectively. The bounds are always items. The X parent of a spanner has little musical sense, but is usually set to the left bound.

See also

Notation Reference: Spanners.

Internals Reference: all-layout-objects, spanner-interface.


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.21 Available music functions

\absolute [music] - music (music)

Make music absolute. This does not actually change the music itself but rather hides it from surrounding \relative and \fixed commands.

\acciaccatura [music] - music (music)

Create an acciaccatura from the following music expression

\accidentalStyle [music] - style (symbol list)

Set accidental style to symbol list style in the form ‘piano-cautionary’. If style has a form like ‘Staff.piano-cautionary’, the settings are applied to that context. Otherwise, the context defaults to ‘Staff’, except for piano styles, which use ‘GrandStaff’ as a context.

\addChordShape [void] - 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 [void] - name (string) lst (list)

Create instrument name with properties list.

This function is deprecated.

\addQuote [void] - name (string) music (music)

Define music as a quotable music expression named name

\after [music] - delta (duration) ev (music) mus (music)

Add music ev (usually a post-event) with a delay of delta after the onset of mus.

\afterGrace [music] - fraction [non-negative rational, fraction, or moment] main (music) grace (music)

Create grace note(s) after a main music expression.

The musical position of the grace expression is after a given fraction of the main note’s duration has passed. If fraction is not specified as first argument, it is taken from afterGraceFraction which has a default value of 3/4.

\allowPageTurn [music]

Allow a page turn. May be used at toplevel (ie between scores or markups), or inside a score.

\allowVoltaHook [void] - bar (string)

Allow the volta bracket hook being drawn over bar line bar.

\alterBroken [music] - property (key list or symbol) arg (list) target (key list or music)

Override property for pieces of broken spanner target with values arg. target may either be music in the form of a starting spanner event, or a symbol list in the form ‘Context.Grob’ or just ‘Grob’. Iff target is in the form of a spanner event, property may also have the form ‘Grob.property’ for specifying a directed tweak.

\ambitusAfter [music] - target (symbol)

Move the ambitus after the break-align symbol target.

\appendToTag [music] - tag (symbol) more (music) music (music)

Append more to the back of music tagged with tag. A post-event can be added to the articulations of rhythmic events or chords; other expressions may be added to chords, sequential or simultaneous music.

\applyContext [music] - proc (procedure)

Modify context properties with Scheme procedure proc.

\applyMusic [music] - func (procedure) music (music)

Apply procedure func to music.

\applyOutput [music] - target (symbol list or symbol) proc (procedure)

Apply function proc to every layout object matched by target which takes the form Context or Context.Grob.

\appoggiatura [music] - music (music)

Create an appoggiatura from music

\assertBeamQuant [music] - l (pair) r (pair)

Testing function: check whether the beam quants l and r are correct

\assertBeamSlope [music] - comp (procedure)

Testing function: check whether the slope of the beam is the same as comp

\autoChange [music] - pitch [pitch] clef-1 [context modification] clef-2 [context modification] music (music)

Make voices that switch between staves automatically. As an option the pitch where to switch staves may be specified. The clefs for the staves are optional as well. Setting clefs works only for implicitly instantiated staves.

\balloonGrobText [music] - grob-name (symbol) offset (pair of numbers) text (markup)

Attach text to grob-name at offset offset (use like \once)

\balloonText [post event] - offset (pair of numbers) text (markup)

Attach text at offset (use like \tweak)

\bar [music] - type (string)

Insert a bar line of type type, overriding any automatic bar lines.

\barNumberCheck [music] - n (integer)

Print a warning if the current bar number is not n.

\beamExceptions (any type) - music (music)

Extract a value suitable for setting Timing.beamExceptions from the given pattern with explicit beams in music. A bar check | has to be used between bars of patterns in order to reset the timing.

\bendAfter [post event] - delta (real number)

Create a fall or doit of pitch interval delta.

\bendHold [post event] - mus (music)

Sets the 'style of a BendSpanner to 'hold.

\bendStartLevel [post event] - idx (non-negative, exact integer) mus (music)

Sets the details.successive-level of a BendSpanner to idx.

\bookOutputName [void] - newfilename (string)

Direct output for the current book block to newfilename.

\bookOutputSuffix [void] - newsuffix (string)

Set the output filename suffix for the current book block to newsuffix.

\breathe [music]

Insert a breath mark.

\caesura [music]

Insert a caesura.

\chordRepeats [music] - event-types [list] music (music)

Walk through music putting the notes of the previous chord into repeat chords, as well as an optional list of event-types such as #'(string-number-event).

\clef [music] - type (string)

Set the current clef to type.

\codaMark [music] - num [non-negative, exact integer]

Create a coda mark. num may be 1 for the first mark, 2 for the second, etc., or it may be \default to use the next number in sequence automatically.

\compoundMeter [music] - 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).

\compressMMRests [music] - music (music)

Remove the empty bars created by multi-measure rests, leaving just the first bar containing the MM rest itself.

\crossStaff [music] - notes (music)

Create cross-staff stems

\cueClef [music] - type (string)

Set the current cue clef to type.

\cueClefUnset [music]

Unset the current cue clef.

\cueDuring [music] - what (string) dir (direction) main-music (music)

Insert contents of quote what corresponding to main-music, in a CueVoice oriented by dir.

\cueDuringWithClef [music] - 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 [music] - note (music)

Print note with a cross-shaped note head.

\defineBarLine [void] - bar (string) glyph-list (list)

Define bar line settings for bar line bar. The list glyph-list must have three entries which define substitute glyphs for the end of a line, the beginning of a line, and a span bar, respectively. The substitute glyphs may be either strings or booleans: #t calls for the same value as bar and #f calls for no glyph.

\displayLilyMusic [music] - port [output port] music (music)

Display the LilyPond input representation of music to port, defaulting to the console.

\displayMusic [music] - port [output port] music (music)

Display the internal representation of music to port, default to the console.

\displayScheme (any type) - port [output port] expr (any type)

Display the internal representation of expr to port, default to the console.

\dropNote [music] - num (integer) music (music)

Drop a note of any chords in music, in num position from above.

\enablePolymeter [void]

For use within an output definition. Enables polymetry, moving timing management from Score to Staff-like contexts. This is done by removing the Timing_translator from Score, and adding it to all contexts having the Staff alias.

\endSpanners [music] - music (music)

Terminate the next spanner prematurely after exactly one note without the need of a specific end spanner.

\eventChords [music] - music (music)

Compatibility function wrapping EventChord around isolated rhythmic events occuring since version 2.15.28, after expanding repeat chords ‘q’.

\featherDurations [music] - scale (non-negative rational, fraction, or moment) argument (music)

Adjust durations of music in argument by scale.

\finger [post event] - finger (index or markup)

Apply finger as a fingering indication.

\fixed [music] - pitch (pitch) music (music)

Use the octave of pitch as the default octave for music.

\footnote [music] - mark [markup] offset (pair of numbers) footnote (markup) item (symbol list or music)

Make the markup footnote a footnote on item. The footnote is marked with a markup mark moved by offset with respect to the marked music.

If mark is not given or specified as \default, it is replaced by an automatically generated sequence number. If item is a symbol list of form ‘Grob’ or ‘Context.Grob’, then grobs of that type will be marked at the current time step in the given context (default Bottom).

If item is music, the music will get a footnote attached to a grob immediately attached to the event, like \tweak does. For attaching a footnote to an indirectly caused grob, write \single\footnote, use item to specify the grob, and follow it with the music to annotate.

Like with \tweak, if you use a footnote on a following post-event, the \footnote command itself needs to be attached to the preceding note or rest as a post-event with -.

\grace [music] - music (music)

Insert music as grace notes.

\grobdescriptions (any type) - descriptions (list)

Create a context modification from descriptions, a list in the format of all-grob-descriptions.

\harmonicByFret [music] - fret (number) music (music)

Convert music into mixed harmonics; the resulting notes resemble harmonics played on a fretted instrument by touching the strings at fret.

\harmonicByRatio [music] - ratio (number) music (music)

Convert music into mixed harmonics; the resulting notes resemble harmonics played on a fretted instrument by touching the strings at the point given through ratio.

\harmonicNote [music] - note (music)

Print note with a diamond-shaped note head.

\harmonicsOn [music]

Set the default note head style to a diamond-shaped style.

\hide [music] - item (symbol list or music)

Set item’s ‘transparent’ property to #t, making it invisible while still retaining its dimensions.

If item is a symbol list of form GrobName or Context.GrobName, the result is an override for the grob name specified by it. If item is a music expression, the result is the same music expression with an appropriate tweak applied to it.

\incipit [music] - incipit-music (music)

Output incipit-music before the main staff as an indication of its appearance in the original music.

\inherit-acceptability [void] - to (symbol) from (symbol)

When used in an output definition, will modify all context definitions such that context to is accepted as a child by all contexts that also accept from.

\inStaffSegno [music]

Put the segno variant ’varsegno’ at this position into the staff, compatible with the repeat command.

\instrumentSwitch [music] - name (string)

Switch instrument to name, which must have been predefined with function \addInstrumentDefinition.

This function is deprecated.

\inversion [music] - around (pitch) to (pitch) music (music)

Invert music about around and transpose from around to to.

\invertChords [music] - num (integer) music (music)

Invert any chords in music into their num-th position. (Chord inversions may be directed downwards using negative integers.)

\jump [music] - text (markup)

Mark a point of departure, e.g. ‘Gavotte I D.C.’.

\keepWithTag [music] - tags (symbol list or symbol) music (music)

Include only elements of music that are tagged with one of the tags in tags. tags may be either a single symbol or a list of symbols.

Each tag may be declared as a member of at most one tag group (defined with \tagGroup). If none of a music element’s tags share a tag group with one of the specified tags, the element is retained.

\key [music] - tonic [pitch] pitch-alist [list of number pairs]

Set key to tonic and scale pitch-alist. If both are null, just generate KeyChangeEvent.

\killCues [music] - music (music)

Remove cue notes from music.

\label [music] - label (symbol)

Create label as a referrable label.

\language [void] - language (string)

Set note names for language language.

\languageRestore [void]

Restore a previously-saved pitchnames alist.

\languageSaveAndChange [void] - language (string)

Store the previous pitchnames alist, and set a new one.

\magnifyMusic [music] - mag (positive number) music (music)

Magnify the notation of music without changing the staff-size, using mag as a size factor. Stems, beams, slurs, ties, and horizontal spacing are adjusted automatically.

\magnifyStaff [music] - mag (positive number)

Change the size of the staff, adjusting notation size and horizontal spacing automatically, using mag as a size factor.

\makeClusters [music] - arg (music)

Display chords in arg as clusters.

\makeDefaultStringTuning [void] - symbol (symbol) pitches (list)

This defines a string tuning symbol via a list of pitches. The symbol also gets registered in defaultStringTunings for documentation purposes.

\mark [music] - label [index or markup]

Create a rehearsal mark. If label is an integer, create the rehearsal mark for the given sequence number. If label is \default, create the next sequential rehearsal mark. If label is markup, use it for the mark.

\markupMap [music] - path (symbol list or symbol) markupfun (markup-function) music (music)

This applies the given markup function markupfun to all markup music properties matching path in music.

For example,

\new Voice { g'2 c'' }
\addlyrics {
  \markupMap LyricEvent.text
             \markup \with-color #red \etc
             { Oh yes! }
}
\modalInversion [music] - around (pitch) to (pitch) scale (music) music (music)

Invert music about around using scale and transpose from around to to.

\modalTranspose [music] - from (pitch) to (pitch) scale (music) music (music)

Transpose music from pitch from to pitch to using scale.

\musicMap [music] - proc (procedure) mus (music)

Apply proc to mus and all of the music it contains.

\noPageBreak [music]

Forbid a page break. May be used at toplevel (i.e., between scores or markups), or inside a score.

\noPageTurn [music]

Forbid a page turn. May be used at toplevel (i.e., between scores or markups), or inside a score.

\octaveCheck [music] - pitch (pitch)

Octave check.

\offset [music] - property (symbol list or symbol) offsets (any type) item (key list or music)

Offset the default value of property of item by offsets. If item is a string, the result is \override for the specified grob type. If item is a music expression, the result is the same music expression with an appropriate tweak applied.

\omit [music] - item (symbol list or music)

Set item’s ‘stencil’ property to #f, effectively omitting it without taking up space.

If item is a symbol list of form GrobName or Context.GrobName, the result is an override for the grob name specified by it. If item is a music expression, the result is the same music expression with an appropriate tweak applied to it.

\once [music] - music (music)

Set once to #t on all layout instruction events in music. This will complain about music with an actual duration. As a special exception, if music might be the result of a \tweak command, no warning will be given in order to allow for \once \propertyTweak to work as both one-time override and proper tweak.

\ottava [music] - octave (integer)

Set the octavation.

\overrideProperty [music] - grob-property-path (list of indexes or symbols) value (any type)

Set the grob property specified by grob-property-path to value. grob-property-path is a symbol list of the form Context.GrobName.property or GrobName.property, possibly with subproperties given as well.

As opposed to \override which overrides the context-dependent defaults with which a grob is created, this command uses Output_property_engraver at the grob acknowledge stage. This may be necessary for overriding values set after the initial grob creation.

\overrideTimeSignatureSettings [music] - time-signature (fraction, as pair) base-moment (fraction, as 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 [music]

Force a page break. May be used at toplevel (i.e., between scores or markups), or inside a score.

\pageTurn [music]

Force a page turn between two scores or top-level markups.

\palmMute [music] - note (music)

Print note with a triangle-shaped note head.

\palmMuteOn [music]

Set the default note head style to a triangle-shaped style.

\parallelMusic [void] - 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 }

The last bar checks in a sequence are not copied to the result in order to facilitate ending the last entry at non-bar boundaries.

\parenthesize [music] - arg (symbol list or music)

Tag arg to be parenthesized. arg may be either a music event or a grob path.

\partCombine [music] - chord-range [pair of numbers] part1 (music) part2 (music)

Take the music in part1 and part2 and return a music expression containing simultaneous voices, where part1 and part2 are combined into one voice where appropriate. Optional chord-range sets the distance in steps between notes that may be combined into a chord or unison.

\partCombineDown [music] - chord-range [pair of numbers] part1 (music) part2 (music)

Take the music in part1 and part2 and typeset so that they share a staff with stems directed downward.

\partCombineForce [music] - type [symbol]

Override the part-combiner.

\partCombineUp [music] - chord-range [pair of numbers] part1 (music) part2 (music)

Take the music in part1 and part2 and typeset so that they share a staff with stems directed upward.

\partial [music] - dur (duration)

Make a partial measure.

\phrasingSlurDashPattern [music] - 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 for phrasing slurs.

\pitchedTrill [music] - 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 [void]

Suppress generating extra code in final-format (e.g. pdf) files to point back to the lilypond source statement.

\pointAndClickOn [void]

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.

\pointAndClickTypes [void] - types (symbol list or symbol)

Set a type or list of types (such as #'note-event) for which point-and-click info is generated.

\preBend [post event] - mus (music)

Sets the 'style of a BendSpanner to 'pre-bend.

\preBendHold [post event] - mus (music)

Sets the 'style of a BendSpanner to 'pre-bend-hold.

\propertyOverride [music] - grob-property-path (list of indexes or symbols) value (any type)

Set the grob property specified by grob-property-path to value. grob-property-path is a symbol list of the form Context.GrobName.property or GrobName.property, possibly with subproperties given as well. This music function is mostly intended for use from Scheme as a substitute for the built-in \override command.

\propertyRevert [music] - grob-property-path (list of indexes or symbols)

Revert the grob property specified by grob-property-path to its previous value. grob-property-path is a symbol list of the form Context.GrobName.property or GrobName.property, possibly with subproperties given as well. This music function is mostly intended for use from Scheme as a substitute for the built-in \revert command.

\propertySet [music] - property-path (symbol list or symbol) value (any type)

Set the context property specified by property-path to value. This music function is mostly intended for use from Scheme as a substitute for the built-in \set command.

\propertyTweak [music] - prop (key list or symbol) value (any type) item (key list or music)

Add a tweak to the following item, usually music. This generally behaves like \tweak but will turn into an \override when item is a symbol list.

In that case, item specifies the grob path to override. This is mainly useful when using \propertyTweak as as a component for building other functions like \omit. It is not the default behavior for \tweak since many input strings in \lyricmode can serve equally as music or as symbols which causes surprising behavior when tweaking lyrics using the less specific semantics of \propertyTweak.

prop can contain additional elements in which case a nested property (inside of an alist) is tweaked.

\propertyUnset [music] - property-path (symbol list or symbol)

Unset the context property specified by property-path. This music function is mostly intended for use from Scheme as a substitute for the built-in \unset command.

\pushToTag [music] - tag (symbol) more (music) music (music)

Add more to the front of music tagged with tag. A post-event can be added to the articulations of rhythmic events or chords; other expressions may be added to chords, sequential or simultaneous music.

\quoteDuring [music] - 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.

\raiseNote [music] - num (integer) music (music)

Raise a note of any chords in music, in num position from below.

\reduceChords [music] - music (music)

Reduce chords contained in music to single notes, intended mainly for reusing music in RhythmicStaff. Does not reduce parallel music.

\relative [music] - pitch [pitch] music (music)

Make music relative to pitch. If pitch is omitted, the first note in music is given in absolute pitch.

\removeWithTag [music] - tags (symbol list or symbol) music (music)

Remove elements of music that are tagged with one of the tags in tags. tags may be either a single symbol or a list of symbols.

\resetRelativeOctave [music] - pitch (pitch)

Set the octave inside a \relative section.

\retrograde [music] - music (music)

Return music in reverse order.

\revertTimeSignatureSettings [music] - time-signature (pair)

Revert timeSignatureSettings for time signatures of time-signature.

\rightHandFinger [post event] - finger (index or markup)

Apply finger as a fingering indication.

\scaleDurations [music] - fraction (non-negative rational, fraction, or moment) music (music)

Multiply the duration of events in music by fraction.

\sectionLabel [music] - text (markup)

Mark the beginning of a named passage, e.g. “Coda”. This is well suited for use at a section division created with \section, but it does not imply \section and may be used alone.

\segnoMark [music] - num [non-negative, exact integer]

Create a segno mark (or bar line, if the segnoStyle context property is 'bar-line). num may be 1 for the first segno, 2 for the second, etc., or it may be \default to use the next number in sequence automatically.

\settingsFrom (any type) - ctx [symbol] music (music)

Take the layout instruction events from music, optionally restricted to those applying to context type ctx, and return a context modification duplicating their effect.

\shape [music] - offsets (list) item (key list or music)

Offset control-points of item by offsets. The argument is a list of number pairs or list of such lists. Each element of a pair represents an offset to one of the coordinates of a control-point. The y-coordinate of each number pair is scaled by staff space. If item is a string, the result is \once\override for the specified grob type. If item is a music expression, the result is the same music expression with an appropriate tweak applied.

\shiftDurations [music] - dur (integer) dots (integer) arg (music)

Change the duration of arg by adding dur to the durlog of arg and dots to the dots of arg.

\single [music] - overrides (music) music (music)

Convert overrides to tweaks and apply them to music. This does not convert \revert, \set or \unset.

\skip [music] - arg (duration-or-music)

Skip over arg, which may be music or a duration.

\slashedGrace [music] - music (music)

Create slashed graces (slashes through stems, but no slur) from the following music expression

\slurDashPattern [music] - 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 for slurs.

\staffHighlight [music] - color (color)

Start a highlight with the specified color.

\storePredefinedDiagram [void] - 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.

\stringTuning (any type) - chord (music)

Convert chord to a string tuning. chord must be in absolute pitches and should have the highest string number (generally the lowest pitch) first.

\styledNoteHeads [music] - style (symbol) heads (symbol list or symbol) music (music)

Set heads in music to style.

\tabChordRepeats [music] - event-types [list] music (music)

Walk through music putting the notes, fingerings and string numbers of the previous chord into repeat chords, as well as an optional list of event-types such as #'(articulation-event).

\tabChordRepetition [void]

Include the string and fingering information in a chord repetition. This function is deprecated; try using \tabChordRepeats instead.

\tag [music] - tags (symbol list or symbol) music (music)

Tag the following music with tags and return the result, by adding the single symbol or symbol list tags to the tags property of music.

\tagGroup [void] - tags (symbol list)

Define a tag group comprising the symbols in the symbol list tags. Tag groups must not overlap.

\temporary [music] - music (music)

Make any \override in music replace an existing grob property value only temporarily, restoring the old value when a corresponding \revert is executed. This is achieved by clearing the ‘pop-first’ property normally set on \overrides.

An \override/\revert sequence created by using \temporary and \undo on the same music containing overrides will cancel out perfectly or cause a warning.

Non-property-related music is ignored, warnings are generated for any property-changing music that isn’t an \override.

\textEndMark [music] - text (markup)

(undocumented; fixme)

\textMark [music] - text (markup)

(undocumented; fixme)

\tieDashPattern [music] - 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 for ties.

\time [music] - beat-structure [number list] fraction (fraction, as pair)

Set fraction as time signature, with optional number list beat-structure before it.

\times [music] - fraction (fraction, as pair) music (music)

Scale music in time by fraction.

\tocItem [music] - label [symbol list or symbol] text (markup)

Add a line to the table of contents, using the tocItemMarkup paper variable markup and assigning it to label if one is provided. If a hierarchy of labels is given, make the current item a child of the corresponding objects.

\transpose [music] - from (pitch) to (pitch) music (music)

Transpose music from pitch from to pitch to.

\transposedCueDuring [music] - what (string) dir (direction) pitch (pitch) main-music (music)

Insert notes from the part what into a voice called cue, using the transposition defined by pitch. 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 [music] - pitch (pitch)

Set instrument transposition

\tuplet [music] - ratio (fraction, as pair) tuplet-span [duration] music (music)

Scale the given music to tuplets. ratio is a fraction that specifies how many notes are played in place of the nominal value: it will be ‘3/2’ for triplets, namely three notes being played in place of two. If the optional duration tuplet-span is specified, it is used instead of tupletSpannerDuration for grouping the tuplets. For example,

\tuplet 3/2 4 { c8 c c c c c }

will result in two groups of three tuplets, each group lasting for a quarter note.

\tupletSpan [music] - tuplet-span [duration]

Set tupletSpannerDuration, the length into which \tuplet without an explicit ‘tuplet-span’ argument of its own will group its tuplets, to the duration tuplet-span. To revert to the default of not subdividing the contents of a \tuplet command without explicit ‘tuplet-span’, use

\tupletSpan \default
\tweak [music] - prop (key list or symbol) value (any type) music (music)

Add a tweak to the following music. Layout objects created by music get their property prop set to value. If prop has the form ‘Grob.property’, like with

\tweak Accidental.color #red cis'

an indirectly created grob (‘Accidental’ is caused by ‘NoteHead’) can be tweaked; otherwise only directly created grobs are affected.

prop can contain additional elements in which case a nested property (inside of an alist) is tweaked.

If music is an ‘event-chord’, every contained ‘rhythmic-event’ is tweaked instead.

\undo [music] - music (music)

Convert \override and \set in music to \revert and \unset, respectively. Any reverts and unsets already in music cause a warning. Non-property-related music is ignored.

\unfolded [music] - music (music)

Mask music until the innermost enclosing repeat is unfolded.

\unfoldRepeats [music] - types [symbol list or symbol] music (music)

Force \repeat volta, \repeat tremolo or \repeat percent commands in music to be interpreted as \repeat unfold, if specified in the optional symbol-list types. The default for types is an empty list, which will force any of those commands in music to be interpreted as \repeat unfold. Possible entries are volta, tremolo or percent. Multiple entries are possible.

\voices [music] - ids (list of indexes or symbols) music (music)

Take the given key list of numbers (indicating the use of ‘\voiceOne’…) or symbols (indicating voice names, typically converted from strings by argument list processing) and assign the following \\-separated music to contexts according to that list. Named rather than numbered contexts can be used for continuing one voice (for the sake of spanners and lyrics), usually requiring a \voiceOne-style override at the beginning of the passage and a \oneVoice override at its end.

The default

<< … \\ … \\ … >>

construct would correspond to

\voices 1,2,3 << … \\ … \\ … >>
\void [void] - arg (any type)

Accept a scheme argument, return a void expression. Use this if you want to have a scheme expression evaluated because of its side-effects, but its value ignored.

\volta [music] - volta-numbers (number list) music (music)

Mark music as being limited to the volte given in volta-numbers when the innermost enclosing repeat is unfolded. Volta number begins at 1 and increases by 1 with each repetition.

\vshape [music] - offsets (list) item (key list or music)

Like \shape, but additionally show control points for ease of tweaking.

\withMusicProperty [music] - sym (symbol) val (any type) music (music)

Set sym to val in music.

\xNote [music] - note (music)

Print note with a cross-shaped note head.

\= [post event] - id (index or symbol) event (post event)

This sets the spanner-id property of the following event to the given id (non-negative integer or symbol). This can be used to tell LilyPond how to connect overlapping or parallel slurs or phrasing slurs within a single Voice.

\fixed c' { c\=1( d\=2( e\=1) f\=2) }

[image of music]


A.22 Context modification identifiers

The following commands are defined for use as context modifications within a \layout or \with block.

\EnableGregorianDivisiones

Configure division commands such as \section to create Divisio grobs rather than BarLine grobs. This does not affect measure bar lines or the properties of the grobs themselves.

  • Sets translator property caesuraTypeTransform to caesura-to-divisio.
  • Sets translator property doubleRepeatBarType to '().
  • Sets translator property endRepeatBarType to '().
  • Sets translator property fineBarType to "".
  • Sets translator property sectionBarType to "".
  • Sets translator property startRepeatBarType to '().
  • Sets translator property underlyingRepeatBarType to "".
  • Sets translator property doubleRepeatSegnoBarType to "S-||".
  • Sets translator property endRepeatSegnoBarType to "S-||".
  • Sets translator property fineSegnoBarType to "S-||".
  • Sets translator property fineStartRepeatSegnoBarType to "S-||".
  • Sets translator property segnoBarType to "S-||".
  • Sets translator property startRepeatSegnoBarType to "S-||".
\RemoveAllEmptyStaves

Remove staves which are considered to be empty according to the list of interfaces set by keepAliveInterfaces, including those in the first system.

\RemoveEmptyStaves

Remove staves which are considered to be empty according to the list of interfaces set by keepAliveInterfaces.


A.23 Naming conventions

Naming conventions are used so that it is easier to keep the nature of an object in mind.

Object/property typeNaming conventionExamples
Keywordsaaaa\score, \addlyrics
Music functions and shortcutsaaaa or aaaaAaaaAaaa\time, \stemUp
Markup functionsaaaa or aaaa-aaaa-aaaa\bold, \with-dimensions
Paper variablesaaaa or aaaa-aaaa-aaaaindent, page-breaking
Music expressionsAaaa or AaaaAaaaAaaaNoteEvent, SequentialMusic
Music classesaaaa or aaaa-aaaa-aaaanote-event, rhythmic-event
Music propertiesaaaa or aaaa-aaaa-aaaaforce-accidental, iterator-ctor
ContextsAaaa or AaaaAaaaAaaaStaff, GrandStaff
Context propertiesaaaa or aaaaAaaaAaaastanza, instrumentName
EngraversAaaa_engraver or Aaaa_aaaa_aaaa_engraverClef_engraver, Note_heads_engraver
Layout ObjectsAaaa or AaaaAaaaAaaaSlur, NoteHead
Layout Object Propertiesaaa or aaa-aaa-aaadirection, beam-thickness
Interfacesaaa-aaa-interfacegrob-interface, break-aligned-interface
Scheme functions defined in Guileaaaa or aaaa-aaaa-aaaamap, for-each
Scheme functions defined in LilyPondly:aaaa or ly:aaaa-aaaa-aaaa or aaaa or aaaa-aaaa-aaaa 12ly:round-filled-box, music-map

A.24 Predefined type predicates

Predicates return #t when their argument is of the named type and #f if it isn’t.


R5RS primary predicates

Primary predicates can be applied to any expression. They can be used on their own as predicates for LilyPond functions. The predicates here are part of the Scheme standard R5RS.

Type predicateDescription
boolean?boolean
char?character
complex?complex number
eof-object?end-of-file object
input-port?input port
integer?integer
list?list (use cheap-list? for faster processing)
null?null
number?number
output-port?output port
pair?pair
port?port
procedure?procedure
rational?rational number
real?real number
string?string
symbol?symbol
vector?vector

R5RS secondary predicates

Secondary predicates are only applicable to specific expressions (for example, to numbers). They will throw a type error when applied to expressions they are not intended for. The predicates here are part of the Scheme standard R5RS.

Type predicateDescription
char-alphabetic?alphabetic character
char-lower-case?lower-case character
char-numeric?numeric character
char-upper-case?upper-case character
char-whitespace?whitespace character
even?even number
exact?exact number
inexact?inexact number
negative?negative number
odd?odd number
positive?positive number
zero?zero

Guile predicates

These predicates are defined by Guile but are not part of a Scheme standard.

Type predicateDescription
hash-table?hash table

LilyPond scheme predicates

These predicates are only available within LilyPond and defined in Scheme.

Type predicateDescription
alist?association list (list of pairs)
boolean-or-symbol?boolean or symbol
cheap-list?list (use this instead of list? for faster processing)
color?color
exact-rational?an exact rational number
fraction?fraction, as pair
grob-list?list of grobs
index?non-negative, exact integer
index-or-markup?index or markup
key?index or symbol
key-list?list of indexes or symbols
key-list-or-music?key list or music
key-list-or-symbol?key list or symbol
ly:skyline-pair?pair of skylines
markup?markup
markup-command-list?markup command list
markup-list?markup list
moment-pair?pair of moment objects
number-list?number list
number-or-grob?number or grob
number-or-pair?number or pair
number-or-string?number or string
number-pair?pair of numbers
number-pair-list?list of number pairs
rational-or-procedure?an exact rational or procedure
rhythmic-location?rhythmic location
scale?non-negative rational, fraction, or moment
scheme?any type
string-or-music?string or music
string-or-pair?string or pair
string-or-symbol?string or symbol
symbol-key-alist?alist, with symbols as keys
symbol-list?symbol list
symbol-list-or-music?symbol list or music
symbol-list-or-symbol?symbol list or symbol
void?void

LilyPond exported predicates

These predicates are only available within LilyPond and usually defined in C++.

Type predicateDescription
ly:book?book
ly:context?context
ly:context-def?context definition
ly:context-mod?context modification
ly:dimension?dimension, in staff space
ly:dir?direction
ly:dispatcher?dispatcher
ly:duration?duration
ly:event?post event
ly:font-metric?font metric
ly:grob?graphical (layout) object
ly:grob-array?array of grobs
ly:grob-properties?grob properties
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:skyline?skyline
ly:source-file?source file
ly:spanner?spanner
ly:spring?spring
ly:stencil?stencil
ly:stream-event?stream event
ly:transform?coordinate transform
ly:translator?translator
ly:translator-group?translator group
ly:unpure-pure-container?unpure/pure container

B. Cheat sheet

SyntaxDescriptionExample
1 2 8 16durations [image of music]
c4. c4..augmentation dots [image of music]
c d e f g a b scale [image of music]
fis besalteration [image of music]
\clef treble \clef bass clefs [image of music]
\time 3/4 \time 4/4 time signature [image of music]
r4 r8rest [image of music]
d ~ dtie [image of music]
\key es \major key signature [image of music]
note'raise octave [image of music]
note,lower octave [image of music]
c( d e)slur [image of music]
c\( c( d) e\)phrasing slur [image of music]
a8[ b]beam [image of music]
<< \new Staff … >>more staves [image of music]
c-> c-.articulations [image of music]
c2\mf c\sfzdynamics [image of music]
a\< a a\!crescendo [image of music]
a\> a a\!decrescendo [image of music]
< >chord [image of music]
\partial 8pickup / upbeat [image of music]
\tuplet 3/2 {f g a}triplets [image of music]
\gracegrace notes [image of music]
\lyricmode { twinkle }entering lyricstwinkle
\new Lyricsprinting lyrics [image of music]
twin -- klelyric hyphen [image of music]
\chordmode { c:dim f:maj7 }chords [image of music]
\new ChordNamesprinting chord names [image of music]
<<{e f} \\ {c d}>>polyphony [image of music]
s4 s8 s16spacer rests

C. GNU Free Documentation License

Version 1.3, 3 November 2008

 
Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
https://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 https://www.gnu.org/licenses/.

    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.


D. LilyPond command index

This index lists all the LilyPond commands and keywords with links to those sections of the manual that 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   K   L   M   N   O   P   Q   R   S   T   U   V   X  
Index Entry Section

!
!Accidentals

"
"|"Bar and bar number checks

%
%3.2.1 Structure of a score
%3.2.5 File structure
%{ … %}3.2.1 Structure of a score
%{ … %}3.2.5 File structure

'
'Absolute octave entry

(
(Slurs

)
)Slurs

,
,Absolute octave entry

-
-Articulations and ornamentations
-Articulation direction indicators
--A.15 List of articulations
-!A.15 List of articulations
-+Fermata scripts
-.A.15 List of articulations
->A.15 List of articulations
-^A.15 List of articulations
-_A.15 List of articulations

.
.Durations

/
/Extended and altered chords
/+Extended and altered chords

:
:Tremolo repeats

<
<Chorded notes
<...>Chorded notes
<>Chorded notes
<>Changing staff manually

=
=Octave checks

>
>Chorded notes

?
?Accidentals

[
[Manual beams

\
\!Dynamics
\(Phrasing slurs
\)Phrasing slurs
\-2.8.3 Graphical notation
\<Dynamics
\=Slurs
\=A.21 Available music functions
\>Dynamics
\abs-fontsizeSelecting font and font size
\abs-fontsizeA.12.1 Font
\absoluteA.21 Available music functions
\accentArticulations and ornamentations
\accentA.15 List of articulations
\accentusGregorian articulation signs
\accentusRepeat sign scripts
\acceptsContext definition overview
\acceptsContext definition overview
\accepts5.1.7 Context layout order
\acciaccaturaGrace notes
\acciaccaturaA.21 Available music functions
\accidentalA.12.4 Music
\accidentalStyleAutomatic accidentals
\accidentalStyleA.21 Available music functions
\addChordShapePredefined fret diagrams
\addChordShapeA.21 Available music functions
\addInstrumentDefinitionA.21 Available music functions
\addlyricsAligning lyrics to a melody
\addlyricsAutomatic syllable durations
\addlyricsUsing \addlyrics
\addQuoteQuoting other voices
\addQuoteA.21 Available music functions
\aeolianKey signature
\afterDynamics
\afterPercent repeats
\afterA.21 Available music functions
\afterGraceGrace notes
\afterGraceA.21 Available music functions
\aikenHeadsShape note heads
\aikenHeadsMinorShape note heads
\aikenThinHeadsShape note heads
\aikenThinHeadsMinorShape note heads
\aliasContext definition overview
\aliasContext definition overview
\align-on-otherA.12.2 Align
\allowPageTurnPredefined commands
\allowPageTurnA.21 Available music functions
\allowVoltaHookA.21 Available music functions
\alterBrokenModifying broken spanners
\alterBrokenA.21 Available music functions
\alternativeAlternative endings
\alternativeAlternative endings
\ambitusAfterA.21 Available music functions
\appendToTagUsing tags
\appendToTagA.21 Available music functions
\applyContext5.1.2 Creating and referencing contexts
\applyContextA.21 Available music functions
\applyMusicA.21 Available music functions
\applyOutputA.21 Available music functions
\applySwingThe ‘swing’ script
\applySwingWithOffsetThe ‘swing’ script
\appoggiaturaGrace notes
\appoggiaturaA.21 Available music functions
\arabicStringNumbersString number indications
\arpeggioArpeggio
\arpeggioArrowDownArpeggio
\arpeggioArrowUpArpeggio
\arpeggioBracketArpeggio
\arpeggioNormalArpeggio
\arpeggioParenthesisArpeggio
\arpeggioParenthesisDashedArpeggio
\arrow-headGraphic notation inside markup
\arrow-headA.12.3 Graphic
\articulateThe ‘articulate’ script
\ascendensGregorian square neume ligatures
\ascendensPredefined commands
\assertBeamQuantA.21 Available music functions
\assertBeamSlopeA.21 Available music functions
\auctumGregorian square neume ligatures
\auctumPredefined commands
\augmentumPredefined commands
\auto-footnoteA.12.8 Other
\autoBeamOffAutomatic beams
\autoBeamOffSelected Snippets
\autoBeamOnAutomatic beams
\autoBreaksOff4.3.1 Line breaking
\autoBreaksOn4.3.1 Line breaking
\autoChangeChanging staff automatically
\autoChangeA.21 Available music functions
\autoLineBreaksOff4.3.1 Line breaking
\autoLineBreaksOn4.3.1 Line breaking
\autoPageBreaksOffManual page breaking
\autoPageBreaksOnManual page breaking
\backslashed-digitA.12.8 Other
\balloonGrobTextBalloon help
\balloonGrobTextA.21 Available music functions
\balloonLengthOffBalloon help
\balloonLengthOnBalloon help
\balloonTextBalloon help
\balloonTextA.21 Available music functions
\barBar lines
\barBar lines
\barA.21 Available music functions
\barNumberCheckBar and bar number checks
\barNumberCheckA.21 Available music functions
\bassFigureExtendersOffEntering figured bass
\bassFigureExtendersOnEntering figured bass
\bassFigureStaffAlignmentDownDisplaying figured bass
\bassFigureStaffAlignmentNeutralDisplaying figured bass
\bassFigureStaffAlignmentUpDisplaying figured bass
\beamA.12.3 Graphic
\beamExceptionsSetting automatic beam behavior
\beamExceptionsA.21 Available music functions
\bendAfterFalls and doits
\bendAfterA.21 Available music functions
\bendHoldDefault tablatures
\bendHoldA.21 Available music functions
\bendStartLevelDefault tablatures
\bendStartLevelA.21 Available music functions
\blackTriangleMarkupCustomizing chord names
\boldSelecting font and font size
\boldA.12.1 Font
\book3.2.2 Multiple scores in a book
\book3.2.2 Multiple scores in a book
\book3.2.5 File structure
\bookOutputName3.2.4 Output file names
\bookOutputNameA.21 Available music functions
\bookOutputSuffix3.2.4 Output file names
\bookOutputSuffixA.21 Available music functions
\bookpart3.2.2 Multiple scores in a book
\bookpart3.2.5 File structure
\bookpartManual page breaking
\boxGraphic notation inside markup
\boxA.12.1 Font
\bp5.4.2 Distances and measurements
\bracketNew dynamic marks
\bracketGraphic notation inside markup
\bracketA.12.3 Graphic
\break4.3.1 Line breaking
\breatheBreath marks
\breatheA.21 Available music functions
\breveDurations
\breveRests
\cadenzaOffUnmetered music
\cadenzaOnUnmetered music
\caesuraCaesuras
\caesuraSelected Snippets
\caesuraAutomatic bar lines
\caesuraAutomatic bar lines
\caesuraPhrase bar lines in hymn tunes
\caesuraPredefined commands
\caesuraKievan bar lines
\caesuraA.21 Available music functions
\capsA.12.1 Font
\cavumGregorian square neume ligatures
\cavumPredefined commands
\center-alignText alignment
\center-alignA.12.2 Align
\center-columnText alignment
\center-columnA.12.2 Align
\changeChanging staff manually
\charA.12.8 Other
\chordmodeSee also
\chordmodeSee also
\chordmodePredefined fret diagrams
\chordmode Chord mode
\chordRepeatsDefault tablatures
\chordRepeatsA.21 Available music functions
\chordsPrinting chord names
\chords Chord mode
\circleGraphic notation inside markup
\circleA.12.3 Graphic
\circulusGregorian articulation signs
\circulusRepeat sign scripts
\clefClef
\clefA.21 Available music functions
\cm5.4.2 Distances and measurements
\codaArticulations and ornamentations
\codaA.12.4 Music
\codaInstrument-specific scripts
\codaMarkAutomatic bar lines
\codaMarkSegno repeat appearance
\codaMarkManual repeat marks
\codaMarkA.21 Available music functions
\columnText alignment
\columnA.12.2 Align
\column-linesA.13 Text markup list commands
\combineGraphic notation inside markup
\combineA.12.2 Align
\compound-meterA.12.4 Music
\compoundMeter Different time signatures with unequal-length measures
\compoundMeterA.21 Available music functions
\compressEmptyMeasuresCompressing empty measures
\compressMMRestsFull measure rests
\compressMMRestsFull measure rests
\compressMMRestsCompressing empty measures
\compressMMRestsA.21 Available music functions
\concatA.12.2 Align
\consists5.1.4 Modifying context plug-ins
\consistsContext definition overview
\consistsContext definition overview
\context5.1.2 Creating and referencing contexts
\contextChanging all contexts of the same type
\crDynamics
\crescDynamics
\crescHairpinDynamics
\crescTextCrescDynamics
\crossStaffSelected Snippets
\crossStaffA.21 Available music functions
\cueClefFormatting cue notes
\cueClefA.21 Available music functions
\cueClefUnsetFormatting cue notes
\cueClefUnsetA.21 Available music functions
\cueDuringFormatting cue notes
\cueDuringA.21 Available music functions
\cueDuringWithClefFormatting cue notes
\cueDuringWithClefA.21 Available music functions
\customTabClefA.12.4 Music
\dashBangSelected Snippets
\dashDashSelected Snippets
\dashDotSelected Snippets
\dashHatSelected Snippets
\dashLargerSelected Snippets
\dashPlusSelected Snippets
\dashUnderscoreSelected Snippets
\deadNoteSpecial note heads
\deadNoteA.21 Available music functions
\deadNotesOffSpecial note heads
\deadNotesOnSpecial note heads
\decrDynamics
\decrescDynamics
\defaultRehearsal marks
\default Music footnotes overview
\defaultchild5.1.7 Context layout order
\defaultTimeSignatureTime signature
\defineBarLineBar lines
\defineBarLineA.21 Available music functions
\deminutumGregorian square neume ligatures
\deminutumPredefined commands
\deniesContext definition overview
\deniesContext definition overview
\denies5.1.7 Context layout order
\descendensGregorian square neume ligatures
\descendensPredefined commands
\dimDynamics
\dimHairpinDynamics
\dimTextDecrDynamics
\dimTextDecrescDynamics
\dimTextDimDynamics
\dir-columnA.12.2 Align
\discantA.12.7 Accordion Registers
\displayLilyMusic3.7.1 Displaying LilyPond notation
\displayLilyMusicA.21 Available music functions
\displayMusicA.21 Available music functions
\displaySchemeA.21 Available music functions
\divisioMaiorPredefined commands
\divisioMaximaPredefined commands
\divisioMinimaPredefined commands
\dorianKey signature
\dotsDownDurations
\dotsNeutralDurations
\dotsUpDurations
\doubleflatA.12.4 Music
\doublesharpA.12.4 Music
\downbowArticulations and ornamentations
\downbowBowing indications
\downbowFermata scripts
\downmordentArticulations and ornamentations
\downmordentArticulation scripts
\downprallArticulations and ornamentations
\downprallArticulation scripts
\draw-circleGraphic notation inside markup
\draw-circleA.12.3 Graphic
\draw-dashed-lineA.12.3 Graphic
\draw-dotted-lineA.12.3 Graphic
\draw-hlineA.12.3 Graphic
\draw-lineGraphic notation inside markup
\draw-lineA.12.3 Graphic
\draw-squiggle-lineA.12.3 Graphic
\dropNoteChord inversions and specific voicings
\dropNoteA.21 Available music functions
\drummodeInstantiating new staves
\drummodeBasic percussion notation
\drummode Drum mode
\drumsBasic percussion notation
\drums Drum mode
\dwnArabic note names
\dynamicNew dynamic marks
\dynamicA.12.1 Font
\dynamicDownDynamics
\dynamicNeutralDynamics
\dynamicUpDynamics
\easyHeadsOffEasy notation note heads
\easyHeadsOnEasy notation note heads
\ellipseA.12.3 Graphic
\EnableGregorianDivisionesA.22 Context modification identifiers
\enablePolymeterA.21 Available music functions
\endcrDynamics
\enddecrDynamics
\endSpanners5.4.6 Line spanners
\endSpannersA.21 Available music functions
\episemFinisGregorian articulation signs
\episemInitiumGregorian articulation signs
\epsfileGraphic notation inside markup
\epsfileA.12.3 Graphic
\espressivoArticulations and ornamentations
\espressivoDynamics
\espressivoA.15 List of articulations
\etcText markup introduction
\etc3.4.3.2 Substitution function examples
\eventChordsA.21 Available music functions
\expandEmptyMeasuresCompressing empty measures
\eyeglassesA.12.8 Other
\fDynamics
\featherDurationsFeathered beams
\featherDurationsA.21 Available music functions
\fermataSelected Snippets
\fermataArticulations and ornamentations
\fermataA.12.4 Music
\fermataOrnament scripts
\ffDynamics
\fffDynamics
\ffffDynamics
\fffffDynamics
\figured-bassA.12.1 Font
\figuremodeIntroduction to figured bass
\figuremode Figure mode
\figuresIntroduction to figured bass
\figures Figure mode
\fill-lineText alignment
\fill-lineA.12.2 Align
\fill-with-pattern3.3.6 Table of contents
\fill-with-patternA.12.2 Align
\filled-boxGraphic notation inside markup
\filled-boxA.12.3 Graphic
\finalisPredefined commands
\fineAutomatic bar lines
\fineSection divisions
\fineAl-fine repeats
\fineSegno repeat structure
\fineKievan bar lines
\fingerFingering instructions
\fingerA.12.1 Font
\fingerA.21 Available music functions
\first-visibleA.12.8 Other
\fixedAbsolute octave entry
\fixedA.21 Available music functions
\flageoletArticulations and ornamentations
\flageoletFermata scripts
\flatA.12.4 Music
\flexaPredefined commands
\fontCapsA.12.1 Font
\fontsizeSelecting font and font size
\fontsizeA.12.1 Font
\footnoteFootnotes in music expressions
\footnoteA.12.8 Other
\footnoteA.21 Available music functions
\fpDynamics
\fractionA.12.8 Other
\freeBassA.12.7 Accordion Registers
\frenchChordsCustomizing chord names
\fret-diagramFret diagram markups
\fret-diagramA.12.6 Instrument Specific Markup
\fret-diagram-terseFret diagram markups
\fret-diagram-terseA.12.6 Instrument Specific Markup
\fret-diagram-verboseFret diagram markups
\fret-diagram-verboseA.12.6 Instrument Specific Markup
\frompropertyA.12.8 Other
\funkHeadsShape note heads
\funkHeadsMinorShape note heads
\general-alignText alignment
\general-alignA.12.2 Align
\germanChordsCustomizing chord names
\glideGliding fingers
\glissandoGlissando
\glissandoMapGlissando
\graceGrace notes
\graceA.21 Available music functions
\grobdescriptionsA.21 Available music functions
\halfopenArticulations and ornamentations
\halfopenCustom percussion staves
\halfopenFermata scripts
\halignText alignment
\halignA.12.2 Align
\harmonicSpecial note heads
\harmonicHarmonics
\harmonicDefault tablatures
\harmonicByFretDefault tablatures
\harmonicByFretA.21 Available music functions
\harmonicByRatioDefault tablatures
\harmonicByRatioA.21 Available music functions
\harmonicNoteA.21 Available music functions
\harmonicsOffHarmonics
\harmonicsOnHarmonics
\harmonicsOnA.21 Available music functions
\harp-pedalA.12.6 Instrument Specific Markup
\haydnturnArticulations and ornamentations
\haydnturnArticulation scripts
\hbracketGraphic notation inside markup
\hbracketA.12.3 Graphic
\hcenter-inA.12.2 Align
\header3.2.5 File structure
\henzelongfermataArticulations and ornamentations
\henzelongfermataOrnament scripts
\henzeshortfermataArticulations and ornamentations
\henzeshortfermataOrnament scripts
\hideMaking objects transparent
\hideA.21 Available music functions
\hideKeySignatureBagpipe definitions
\hideNotesHidden notes
\hideSplitTiedTabNotesDefault tablatures
\hideStaffSwitchStaff-change lines
\hspaceText alignment
\hspaceA.12.2 Align
\hugeSelecting notation font size
\hugeSelecting font and font size
\hugeA.12.1 Font
\ictusGregorian articulation signs
\ictusRepeat sign scripts
\ifCustom layout for headers and footers
\ifA.12.5 Conditionals
\IIJ Special signs
\iij Special signs
\ij Special signs
\IJ Special signs
\improvisationOffImprovisation
\improvisationOffShowing melody rhythms
\improvisationOnImprovisation
\improvisationOnShowing melody rhythms
\in5.4.2 Distances and measurements
\incipitIncipits
\incipitA.21 Available music functions
\inclinatumGregorian square neume ligatures
\inclinatumPredefined commands
\include3.2.5 File structure
\include3.4.1 Including LilyPond files
\inherit-acceptabilityContext definition overview
\inherit-acceptabilityA.21 Available music functions
\inStaffSegnoAutomatic bar lines
\inStaffSegnoAutomatic bar lines
\inStaffSegnoManual repeat marks
\inStaffSegnoA.21 Available music functions
\instrumentSwitchA.21 Available music functions
\inversionInversion
\inversionA.21 Available music functions
\invertChordsChord inversions and specific voicings
\invertChordsA.21 Available music functions
\ionianKey signature
\italianChordsCustomizing chord names
\italicSelecting font and font size
\italicA.12.1 Font
\jumpManual repeat marks
\jumpA.21 Available music functions
\justified-linesText markup introduction
\justified-linesA.13 Text markup list commands
\justifyText alignment
\justifyA.12.2 Align
\justify-fieldA.12.2 Align
\justify-lineA.12.2 Align
\justify-stringA.12.2 Align
\keepWithTagUsing tags
\keepWithTagA.21 Available music functions
\keyKey signature
\keyShape note heads
\keyA.21 Available music functions
\kievanOffKievan notes
\kievanOnKievan notes
\killCuesFormatting cue notes
\killCuesA.21 Available music functions
\labelPredefined commands
\labelA.21 Available music functions
\laissezVibrerTies
\languageA.21 Available music functions
\languageRestoreA.21 Available music functions
\languageSaveAndChangeA.21 Available music functions
\largeSelecting notation font size
\largeSelecting font and font size
\largeA.12.1 Font
\largerSelecting font and font size
\largerSelecting font and font size
\largerA.12.1 Font
\layout3.2.5 File structure
\layout4.2.1 The \layout block
\layoutOutput definitions – blueprints for contexts
\layoutChanging all contexts of the same type
\left-alignText alignment
\left-alignA.12.2 Align
\left-braceA.12.8 Other
\left-columnA.12.2 Align
\lheelArticulations and ornamentations
\lheelFermata scripts
\lineA.12.2 Align
\lineaGregorian square neume ligatures
\lineaPredefined commands
\lineprallArticulations and ornamentations
\lineprallArticulation scripts
\locrianKey signature
\longaDurations
\longaRests
\longfermataArticulations and ornamentations
\longfermataOrnament scripts
\lookupA.12.8 Other
\lowerText alignment
\lowerA.12.2 Align
\ltoeArticulations and ornamentations
\ltoeFermata scripts
\lydianKey signature
\lyricmodeEntering lyrics
\lyricmodeAligning lyrics to a melody
\lyricmode Lyrics mode
\lyrics Lyrics mode
\lyricstoAligning lyrics to a melody
\lyricstoAutomatic syllable durations
\lyricstoUsing \lyricsto
\magnifySelecting font and font size
\magnifyA.12.1 Font
\magnifyMusicSelecting notation font size
\magnifyMusicA.21 Available music functions
\magnifyStaff4.2.2 Setting the staff size
\magnifyStaffA.21 Available music functions
\majorKey signature
\makeClustersClusters
\makeClustersA.21 Available music functions
\makeDefaultStringTuningA.21 Available music functions
\map-commandsA.13 Text markup list commands
\marcatoArticulations and ornamentations
\marcatoA.15 List of articulations
\markRehearsal marks
\markText marks
\markA.21 Available music functions
\markalphabetA.12.8 Other
\markLengthOffMetronome marks
\markLengthOffText marks
\markLengthOnMetronome marks
\markLengthOnText marks
\markletterA.12.8 Other
\markupText objects overview
\markupText marks
\markupSeparate text
\markupSeparate text
\markupText markup introduction
\markup Markup mode
\markuplistSeparate text
\markuplistText markup introduction
\markupMapA.21 Available music functions
\maximaDurations
\maximaRests
\mediumA.12.1 Font
\melismaMultiple notes to one syllable
\melismaEndMultiple notes to one syllable
\mergeDifferentlyDottedOffCollision resolution
\mergeDifferentlyDottedOnCollision resolution
\mergeDifferentlyHeadedOffCollision resolution
\mergeDifferentlyHeadedOnCollision resolution
\mfDynamics
\midi3.2.5 File structure
\midiOutput definitions – blueprints for contexts
\minorKey signature
\mixolydianKey signature
\mm5.4.2 Distances and measurements
\modalInversion Modal inversion
\modalInversionA.21 Available music functions
\modalTranspose Modal transposition
\modalTransposeA.21 Available music functions
\mordentArticulations and ornamentations
\mordentArticulation scripts
\mpDynamics
\multi-measure-rest-by-numberA.12.4 Music
\musicglyphA.12.4 Music
\musicMapA.21 Available music functions
\nDynamics
\nameContext definition overview
\nameContext definition overview
\naturalA.12.4 Music
\new5.1.2 Creating and referencing contexts
\newSpacingSection4.5.2 New spacing section
\noBeamManual beams
\noBreak4.3.1 Line breaking
\noPageBreakManual page breaking
\noPageBreakA.21 Available music functions
\noPageTurnPredefined commands
\noPageTurnA.21 Available music functions
\normal-size-subA.12.1 Font
\normal-size-superSelecting font and font size
\normal-size-superA.12.1 Font
\normal-textA.12.1 Font
\normalsizeSelecting notation font size
\normalsizeSelecting font and font size
\normalsizeA.12.1 Font
\noteA.12.4 Music
\note-by-numberA.12.4 Music
\notemode Note mode
\nullText alignment
\nullA.12.8 Other
\numberA.12.1 Font
\numericTimeSignatureTime signature
\octaveCheckOctave checks
\octaveCheckA.21 Available music functions
\offset5.3.6 The \offset command
\offsetA.21 Available music functions
\omitRemoving the stencil
\omitA.21 Available music functions
\on-the-flyA.12.8 Other
\once5.3.2 The \set command
\once5.3.3 The \override command
\once \offset as an override
\onceModifying broken spanners
\onceA.21 Available music functions
\oneVoiceSingle-staff polyphony
\openArticulations and ornamentations
\openBowing indications
\openSelected Snippets
\openFermata scripts
\oriscusGregorian square neume ligatures
\oriscusPredefined commands
\ottavaOttava brackets
\ottavaA.21 Available music functions
\ovalA.12.3 Graphic
\overlayA.12.2 Align
\override5.3.3 The \override command
\override5.3.5 \set vs. \override
\overrideA.12.8 Other
\override-linesA.13 Text markup list commands
\overrideProperty5.3.5 \set vs. \override
\overridePropertyA.21 Available music functions
\overrideTimeSignatureSettingsTime signature
\overrideTimeSignatureSettingsA.21 Available music functions
\overtieA.12.1 Font
\pDynamics
\padA.12.2 Align
\pad-aroundGraphic notation inside markup
\pad-aroundA.12.2 Align
\pad-markupGraphic notation inside markup
\pad-to-boxGraphic notation inside markup
\pad-to-boxA.12.2 Align
\pad-xGraphic notation inside markup
\pad-xA.12.2 Align
\page-linkA.12.8 Other
\page-refPredefined commands
\page-refA.12.8 Other
\pageBreakManual page breaking
\pageBreakA.21 Available music functions
\pageTurnPredefined commands
\pageTurnA.21 Available music functions
\palmMuteA.21 Available music functions
\palmMuteOnA.21 Available music functions
\paper3.2.5 File structure
\paper4.1.2 Paper size and automatic scaling
\parallelMusicWriting music in parallel
\parallelMusicA.21 Available music functions
\parenthesizeParentheses
\parenthesizeA.12.3 Graphic
\parenthesizeA.21 Available music functions
\partCombineAutomatic part combining
\partCombinePolyphony with shared lyrics
\partCombineA.21 Available music functions
\partCombineApartAutomatic part combining
\partCombineAutomaticAutomatic part combining
\partCombineChordsAutomatic part combining
\partCombineDownA.21 Available music functions
\partCombineForceA.21 Available music functions
\partCombineSoloIAutomatic part combining
\partCombineSoloIIAutomatic part combining
\partCombineUnisonoAutomatic part combining
\partCombineUpA.21 Available music functions
\partialUpbeats
\partialSimple repeats
\partialA.21 Available music functions
\pathA.12.3 Graphic
\patternA.12.8 Other
\pesPredefined commands
\phrasingSlurDashedPhrasing slurs
\phrasingSlurDashPatternPhrasing slurs
\phrasingSlurDashPatternA.21 Available music functions
\phrasingSlurDottedPhrasing slurs
\phrasingSlurDownPhrasing slurs
\phrasingSlurHalfDashedPhrasing slurs
\phrasingSlurHalfSolidPhrasing slurs
\phrasingSlurNeutralPhrasing slurs
\phrasingSlurSolidPhrasing slurs
\phrasingSlurUpPhrasing slurs
\phrygianKey signature
\pitchedTrillTrills
\pitchedTrillA.21 Available music functions
\pointAndClickOffA.21 Available music functions
\pointAndClickOnA.21 Available music functions
\pointAndClickTypesA.21 Available music functions
\polygonA.12.3 Graphic
\portatoArticulations and ornamentations
\portatoA.15 List of articulations
\postscriptGraphic notation inside markup
\postscriptA.12.3 Graphic
\ppDynamics
\pppDynamics
\ppppDynamics
\pppppDynamics
\prallArticulations and ornamentations
\prallArticulation scripts
\pralldownArticulations and ornamentations
\pralldownArticulation scripts
\prallmordentArticulations and ornamentations
\prallmordentArticulation scripts
\prallprallArticulations and ornamentations
\prallprallArticulation scripts
\prallupArticulations and ornamentations
\prallupArticulation scripts
\preBendDefault tablatures
\preBendA.21 Available music functions
\preBendHoldDefault tablatures
\preBendHoldA.21 Available music functions
\predefinedFretboardsOffAutomatic fret diagrams
\predefinedFretboardsOnAutomatic fret diagrams
\property-recursiveA.12.8 Other
\propertyOverrideA.21 Available music functions
\propertyRevertA.21 Available music functions
\propertySetA.21 Available music functions
\propertyTweakA.21 Available music functions
\propertyUnsetA.21 Available music functions
\pt5.4.2 Distances and measurements
\pushToTagUsing tags
\pushToTagA.21 Available music functions
\put-adjacentA.12.2 Align
\quilismaGregorian square neume ligatures
\quilismaPredefined commands
\quoteDuringQuoting other voices
\quoteDuringFormatting cue notes
\quoteDuringA.21 Available music functions
\raiseText alignment
\raiseA.12.2 Align
\raiseNoteChord inversions and specific voicings
\raiseNoteA.21 Available music functions
\reduceChordsShowing melody rhythms
\reduceChordsA.21 Available music functions
\relativeRelative octave entry
\relativeSee also
\relativeSee also
\relativeChanging staff automatically
\relativeA.21 Available music functions
\remove5.1.4 Modifying context plug-ins
\RemoveAllEmptyStavesHiding staves
\RemoveAllEmptyStavesA.22 Context modification identifiers
\RemoveEmptyStavesHiding staves
\RemoveEmptyStavesA.22 Context modification identifiers
\removeWithTagUsing tags
\removeWithTagA.21 Available music functions
\repeat1.4.1 Long repeats
\repeatSee also
\repeatAlternative endings
\repeat percentPercent repeats
\repeat segnoAutomatic bar lines
\repeat segnoAutomatic bar lines
\repeat segnoSegno repeat structure
\repeat tremoloTremolo repeats
\repeat unfold1.4.1 Long repeats
\repeat voltaAutomatic bar lines
\repeat voltaAutomatic bar lines
\repeat voltaSee also
\repeat voltaAlternative endings
\repeatTieTies
\repeatTieRepeats with alternative endings
\replaceA.12.1 Font
\resetRelativeOctaveRelative octave entry
\resetRelativeOctaveA.21 Available music functions
\responsum Special signs
\restRests
\restA.12.4 Music
\rest-by-numberA.12.4 Music
\retrogradeRetrograde
\retrogradeA.21 Available music functions
\reverseturnArticulations and ornamentations
\reverseturnArticulation scripts
\revert5.3.3 The \override command
\revertTimeSignatureSettingsTime signature
\revertTimeSignatureSettingsA.21 Available music functions
\rfzDynamics
\rheelArticulations and ornamentations
\rheelFermata scripts
\rhythmA.12.4 Music
\right-alignText alignment
\right-alignA.12.2 Align
\right-braceA.12.8 Other
\right-columnA.12.2 Align
\rightHandFingerRight-hand fingerings
\rightHandFingerA.21 Available music functions
\romanA.12.1 Font
\romanStringNumbersBowing indications
\romanStringNumbersString number indications
\rotateA.12.2 Align
\rounded-boxGraphic notation inside markup
\rounded-boxA.12.3 Graphic
\rtoeArticulations and ornamentations
\rtoeFermata scripts
\sacredHarpHeadsShape note heads
\sacredHarpHeadsMinorShape note heads
\sansA.12.1 Font
\scaleA.12.3 Graphic
\scaleDurationsScaling durations
\scaleDurationsPolymetric notation
\scaleDurationsA.21 Available music functions
\score3.2.1 Structure of a score
\score3.2.5 File structure
\scoreA.12.4 Music
\score-linesA.13 Text markup list commands
\sectionAutomatic bar lines
\sectionSection divisions
\sectionKievan bar lines
\sectionLabelSegno repeat structure
\sectionLabelSection labels
\sectionLabelA.21 Available music functions
\segnoArticulations and ornamentations
\segnoA.12.4 Music
\segnoInstrument-specific scripts
\segnoMarkAutomatic bar lines
\segnoMarkAutomatic bar lines
\segnoMarkSegno repeat appearance
\segnoMarkManual repeat marks
\segnoMarkA.21 Available music functions
\semicirculusGregorian articulation signs
\semicirculusRepeat sign scripts
\semiflatA.12.4 Music
\semiGermanChordsCustomizing chord names
\semisharpA.12.4 Music
\sesquiflatA.12.4 Music
\sesquisharpA.12.4 Music
\setSetting automatic beam behavior
\set5.3.2 The \set command
\set5.3.5 \set vs. \override
\settingsFromA.21 Available music functions
\sfDynamics
\sffDynamics
\sfzDynamics
\shape Specifying displacements from current control points
\shapeA.21 Available music functions
\sharpA.12.4 Music
\shiftDurationsA.21 Available music functions
\shiftOffCollision resolution
\shiftOnCollision resolution
\shiftOnnCollision resolution
\shiftOnnnCollision resolution
\shortfermataArticulations and ornamentations
\shortfermataOrnament scripts
\showKeySignatureBagpipe definitions
\showStaffSwitchStaff-change lines
\signumcongruentiaeArticulations and ornamentations
\signumcongruentiaeRepeat sign scripts
\simpleA.12.1 Font
\single Time-based footnotes
\single \offset as an override
\singleA.21 Available music functions
\skipInvisible rests
\skipRepeats with alternative endings
\skipA.21 Available music functions
\slashed-digitA.12.8 Other
\slashedGraceGrace notes
\slashedGraceA.21 Available music functions
\slashSeparator\paper variables concerning headers and markups
\slashturnArticulations and ornamentations
\slashturnArticulation scripts
\slurDashedSlurs
\slurDashPatternSlurs
\slurDashPatternA.21 Available music functions
\slurDottedSlurs
\slurDownSlurs
\slurHalfDashedSlurs
\slurHalfSolidSlurs
\slurNeutralSlurs
\slurSolidSlurs
\slurUpSlurs
\smallSelecting notation font size
\smallSelecting font and font size
\smallA.12.1 Font
\smallCapsA.12.1 Font
\smallerSelecting font and font size
\smallerSelecting font and font size
\smallerA.12.1 Font
\snappizzicatoArticulations and ornamentations
\snappizzicatoFermata scripts
\sostenutoOffPiano pedals
\sostenutoOnPiano pedals
\sourcefileline3.2.5 File structure
\sourcefilename3.2.5 File structure
\southernHarmonyHeadsShape note heads
\southernHarmonyHeadsMinorShape note heads
\spDynamics
\sppDynamics
\staccatissimoArticulations and ornamentations
\staccatissimoA.15 List of articulations
\staccatoArticulations and ornamentations
\staccatoA.15 List of articulations
\staff-space5.4.2 Distances and measurements
\staffHighlightStaff highlights
\staffHighlightA.21 Available music functions
\startGroupAnalysis brackets
\startStaffStaff symbol
\startStaffOssia staves
\startTrillSpanTrills
\stdBassA.12.7 Accordion Registers
\stdBassIVA.12.7 Accordion Registers
\stdBassVA.12.7 Accordion Registers
\stdBassVIA.12.7 Accordion Registers
\stemDownStems
\stemNeutralStems
\stemUpStems
\stencilA.12.8 Other
\stopGroupAnalysis brackets
\stoppedArticulations and ornamentations
\stoppedCustom percussion staves
\stoppedSelected Snippets
\stoppedFermata scripts
\stopStaffStaff symbol
\stopStaffOssia staves
\stopStaffHiding staves
\stopStaffHighlightStaff highlights
\stopTrillSpanTrills
\storePredefinedDiagramPredefined fret diagrams
\storePredefinedDiagramChordChanges for FretBoards
\storePredefinedDiagramA.21 Available music functions
\string-linesA.13 Text markup list commands
\stringTuningCustom tablatures
\stringTuningA.21 Available music functions
\strophaGregorian square neume ligatures
\strophaPredefined commands
\strutA.12.8 Other
\styledNoteHeadsA.21 Available music functions
\subSelecting font and font size
\subA.12.1 Font
\superSelecting font and font size
\superA.12.1 Font
\sustainOffPiano pedals
\sustainOnPiano pedals
\tabChordRepeatsDefault tablatures
\tabChordRepeatsA.21 Available music functions
\tabChordRepetitionA.21 Available music functions
\tabFullNotationDefault tablatures
\tableA.13 Text markup list commands
\table-of-contentsPredefined commands
\table-of-contentsA.13 Text markup list commands
\tagUsing tags
\tagA.21 Available music functions
\tagGroupUsing tags
\tagGroupA.21 Available music functions
\taorBagpipe definitions
\teenySelecting notation font size
\teenySelecting font and font size
\teenyA.12.1 Font
\tempoMetronome marks
\temporary \offset as an override
\temporaryModifying broken spanners
\temporaryA.21 Available music functions
\tenutoArticulations and ornamentations
\tenutoA.15 List of articulations
\textA.12.1 Font
\textEndMarkText marks
\textEndMarkA.21 Available music functions
\textLengthOffFull measure rests
\textLengthOffPositioning multi-measure rests
\textLengthOffText scripts
\textLengthOnFull measure rests
\textLengthOnPositioning multi-measure rests
\textLengthOnPrinting hairpins in various styles
\textLengthOnText scripts
\textMarkText marks
\textMarkA.21 Available music functions
\textSpannerDownText spanners
\textSpannerNeutralText spanners
\textSpannerUpText spanners
\thumbArticulations and ornamentations
\thumbFingering instructions
\tieA.12.1 Font
\tied-lyricA.12.4 Music
\tieDashedTies
\tieDashPatternTies
\tieDashPatternA.21 Available music functions
\tieDottedTies
\tieDownTies
\tieHalfDashedTies
\tieHalfSolidTies
\tieNeutralTies
\tieSolidTies
\tieUpTies
\timeTime signature
\timeSetting automatic beam behavior
\timeA.21 Available music functions
\timesA.21 Available music functions
\tinySelecting notation font size
\tinySelecting font and font size
\tinyA.12.1 Font
\tocItemPredefined commands
\tocItemA.21 Available music functions
\tocItemWithDotsMarkup3.3.6 Table of contents
\translateText alignment
\translateA.12.2 Align
\translate-scaledText alignment
\translate-scaledA.12.2 Align
\transparentA.12.8 Other
\transposeSee also
\transposeTranspose
\transposeSee also
\transposeA.21 Available music functions
\transposedCueDuringFormatting cue notes
\transposedCueDuringA.21 Available music functions
\transpositionInstrument transpositions
\transpositionQuoting other voices
\transpositionA.21 Available music functions
\treCordePiano pedals
\triangleGraphic notation inside markup
\triangleA.12.3 Graphic
\trillArticulations and ornamentations
\trillTrills
\trillArticulation scripts
\tripletFeelThe ‘swing’ script
\tupletTuplets
\tupletPolymetric notation
\tupletA.21 Available music functions
\tupletDownTuplets
\tupletNeutralTuplets
\tupletSpanSelected Snippets
\tupletSpanA.21 Available music functions
\tupletUpTuplets
\turnArticulations and ornamentations
\turnArticulation scripts
\tweak5.3.4 The \tweak command
\tweak5.3.5 \set vs. \override
\tweakA.21 Available music functions
\typeContext definition overview
\typeContext definition overview
\typewriterA.12.1 Font
\unaCordaPiano pedals
\underlineSelecting font and font size
\underlineA.12.1 Font
\undertieA.12.1 Font
\undo \offset as an override
\undoA.21 Available music functions
\unfoldedAlternative endings
\unfoldedA.21 Available music functions
\unfoldRepeatsAlternative endings
\unfoldRepeats3.6.6 Using repeats with MIDI
\unfoldRepeatsA.21 Available music functions
\unHideNotesHidden notes
\unlessCustom layout for headers and footers
\unlessA.12.5 Conditionals
\unset5.3.2 The \set command
\upbowArticulations and ornamentations
\upbowBowing indications
\upbowFermata scripts
\upmordentArticulations and ornamentations
\upmordentArticulation scripts
\upprallArticulations and ornamentations
\upprallArticulation scripts
\uprightA.12.1 Font
\varcodaArticulations and ornamentations
\varcodaA.12.4 Music
\varcodaInstrument-specific scripts
\vcenterA.12.2 Align
\verbatim-fileA.12.8 Other
\version3.2.5 File structure
\versus Special signs
\verylongfermataArticulations and ornamentations
\verylongfermataOrnament scripts
\veryshortfermataArticulations and ornamentations
\veryshortfermataOrnament scripts
\virgaGregorian square neume ligatures
\virgaPredefined commands
\virgulaPredefined commands
\voiceFourSingle-staff polyphony
\voiceFourStyleVoice styles
\voiceNeutralStyleVoice styles
\voiceOneSingle-staff polyphony
\voiceOneStyleVoice styles
\voices Voice order
\voicesA.21 Available music functions
\voiceThreeSingle-staff polyphony
\voiceThreeStyleVoice styles
\voiceTwoSingle-staff polyphony
\voiceTwoStyleVoice styles
\void3.7.1 Displaying LilyPond notation
\voidA.21 Available music functions
\voltaAlternative endings
\voltaAlternative endings
\voltaA.21 Available music functions
\vshapeA.21 Available music functions
\vspaceText alignment
\vspaceA.12.2 Align
\walkerHeadsShape note heads
\walkerHeadsMinorShape note heads
\whiteoutA.12.8 Other
\whiteTriangleMarkupCustomizing chord names
\with5.1.4 Modifying context plug-ins
\withChanging just one specific context
\with-colorColoring objects
\with-colorA.12.8 Other
\with-dimensionA.12.8 Other
\with-dimension-fromA.12.8 Other
\with-dimensionsA.12.8 Other
\with-dimensions-fromA.12.8 Other
\with-linkA.12.8 Other
\with-outlineA.12.8 Other
\with-string-transformerA.12.1 Font
\with-true-dimensionA.12.8 Other
\with-true-dimensionsA.12.8 Other
\with-urlA.12.3 Graphic
\withMusicPropertyA.21 Available music functions
\woodwind-diagramA.12.6 Instrument Specific Markup
\wordwrapText alignment
\wordwrapA.12.2 Align
\wordwrap-fieldA.12.2 Align
\wordwrap-internalA.13 Text markup list commands
\wordwrap-linesText markup introduction
\wordwrap-linesA.13 Text markup list commands
\wordwrap-stringA.12.2 Align
\wordwrap-string-internalA.13 Text markup list commands
\xNoteSpecial note heads
\xNoteA.21 Available music functions
\xNotesOffSpecial note heads
\xNotesOnSpecial note heads
\[Ligatures
\]Ligatures

]
]Manual beams

^
^Extended and altered chords
^Articulation direction indicators

_
_Multiple syllables to one note
_Articulation direction indicators

|
|Bar and bar number checks
|Bar and bar number checks

~
~Ties

A
AccidentalSuggestionControlling the vertical ordering of scripts
add-grace-propertyUsing grace note slashes with normal heads
add-stem-supportControlling the placement of chord fingerings
add-toc-item!3.3.6 Table of contents
additionalPitchPrefixCustomizing chord names
afterGraceFractionparser variable
alignAboveContextSelected Snippets
alignAboveContext5.1.7 Context layout order
alignBelowContextSelected Snippets
alignBelowContextSimple repeats
alignBelowContext5.1.7 Context layout order
ambitusAfterChanging the ambitus gap
AmbitusLineAmbitus with multiple voices
annotate-spacing4.6.1 Displaying spacing
arpeggio-directionArpeggio
articulation-eventQuoting other voices
associatedVoiceAligning lyrics to a melody
associatedVoiceAutomatic syllable durations
associatedVoiceSwitching to an alternative melody
augCommon chords
auto-first-page-number\paper variables for page numbering
autoBeamingSetting automatic beam behavior
autoBeamingOutput definitions – blueprints for contexts

B
Balloon_engraverBalloon help
banjo-c-tuningBanjo tablatures
banjo-double-c-tuningBanjo tablatures
banjo-double-d-tuningBanjo tablatures
banjo-modal-tuningBanjo tablatures
banjo-open-d-tuningBanjo tablatures
banjo-open-dm-tuningBanjo tablatures
banjo-open-g-tuningBanjo tablatures
barCheckSynchronizeBar and bar number checks
BarNumberBar numbers
barNumberVisibilityBar numbers
bartypeBar lines
base-shortest-duration4.5.1 Horizontal spacing overview
baseMomentSetting automatic beam behavior
baseMomentSelected Snippets
beatStructureSetting automatic beam behavior
beatStructureSelected Snippets
binding-offset\paper variables for two-sided mode
blank-after-score-page-penalty\paper variables for page breaking
blank-last-page-penalty\paper variables for page breaking
blank-page-penalty\paper variables for page breaking
bookpart-level-page-numbering\paper variables for page numbering
bookTitleMarkupCustom layout for titles
bottom-margin4.1.3 Fixed vertical spacing \paper variables
bracketPiano pedals
break-align-symbolsUsing the break-alignable-interface
break-visibilityUsing break-visibility
breakablePredefined commands
breakbeforeDefault layout of bookpart and score titles

C
check-consistency\paper variables for widths and margins
choralAutomatic accidentals
choral-cautionaryAutomatic accidentals
chordChangesDefining predefined fretboards for other instruments
chordChangesSelected Snippets
ChordGridChord grids
chordNameExceptionsCustomizing chord names
chordNameExceptionsSelected Snippets
chordNameLowercaseMinorCustomizing chord names
ChordNamesPredefined fret diagrams
chordNameSeparatorCustomizing chord names
chordNameSeparatorVolta below chords
chordNoteNamerCustomizing chord names
chordPrefixSpacerCustomizing chord names
chordRootNamerCustomizing chord names
clip-regions3.5 Controlling output
colorColoring objects
common-shortest-duration4.5.1 Horizontal spacing overview
Completion_heads_engraverAutomatic note splitting
Completion_rest_engraverAutomatic note splitting
context-spec-musicSelected Snippets
controlpitchOctave checks
countPercentRepeatsSelected Snippets
crescendo-eventQuoting other voices
crescendoSpannerHiding the extender line for text dynamics
crescendoTextHiding the extender line for text dynamics
crossSpecial note heads
CueVoiceFormatting cue notes
currentBarNumberBar numbers
currentBarNumberTime administration

D
debug-beam-scoring\paper variables for debugging
debug-slur-scoring\paper variables for debugging
debug-tie-scoring\paper variables for debugging
decrescendoSpannerHiding the extender line for text dynamics
decrescendoTextHiding the extender line for text dynamics
defaultAutomatic accidentals
defaultAutomatic accidentals
default-staff-staff-spacingWithin-system spacing properties
dimCommon chords
dodecaphonicAutomatic accidentals
dodecaphonic-firstAutomatic accidentals
dodecaphonic-no-repeatAutomatic accidentals
drumPitchNamesCustom percussion staves
drumPitchTableCustom percussion staves
DrumStaffInstantiating new staves
drumStyleTableCustom percussion staves
dynamic-eventQuoting other voices
DynamicLineSpannerDynamics
DynamicLineSpannerPrinting hairpins in various styles

E
Engraver_groupContext definition overview
explicitClefVisibility Visibility following explicit changes
explicitKeySignatureVisibility Visibility following explicit changes
extra-offsetWithin-system spacing properties
extra-spacing-height4.5.4.3 Spacing between adjacent columns
extra-spacing-width4.5.4.3 Spacing between adjacent columns
Ez_numbers_engraverSelected Snippets

F
figuredBassAlterationDirectionSelected Snippets
figuredBassPlusDirectionSelected Snippets
figuredBassPlusStrokedAlistChanging the positions of figured bass alterations
fingeringOrientationsSelected Snippets
first-page-number\paper variables for page numbering
followVoiceStaff-change lines
font-encodingMusic fonts
font-interface Understanding the fontSize property
font-interfaceMusic fonts
font-sizeSelecting notation font size
font-size Understanding the fontSize property
fontSizeSelecting notation font size
footnote-separator-markup\paper variables concerning headers and markups
Forbid_line_break_engraverPrinting tuplet brackets on the note head side
forgetAutomatic accidentals
four-string-banjoBanjo tablatures
fret-diagram-interfaceFret diagram markups
FretBoardsPredefined fret diagrams

G
glideGliding fingers
GregorianTranscriptionStaffInstantiating new staves
gridIntervalGrid lines
Grid_line_span_engraverGrid lines
Grid_point_engraverGrid lines
grob-interfaceinterface
grow-directionFeathered beams

H
horizontal-shift\paper variables for shifts and indents
HorizontalBracketTextAnalysis brackets above the staff
Horizontal_bracket_engraverAnalysis brackets

I
indentInstrument names
indent\paper variables for shifts and indents
indent4.5.5 Line width
inner-margin\paper variables for two-sided mode

K
keepAliveInterfacesHiding staves
KievanStaffKievan contexts
KievanVoiceKievan contexts

L
last-bottom-spacingList of flexible vertical spacing \paper variables
layout-set-staff-size4.2.2 Setting the staff size
left-margin\paper variables for widths and margins
line-widthText alignment
line-width\paper variables for widths and margins
line-width4.5.5 Line width
ly:minimal-breakingMinimal page breaking
ly:one-line-auto-height-breakingOne-line-auto-height page breaking
ly:one-line-breakingOne-line page breaking
ly:one-page-breakingOne-page page breaking
ly:optimal-breakingOptimal page breaking
ly:page-turn-breakingOptimal page turning

M
mCommon chords
magnification->font-sizeSelecting notation font size
magnification->font-size4.2.2 Setting the staff size
magstepSelecting notation font size
magstep4.2.2 Setting the staff size
magstep5.4.2 Distances and measurements
majCommon chords
majorSevenSymbolCustomizing chord names
majorSevenSymbolChord name exceptions
make-dynamic-scriptNew dynamic marks
make-pango-font-treeEntire document fonts
markup-markup-spacingList of flexible vertical spacing \paper variables
markup-system-spacingList of flexible vertical spacing \paper variables
Mark_engraverSelected Snippets
max-systems-per-page\paper variables for line breaking
measureBarTypeBar lines
measureLengthSetting automatic beam behavior
measureLengthTime administration
measurePositionUpbeats
measurePositionTime administration
Measure_grouping_engraverStrict beat beaming
MensuralStaffInstantiating new staves
MensuralStaffMensural contexts
MensuralVoiceMensural contexts
midiBalance3.6.8 Context properties for MIDI effects
midiChannelMapping3.6.7 MIDI channel mapping
midiChorusLevel3.6.8 Context properties for MIDI effects
midiDrumPitchesCustom percussion staves
midiExpression3.6.8 Context properties for MIDI effects
midiPanPosition3.6.8 Context properties for MIDI effects
midiReverbLevel3.6.8 Context properties for MIDI effects
min-systems-per-page\paper variables for line breaking
minimum-Y-extentWithin-system spacing properties
minimumFretDefault tablatures
minimumFretAutomatic fret diagrams
minimumPageTurnLengthOptimal page turning
minimumRepeatLengthForPageTurnOptimal page turning
minorChordModifierCustomizing chord names
mixedPiano pedals
modeparser variable
modernAutomatic accidentals
modern-cautionaryAutomatic accidentals
modern-voiceAutomatic accidentals
modern-voice-cautionaryAutomatic accidentals
MultiMeasureRestScriptFull measure rests
MultiMeasureRestTextFull measure rests
musicQuotesparser variable

N
neo-modernAutomatic accidentals
neo-modern-cautionaryAutomatic accidentals
neo-modern-voiceAutomatic accidentals
neo-modern-voice-cautionaryAutomatic accidentals
no-resetAutomatic accidentals
noChordSymbolSimple lead sheet
nonstaff-nonstaff-spacingWithin-system spacing properties
nonstaff-relatedstaff-spacingWithin-system spacing properties
nonstaff-unrelatedstaff-spacingWithin-system spacing properties
note-eventQuoting other voices
noteNameFunctionNote names
NoteNamesNote names
noteNameSeparatorNote names
Note_heads_engraverAutomatic note splitting
Note_name_engraverNote names
NullVoicePolyphony with shared lyrics

O
OneStaffGrouping staves
ottavationSelected Snippets
ottavation-numbersOttava brackets
ottavation-ordinalsOttava brackets
ottavation-simple-ordinalsOttava brackets
ottavationMarkupsOttava brackets
outer-margin\paper variables for two-sided mode
output-countparser variable
output-defoutput-def
output-suffixparser variable
outside-staff-horizontal-padding4.4.3 Vertical collision avoidance
outside-staff-padding4.4.3 Vertical collision avoidance
outside-staff-priority4.4.3 Vertical collision avoidance

P
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-number-type\paper variables for page numbering
page-spacing-weight\paper variables for page breaking
paper-height4.1.3 Fixed vertical spacing \paper variables
paper-width\paper variables for widths and margins
partCombineListenerparser variable
pedalSustainStylePiano pedals
percentPercent repeats
Performer_groupNew contexts in MIDI
pianoAutomatic accidentals
piano-cautionaryAutomatic accidentals
PianoStaffReferences for keyboards
PianoStaffChanging staff automatically
pitchnamesparser variable
Pitch_squash_engraverShowing melody rhythms
predefinedDiagramTableChordChanges for FretBoards
print-all-headers\paper variables concerning headers and markups
print-first-page-number\paper variables for page numbering
print-page-number\paper variables for page numbering
printAccidentalNamesNote names
printNotesLanguageNote names
printOctaveNamesNote names

Q
quotedCueEventTypesQuoting other voices
quotedEventTypesQuoting other voices

R
rRests
RFull measure rests
ragged-bottom4.1.3 Fixed vertical spacing \paper variables
ragged-last\paper variables for widths and margins
ragged-last4.5.5 Line width
ragged-last-bottom4.1.3 Fixed vertical spacing \paper variables
ragged-right\paper variables for widths and margins
ragged-right4.5.5 Line width
remove-emptyHiding staves
remove-firstHiding staves
remove-grace-propertyUsing grace note slashes with normal heads
remove-layerHiding staves
repeatCommandsManual repeat marks
repeatCountVisibilityPercent repeat counter
reset-footnotes-on-new-page\paper variables concerning headers and markups
rest-eventQuoting other voices
restNumberThresholdSelected Snippets
restrainOpenStringsDefault tablatures
rgb-colorColoring objects
RhythmicStaffInstantiating new staves
right-margin\paper variables for widths and margins

S
sInvisible rests
score-markup-spacingList of flexible vertical spacing \paper variables
score-system-spacingList of flexible vertical spacing \paper variables
scoreTitleMarkupCustom layout for titles
Score_engraverReplacing the Score context
Score_performerReplacing the Score context
self-alignment-XWithin-system spacing properties
set-global-fontsEntire document fonts
set-global-staff-size4.2.2 Setting the staff size
short-indentInstrument names
short-indent\paper variables for shifts and indents
show-available-fontsSingle entry fonts
showFirstLength3.5.2 Skipping corrected music
showFirstLengthparser variable
showLastLength3.5.2 Skipping corrected music
showLastLengthparser variable
skipBarsCompressing empty measures
skipTypesetting3.5.2 Skipping corrected music
slashChordSeparatorCustomizing chord names
slur-eventQuoting other voices
space-alist4.5.4.2 Spacing between adjacent non-musical items
spacing4.5.1 Horizontal spacing overview
Span_stem_engraverSelected Snippets
staff-affinityWithin-system spacing properties
staff-paddingControlling the placement of chord fingerings
staff-staff-spacingWithin-system spacing properties
Staff.midiInstrument3.6.9 Enhancing MIDI output
staffgroup-staff-spacingWithin-system spacing properties
Staff_collecting_engraverSelected Snippets
Staff_collecting_engraverSelected Snippets
Staff_symbol_engraverHiding staves
start-repeatManual repeat marks
startAcciaccaturaMusicTweaking grace layout within music
startAppoggiaturaMusicTweaking grace layout within music
startGraceMusicTweaking grace layout within music
stem-spacing-correction4.5.1 Horizontal spacing overview
stemLeftBeamCountManual beams
stemLeftBeamCountSelected Snippets
stemRightBeamCountManual beams
stemRightBeamCountSelected Snippets
stopAcciaccaturaMusicTweaking grace layout within music
stopAppoggiaturaMusicTweaking grace layout within music
stopGraceMusicTweaking grace layout within music
strictBeatBeamingSubdividing beams
stringNumberOrientationsSelected Snippets
stringTuningsCustom tablatures
stringTuningsPredefined fret diagrams
strokeFingerOrientationsSelected Snippets
strokeFingerOrientationsSelected Snippets
subdivideBeamsSelected Snippets
suggestAccidentalsControlling the vertical ordering of scripts
suggestAccidentalsAnnotational accidentals (musica ficta)
susExtended and altered chords
system-count\paper variables for line breaking
system-separator-markup\paper variables concerning headers and markups
system-system-spacingList of flexible vertical spacing \paper variables
systems-per-page\paper variables for line breaking

T
TabStaffInstantiating new staves
TabStaffDefault tablatures
TabVoiceDefault tablatures
teachingAutomatic accidentals
textPiano pedals
Text_mark_engraverSelected Snippets
TieColumnUsing ties with arpeggios
tieWaitForNoteSelected Snippets
timeSignatureFractionPolymetric notation
TimingTime administration
tocFormatMarkupPredefined commands
tocIndentMarkupPredefined commands
tocItemMarkupPredefined commands
tocTitleMarkupPredefined commands
top-margin4.1.3 Fixed vertical spacing \paper variables
top-markup-spacingList of flexible vertical spacing \paper variables
top-system-spacingList of flexible vertical spacing \paper variables
toplevel-bookpartsparser variable
toplevel-scoresparser variable
tremoloTremolo repeats
tuplet-slurTuplets
TupletNumberEntering several tuplets using only one tuplet command
tupletSpannerDurationSelected Snippets
two-sided\paper variables for two-sided mode

U
unfold1.4.1 Long repeats
universal-colorColoring objects
universal-colorColor-blind-safe colors

V
VaticanaStaffInstantiating new staves
VaticanaStaffGregorian chant contexts
VaticanaVoiceGregorian chant contexts
VerticalAxisGroupWithin-system spacing properties
voiceAutomatic accidentals
VoiceSingle-staff polyphony
voiceAutomatic accidentals
voltaSee also
voltaAlternative endings
Volta_engraverShortening volta brackets

X
X-offsetWithin-system spacing properties
x11-colorColoring objects
x11-colorSee also
x11-colorX color names

Jump to:   !   "   %   '   (   )   ,   -   .   /   :   <   =   >   ?   [   \   ]   ^   _   |   ~  
A   B   C   D   E   F   G   H   I   K   L   M   N   O   P   Q   R   S   T   U   V   X  

E. LilyPond index

In addition to all the LilyPond commands and keywords, this index lists musical terms and words that relate to each of them, with links to those sections of the manual that 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

"
"|"Bar and bar number checks

%
%3.2.1 Structure of a score
%3.2.5 File structure
%{ … %}3.2.1 Structure of a score
%{ … %}3.2.5 File structure

'
'Absolute octave entry

(
(Slurs

)
)Slurs

,
,Absolute octave entry

-
-Articulations and ornamentations
-Articulation direction indicators
--A.15 List of articulations
-!A.15 List of articulations
-+Fermata scripts
-.A.15 List of articulations
->A.15 List of articulations
-^A.15 List of articulations
-_A.15 List of articulations

.
.Durations

/
/Extended and altered chords
/+Extended and altered chords

1
15maOttava brackets
15mbOttava brackets

8
8vaOttava brackets
8vbOttava brackets

:
:Tremolo repeats

<
<Chorded notes
<...>Chorded notes
<>Chorded notes
<>Changing staff manually

=
=Octave checks

>
>Chorded notes

?
?Accidentals

[
[Manual beams

\
\!Dynamics
\(Phrasing slurs
\)Phrasing slurs
\-2.8.3 Graphical notation
\<Dynamics
\=Slurs
\=A.21 Available music functions
\>Dynamics
\abs-fontsizeSelecting font and font size
\abs-fontsizeA.12.1 Font
\absoluteA.21 Available music functions
\accentArticulations and ornamentations
\accentA.15 List of articulations
\accentusGregorian articulation signs
\accentusRepeat sign scripts
\acceptsContext definition overview
\acceptsContext definition overview
\accepts5.1.7 Context layout order
\acciaccaturaGrace notes
\acciaccaturaA.21 Available music functions
\accidentalA.12.4 Music
\accidentalStyleAutomatic accidentals
\accidentalStyleA.21 Available music functions
\addChordShapePredefined fret diagrams
\addChordShapeA.21 Available music functions
\addInstrumentDefinitionA.21 Available music functions
\addlyricsAligning lyrics to a melody
\addlyricsAutomatic syllable durations
\addlyricsUsing \addlyrics
\addQuoteQuoting other voices
\addQuoteA.21 Available music functions
\aeolianKey signature
\afterDynamics
\afterPercent repeats
\afterA.21 Available music functions
\afterGraceGrace notes
\afterGraceA.21 Available music functions
\aikenHeadsShape note heads
\aikenHeadsMinorShape note heads
\aikenThinHeadsShape note heads
\aikenThinHeadsMinorShape note heads
\aliasContext definition overview
\aliasContext definition overview
\align-on-otherA.12.2 Align
\allowPageTurnPredefined commands
\allowPageTurnA.21 Available music functions
\allowVoltaHookA.21 Available music functions
\alterBrokenModifying broken spanners
\alterBrokenA.21 Available music functions
\alternativeAlternative endings
\alternativeAlternative endings
\ambitusAfterA.21 Available music functions
\appendToTagUsing tags
\appendToTagA.21 Available music functions
\applyContext5.1.2 Creating and referencing contexts
\applyContextA.21 Available music functions
\applyMusicA.21 Available music functions
\applyOutputA.21 Available music functions
\applySwingThe ‘swing’ script
\applySwingWithOffsetThe ‘swing’ script
\appoggiaturaGrace notes
\appoggiaturaA.21 Available music functions
\arabicStringNumbersString number indications
\arpeggioArpeggio
\arpeggioArrowDownArpeggio
\arpeggioArrowUpArpeggio
\arpeggioBracketArpeggio
\arpeggioNormalArpeggio
\arpeggioParenthesisArpeggio
\arpeggioParenthesisDashedArpeggio
\arrow-headGraphic notation inside markup
\arrow-headA.12.3 Graphic
\articulateThe ‘articulate’ script
\ascendensGregorian square neume ligatures
\ascendensPredefined commands
\assertBeamQuantA.21 Available music functions
\assertBeamSlopeA.21 Available music functions
\auctumGregorian square neume ligatures
\auctumPredefined commands
\augmentumPredefined commands
\auto-footnoteA.12.8 Other
\autoBeamOffAutomatic beams
\autoBeamOffSelected Snippets
\autoBeamOnAutomatic beams
\autoBreaksOff4.3.1 Line breaking
\autoBreaksOn4.3.1 Line breaking
\autoChangeChanging staff automatically
\autoChangeA.21 Available music functions
\autoChange, and relative musicChanging staff automatically
\autoLineBreaksOff4.3.1 Line breaking
\autoLineBreaksOn4.3.1 Line breaking
\autoPageBreaksOffManual page breaking
\autoPageBreaksOnManual page breaking
\backslashed-digitA.12.8 Other
\balloonGrobTextBalloon help
\balloonGrobTextA.21 Available music functions
\balloonLengthOffBalloon help
\balloonLengthOnBalloon help
\balloonTextBalloon help
\balloonTextA.21 Available music functions
\barBar lines
\barBar lines
\barA.21 Available music functions
\barNumberCheckBar and bar number checks
\barNumberCheckA.21 Available music functions
\bassFigureExtendersOffEntering figured bass
\bassFigureExtendersOnEntering figured bass
\bassFigureStaffAlignmentDownDisplaying figured bass
\bassFigureStaffAlignmentNeutralDisplaying figured bass
\bassFigureStaffAlignmentUpDisplaying figured bass
\beamA.12.3 Graphic
\beamExceptionsSetting automatic beam behavior
\beamExceptionsA.21 Available music functions
\bendAfterFalls and doits
\bendAfterA.21 Available music functions
\bendHoldDefault tablatures
\bendHoldA.21 Available music functions
\bendStartLevelDefault tablatures
\bendStartLevelA.21 Available music functions
\blackTriangleMarkupCustomizing chord names
\boldSelecting font and font size
\boldA.12.1 Font
\book3.2.2 Multiple scores in a book
\book3.2.2 Multiple scores in a book
\book3.2.5 File structure
\bookOutputName3.2.4 Output file names
\bookOutputNameA.21 Available music functions
\bookOutputSuffix3.2.4 Output file names
\bookOutputSuffixA.21 Available music functions
\bookpart3.2.2 Multiple scores in a book
\bookpart3.2.5 File structure
\bookpartManual page breaking
\boxGraphic notation inside markup
\boxA.12.1 Font
\bp5.4.2 Distances and measurements
\bracketNew dynamic marks
\bracketGraphic notation inside markup
\bracketA.12.3 Graphic
\break4.3.1 Line breaking
\breatheBreath marks
\breatheA.21 Available music functions
\breveDurations
\breveRests
\cadenzaOffUnmetered music
\cadenzaOnUnmetered music
\caesuraCaesuras
\caesuraSelected Snippets
\caesuraAutomatic bar lines
\caesuraAutomatic bar lines
\caesuraPhrase bar lines in hymn tunes
\caesuraPredefined commands
\caesuraKievan bar lines
\caesuraA.21 Available music functions
\capsA.12.1 Font
\cavumGregorian square neume ligatures
\cavumPredefined commands
\center-alignText alignment
\center-alignA.12.2 Align
\center-columnText alignment
\center-columnA.12.2 Align
\changeChanging staff manually
\charA.12.8 Other
\chordmodeSee also
\chordmodeSee also
\chordmodePredefined fret diagrams
\chordmode Chord mode
\chordRepeatsDefault tablatures
\chordRepeatsA.21 Available music functions
\chordsPrinting chord names
\chords Chord mode
\circleGraphic notation inside markup
\circleA.12.3 Graphic
\circulusGregorian articulation signs
\circulusRepeat sign scripts
\clefClef
\clefA.21 Available music functions
\cm5.4.2 Distances and measurements
\codaArticulations and ornamentations
\codaA.12.4 Music
\codaInstrument-specific scripts
\codaMarkAutomatic bar lines
\codaMarkSegno repeat appearance
\codaMarkManual repeat marks
\codaMarkA.21 Available music functions
\columnText alignment
\columnA.12.2 Align
\column-linesA.13 Text markup list commands
\combineGraphic notation inside markup
\combineA.12.2 Align
\compound-meterA.12.4 Music
\compoundMeter Different time signatures with unequal-length measures
\compoundMeterA.21 Available music functions
\compressEmptyMeasuresCompressing empty measures
\compressMMRestsFull measure rests
\compressMMRestsFull measure rests
\compressMMRestsCompressing empty measures
\compressMMRestsA.21 Available music functions
\concatA.12.2 Align
\consists5.1.4 Modifying context plug-ins
\consistsContext definition overview
\consistsContext definition overview
\context5.1.2 Creating and referencing contexts
\contextChanging all contexts of the same type
\context in \layout blockChanging all contexts of the same type
\crDynamics
\crescDynamics
\crescHairpinDynamics
\crescTextCrescDynamics
\crossStaffSelected Snippets
\crossStaffA.21 Available music functions
\cueClefFormatting cue notes
\cueClefA.21 Available music functions
\cueClefUnsetFormatting cue notes
\cueClefUnsetA.21 Available music functions
\cueDuringFormatting cue notes
\cueDuringA.21 Available music functions
\cueDuringWithClefFormatting cue notes
\cueDuringWithClefA.21 Available music functions
\customTabClefA.12.4 Music
\dashBangSelected Snippets
\dashDashSelected Snippets
\dashDotSelected Snippets
\dashHatSelected Snippets
\dashLargerSelected Snippets
\dashPlusSelected Snippets
\dashUnderscoreSelected Snippets
\deadNoteSpecial note heads
\deadNoteA.21 Available music functions
\deadNotesOffSpecial note heads
\deadNotesOnSpecial note heads
\decrDynamics
\decrescDynamics
\defaultRehearsal marks
\default Music footnotes overview
\defaultchild5.1.7 Context layout order
\defaultTimeSignatureTime signature
\defineBarLineBar lines
\defineBarLineA.21 Available music functions
\deminutumGregorian square neume ligatures
\deminutumPredefined commands
\deniesContext definition overview
\deniesContext definition overview
\denies5.1.7 Context layout order
\descendensGregorian square neume ligatures
\descendensPredefined commands
\dimDynamics
\dimHairpinDynamics
\dimTextDecrDynamics
\dimTextDecrescDynamics
\dimTextDimDynamics
\dir-columnA.12.2 Align
\discantA.12.7 Accordion Registers
\displayLilyMusic3.7.1 Displaying LilyPond notation
\displayLilyMusicA.21 Available music functions
\displayMusicA.21 Available music functions
\displaySchemeA.21 Available music functions
\divisioMaiorPredefined commands
\divisioMaximaPredefined commands
\divisioMinimaPredefined commands
\dorianKey signature
\dotsDownDurations
\dotsNeutralDurations
\dotsUpDurations
\doubleflatA.12.4 Music
\doublesharpA.12.4 Music
\downbowArticulations and ornamentations
\downbowBowing indications
\downbowFermata scripts
\downmordentArticulations and ornamentations
\downmordentArticulation scripts
\downprallArticulations and ornamentations
\downprallArticulation scripts
\draw-circleGraphic notation inside markup
\draw-circleA.12.3 Graphic
\draw-dashed-lineA.12.3 Graphic
\draw-dotted-lineA.12.3 Graphic
\draw-hlineA.12.3 Graphic
\draw-lineGraphic notation inside markup
\draw-lineA.12.3 Graphic
\draw-squiggle-lineA.12.3 Graphic
\dropNoteChord inversions and specific voicings
\dropNoteA.21 Available music functions
\drummodeInstantiating new staves
\drummodeBasic percussion notation
\drummode Drum mode
\drumsBasic percussion notation
\drums Drum mode
\dwnArabic note names
\dynamicNew dynamic marks
\dynamicA.12.1 Font
\dynamicDownDynamics
\dynamicNeutralDynamics
\dynamicUpDynamics
\easyHeadsOffEasy notation note heads
\easyHeadsOnEasy notation note heads
\ellipseA.12.3 Graphic
\EnableGregorianDivisionesA.22 Context modification identifiers
\enablePolymeterA.21 Available music functions
\endcrDynamics
\enddecrDynamics
\endSpanners5.4.6 Line spanners
\endSpannersA.21 Available music functions
\episemFinisGregorian articulation signs
\episemInitiumGregorian articulation signs
\epsfileGraphic notation inside markup
\epsfileA.12.3 Graphic
\espressivoArticulations and ornamentations
\espressivoDynamics
\espressivoA.15 List of articulations
\etcText markup introduction
\etc3.4.3.2 Substitution function examples
\eventChordsA.21 Available music functions
\expandEmptyMeasuresCompressing empty measures
\eyeglassesA.12.8 Other
\fDynamics
\featherDurationsFeathered beams
\featherDurationsA.21 Available music functions
\fermataSelected Snippets
\fermataArticulations and ornamentations
\fermataA.12.4 Music
\fermataOrnament scripts
\ffDynamics
\fffDynamics
\ffffDynamics
\fffffDynamics
\figured-bassA.12.1 Font
\figuremodeIntroduction to figured bass
\figuremode Figure mode
\figuresIntroduction to figured bass
\figures Figure mode
\fill-lineText alignment
\fill-lineA.12.2 Align
\fill-with-pattern3.3.6 Table of contents
\fill-with-patternA.12.2 Align
\filled-boxGraphic notation inside markup
\filled-boxA.12.3 Graphic
\finalisPredefined commands
\fineAutomatic bar lines
\fineSection divisions
\fineAl-fine repeats
\fineSegno repeat structure
\fineKievan bar lines
\fingerFingering instructions
\fingerA.12.1 Font
\fingerA.21 Available music functions
\first-visibleA.12.8 Other
\fixedAbsolute octave entry
\fixedA.21 Available music functions
\flageoletArticulations and ornamentations
\flageoletFermata scripts
\flatA.12.4 Music
\flexaPredefined commands
\fontCapsA.12.1 Font
\fontsizeSelecting font and font size
\fontsizeA.12.1 Font
\footnoteFootnotes in music expressions
\footnoteA.12.8 Other
\footnoteA.21 Available music functions
\fpDynamics
\fractionA.12.8 Other
\freeBassA.12.7 Accordion Registers
\frenchChordsCustomizing chord names
\fret-diagramFret diagram markups
\fret-diagramA.12.6 Instrument Specific Markup
\fret-diagram-terseFret diagram markups
\fret-diagram-terseA.12.6 Instrument Specific Markup
\fret-diagram-terse markupFret diagram markups
\fret-diagram-verboseFret diagram markups
\fret-diagram-verboseA.12.6 Instrument Specific Markup
\fret-diagram-verbose markupFret diagram markups
\frompropertyA.12.8 Other
\funkHeadsShape note heads
\funkHeadsMinorShape note heads
\general-alignText alignment
\general-alignA.12.2 Align
\germanChordsCustomizing chord names
\glideGliding fingers
\glissandoGlissando
\glissandoMapGlissando
\graceGrace notes
\graceA.21 Available music functions
\grobdescriptionsA.21 Available music functions
\halfopenArticulations and ornamentations
\halfopenCustom percussion staves
\halfopenFermata scripts
\halignText alignment
\halignA.12.2 Align
\harmonicSpecial note heads
\harmonicHarmonics
\harmonicDefault tablatures
\harmonicByFretDefault tablatures
\harmonicByFretA.21 Available music functions
\harmonicByRatioDefault tablatures
\harmonicByRatioA.21 Available music functions
\harmonicNoteA.21 Available music functions
\harmonicsOffHarmonics
\harmonicsOnHarmonics
\harmonicsOnA.21 Available music functions
\harp-pedalA.12.6 Instrument Specific Markup
\haydnturnArticulations and ornamentations
\haydnturnArticulation scripts
\hbracketGraphic notation inside markup
\hbracketA.12.3 Graphic
\hcenter-inA.12.2 Align
\header3.2.5 File structure
\henzelongfermataArticulations and ornamentations
\henzelongfermataOrnament scripts
\henzeshortfermataArticulations and ornamentations
\henzeshortfermataOrnament scripts
\hideMaking objects transparent
\hideA.21 Available music functions
\hideKeySignatureBagpipe definitions
\hideNotesHidden notes
\hideSplitTiedTabNotesDefault tablatures
\hideStaffSwitchStaff-change lines
\hspaceText alignment
\hspaceA.12.2 Align
\hugeSelecting notation font size
\hugeSelecting font and font size
\hugeA.12.1 Font
\ictusGregorian articulation signs
\ictusRepeat sign scripts
\ifCustom layout for headers and footers
\ifA.12.5 Conditionals
\IIJ Special signs
\iij Special signs
\ij Special signs
\IJ Special signs
\improvisationOffImprovisation
\improvisationOffShowing melody rhythms
\improvisationOnImprovisation
\improvisationOnShowing melody rhythms
\in5.4.2 Distances and measurements
\incipitIncipits
\incipitA.21 Available music functions
\inclinatumGregorian square neume ligatures
\inclinatumPredefined commands
\include3.2.5 File structure
\include3.4.1 Including LilyPond files
\inherit-acceptabilityContext definition overview
\inherit-acceptabilityA.21 Available music functions
\inStaffSegnoAutomatic bar lines
\inStaffSegnoAutomatic bar lines
\inStaffSegnoManual repeat marks
\inStaffSegnoA.21 Available music functions
\instrumentSwitchA.21 Available music functions
\inversionInversion
\inversionA.21 Available music functions
\invertChordsChord inversions and specific voicings
\invertChordsA.21 Available music functions
\ionianKey signature
\italianChordsCustomizing chord names
\italicSelecting font and font size
\italicA.12.1 Font
\jumpManual repeat marks
\jumpA.21 Available music functions
\justified-linesText markup introduction
\justified-linesA.13 Text markup list commands
\justifyText alignment
\justifyA.12.2 Align
\justify-fieldA.12.2 Align
\justify-lineA.12.2 Align
\justify-stringA.12.2 Align
\keepWithTagUsing tags
\keepWithTagA.21 Available music functions
\keyKey signature
\keyShape note heads
\keyA.21 Available music functions
\kievanOffKievan notes
\kievanOnKievan notes
\killCuesFormatting cue notes
\killCuesA.21 Available music functions
\labelPredefined commands
\labelA.21 Available music functions
\laissezVibrerTies
\languageA.21 Available music functions
\languageRestoreA.21 Available music functions
\languageSaveAndChangeA.21 Available music functions
\largeSelecting notation font size
\largeSelecting font and font size
\largeA.12.1 Font
\largerSelecting font and font size
\largerSelecting font and font size
\largerA.12.1 Font
\layout3.2.5 File structure
\layout4.2.1 The \layout block
\layoutOutput definitions – blueprints for contexts
\layoutChanging all contexts of the same type
\left-alignText alignment
\left-alignA.12.2 Align
\left-braceA.12.8 Other
\left-columnA.12.2 Align
\lheelArticulations and ornamentations
\lheelFermata scripts
\lineA.12.2 Align
\lineaGregorian square neume ligatures
\lineaPredefined commands
\lineprallArticulations and ornamentations
\lineprallArticulation scripts
\locrianKey signature
\longaDurations
\longaRests
\longfermataArticulations and ornamentations
\longfermataOrnament scripts
\lookupA.12.8 Other
\lowerText alignment
\lowerA.12.2 Align
\ltoeArticulations and ornamentations
\ltoeFermata scripts
\lydianKey signature
\lyricmodeEntering lyrics
\lyricmodeAligning lyrics to a melody
\lyricmode Lyrics mode
\lyrics Lyrics mode
\lyricstoAligning lyrics to a melody
\lyricstoAutomatic syllable durations
\lyricstoUsing \lyricsto
\magnifySelecting font and font size
\magnifyA.12.1 Font
\magnifyMusicSelecting notation font size
\magnifyMusicA.21 Available music functions
\magnifyStaff4.2.2 Setting the staff size
\magnifyStaffA.21 Available music functions
\majorKey signature
\makeClustersClusters
\makeClustersA.21 Available music functions
\makeDefaultStringTuningA.21 Available music functions
\map-commandsA.13 Text markup list commands
\marcatoArticulations and ornamentations
\marcatoA.15 List of articulations
\markRehearsal marks
\markText marks
\markA.21 Available music functions
\markalphabetA.12.8 Other
\markLengthOffMetronome marks
\markLengthOffText marks
\markLengthOnMetronome marks
\markLengthOnText marks
\markletterA.12.8 Other
\markupText objects overview
\markupText marks
\markupSeparate text
\markupSeparate text
\markupText markup introduction
\markup Markup mode
\markuplistSeparate text
\markuplistText markup introduction
\markupMapA.21 Available music functions
\maximaDurations
\maximaRests
\mediumA.12.1 Font
\melismaMultiple notes to one syllable
\melismaEndMultiple notes to one syllable
\mergeDifferentlyDottedOffCollision resolution
\mergeDifferentlyDottedOnCollision resolution
\mergeDifferentlyHeadedOffCollision resolution
\mergeDifferentlyHeadedOnCollision resolution
\mfDynamics
\midi3.2.5 File structure
\midiOutput definitions – blueprints for contexts
\minorKey signature
\mixolydianKey signature
\mm5.4.2 Distances and measurements
\modalInversion Modal inversion
\modalInversionA.21 Available music functions
\modalTranspose Modal transposition
\modalTransposeA.21 Available music functions
\mordentArticulations and ornamentations
\mordentArticulation scripts
\mpDynamics
\multi-measure-rest-by-numberA.12.4 Music
\musicglyphA.12.4 Music
\musicMapA.21 Available music functions
\nDynamics
\nameContext definition overview
\nameContext definition overview
\naturalA.12.4 Music
\new5.1.2 Creating and referencing contexts
\newSpacingSection4.5.2 New spacing section
\noBeamManual beams
\noBreak4.3.1 Line breaking
\noPageBreakManual page breaking
\noPageBreakA.21 Available music functions
\noPageTurnPredefined commands
\noPageTurnA.21 Available music functions
\normal-size-subA.12.1 Font
\normal-size-superSelecting font and font size
\normal-size-superA.12.1 Font
\normal-textA.12.1 Font
\normalsizeSelecting notation font size
\normalsizeSelecting font and font size
\normalsizeA.12.1 Font
\noteA.12.4 Music
\note-by-numberA.12.4 Music
\notemode Note mode
\nullText alignment
\nullA.12.8 Other
\numberA.12.1 Font
\numericTimeSignatureTime signature
\octaveCheckOctave checks
\octaveCheckA.21 Available music functions
\offset5.3.6 The \offset command
\offsetA.21 Available music functions
\omitRemoving the stencil
\omitA.21 Available music functions
\on-the-flyA.12.8 Other
\once5.3.2 The \set command
\once5.3.3 The \override command
\once \offset as an override
\onceModifying broken spanners
\onceA.21 Available music functions
\oneVoiceSingle-staff polyphony
\openArticulations and ornamentations
\openBowing indications
\openSelected Snippets
\openFermata scripts
\oriscusGregorian square neume ligatures
\oriscusPredefined commands
\ottavaOttava brackets
\ottavaA.21 Available music functions
\ovalA.12.3 Graphic
\overlayA.12.2 Align
\override5.3.3 The \override command
\override5.3.5 \set vs. \override
\overrideA.12.8 Other
\override-linesA.13 Text markup list commands
\overrideProperty5.3.5 \set vs. \override
\overridePropertyA.21 Available music functions
\overrideTimeSignatureSettingsTime signature
\overrideTimeSignatureSettingsA.21 Available music functions
\overtieA.12.1 Font
\pDynamics
\padA.12.2 Align
\pad-aroundGraphic notation inside markup
\pad-aroundA.12.2 Align
\pad-markupGraphic notation inside markup
\pad-to-boxGraphic notation inside markup
\pad-to-boxA.12.2 Align
\pad-xGraphic notation inside markup
\pad-xA.12.2 Align
\page-linkA.12.8 Other
\page-refPredefined commands
\page-refA.12.8 Other
\pageBreakManual page breaking
\pageBreakA.21 Available music functions
\pageTurnPredefined commands
\pageTurnA.21 Available music functions
\palmMuteA.21 Available music functions
\palmMuteOnA.21 Available music functions
\paper3.2.5 File structure
\paper4.1.2 Paper size and automatic scaling
\parallelMusicWriting music in parallel
\parallelMusicA.21 Available music functions
\parenthesizeParentheses
\parenthesizeA.12.3 Graphic
\parenthesizeA.21 Available music functions
\partCombineAutomatic part combining
\partCombinePolyphony with shared lyrics
\partCombineA.21 Available music functions
\partCombine and lyrics Using \partCombine with lyrics
\partCombine and lyricsPolyphony with shared lyrics
\partCombineApartAutomatic part combining
\partCombineAutomaticAutomatic part combining
\partCombineChordsAutomatic part combining
\partCombineDownA.21 Available music functions
\partCombineForceA.21 Available music functions
\partCombineSoloIAutomatic part combining
\partCombineSoloIIAutomatic part combining
\partCombineUnisonoAutomatic part combining
\partCombineUpA.21 Available music functions
\partialUpbeats
\partialSimple repeats
\partialA.21 Available music functions
\pathA.12.3 Graphic
\patternA.12.8 Other
\pesPredefined commands
\phrasingSlurDashedPhrasing slurs
\phrasingSlurDashPatternPhrasing slurs
\phrasingSlurDashPatternA.21 Available music functions
\phrasingSlurDottedPhrasing slurs
\phrasingSlurDownPhrasing slurs
\phrasingSlurHalfDashedPhrasing slurs
\phrasingSlurHalfSolidPhrasing slurs
\phrasingSlurNeutralPhrasing slurs
\phrasingSlurSolidPhrasing slurs
\phrasingSlurUpPhrasing slurs
\phrygianKey signature
\pitchedTrillTrills
\pitchedTrillA.21 Available music functions
\pointAndClickOffA.21 Available music functions
\pointAndClickOnA.21 Available music functions
\pointAndClickTypesA.21 Available music functions
\polygonA.12.3 Graphic
\portatoArticulations and ornamentations
\portatoA.15 List of articulations
\postscriptGraphic notation inside markup
\postscriptA.12.3 Graphic
\ppDynamics
\pppDynamics
\ppppDynamics
\pppppDynamics
\prallArticulations and ornamentations
\prallArticulation scripts
\pralldownArticulations and ornamentations
\pralldownArticulation scripts
\prallmordentArticulations and ornamentations
\prallmordentArticulation scripts
\prallprallArticulations and ornamentations
\prallprallArticulation scripts
\prallupArticulations and ornamentations
\prallupArticulation scripts
\preBendDefault tablatures
\preBendA.21 Available music functions
\preBendHoldDefault tablatures
\preBendHoldA.21 Available music functions
\predefinedFretboardsOffAutomatic fret diagrams
\predefinedFretboardsOnAutomatic fret diagrams
\property-recursiveA.12.8 Other
\propertyOverrideA.21 Available music functions
\propertyRevertA.21 Available music functions
\propertySetA.21 Available music functions
\propertyTweakA.21 Available music functions
\propertyUnsetA.21 Available music functions
\pt5.4.2 Distances and measurements
\pushToTagUsing tags
\pushToTagA.21 Available music functions
\put-adjacentA.12.2 Align
\quilismaGregorian square neume ligatures
\quilismaPredefined commands
\quoteDuringQuoting other voices
\quoteDuringFormatting cue notes
\quoteDuringA.21 Available music functions
\raiseText alignment
\raiseA.12.2 Align
\raiseNoteChord inversions and specific voicings
\raiseNoteA.21 Available music functions
\reduceChordsShowing melody rhythms
\reduceChordsA.21 Available music functions
\relativeRelative octave entry
\relativeSee also
\relativeSee also
\relativeChanging staff automatically
\relativeA.21 Available music functions
\remove5.1.4 Modifying context plug-ins
\RemoveAllEmptyStavesHiding staves
\RemoveAllEmptyStavesA.22 Context modification identifiers
\RemoveEmptyStavesHiding staves
\RemoveEmptyStavesA.22 Context modification identifiers
\removeWithTagUsing tags
\removeWithTagA.21 Available music functions
\repeat1.4.1 Long repeats
\repeatSee also
\repeatAlternative endings
\repeat percentPercent repeats
\repeat segnoAutomatic bar lines
\repeat segnoAutomatic bar lines
\repeat segnoSegno repeat structure
\repeat tremoloTremolo repeats
\repeat unfold1.4.1 Long repeats
\repeat voltaAutomatic bar lines
\repeat voltaAutomatic bar lines
\repeat voltaSee also
\repeat voltaAlternative endings
\repeatTieTies
\repeatTieRepeats with alternative endings
\replaceA.12.1 Font
\resetRelativeOctaveRelative octave entry
\resetRelativeOctaveA.21 Available music functions
\responsum Special signs
\restRests
\restA.12.4 Music
\rest-by-numberA.12.4 Music
\retrogradeRetrograde
\retrogradeA.21 Available music functions
\reverseturnArticulations and ornamentations
\reverseturnArticulation scripts
\revert5.3.3 The \override command
\revertTimeSignatureSettingsTime signature
\revertTimeSignatureSettingsA.21 Available music functions
\rfzDynamics
\rheelArticulations and ornamentations
\rheelFermata scripts
\rhythmA.12.4 Music
\right-alignText alignment
\right-alignA.12.2 Align
\right-braceA.12.8 Other
\right-columnA.12.2 Align
\rightHandFingerRight-hand fingerings
\rightHandFingerA.21 Available music functions
\romanA.12.1 Font
\romanStringNumbersBowing indications
\romanStringNumbersString number indications
\rotateA.12.2 Align
\rounded-boxGraphic notation inside markup
\rounded-boxA.12.3 Graphic
\rtoeArticulations and ornamentations
\rtoeFermata scripts
\sacredHarpHeadsShape note heads
\sacredHarpHeadsMinorShape note heads
\sansA.12.1 Font
\scaleA.12.3 Graphic
\scaleDurationsScaling durations
\scaleDurationsPolymetric notation
\scaleDurationsA.21 Available music functions
\score3.2.1 Structure of a score
\score3.2.5 File structure
\scoreA.12.4 Music
\score-linesA.13 Text markup list commands
\sectionAutomatic bar lines
\sectionSection divisions
\sectionKievan bar lines
\sectionLabelSegno repeat structure
\sectionLabelSection labels
\sectionLabelA.21 Available music functions
\segnoArticulations and ornamentations
\segnoA.12.4 Music
\segnoInstrument-specific scripts
\segnoMarkAutomatic bar lines
\segnoMarkAutomatic bar lines
\segnoMarkSegno repeat appearance
\segnoMarkManual repeat marks
\segnoMarkA.21 Available music functions
\semicirculusGregorian articulation signs
\semicirculusRepeat sign scripts
\semiflatA.12.4 Music
\semiGermanChordsCustomizing chord names
\semisharpA.12.4 Music
\sesquiflatA.12.4 Music
\sesquisharpA.12.4 Music
\setSetting automatic beam behavior
\set5.3.2 The \set command
\set5.3.5 \set vs. \override
\settingsFromA.21 Available music functions
\sfDynamics
\sffDynamics
\sfzDynamics
\shape Specifying displacements from current control points
\shapeA.21 Available music functions
\sharpA.12.4 Music
\shiftDurationsA.21 Available music functions
\shiftOffCollision resolution
\shiftOnCollision resolution
\shiftOnnCollision resolution
\shiftOnnnCollision resolution
\shortfermataArticulations and ornamentations
\shortfermataOrnament scripts
\showKeySignatureBagpipe definitions
\showStaffSwitchStaff-change lines
\signumcongruentiaeArticulations and ornamentations
\signumcongruentiaeRepeat sign scripts
\simpleA.12.1 Font
\single Time-based footnotes
\single \offset as an override
\singleA.21 Available music functions
\skipInvisible rests
\skipRepeats with alternative endings
\skipA.21 Available music functions
\slashed-digitA.12.8 Other
\slashedGraceGrace notes
\slashedGraceA.21 Available music functions
\slashSeparator\paper variables concerning headers and markups
\slashturnArticulations and ornamentations
\slashturnArticulation scripts
\slurDashedSlurs
\slurDashPatternSlurs
\slurDashPatternA.21 Available music functions
\slurDottedSlurs
\slurDownSlurs
\slurHalfDashedSlurs
\slurHalfSolidSlurs
\slurNeutralSlurs
\slurSolidSlurs
\slurUpSlurs
\smallSelecting notation font size
\smallSelecting font and font size
\smallA.12.1 Font
\smallCapsA.12.1 Font
\smallerSelecting font and font size
\smallerSelecting font and font size
\smallerA.12.1 Font
\snappizzicatoArticulations and ornamentations
\snappizzicatoFermata scripts
\sostenutoOffPiano pedals
\sostenutoOnPiano pedals
\sourcefileline3.2.5 File structure
\sourcefilename3.2.5 File structure
\southernHarmonyHeadsShape note heads
\southernHarmonyHeadsMinorShape note heads
\spDynamics
\sppDynamics
\staccatissimoArticulations and ornamentations
\staccatissimoA.15 List of articulations
\staccatoArticulations and ornamentations
\staccatoA.15 List of articulations
\staff-space5.4.2 Distances and measurements
\staffHighlightStaff highlights
\staffHighlightA.21 Available music functions
\startGroupAnalysis brackets
\startStaffStaff symbol
\startStaffOssia staves
\startTrillSpanTrills
\stdBassA.12.7 Accordion Registers
\stdBassIVA.12.7 Accordion Registers
\stdBassVA.12.7 Accordion Registers
\stdBassVIA.12.7 Accordion Registers
\stemDownStems
\stemNeutralStems
\stemUpStems
\stencilA.12.8 Other
\stopGroupAnalysis brackets
\stoppedArticulations and ornamentations
\stoppedCustom percussion staves
\stoppedSelected Snippets
\stoppedFermata scripts
\stopStaffStaff symbol
\stopStaffOssia staves
\stopStaffHiding staves
\stopStaffHighlightStaff highlights
\stopTrillSpanTrills
\storePredefinedDiagramPredefined fret diagrams
\storePredefinedDiagramChordChanges for FretBoards
\storePredefinedDiagramA.21 Available music functions
\string-linesA.13 Text markup list commands
\stringTuningCustom tablatures
\stringTuningA.21 Available music functions
\strophaGregorian square neume ligatures
\strophaPredefined commands
\strutA.12.8 Other
\styledNoteHeadsA.21 Available music functions
\subSelecting font and font size
\subA.12.1 Font
\superSelecting font and font size
\superA.12.1 Font
\sustainOffPiano pedals
\sustainOnPiano pedals
\tabChordRepeatsDefault tablatures
\tabChordRepeatsA.21 Available music functions
\tabChordRepetitionA.21 Available music functions
\tabFullNotationDefault tablatures
\tableA.13 Text markup list commands
\table-of-contentsPredefined commands
\table-of-contentsA.13 Text markup list commands
\tagUsing tags
\tagA.21 Available music functions
\tagGroupUsing tags
\tagGroupA.21 Available music functions
\taorBagpipe definitions
\teenySelecting notation font size
\teenySelecting font and font size
\teenyA.12.1 Font
\tempoMetronome marks
\temporary \offset as an override
\temporaryModifying broken spanners
\temporaryA.21 Available music functions
\tenutoArticulations and ornamentations
\tenutoA.15 List of articulations
\textA.12.1 Font
\textEndMarkText marks
\textEndMarkA.21 Available music functions
\textLengthOffFull measure rests
\textLengthOffPositioning multi-measure rests
\textLengthOffText scripts
\textLengthOnFull measure rests
\textLengthOnPositioning multi-measure rests
\textLengthOnPrinting hairpins in various styles
\textLengthOnText scripts
\textMarkText marks
\textMarkA.21 Available music functions
\textSpannerDownText spanners
\textSpannerNeutralText spanners
\textSpannerUpText spanners
\thumbArticulations and ornamentations
\thumbFingering instructions
\tieA.12.1 Font
\tied-lyricA.12.4 Music
\tieDashedTies
\tieDashPatternTies
\tieDashPatternA.21 Available music functions
\tieDottedTies
\tieDownTies
\tieHalfDashedTies
\tieHalfSolidTies
\tieNeutralTies
\tieSolidTies
\tieUpTies
\timeTime signature
\timeSetting automatic beam behavior
\timeA.21 Available music functions
\timesA.21 Available music functions
\tinySelecting notation font size
\tinySelecting font and font size
\tinyA.12.1 Font
\tocItemPredefined commands
\tocItemA.21 Available music functions
\tocItemWithDotsMarkup3.3.6 Table of contents
\translateText alignment
\translateA.12.2 Align
\translate-scaledText alignment
\translate-scaledA.12.2 Align
\transparentA.12.8 Other
\transposeSee also
\transposeTranspose
\transposeSee also
\transposeA.21 Available music functions
\transposedCueDuringFormatting cue notes
\transposedCueDuringA.21 Available music functions
\transpositionInstrument transpositions
\transpositionQuoting other voices
\transpositionA.21 Available music functions
\treCordePiano pedals
\triangleGraphic notation inside markup
\triangleA.12.3 Graphic
\trillArticulations and ornamentations
\trillTrills
\trillArticulation scripts
\tripletFeelThe ‘swing’ script
\tupletTuplets
\tupletPolymetric notation
\tupletA.21 Available music functions
\tupletDownTuplets
\tupletNeutralTuplets
\tupletSpanSelected Snippets
\tupletSpanA.21 Available music functions
\tupletUpTuplets
\turnArticulations and ornamentations
\turnArticulation scripts
\tweak5.3.4 The \tweak command
\tweak5.3.5 \set vs. \override
\tweakA.21 Available music functions
\typeContext definition overview
\typeContext definition overview
\typewriterA.12.1 Font
\unaCordaPiano pedals
\underlineSelecting font and font size
\underlineA.12.1 Font
\undertieA.12.1 Font
\undo \offset as an override
\undoA.21 Available music functions
\unfoldedAlternative endings
\unfoldedA.21 Available music functions
\unfoldRepeatsAlternative endings
\unfoldRepeats3.6.6 Using repeats with MIDI
\unfoldRepeatsA.21 Available music functions
\unHideNotesHidden notes
\unlessCustom layout for headers and footers
\unlessA.12.5 Conditionals
\unset5.3.2 The \set command
\upbowArticulations and ornamentations
\upbowBowing indications
\upbowFermata scripts
\upmordentArticulations and ornamentations
\upmordentArticulation scripts
\upprallArticulations and ornamentations
\upprallArticulation scripts
\uprightA.12.1 Font
\varcodaArticulations and ornamentations
\varcodaA.12.4 Music
\varcodaInstrument-specific scripts
\vcenterA.12.2 Align
\verbatim-fileA.12.8 Other
\version3.2.5 File structure
\versus Special signs
\verylongfermataArticulations and ornamentations
\verylongfermataOrnament scripts
\veryshortfermataArticulations and ornamentations
\veryshortfermataOrnament scripts
\virgaGregorian square neume ligatures
\virgaPredefined commands
\virgulaPredefined commands
\voiceFourSingle-staff polyphony
\voiceFourStyleVoice styles
\voiceNeutralStyleVoice styles
\voiceOneSingle-staff polyphony
\voiceOneStyleVoice styles
\voices Voice order
\voicesA.21 Available music functions
\voiceThreeSingle-staff polyphony
\voiceThreeStyleVoice styles
\voiceTwoSingle-staff polyphony
\voiceTwoStyleVoice styles
\void3.7.1 Displaying LilyPond notation
\voidA.21 Available music functions
\voltaAlternative endings
\voltaAlternative endings
\voltaA.21 Available music functions
\vshapeA.21 Available music functions
\vspaceText alignment
\vspaceA.12.2 Align
\walkerHeadsShape note heads
\walkerHeadsMinorShape note heads
\whiteoutA.12.8 Other
\whiteTriangleMarkupCustomizing chord names
\with5.1.4 Modifying context plug-ins
\withChanging just one specific context
\with-colorColoring objects
\with-colorA.12.8 Other
\with-dimensionA.12.8 Other
\with-dimension-fromA.12.8 Other
\with-dimensionsA.12.8 Other
\with-dimensions-fromA.12.8 Other
\with-linkA.12.8 Other
\with-outlineA.12.8 Other
\with-string-transformerA.12.1 Font
\with-true-dimensionA.12.8 Other
\with-true-dimensionsA.12.8 Other
\with-urlA.12.3 Graphic
\withMusicPropertyA.21 Available music functions
\woodwind-diagramA.12.6 Instrument Specific Markup
\wordwrapText alignment
\wordwrapA.12.2 Align
\wordwrap-fieldA.12.2 Align
\wordwrap-internalA.13 Text markup list commands
\wordwrap-linesText markup introduction
\wordwrap-linesA.13 Text markup list commands
\wordwrap-stringA.12.2 Align
\wordwrap-string-internalA.13 Text markup list commands
\xNoteSpecial note heads
\xNoteA.21 Available music functions
\xNotesOffSpecial note heads
\xNotesOnSpecial note heads
\[Ligatures
\]Ligatures

]
]Manual beams

^
^Extended and altered chords
^Articulation direction indicators

_
_Multiple syllables to one note
_Articulation direction indicators

`
‘accent’ articulationArticulations and ornamentations
‘accent’ articulationA.15 List of articulations
‘accentus’ Gregorian articulationGregorian articulation signs
‘accentus’ Gregorian articulationRepeat sign scripts
‘circulus’ Gregorian articulationGregorian articulation signs
‘circulus’ Gregorian articulationRepeat sign scripts
‘coda’ signArticulations and ornamentations
‘coda’ signInstrument-specific scripts
‘coda’ sign, manualManual repeat marks
‘coda’ sign, variantArticulations and ornamentations
‘coda’ sign, variantSegno repeat appearance
‘coda’ sign, variantInstrument-specific scripts
‘coda’ sign, with repeatsSegno repeat structure
‘down pralltriller’ ornamentArticulations and ornamentations
‘down pralltriller’ ornamentArticulation scripts
‘down-bow’ bowing indicationArticulations and ornamentations
‘down-bow’ bowing indicationFermata scripts
‘episem finis’ Gregorian articulationGregorian articulation signs
‘episem initium’ Gregorian articulationGregorian articulation signs
‘espressivo’ articulationArticulations and ornamentations
‘espressivo’ articulationA.15 List of articulations
‘flageolet’ harmonicsArticulations and ornamentations
‘flageolet’ harmonicsFermata scripts
‘half open’ articulationArticulations and ornamentations
‘half open’ articulationFermata scripts
‘Haydn turn’ ornamentArticulations and ornamentations
‘Haydn turn’ ornamentArticulation scripts
‘heel’ pedal markArticulations and ornamentations
‘heel’ pedal markFermata scripts
‘ictus’ Gregorian articulationGregorian articulation signs
‘ictus’ Gregorian articulationRepeat sign scripts
‘lower mordent’ ornamentArticulations and ornamentations
‘lower mordent’ ornamentArticulation scripts
‘marcato’ articulationArticulations and ornamentations
‘marcato’ articulationA.15 List of articulations
‘mordent’ ornamentArticulations and ornamentations
‘mordent’ ornamentArticulation scripts
‘mordent, lower’ ornamentArticulations and ornamentations
‘mordent, lower’ ornamentArticulation scripts
‘mordent, upper’ ornamentArticulations and ornamentations
‘mordent, upper’ ornamentArticulation scripts
‘open’ articulationArticulations and ornamentations
‘open’ articulationSelected Snippets
‘open’ articulationFermata scripts
‘portato’ articulationArticulations and ornamentations
‘portato’ articulationA.15 List of articulations
‘pralltriller’ ornamentArticulations and ornamentations
‘pralltriller’ ornamentArticulation scripts
‘pralltriller, down’ ornamentArticulations and ornamentations
‘pralltriller, down’ ornamentArticulation scripts
‘pralltriller, long’ ornamentArticulations and ornamentations
‘pralltriller, long’ ornamentArticulation scripts
‘pralltriller, up’ ornamentArticulations and ornamentations
‘pralltriller, up’ ornamentArticulation scripts
‘reverse turn’ ornamentArticulations and ornamentations
‘reverse turn’ ornamentArticulation scripts
‘segno’ signArticulations and ornamentations
‘segno’ signInstrument-specific scripts
‘segno’ sign, bar lineBar lines
‘segno’ sign, bar lineSegno repeat appearance
‘segno’ sign, manualManual repeat marks
‘segno’ sign, with repeatsSegno repeat structure
‘segno’ sign, with repeatsSegno repeat appearance
‘semicirculus’ Gregorian articulationGregorian articulation signs
‘semicirculus’ Gregorian articulationRepeat sign scripts
‘signum congruentiae’ mensural notationRepeat sign scripts
‘signum congruentiae’ ornamentArticulations and ornamentations
‘slash turn’ ornamentArticulations and ornamentations
‘slash turn’ ornamentArticulation scripts
‘snappizzicato’ signArticulations and ornamentations
‘snappizzicato’ signFermata scripts
‘staccatissimo’ articulationArticulations and ornamentations
‘staccatissimo’ articulationA.15 List of articulations
‘staccato’ articulationArticulations and ornamentations
‘staccato’ articulationA.15 List of articulations
‘stopped’ articulationArticulations and ornamentations
‘stopped’ articulationSelected Snippets
‘stopped’ articulationFermata scripts
‘tenuto’ articulationArticulations and ornamentations
‘tenuto’ articulationA.15 List of articulations
‘thumb’ fingeringArticulations and ornamentations
‘thumb’ fingeringFingering instructions
‘thumb’ fingeringFermata scripts
‘toe’ pedal markArticulations and ornamentations
‘toe’ pedal markFermata scripts
‘trill’ ornamentArticulations and ornamentations
‘trill’ ornamentArticulation scripts
‘turn’ ornamentArticulations and ornamentations
‘turn’ ornamentArticulation scripts
‘up pralltriller’ ornamentArticulations and ornamentations
‘up pralltriller’ ornamentArticulation scripts
‘up-bow’ bowing indicationArticulations and ornamentations
‘up-bow’ bowing indicationFermata scripts
‘upper mordent’ ornamentArticulations and ornamentations
‘upper mordent’ ornamentArticulation scripts

|
|Bar and bar number checks
|Bar and bar number checks

~
~Ties

A
a dueSee also
a due partAutomatic part combining
absoluteAbsolute octave entry
absolute dynamicsDynamics
absolute octave entryAbsolute octave entry
absolute octave specificationAbsolute octave entry
accentSee also
acciaccaturaSee also
acciaccatura, multi-noteKnown issues and warnings
accidentalSee also
AccidentalSee also
accidentalSee also
AccidentalSee also
accidentalSee also
accidental glyph setA.10 Accidental glyph sets
accidental styleAutomatic accidentals
accidental style, choralAutomatic accidentals
accidental style, choral-cautionaryAutomatic accidentals
accidental style, defaultAutomatic accidentals
accidental style, defaultAutomatic accidentals
accidental style, dodecaphonicAutomatic accidentals
accidental style, dodecaphonic-firstAutomatic accidentals
accidental style, dodecaphonic-no-repeatAutomatic accidentals
accidental style, forgetAutomatic accidentals
accidental style, modernAutomatic accidentals
accidental style, modernAutomatic accidentals
accidental style, modern-cautionaryAutomatic accidentals
accidental style, modern-cautionaryAutomatic accidentals
accidental style, modern-voice-cautionaryAutomatic accidentals
accidental style, neo-modernAutomatic accidentals
accidental style, neo-modern-cautionaryAutomatic accidentals
accidental style, neo-modern-voiceAutomatic accidentals
accidental style, neo-modern-voice-cautionaryAutomatic accidentals
accidental style, no-resetAutomatic accidentals
accidental style, pianoAutomatic accidentals
accidental style, piano-cautionaryAutomatic accidentals
accidental style, teachingAutomatic accidentals
accidental style, voiceAutomatic accidentals
accidental, alternate glyphsAlternate accidental glyphs
accidental, and simultaneous notesSee also
accidental, automaticAutomatic accidentals
accidental, cautionaryAccidentals
accidental, GregorianGregorian accidentals and key signatures
accidental, hiding, on tied notes at start of systemSelected Snippets
accidental, in cadenzasUnmetered music
accidental, in chordsSee also
accidental, in unmetered musicUnmetered music
accidental, KievanKievan accidentals
accidental, mensuralMensural accidentals and key signatures
accidental, modern styleAutomatic accidentals
accidental, multi-voiceAutomatic accidentals
accidental, musica fictaAnnotational accidentals (musica ficta)
accidental, on tied noteAccidentals
accidental, parenthesizedAccidentals
accidental, quarter toneSee also
accidental, reminderAccidentals
accidental-interfaceSee also
accidental-suggestion-interfaceSee also
accidental-switch-interfaceSee also
AccidentalCautionarySee also
AccidentalPlacementSee also
AccidentalSuggestionControlling the vertical ordering of scripts
AccidentalSuggestionSee also
Accidental_engraverSee also
Accidental_engraverSee also
Accidental_engraverSee also
accordion2.2.3 Accordion
accordion discant symbolDiscant symbols
accordion register symbolDiscant symbols
accordion shift symbolDiscant symbols
acoustic bassA.17 Percussion notes
acoustic snareA.17 Percussion notes
add-grace-propertyUsing grace note slashes with normal heads
add-stem-supportControlling the placement of chord fingerings
add-toc-item!3.3.6 Table of contents
Adding and removing engraversSee also
adding custom fret diagramPredefined fret diagrams
adding white background, to textA.12.8 Other
addition, in chordsExtended and altered chords
additional voices in polyphonic musicSelected Snippets
additionalPitchPrefixCustomizing chord names
AdHocMarkEventSee also
Advanced command line options for LilyPondInstallation Instructions
aeolianKey signature
afterGraceFractionparser variable
agogoA.17 Percussion notes
Aiken shape note headShape note heads
Aiken shape note head, thin variantSelected Snippets
al codaSegno repeat structure
al fineSegno repeat structure
al nienteSee also
al niente, hairpinMoving the ends of hairpins
align to objectUsing the break-alignable-interface
alignAboveContextSelected Snippets
alignAboveContext5.1.7 Context layout order
alignBelowContextSelected Snippets
alignBelowContextSimple repeats
alignBelowContext5.1.7 Context layout order
Aligning lyrics to a melodySee also
Aligning lyrics to a melodySee also
aligning markupText alignment
aligning markup textText alignment
aligning textText alignment
aligning to cadenzaAligning to cadenzas
alignment, bar numbersAlternative bar numbering
alignment, horizontal, lyricsSelected Snippets
alignment, text, commandsText alignment
alignment, vertical, dynamicsPrinting hairpins in various styles
alignment, vertical, textText alignment
alignment, vertical, text scriptsPrinting hairpins in various styles
alistalist
All context propertiesSee also
All layout objects Resizing individual layout objects
All layout objectsSee also
All layout objects Properties which may be offset
All layout objects Properties which may be offset
All layout objectsSee also
All layout objectsSee also
all-layout-objectsSee also
alla codaSegno repeat structure
alpha transparencyColoring objects
alteration, figured bass, glyphsChanging the positions of figured bass alterations
alteration, figured bass, positionSelected Snippets
Alteration_glyph_engraverSee also
altered chordExtended and altered chords
alternate accidental glyphAlternate accidental glyphs
alternate fretboard tableChordChanges for FretBoards
alternative chord nameCustomizing chord names
alternative endingAlternative endings
alternative ending, and lyricsRepeats with alternative endings
alternative ending, with tiesTies
alternative melody, switching toSwitching to an alternative melody
alternative style of breve notesSelected Snippets
alto clefClef
alto clefA.11 Clef styles
alto varC clefA.11 Clef styles
Amazing Grace bagpipe exampleBagpipe example
AmbitusSee also
ambitusSee also
ambitusSee also
ambitus, line gapAmbitus with multiple voices
ambitus, multiple voicesAdding ambitus per voice
ambitus, per voiceSelected Snippets
ambitus, placementChanging the ambitus gap
ambitus-interfaceSee also
AmbitusAccidentalSee also
ambitusAfterChanging the ambitus gap
AmbitusLineAmbitus with multiple voices
AmbitusNoteHeadSee also
Ambitus_engraverSee also
An extra staff appearsWritten-out repeats
An extra staff appearsAlternative endings
An extra staff appearsSee also
anacrusisSee also
anacrusis, in a repeatSimple repeats
analysis bracket, musicologicalAnalysis brackets
analysis bracket, with labelAnalysis brackets above the staff
ancient clefClef
ancient music clefMensural clefs
ancient music clefA.11 Clef styles
angled hairpinRotating layout objects
annotate-spacing4.6.1 Displaying spacing
AnnotateOutputEventSee also
anthem2.1.5 Choral
appoggiaturaSee also
Arabic improvisationSelected Snippets
Arabic key signaturesArabic key signatures
Arabic maqamExtending notation and tuning systems
Arabic musicReferences for Arabic music
Arabic music exampleArabic music example
Arabic music templateArabic music example
Arabic note nameArabic note names
Arabic semi-flat symbolArabic note names
Arabic time signaturesArabic time signatures
arpeggioSee also
ArpeggioSee also
Arpeggio Properties which may be offset
arpeggio and tiesSelected Snippets
arpeggio bracket, cross-staffCross staff stems
arpeggio bracket, marking divided voicesSelected Snippets
arpeggio symbol, specialArpeggio
arpeggio, cross-staffSelected Snippets
arpeggio, cross-staff parenthesis-styleKnown issues and warnings
arpeggio, cross-voiceCreating cross-staff arpeggios in other contexts
arpeggio-directionArpeggio
articulate scriptThe ‘articulate’ script
articulate.lyThe ‘articulate’ script
articulation, accentArticulations and ornamentations
articulation, accentA.15 List of articulations
articulation, default values, modifyingSelected Snippets
articulation, espressivoArticulations and ornamentations
articulation, espressivoA.15 List of articulations
articulation, GregorianGregorian articulation signs
articulation, Gregorian, accentusGregorian articulation signs
articulation, Gregorian, accentusRepeat sign scripts
articulation, Gregorian, circulusGregorian articulation signs
articulation, Gregorian, circulusRepeat sign scripts
articulation, Gregorian, episem finisGregorian articulation signs
articulation, Gregorian, episem initiumGregorian articulation signs
articulation, Gregorian, ictusGregorian articulation signs
articulation, Gregorian, ictusRepeat sign scripts
articulation, Gregorian, semicirculusGregorian articulation signs
articulation, Gregorian, semicirculusRepeat sign scripts
articulation, half openArticulations and ornamentations
articulation, half openFermata scripts
articulation, marcatoArticulations and ornamentations
articulation, marcatoA.15 List of articulations
articulation, openArticulations and ornamentations
articulation, openSelected Snippets
articulation, openFermata scripts
articulation, portatoArticulations and ornamentations
articulation, portatoA.15 List of articulations
articulation, staccatissimoArticulations and ornamentations
articulation, staccatissimoA.15 List of articulations
articulation, staccatoArticulations and ornamentations
articulation, staccatoA.15 List of articulations
articulation, stoppedArticulations and ornamentations
articulation, stoppedSelected Snippets
articulation, stoppedFermata scripts
articulation, tenutoArticulations and ornamentations
articulation, tenutoA.15 List of articulations
articulation-eventQuoting other voices
articulationsA.15 List of articulations
Articulations and dynamicsSee also
artificial harmonicsHarmonics
associatedVoiceAligning lyrics to a melody
associatedVoiceAutomatic syllable durations
associatedVoiceSwitching to an alternative melody
association listalist
Association lists (alists)See also
augCommon chords
augmentation dot, change number ofAlternative breve notes
auto-beaming, properties for time signaturesTime signature
auto-first-page-number\paper variables for page numbering
autoBeamingSetting automatic beam behavior
autoBeamingOutput definitions – blueprints for contexts
AutoChangeMusicSee also
automatic accidentalAutomatic accidentals
automatic bar lineAutomatic bar lines
automatic chord diagramAutomatic fret diagrams
automatic fret diagramAutomatic fret diagrams
automatic part combiningAutomatic part combining
automatic staff changeChanging staff automatically
Auto_beam_engraverSee also
Auto_beam_engraverSee also
available fonts, listingSingle entry fonts
Axis_group_engraverSee also
Axis_group_engraverSpacing of non-staff lines

B
Backend5.2.1 Navigating the program reference
BackendSee also
BackendSee also
backslashed digitA.12.8 Other
bagpipeBagpipe definitions
bagpipe exampleBagpipe example
balance in MIDI3.6.8 Context properties for MIDI effects
balloonBalloon help
balloon helpBalloon help
balloon-interfaceSee also
BalloonTextSee also
Balloon_engraverBalloon help
banjo tablature2.4 Fretted string instruments
banjo tablatureBanjo tablatures
banjo tuningBanjo tablatures
banjo-c-tuningBanjo tablatures
banjo-double-c-tuningBanjo tablatures
banjo-double-d-tuningBanjo tablatures
banjo-modal-tuningBanjo tablatures
banjo-open-d-tuningBanjo tablatures
banjo-open-dm-tuningBanjo tablatures
banjo-open-g-tuningBanjo tablatures
bar checkBar and bar number checks
bar check, with repeatsSimple repeats
bar lineBar lines
bar line, automaticAutomatic bar lines
bar line, avoided by lyricsKnown issues and warnings
bar line, between stavesBar lines
bar line, between stavesDisplay bracket with only one staff in a system
bar line, cadenzasUnmetered music
bar line, caesuraAutomatic bar lines
bar line, caesuraAutomatic bar lines
bar line, defaultAutomatic bar lines
bar line, default, changingBar lines
bar line, definingBar lines
bar line, doubleBar lines
bar line, doubleAutomatic bar lines
bar line, doubleAutomatic bar lines
bar line, doubleSection divisions
bar line, finalBar lines
bar line, finalAutomatic bar lines
bar line, finalSection divisions
bar line, hairpin, stopping atSelected Snippets
bar line, in ChordNameschord name major7
bar line, in Gregorian chantDivisiones
bar line, in hymnsPhrase bar lines in hymn tunes
bar line, in Kievan chantKievan bar lines
bar line, invisibleBar lines
bar line, list ofA.18 List of bar lines
bar line, manualBar lines
bar line, measureAutomatic bar lines
bar line, phraseAutomatic bar lines
bar line, phraseAutomatic bar lines
bar line, repeatAutomatic bar lines
bar line, sectionAutomatic bar lines
bar line, sectionSection divisions
bar line, segnoBar lines
bar line, segnoAutomatic bar lines
bar line, segnoSegno repeat appearance
bar line, shortBar lines
bar line, singleAutomatic bar lines
bar line, symbols onText marks
bar line, text overText marks
bar line, tickBar lines
bar line, underlying repeatAutomatic bar lines
bar line, unmetered musicUnmetered music
bar numberBar numbers
bar numberTime administration
bar number checkBar and bar number checks
bar number, alignmentAlternative bar numbering
bar number, alternative, in repeatAdding volta brackets to additional staves
bar number, broken measurePrinting bar numbers with changing regular intervals
bar number, cadenzasUnmetered music
bar number, centeredRemoving bar numbers from a score
bar number, collisionSee also
bar number, modulo bar numberPrinting bar numbers for broken measures
bar number, printed at regular intervalsPrinting the bar number for the first measure
bar number, printed in first measureSelected Snippets
bar number, regular spacingBar numbers
bar number, removalAligning bar numbers
bar number, stylePrinting bar numbers using modulo-bar-number-visible
bar number, unmetered musicUnmetered music
bar number, with letter, in repeatAdding volta brackets to additional staves
barCheckSynchronizeBar and bar number checks
baritone clefClef
baritone clefA.11 Clef styles
baritone varC clefA.11 Clef styles
baritone varF clefA.11 Clef styles
BarLineSee also
BarNumberBar numbers
BarNumberKnown issues and warnings
barNumberVisibilityBar numbers
barre indicationFret diagram markups
bartypeBar lines
Bartók pizzicatoSnap (Bartók) pizzicato
Bar_engraverSee also
Bar_number_engraverSee also
base-shortest-duration4.5.1 Horizontal spacing overview
baseMomentSetting automatic beam behavior
baseMomentSelected Snippets
Basic command line options for LilyPond3.5.3 Alternative output formats
bassA.17 Percussion notes
bass clefClef
bass clefA.11 Clef styles
bass note, for chordsExtended and altered chords
bass, figuredIntroduction to figured bass
bass, thoroughIntroduction to figured bass
BassFigureSee also
BassFigureSee also
BassFigureAlignmentSee also
BassFigureAlignmentSee also
BassFigureBracketSee also
BassFigureBracketSee also
BassFigureContinuationSee also
BassFigureContinuationSee also
BassFigureLineSee also
BassFigureLineSee also
basso continuoIntroduction to figured bass
bayatiSee also
BeamSee also
BeamSee also
BeamSee also
BeamSee also
BeamSee also
beam, cadenzasUnmetered music
beam, cross-staffChanging staff manually
beam, customizing rulesAutomatic beams
beam, endings, in a scoreConducting signs, measure grouping signs
beam, endings, with multiple voicesConducting signs, measure grouping signs
beam, featheredFeathered beams
beam, horizontalSelected Snippets
beam, in tablatureSelected Snippets
beam, line breaksPredefined commands
beam, line breaksSelected Snippets
beam, manualAutomatic beams
beam, manualManual beams
beam, nibsSelected Snippets
beam, subdividingSelected Snippets
beam, unmetered musicUnmetered music
beam, with knee gapPredefined commands
beam, with knee gap, changingBeams across line breaks
beam, with lyricsSetting automatic beam behavior
beam, with melismaAutomatic beams
beam, with polymetric meters Different time signatures with equal-length measures
beam, \partCombine with \autoBeamOffChanging beam knee gap
beam-interfaceSee also
beam-interfaceSee also
beam-interfaceSee also
beamed tuplet, line break withinPrinting tuplet brackets on the note head side
BeamEventSee also
BeamEventSee also
BeamForbidEventSee also
BeamForbidEventSee also
beaming, strict-beatSubdividing beams
beaming, time signature default propertiesTime signature
beamlet, orientationSubdividing beams
Beam_engraverSee also
Beam_engraverSee also
beat repeatPercent repeats
beat, groupingStrict beat beaming
beats per minuteMetronome marks
beatStructureSetting automatic beam behavior
beatStructureSelected Snippets
beginners’ musicEasy notation note heads
bending, string, in tablature notationDefault tablatures
big point (bp)5.4.2 Distances and measurements
binding gutter\paper variables for two-sided mode
binding-offset\paper variables for two-sided mode
bisbigliandoReferences for harps
Bisonparser
blackmensural clefMensural clefs
blackmensural clefA.11 Clef styles
blank-after-score-page-penalty\paper variables for page breaking
blank-last-page-penalty\paper variables for page breaking
blank-page-penalty\paper variables for page breaking
block comment3.2.1 Structure of a score
block comment3.2.5 File structure
BNFparser
bongoA.17 Percussion notes
bookmarks3.3.5 Reference to page numbers
bookmarks3.3.6 Table of contents
bookpart-level-page-numbering\paper variables for page numbering
bookTitleMarkupCustom layout for titles
bottom-margin4.1.3 Fixed vertical spacing \paper variables
bounding box5.4.3 Dimensions
bounding box, of glyphA.12.8 Other
bowing indicationBowing indications
bowing, downArticulations and ornamentations
bowing, downFermata scripts
bowing, upArticulations and ornamentations
bowing, upFermata scripts
braceSee also
brace, at start of single staffUse square bracket at the start of a staff group
brace, nesting ofNested staff groups
brace, various sizesMusic fonts
brace, verticalGrouping staves
bracketPiano pedals
bracketAnalysis brackets
bracket, angleChorded notes
bracket, at start of single staffUse square bracket at the start of a staff group
bracket, cross-staffCross staff stems
bracket, horizontalAnalysis brackets
bracket, nesting ofNested staff groups
bracket, phrasingAnalysis brackets
bracket, phrasing, with labelAnalysis brackets above the staff
bracket, square, at start of staff groupSelected Snippets
bracket, verticalGrouping staves
bracket, vertical, marking divided voicesSelected Snippets
bracket, voltaManual repeat marks
break align symbol4.5.4.2 Spacing between adjacent non-musical items
break, in unmetered musicUnmetered music
break-align-symbolsUsing the break-alignable-interface
break-alignable-interfaceSee also
break-alignable-interfaceUsing the break-alignable-interface
break-aligned-interface4.5.4.2 Spacing between adjacent non-musical items
break-aligned-interfaceSee also
break-aligned-interfaceUsing the break-alignable-interface
break-alignment-interface4.5.4.2 Spacing between adjacent non-musical items
break-alignment-interfaceSee also
break-alignment-interfaceUsing the break-alignable-interface
break-visibilityUsing break-visibility
breakablePredefined commands
breakable glissandoAdding timing marks to long glissandi
BreakAlignGroupSee also
BreakAlignmentSee also
breakbeforeDefault layout of bookpart and score titles
breaking lines4.3.1 Line breaking
breaking pages4.5.5 Line width
Break_align_engraverSee also
breath markSee also
breath mark symbol, changingBreath marks
breath mark symbol, list ofA.16 List of breath marks
BreathingEventSee also
BreathingSignSee also
BreathingSignSee also
Breathing_sign_engraverSee also
breveSee also
breveSee also
breve note, alternative styleSelected Snippets
breve restRests
broken chordArpeggio
broken spanner, modifyingModifying broken spanners
Built-in templatesReferences for choral
Bézier curve, control pointsModifying ties and slurs

C
C clefClef
C clefA.11 Clef styles
cabasaA.17 Percussion notes
cadenzaSee also
cadenzaSee also
cadenza, accidentalsUnmetered music
cadenza, aligning toAligning to cadenzas
cadenza, bar linesUnmetered music
cadenza, bar numbersUnmetered music
cadenza, beamsUnmetered music
cadenza, line breaksUnmetered music
cadenza, page breaksUnmetered music
caesuraSee also
caesuraSee also
caesura bar lineAutomatic bar lines
caesura bar lineAutomatic bar lines
caesura bar line, in hymnsPhrase bar lines in hymn tunes
caesura bar line, in Kievan chantKievan bar lines
CaesuraEventSee also
CaesuraScriptSee also
CaesuraScriptSee also
caesuraTypeSee also
caesuraTypeTransformSee also
Caesura_engraverSee also
callbackcallback
Callback functionsSee also
canticle2.1.7 Chants psalms and hymns
canticleSelected Snippets
capoFret diagram markups
cautionary accidentalAccidentals
centered dynamics in piano musicReferences for keyboards
CenteredBarNumberSee also
CenteredBarNumberLineSpannerSee also
Centered_bar_number_align_engraverSee also
centering column of textA.12.2 Align
centering text on pageText alignment
centimeter (cm)5.4.2 Distances and measurements
change number of augmentation dotsAlternative breve notes
change tempo without metronome markPrinting metronome and rehearsal marks below the staff
change tuplet numberEntering several tuplets using only one tuplet command
changing breath mark symbolBreath marks
changing chord separatorVolta below chords
changing direction of text columnA.12.2 Align
changing fontSelecting font and font size
changing instrument nameInstrument names
changing property5.3.2 The \set command
changing staff automaticallyChanging staff automatically
changing staff manuallyChanging staff manually
chant2.1.7 Chants psalms and hymns
chantSelected Snippets
character nameCharacter names
chart, fingeringFingering symbols for wind instruments
check markBreath marks
check-consistency\paper variables for widths and margins
chinese cymbalA.17 Percussion notes
choir staffGrouping staves
ChoirStaffSee also
ChoirStaffSee also
ChoirStaffSee also
choralAutomatic accidentals
choral accidental styleAutomatic accidentals
choral tenor clefClef
choral-cautionaryAutomatic accidentals
choral-cautionary accidental styleAutomatic accidentals
chordSee also
chordSee also
chordSee also
chord diagramFret diagram markups
chord diagramPredefined fret diagrams
chord diagram, automaticAutomatic fret diagrams
chord gridSee also
chord inversionChord inversions and specific voicings
chord modeChord mode overview
chord nameChord mode overview
chord namePrinting chord names
chord name, with fret diagramsPredefined fret diagrams
chord names, exceptionsSelected Snippets
chord qualityCommon chords
chord separator, changingVolta below chords
chord shape, for fretted instrumentPredefined fret diagrams
chord step, alteringExtended and altered chords
chord voicingChord inversions and specific voicings
chord, accidentals inSee also
chord, alternative nameCustomizing chord names
chord, and relative octave entryRelative octave entry
chord, and tieTies
chord, brokenArpeggio
chord, cross-staffSelected Snippets
chord, emptyTweaking grace layout within music
chord, emptyDynamics
chord, emptyChorded notes
chord, emptyChanging staff manually
chord, fingeringFingering instructions
chord, glissando, in tablaturesSlides in tablature
chord, jazzCustomizing chord names
chord, major 7, layoutChord name exceptions
chord, modifying one note in5.3.4 The \tweak command
chord, powerIndicating power chords
chord, relative pitchChorded notes
chord, repetitionChord repetition
chord, repetitionDefault tablatures
chord, rotatingChord inversions and specific voicings
chord, splitting across staves with \autoChangeKnown issues and warnings
chord, suppressing repeatedDefining predefined fretboards for other instruments
chord, suppressing repeatedSelected Snippets
chordChangesDefining predefined fretboards for other instruments
chordChangesSelected Snippets
ChordGridChord grids
ChordGridScoreSee also
ChordNameSee also
chordNameExceptionsCustomizing chord names
chordNameExceptionsSelected Snippets
chordNameLowercaseMinorCustomizing chord names
ChordNamesPredefined fret diagrams
ChordNamesSee also
ChordNames, with bar lineschord name major7
chordNameSeparatorCustomizing chord names
chordNameSeparatorVolta below chords
chordNoteNamerCustomizing chord names
chordPrefixSpacerCustomizing chord names
chordRootNamerCustomizing chord names
chords, volta repeat, belowAdding bar lines to ChordNames context
ChordSquareSee also
Chord_name_engraverSee also
Chord_square_engraverSee also
chorus level in MIDI3.6.8 Context properties for MIDI effects
Christian Harmony note headShape note heads
church modeSee also
church restNumbering single measure rests
circling textA.12.3 Graphic
clavesA.17 Percussion notes
ClefSee also
clefSee also
ClefSee also
clefSee also
clefSee also
clefKievan clefs
clef styleMensural clefs
clef styleA.11 Clef styles
clef, altoClef
clef, altoA.11 Clef styles
clef, alto varCA.11 Clef styles
clef, ancientClef
clef, ancient musicMensural clefs
clef, ancient musicA.11 Clef styles
clef, baritoneClef
clef, baritone varCA.11 Clef styles
clef, baritone varFA.11 Clef styles
clef, bassClef
clef, bassA.11 Clef styles
clef, blackmensuralMensural clefs
clef, blackmensuralA.11 Clef styles
clef, CClef
clef, CA.11 Clef styles
clef, FClef
clef, FA.11 Clef styles
clef, frenchClef
clef, frenchA.11 Clef styles
clef, GClef
clef, GA.11 Clef styles
clef, G2A.11 Clef styles
clef, GGA.11 Clef styles
clef, KievanMensural clefs
clef, KievanA.11 Clef styles
clef, mensuralMensural clefs
clef, mensuralA.11 Clef styles
clef, mezzosopranoClef
clef, mezzosopranoA.11 Clef styles
clef, moderntabCustom tablatures
clef, percussionBasic percussion notation
clef, percussionA.11 Clef styles
clef, PetrucciMensural clefs
clef, PetrucciA.11 Clef styles
clef, sopranoClef
clef, sopranoA.11 Clef styles
clef, subbassClef
clef, subbassA.11 Clef styles
clef, tabCustom tablatures
clef, tabA.11 Clef styles
clef, tenorClef
clef, tenorA.11 Clef styles
clef, tenor GA.11 Clef styles
clef, tenor varCA.11 Clef styles
clef, transposingClef
clef, trebleClef
clef, trebleA.11 Clef styles
clef, tweaking propertiesSelected Snippets
clef, varbaritoneClef
clef, varbaritoneA.11 Clef styles
clef, varCA.11 Clef styles
clef, violinClef
clef, violinA.11 Clef styles
clef, visibility following explicit change Visibility following explicit changes
clef, visibility of transposition Transposed clefs
clef, with cue notesClef
clef-interfaceSee also
clef-interfaceSee also
ClefModifierSee also
ClefModifierSee also
Clef_engraverSee also
Clef_engraverSee also
clip-regions3.5 Controlling output
closureclosure
clusterSee also
ClusterSpannerSee also
ClusterSpannerBeaconSee also
Cluster_spanner_engraverSee also
codaSegno repeat structure
coda sign, variantInstrument-specific scripts
CodaMarkSee also
CodaMarkSee also
collisionCollision resolution
collision, bar numberSee also
collision, cross-staff voicesChanging staff manually
collision, ignoringSimultaneous expressions
collision, ignoringSee also
colorColoring objects
color blindColoring objects
color in chordSee also
color, css-like codesColoring objects
color, list ofNormal colors
color, rgbColoring objects
color, suitable for dichromatismColor-blind-safe colors
colored noteColoring objects
colored note in chordSee also
colored objectColoring objects
coloring noteColoring objects
coloring objectColoring objects
coloring objectPainting objects white
coloring textA.12.8 Other
coloring voiceVoice styles
column4.5.4.1 Overview of object-specific horizontal spacing tweaks
column, textSelected Snippets
column, textText alignment
Combining notes into chordsSee also
combining partsAutomatic part combining
combining parts, changing textCombining two parts on the same staff
comma intervalReferences for Turkish classical music
Command-line usageSee also
comment3.2.1 Structure of a score
comment3.2.5 File structure
Common Practice PeriodSee also
Common Practice PeriodSee also
common-shortest-duration4.5.1 Horizontal spacing overview
Completion_heads_engraverAutomatic note splitting
Completion_rest_engraverAutomatic note splitting
compound time signature Different time signatures with unequal-length measures
compressing musicScaling durations
concatenating textA.12.2 Align
concert pitchSee also
condensing restsKnown issues and warnings
conducting signsStrict beat beaming
congaA.17 Percussion notes
constante hairpinPrinting hairpins using al niente notation
contemporary glissandoSelected Snippets
context definitions with MIDISetting MIDI block properties
context property, changing default5.1.5 Changing context default settings
context, adding aliasContext definition overview
context, creating and referencing5.1.2 Creating and referencing contexts
context, defining in MIDINew contexts in MIDI
context, defining newContext definition overview
context, implicit5.1.7 Context layout order
context, keeping alive5.1.3 Keeping contexts alive
context, layout order5.1.7 Context layout order
context, lifetime5.1.3 Keeping contexts alive
context, Score-levelReplacing the Score context
context-spec-musicSelected Snippets
ContextChangeSee also
ContextsWithin-system spacing properties
ContextsSee also
ContextsSee also
ContextsSee also
Contexts5.1.4 Modifying context plug-ins
ContextsSee also
Contexts and engravers The double backslash construct
Contexts and engraversSee also
contexts, overlayingGrouping staves
continuation, of notes2.8.3 Graphical notation
control pitchOctave checks
control point, Bézier curveModifying ties and slurs
control point, tweakingKnown issues and warnings
controlling general text alignmentA.12.2 Align
controlpitchOctave checks
copyright signUnicode
count visibility of percent repeatsPercent repeat counter
counter, percent repeatSelected Snippets
countPercentRepeatsSelected Snippets
cowbellA.17 Percussion notes
crash cymbalA.17 Percussion notes
creating a tableA.13 Text markup list commands
creating empty text objectA.12.8 Other
creating horizontal space, in textA.12.2 Align
creating text fractionA.12.8 Other
creating vertical space, in textA.12.2 Align
creating vertical space, in textA.12.8 Other
crescendoSee also
crescendo-eventQuoting other voices
crescendoSpannerHiding the extender line for text dynamics
crescendoTextHiding the extender line for text dynamics
crossSpecial note heads
cross note headSpecial note heads
cross-staff arpeggioSelected Snippets
cross-staff arpeggio bracketCross staff stems
cross-staff beamChanging staff manually
cross-staff chordSelected Snippets
cross-staff collisionChanging staff manually
cross-staff lineStaff-change lines
cross-staff noteChanging staff manually
cross-staff noteSelected Snippets
cross-staff parenthesis-style arpeggioKnown issues and warnings
cross-staff stemSelected Snippets
cross-staff tremoloSelected Snippets
cross-voice arpeggioCreating cross-staff arpeggios in other contexts
css color codesColoring objects
cue clefClef
cue noteQuoting other voices
cue noteFormatting cue notes
cue note, formattingFormatting cue notes
cue note, removingFormatting cue notes
cue, in vocal scoreSelected Snippets
cue, musicalMusical cues
cue-notesSee also
CueVoiceFormatting cue notes
CueVoiceSee also
cuicaA.17 Percussion notes
currentBarNumberBar numbers
currentBarNumberTime administration
custodesCustodes
custom fret diagramFret diagram markups
custom fret diagramChanging fret orientations
custom fret diagram, addingPredefined fret diagrams
custom fretboard fret diagramSelected Snippets
custom metronome mark markupChanging the tempo without a metronome mark
custom rehearsal markRehearsal marks
custom string tuningCustom tablatures
customized fret diagramFret diagram markups
customizing chord nameCustomizing chord names
custosSee also
CustosSee also
custosSee also
cymbal, variousA.17 Percussion notes

D
D.C.Segno repeat structure
D.C., manualManual repeat marks
D.S.Segno repeat structure
D.S., forced at startSegno repeat appearance
D.S., manualManual repeat marks
da capoSee also
da capo, manualManual repeat marks
dal segnoSee also
dal segno, forced at startSegno repeat appearance
dal segno, manualManual repeat marks
dampened note, on fretted instrumentIndicating harmonics and dampened notes
dash patterns, slurSlurs
dash patterns, slurPositioning text markups inside slurs
dashed phrasing slurPhrasing slurs
dashed slurSlurs
dashed tieTies
dead note, percussionGhost notes
debug-beam-scoring\paper variables for debugging
debug-slur-scoring\paper variables for debugging
debug-tie-scoring\paper variables for debugging
Debugging scoring algorithms\paper variables for debugging
decorating textGraphic notation inside markup
decrescendoSee also
decrescendoSpannerHiding the extender line for text dynamics
decrescendoTextHiding the extender line for text dynamics
defaultAutomatic accidentals
defaultAutomatic accidentals
default accidental styleAutomatic accidentals
default accidental styleAutomatic accidentals
default bar lineAutomatic bar lines
default bar line, changingBar lines
default context property, changing5.1.5 Changing context default settings
default note durationDurations
default note nameAccidentals
default pitchDurations
default vertical direction (-)Articulation direction indicators
default, offsetting5.3.6 The \offset command
default-staff-staff-spacingWithin-system spacing properties
define predefined fretboardCustomizing fretboard fret diagrams
defining bar lineBar lines
delayed turn ornamentationControlling the vertical ordering of scripts
desk parts1.6.3 Writing parts
diagram, chord for fretted instrumentsFret diagram markups
diagram, fretFret diagram markups
diagram, fret, customizedFret diagram markups
diagram, fret, transposingPredefined fret diagrams
diamond note headSpecial note heads
diamond-shaped note headHarmonics
dichromatism, suitable colorsColor-blind-safe colors
Difficult tweaksSee also
dimCommon chords
dimension5.4.3 Dimensions
dimension units5.4.2 Distances and measurements
dimensions, of bounding boxA.12.8 Other
diminuendoDynamics
direction, automatic, of stem, on center lineDefault direction of stems on the center line of the staff
direction, default (-)Articulation direction indicators
direction, default, of stem, on center lineSelected Snippets
direction, down (_)Articulation direction indicators
direction, up (^)Articulation direction indicators
discant symbol, accordionDiscant symbols
Displaying music expressions3.7.2 Displaying scheme music expressions
Displaying music expressions5.3.4 The \tweak command
Displaying music expressionsSee also
distance, absolute5.4.2 Distances and measurements
distance, between staves4.4.1 Flexible vertical spacing within systems
distance, scaled5.4.2 Distances and measurements
divided lyricsDivisi lyrics
divided voicesSelected Snippets
divisi stavesHiding staves
divisioSee also
DivisioSee also
divisionesDivisiones
dodecaphonicAutomatic accidentals
dodecaphonic accidental styleAutomatic accidentals
dodecaphonic-firstAutomatic accidentals
dodecaphonic-first accidental styleAutomatic accidentals
dodecaphonic-no-repeatAutomatic accidentals
dodecaphonic-no-repeat accidental styleAutomatic accidentals
doitSee also
dorianKey signature
DotColumnSee also
DotsSee also
dotted noteDurations
dotted note, change number of dotsAlternative breve notes
dotted note, moving horizontallyAdditional voices to avoid collisions
dotted phrasing slurPhrasing slurs
dotted slurSlurs
dotted tieTies
double bar lineBar lines
double bar lineAutomatic bar lines
double bar lineAutomatic bar lines
double bar lineSection divisions
double flatSee also
double sharpSee also
double slurs, for legato chordsSelected Snippets
double-dotted noteDurations
double-time signaturePolymetric notation
DoublePercentEventSee also
DoublePercentRepeatSee also
DoublePercentRepeatCounterSee also
DoubleRepeatSlashSee also
doubleSlursSelected Snippets
Double_percent_repeat_engraverSee also
down direction (_)Articulation direction indicators
down-bow indicationBowing indications
drawing beam, within textA.12.3 Graphic
drawing box, with rounded cornersA.12.3 Graphic
drawing box, with rounded corners, around textA.12.3 Graphic
drawing circle, within textA.12.3 Graphic
drawing dashed line, within textA.12.3 Graphic
drawing dotted line, within textA.12.3 Graphic
drawing ellipse, around textA.12.3 Graphic
drawing graphic objectGraphic notation inside markup
drawing line, across a pageA.12.3 Graphic
drawing line, within textA.12.3 Graphic
drawing oval, around textA.12.3 Graphic
drawing pathA.12.3 Graphic
drawing polygonA.12.3 Graphic
drawing solid box, within textA.12.3 Graphic
drawing squiggled line, within textA.12.3 Graphic
drawing triangle, within textA.12.3 Graphic
drumBasic percussion notation
drumPercussion staves
drum staffInstantiating new staves
drum, variousA.17 Percussion notes
drumPitchNamesCustom percussion staves
drumPitchTableCustom percussion staves
DrumStaffInstantiating new staves
DrumStaffSee also
drumStyleTableCustom percussion staves
DrumVoiceSee also
duration line2.8.3 Graphical notation
Duration names notes and restsSee also
duration, defaultDurations
duration, isolatedDurations
duration, of noteDurations
duration, scalingScaling durations
dynamic mark, multiple on one noteDynamics
dynamic mark, newNew dynamic marks
dynamic-eventQuoting other voices
DynamicLineSpannerDynamics
DynamicLineSpannerPrinting hairpins in various styles
dynamicsDynamics
DynamicsSee also
dynamics in MIDI3.6.4 Controlling MIDI dynamics
dynamics in MIDI, customSelected Snippets
dynamics, absoluteDynamics
dynamics, centered in keyboard musicReferences for keyboards
dynamics, editorialNew dynamic marks
dynamics, extender line, hidingVertically aligned dynamics and textscripts
dynamics, parenthesisNew dynamic marks
dynamics, text spanner, customizeSelected Snippets
dynamics, text, styleHiding the extender line for text dynamics
dynamics, vertical alignmentPrinting hairpins in various styles
dynamics, vertical positioningDynamics
DynamicTextSee also
Dynamic_performerCreating custom dynamics in MIDI output
Dynamic_performerSee also
Dynamic_performerSee also

E
easy notationEasy notation note heads
easy notation, using numbersSelected Snippets
easy play note headEasy notation note heads
editorial dynamicsNew dynamic marks
effects in MIDI3.6.8 Context properties for MIDI effects
electric snareA.17 Percussion notes
embedded graphicsGraphic notation inside markup
embedding graphic objectGraphic notation inside markup
Emmentaler fontA.8 The Emmentaler font
empty chordTweaking grace layout within music
empty chordDynamics
empty chordChanging staff manually
empty staffHiding staves
encapsulated postscript output3.5.3 Alternative output formats
enclosing text in box, with rounded cornersA.12.3 Graphic
enclosing text within a boxA.12.1 Font
end repeatManual repeat marks
engraver, including in contextContext definition overview
Engravers and PerformersSee also
Engravers and Performers5.1.4 Modifying context plug-ins
Engravers and PerformersSee also
Engravers explainedSee also
Engraver_groupContext definition overview
ensemble musicReferences for opera and stage musicals
entering lyricsEntering lyrics
entering multiple tupletsSelected Snippets
EpisemaSee also
EpisemaEventSee also
Episema_engraverSee also
EPS output3.5.3 Alternative output formats
equalization, instrument, replacing MIDI defaultSelected Snippets
espressivo articulationDynamics
exception, chord namesSelected Snippets
expanding musicScaling durations
explicitClefVisibility Visibility following explicit changes
explicitKeySignatureVisibility Visibility following explicit changes
Explicitly instantiating voices The double backslash construct
Explicitly instantiating voicesSee also
expression in MIDI3.6.8 Context properties for MIDI effects
expression, markupText markup introduction
extended chordExtended and altered chords
extenderExtenders and hyphens
extender line, dynamics, hidingVertically aligned dynamics and textscripts
extent, of actual inkingA.12.8 Other
extent, of bounding boxA.12.8 Other
extra natural sign, preventingHiding accidentals on tied notes at the start of a new system
extra voice for handling breaksSelected Snippets
extra-offsetWithin-system spacing properties
extra-spacing-height4.5.4.3 Spacing between adjacent columns
extra-spacing-width4.5.4.3 Spacing between adjacent columns
Ez_numbers_engraverSelected Snippets

F
F clefClef
F clefA.11 Clef styles
fallSee also
false note, percussionGhost notes
feathered beamFeathered beams
feature, OpenType fontFont features
feature, OpenType fontA.12.1 Font
fermataArticulations and ornamentations
fermataOrnament scripts
fermata, HenzeArticulations and ornamentations
fermata, HenzeOrnament scripts
fermata, longArticulations and ornamentations
fermata, longOrnament scripts
fermata, on bar lineSelected Snippets
fermata, on multi-measure restFull measure rests
fermata, shortArticulations and ornamentations
fermata, shortOrnament scripts
Ferneyhough hairpinPrinting hairpins using al niente notation
Feta fontA.8 The Emmentaler font
fifthSee also
figured bassSee also
figured bass, alignmentPredefined commands
figured bass, alteration, glyphsChanging the positions of figured bass alterations
figured bass, alteration, positionSelected Snippets
figured bass, extender linesPredefined commands
figured bass, vertical distance of elementsDisplaying figured bass
FiguredBassSee also
FiguredBassSee also
FiguredBassSee also
figuredBassAlterationDirectionSelected Snippets
figuredBassPlusDirectionSelected Snippets
figuredBassPlusStrokedAlistChanging the positions of figured bass alterations
final bar lineBar lines
final bar lineAutomatic bar lines
final bar lineSection divisions
final bar line, in Gregorian chantDivisiones
final bar line, in Kievan chantKievan bar lines
finalisDivisiones
finding available fontsSingle entry fonts
fineSee also
fineSee also
fineSee also
FineEventSee also
FineEventSee also
finger changeFingering instructions
finger-glide-interfaceSee also
finger-interface5.2.2 Layout interfaces
FingerGlideSpannerSee also
fingeringFingering instructions
FingeringSee also
FingeringSee also
Fingering5.2.1 Navigating the program reference
Fingering5.2.1 Navigating the program reference
Fingering5.2.1 Navigating the program reference
Fingering5.2.1 Navigating the program reference
Fingering5.2.2 Layout interfaces
Fingering5.2.2 Layout interfaces
fingering chartFingering symbols for wind instruments
fingering chordFingering instructions
fingering instruction, for chordsFingering instructions
fingering vs. string numberString number indications
fingering, adding to fret diagramAutomatic fret diagrams
fingering, and multi-measure restSee also
fingering, glideGliding fingers
fingering, inside of staffControlling the placement of chord fingerings
fingering, orientationSelected Snippets
fingering, right-hand, for fretted instrumentsRight-hand fingerings
fingering, right-hand, placementSelected Snippets
fingering, stem supportControlling the placement of chord fingerings
fingering, symbols for wind instrumentsSelected Snippets
fingering, thumbArticulations and ornamentations
fingering, thumbFingering instructions
fingering, thumbFermata scripts
fingering-eventSee also
fingering-event5.2.1 Navigating the program reference
fingering-event5.2.1 Navigating the program reference
fingering-glide-eventSee also
FingeringEventSee also
FingeringEvent5.2.1 Navigating the program reference
FingeringGlideEventSee also
fingeringOrientationsSelected Snippets
Fingering_engraverSee also
Fingering_engraver5.2.1 Navigating the program reference
Fingering_engraver5.2.1 Navigating the program reference
Fingering_engraver5.2.1 Navigating the program reference
Fingering_engraver5.2.3 Determining the grob property
Finger_glide_engraverSee also
first-page-number\paper variables for page numbering
Fixing overlappingChanging staff manually
Fixing overlapping notationChanging staff manually
Fixing overlapping notationSee also
flagSee also
flagSee also
flag, mensuralMensural flags
flags, flatSelected Snippets
flared hairpinPrinting hairpins using al niente notation
flatSee also
flat flagsSelected Snippets
flat, doubleAccidentals
Flexlexer
Flexible architectureText objects overview
Flexible architectureSee also
floor tom tomA.17 Percussion notes
follow voiceStaff-change lines
followVoiceStaff-change lines
fontglyph
font familySelecting font and font size
font family, settingEntire document fonts
font feature, OpenTypeFont features
font feature, OpenTypeA.12.1 Font
font sizeSelecting font and font size
font size (notation)Selecting notation font size
font size (notation), scalingSelecting notation font size
font size (notation), standard Understanding the fontSize property
font size, setting4.2.2 Setting the staff size
font switchingSelecting font and font size
font, changing for entire documentEntire document fonts
font, EmmentalerA.8 The Emmentaler font
font, external filesFinding fonts
font, FetaA.8 The Emmentaler font
font, findingFinding fonts
font, finding availableSingle entry fonts
font, music notationMusic fonts
font, non-text in markupMusic fonts
font, ParmesanA.8 The Emmentaler font
font-encodingMusic fonts
font-interface Understanding the fontSize property
font-interfaceMusic fonts
font-interfaceA.12.8 Other
font-sizeSelecting notation font size
font-size Understanding the fontSize property
FontConfig1.8.3 Fonts
fontSizeSelecting notation font size
foot markArticulations and ornamentations
foot markFermata scripts
footer3.3 Titles and headers
footer, pageDefault layout of headers and footers
footnote3.3.4 Creating footnotes
FootnoteSee also
footnote, event-based Event-based footnotes
footnote, in music expressionsFootnotes in music expressions
footnote, in stand-alone textFootnotes in stand-alone text
footnote, time-based Time-based footnotes
footnote-separator-markup\paper variables concerning headers and markups
FootnoteEventSee also
Footnote_engraverSee also
Forbid_line_break_engraverPrinting tuplet brackets on the note head side
forced vertical direction of grobsArticulation direction indicators
forgetAutomatic accidentals
forget accidental styleAutomatic accidentals
format, rehearsal markRehearsal marks
formatting, cue notesFormatting cue notes
formatting, in lyricsEntering lyrics
formatting, text spannerText spanners
four-bar music4.3.1 Line breaking
Four-part SATB vocal scoreReferences for choral
Four-part SATB vocal scoreSee also
four-string-banjoBanjo tablatures
fragmentFormatting cue notes
fragment, music3.5 Controlling output
fragment, quotingQuoting other voices
framing textGraphic notation inside markup
French clefClef
French clefA.11 Clef styles
Frenched scoreSee also
Frenched staffSee also
Frenched staffSee also
Frenched stavesSee also
fretDefault tablatures
fret diagramFret diagram markups
fret diagramPredefined fret diagrams
fret diagram, adding customPredefined fret diagrams
fret diagram, adding fingeringAutomatic fret diagrams
fret diagram, automaticAutomatic fret diagrams
fret diagram, changing orientationSelected Snippets
fret diagram, customFret diagram markups
fret diagram, customizedFret diagram markups
fret diagram, customizedChanging fret orientations
fret diagram, left-handedFret diagram markups
fret diagram, mandolinPredefined fret diagrams
fret diagram, markupFret diagram markups
fret diagram, transposingPredefined fret diagrams
fret diagram, ukulelePredefined fret diagrams
fret diagram, with chord namesPredefined fret diagrams
fret-diagram-interfaceFret diagram markups
fret-diagram-interfaceSee also
fret-diagram-interfacePredefined fret diagrams
fret-diagram-interfaceSee also
fret-diagram-interfaceAutomatic fret diagrams
fret-diagram-interfaceSee also
fretboard fret diagram, customizedSelected Snippets
fretboard, alternate tableChordChanges for FretBoards
fretboard, define predefinedCustomizing fretboard fret diagrams
FretBoardsPredefined fret diagrams
fretted instrument, chord shapePredefined fret diagrams
fretted instrument, dampened noteIndicating harmonics and dampened notes
fretted instrument, harmonicsIndicating harmonics and dampened notes
fretted instrument, indicating position and barringIndicating position and barring
fretted instrument, predefined string tuningsCustom tablatures
fretted instrument, right-hand fingeringRight-hand fingerings
full score2.1.6 Opera and stage musicals
full scoreReferences for opera and stage musicals
full-measure restFull measure rests
funk shape note headShape note heads

G
G clefClef
ghost noteParentheses
ghost note, percussionGhost notes
glideGliding fingers
gliding fingeringGliding fingers
GlissandoSee also
glissandoSee also
GlissandoSee also
glissando, across repeatsMaking glissandi breakable
glissando, and repeatsKnown issues and warnings
glissando, breakableAdding timing marks to long glissandi
glissando, chords in tablaturesSlides in tablature
glissando, contemporarySelected Snippets
glissando, timing marksContemporary glissando
global variableparser variable
glyphglyph
glyph set, accidentalA.10 Accidental glyph sets
glyph, alternate accidentalsAlternate accidental glyphs
glyph, bounding boxA.12.8 Other
glyph, for figured bass alterationChanging the positions of figured bass alterations
grace noteGrace notes
grace noteBagpipe definitions
grace note, and lyricsAdding syllables to grace notes
grace note, and strict spacingRedefining grace note global defaults
grace note, changing layout settingsGrace notes
grace note, changing layout settingsUsing grace note slashes with normal heads
grace note, followingGrace notes
grace note, synchronizationKnown issues and warnings
grace note, tweakingGrace notes
grace note, tweakingUsing grace note slashes with normal heads
grace notesSee also
GraceMusicSee also
Grace_auto_beam_engraverSee also
Grace_beam_engraverSee also
Grace_engraverSee also
Grace_spacing_engraverSee also
grammar, for LilyPondparser
grand staffSee also
GrandStaffSee also
GrandStaffSee also
graphic notationGraphic notation inside markup
graphic object, drawingGraphic notation inside markup
graphic object, embeddingGraphic notation inside markup
graphical objectgrob
graphical object interfaceinterface
Graphical Object InterfacesSee also
graphics, embeddingGraphic notation inside markup
graphics, embeddingGraphic notation inside markup
Gregorian accidentalGregorian accidentals and key signatures
Gregorian articulationGregorian articulation signs
Gregorian articulation, accentusGregorian articulation signs
Gregorian articulation, accentusRepeat sign scripts
Gregorian articulation, circulusGregorian articulation signs
Gregorian articulation, circulusRepeat sign scripts
Gregorian articulation, episem finisGregorian articulation signs
Gregorian articulation, episem initiumGregorian articulation signs
Gregorian articulation, ictusGregorian articulation signs
Gregorian articulation, ictusRepeat sign scripts
Gregorian articulation, semicirculusGregorian articulation signs
Gregorian articulation, semicirculusRepeat sign scripts
Gregorian key signatureGregorian accidentals and key signatures
Gregorian music, modern transcriptionChant or psalms notation
Gregorian square neumes ligatureGregorian square neume ligatures
Gregorian transcription staffInstantiating new staves
GregorianTranscriptionStaffInstantiating new staves
grid lineGrid lines
grid lines, changing appearanceSelected Snippets
grid-line-interfaceSee also
grid-point-interfaceSee also
GridChordNameSee also
gridIntervalGrid lines
GridLineSee also
GridPointSee also
Grid_chord_name_engraverSee also
Grid_line_span_engraverGrid lines
Grid_point_engraverGrid lines
grob5.2.2 Layout interfaces
grobgrob
grob, and whiteoutTies
grob, and whiteoutPainting objects white
grob, overwritingTies
grob, overwritingPainting objects white
grob, property5.3.3 The \override command
grob, vertical positionArticulation direction indicators
grob, visibility of5.4.7 Visibility of objects
grob-interfaceinterface
grob-interface5.2.2 Layout interfaces
grob-interfaceSee also
grob-interfaceSee also
grouping beatsStrict beat beaming
grow-directionFeathered beams
guiroA.17 Percussion notes
guitar note headSpecial note heads
guitar tablature2.4 Fretted string instruments
guitar, chord chartShowing melody rhythms
guitar, strumming rhythm, showingShowing melody rhythms
guitar, strumming rhythm, showingSelected Snippets
gutter\paper variables for two-sided mode

H
HairpinSee also
hairpinSee also
Hairpin Properties which may be offset
Hairpin Properties which may be offset
Hairpin Properties which may be offset
hairpin, al nienteMoving the ends of hairpins
hairpin, aligning ends to NoteColumn directionsSetting the minimum length of hairpins
hairpin, angledRotating layout objects
hairpin, constantePrinting hairpins using al niente notation
hairpin, FerneyhoughPrinting hairpins using al niente notation
hairpin, flaredPrinting hairpins using al niente notation
hairpin, minimum lengthSetting hairpin behavior at bar lines
hairpin, moving ends ofAligning the ends of hairpins to NoteColumn directions
hairpin, stopping at bar linesSelected Snippets
half open high hatA.17 Percussion notes
half-open high hatArticulations and ornamentations
half-open high hatCustom percussion staves
hammer onChord glissando in tablature
handclapA.17 Percussion notes
Harmonia Sacra note headShape note heads
harmonic indication, in tablature notationDefault tablatures
harmonic note headSpecial note heads
harmonic, in tablaturesPolyphony in tablature
harmonicsSee also
harmonics, artificialHarmonics
harmonics, flageoletArticulations and ornamentations
harmonics, flageoletFermata scripts
harmonics, naturalHarmonics
harmonics, on fretted instrumentIndicating harmonics and dampened notes
harpReferences for harps
harp pedalHarp pedals
harp pedal diagramHarp pedals
header3.3 Titles and headers
header, pageDefault layout of headers and footers
Hel-arabic note nameArabic note names
help, balloonBalloon help
Henze fermataArticulations and ornamentations
Henze fermataOrnament scripts
hidden noteHidden notes
hiding accidentals, on tied notes at start of systemSelected Snippets
hiding ancient stavesHiding staves
hiding dynamics extender lineVertically aligned dynamics and textscripts
hiding rhythmic stavesHiding staves
hiding stavesHiding staves
hiding vaticana stavesHiding staves
high bongoA.17 Percussion notes
high congaA.17 Percussion notes
high hatA.17 Percussion notes
high hat, half openArticulations and ornamentations
high hat, half openCustom percussion staves
high hat, half openA.17 Percussion notes
high hat, openArticulations and ornamentations
high hat, openA.17 Percussion notes
high hat, pedalArticulations and ornamentations
high hat, pedalCustom percussion staves
high hat, pedalA.17 Percussion notes
high timbaleA.17 Percussion notes
high tom tomA.17 Percussion notes
highlight, staffStaff highlights
horizontal alignment, lyricsSelected Snippets
horizontal beamsSelected Snippets
horizontal bracketAnalysis brackets
horizontal padding in markupText alignment
horizontal shift of notesMoving dotted notes in polyphony
horizontal spacing4.5 Horizontal spacing
horizontal spacing, between columns4.5.4.3 Spacing between adjacent columns
horizontal spacing, between non-musical items4.5.4.2 Spacing between adjacent non-musical items
horizontal text alignmentText alignment
horizontal-bracket-interfaceSee also
horizontal-bracket-text-interfaceSee also
horizontal-shift\paper variables for shifts and indents
HorizontalBracketSee also
HorizontalBracketTextAnalysis brackets above the staff
horizontally centering textA.12.2 Align
Horizontal_bracket_engraverAnalysis brackets
How LilyPond input files workSee also
How LilyPond input files workSee also
hufnagel2.9 Ancient notation
hufnagel2.9.1 Overview of the supported styles
hymn2.1.7 Chants psalms and hymns
hymnSelected Snippets
hymn, and partial measuresPartial measures in hymn tunes
hyphenExtenders and hyphens

I
I'm hearing VoicesSee also
I'm hearing VoicesPercussion staves
I'm hearing VoicesSee also
image, embeddingGraphic notation inside markup
immutable objectimmutable
immutable propertyimmutable
implicit context5.1.7 Context layout order
importing stencil, into textA.12.8 Other
improvisationImprovisation
improvisation, ArabicSelected Snippets
inch (in)5.4.2 Distances and measurements
incipit, addingIncipits
include settingsUsing global settings
including files3.4.1 Including LilyPond files
indentInstrument names
indent\paper variables for shifts and indents
indent4.5.5 Line width
indicating No Chord in ChordNamesPrinting chord names
indicating position and barring for fretted instrumentIndicating position and barring
individual parts1.6.3 Writing parts
inlining an Encapsulated PostScript imageA.12.3 Graphic
inner-margin\paper variables for two-sided mode
inserting music, into textA.12.4 Music
inserting PostScript directly, into textA.12.3 Graphic
inserting URL link, into textA.12.3 Graphic
instrument equalization in MIDI, replacing defaultSelected Snippets
instrument nameInstrument names
instrument name3.6.9 Enhancing MIDI output
instrument name, adding to other contextsInstrument names
instrument name, centeringInstrument names
instrument name, changingInstrument names
instrument name, complexInstrument names
instrument name, shortInstrument names
instrument, transposingTranspose
instrument-specific-markup-interfaceSee also
instrument-specific-markup-interfaceA.12.8 Other
InstrumentNameSee also
interfaceinterface
interface, layout5.2.2 Layout interfaces
Interfaces for programmersSee also
interleaved musicWriting music in parallel
IntermediateModifying broken spanners
Intermediate substitution \offset as an override
Internals Reference5. Changing defaults
intervalSee also
inversionInversion
inversion, modal Modal inversion
invisible noteHidden notes
invisible restInvisible rests
invisible stemStems
ionianKey signature
iraqSee also
isolated durationDurations
isolated percent repeatPercent repeat count visibility
isolated pitchDurations
item, musical4.5.4.1 Overview of object-specific horizontal spacing tweaks
item, non-musical4.5.4.1 Overview of object-specific horizontal spacing tweaks
item-interfaceSee also
item-interface5.2.2 Layout interfaces

J
jazz chordCustomizing chord names
JumpScriptSee also
JumpScriptSee also
JumpScriptSee also
Jump_engraverSee also
Jump_engraverSee also
justified textText alignment
justifying lines of textA.13 Text markup list commands
justifying textA.12.2 Align

K
keep tagged musicUsing tags
keepAliveInterfacesHiding staves
Keep_alive_together_engraverSee also
key signatureSee also
key signatureSee also
key signature, GregorianGregorian accidentals and key signatures
key signature, mensuralMensural accidentals and key signatures
key signature, non-traditionalPreventing natural signs from being printed when the key signature changes
key signature, preventing natural signsSelected Snippets
key signature, visibility following explicit change Visibility following explicit changes
key-signature-interfaceSee also
key-signature-interfaceSee also
keyboard instrument staffReferences for keyboards
keyboard music, centering dynamicsReferences for keyboards
KeyCancellationSee also
KeyChangeEventSee also
keyed instrument staffReferences for keyboards
KeySignatureSee also
KeySignatureSee also
KeySignatureSee also
KeySignatureSee also
Key_engraverSee also
Key_performerSee also
Kievan accidentalKievan accidentals
Kievan clefMensural clefs
Kievan clefA.11 Clef styles
Kievan ligatureKievan melismata
kievan notationSee also
kievan notationSee also
kievan notationSee also
kievan notationSee also
KievanStaffKievan contexts
KievanVoiceKievan contexts
kirchenpauseNumbering single measure rests
knee gap, with beamsPredefined commands
knee gap, with beams, changingBeams across line breaks
koronPersian music notation
kurdSee also

L
laissez vibrerSee also
LaissezVibrerTieSee also
LaissezVibrerTieColumnSee also
language, note names in otherNote names in other languages
language, pitch names in otherNote names in other languages
last-bottom-spacingList of flexible vertical spacing \paper variables
layerPainting objects white
layout interface5.2.2 Layout interfaces
layout objectgrob
layout, file4.2.2 Setting the staff size
layout, major 7 chordChord name exceptions
layout-set-staff-size4.2.2 Setting the staff size
lead sheetShowing chords at changes
ledger lineSee also
ledger line, internalStaff symbol
ledger line, modifyingStaff symbol
ledger-line-spanner-interfaceSee also
LedgerLineSpannerSee also
Ledger_line_engraverSee also
left-aligning textA.12.2 Align
left-handed fret diagramFret diagram markups
left-margin\paper variables for widths and margins
Length and thickness of objectsSee also
Length and thickness of objects5.4.2 Distances and measurements
Length and thickness of objectsSee also
length of multi-measure restSelected Snippets
length of noteDurations
lexerlexer
ligatureSee also
ligatureSee also
ligatureSee also
ligatureSee also
ligatureSee also
ligatureSee also
ligature, in textA.12.2 Align
ligature, KievanKievan melismata
ligature, mensuralWhite mensural ligatures
ligature, square neumesGregorian square neume ligatures
LilyPond grammarparser
lineSee also
line breakBar lines
line break, beamsPredefined commands
line break, beamsSelected Snippets
line break, cadenzasUnmetered music
line break, managing with extra voiceSelected Snippets
line break, unmetered musicUnmetered music
line comment3.2.1 Structure of a score
line comment3.2.5 File structure
line, cross-staffStaff-change lines
line, gridGrid lines
line, staff-changeStaff-change lines
line, staff-change followerStaff-change lines
line, to indicate duration2.8.3 Graphical notation
line-interface5.4.5 Line styles
line-spanner-interfaceSee also
line-widthText alignment
line-width\paper variables for widths and margins
line-width4.5.5 Line width
LineBreakEventSee also
lines, vertical, between stavesGrid lines
list of colorsNormal colors
list of keys in woodwind diagramsChanging the size of woodwind diagrams
list of markupsText markup introduction
list of woodwind diagramsSelected Snippets
listing available fontsSingle entry fonts
Literature listCustomizing chord names
Literature listSee also
locrianKey signature
long fermataArticulations and ornamentations
long fermataOrnament scripts
longaSee also
longaSee also
longa restRests
low bongoA.17 Percussion notes
low congaA.17 Percussion notes
low timbaleA.17 Percussion notes
low tom tomA.17 Percussion notes
lowering textA.12.2 Align
lute tablatureLute tablatures
lute tuningLute tablatures
ly:minimal-breakingMinimal page breaking
ly:one-line-auto-height-breakingOne-line-auto-height page breaking
ly:one-line-breakingOne-line page breaking
ly:one-page-breakingOne-page page breaking
ly:optimal-breakingOptimal page breaking
ly:page-turn-breakingOptimal page turning
lydianKey signature
LyricCombineMusicSee also
LyricCombineMusicSee also
LyricExtenderSee also
LyricHyphenSee also
LyricsSee also
LyricsSee also
LyricsSee also
LyricsSee also
LyricsSee also
lyrics, aligning to a melodyAligning lyrics to a melody
lyrics, aligning with sporadic melody5.1.3 Keeping contexts alive
lyrics, and markupSelected Snippets
lyrics, and melodiesAutomatic syllable durations
lyrics, and tied notesRepeats with alternative endings
lyrics, assigned to one voiceSingle-staff polyphony
lyrics, avoid bar linesKnown issues and warnings
lyrics, dividedDivisi lyrics
lyrics, enteringEntering lyrics
lyrics, formattingEntering lyrics
lyrics, horizontal alignmentSelected Snippets
lyrics, increasing space betweenPlacing syllables horizontally
lyrics, keeping inside marginSee also
lyrics, keeping inside marginKnown issues and warnings
lyrics, on grace notesAdding syllables to grace notes
lyrics, positioningSelected Snippets
lyrics, positioningPlacing lyrics vertically
lyrics, punctuationEntering lyrics
lyrics, repeatingLyrics and repeats
lyrics, repeats with alternative endingsRepeats with alternative endings
lyrics, shared among voicesPolyphony with shared lyrics
lyrics, skipInvisible rests
lyrics, skipping notesRepeats with alternative endings
lyrics, using variablesWorking with lyrics and variables
lyrics, version 2.12 spacingSelected Snippets
lyrics, with beamSetting automatic beam behavior
LyricTextSee also
LyricTextSee also
LyricTextSee also

M
mCommon chords
magnification->font-sizeSelecting notation font size
magnification->font-size4.2.2 Setting the staff size
magnifying textA.12.1 Font
magstepSelecting notation font size
magstep4.2.2 Setting the staff size
magstep5.4.2 Distances and measurements
majCommon chords
majorKey signature
major 7 chord, layoutChord name exceptions
major seven symbolPredefined commands
majorSevenSymbolCustomizing chord names
majorSevenSymbolChord name exceptions
makamSee also
makamReferences for Turkish classical music
makamTurkish note names
makam, exampleSelected Snippets
makamlarSee also
makamlarSee also
makamlarTurkish note names
make-dynamic-scriptNew dynamic marks
make-pango-font-treeEntire document fonts
manual bar lineBar lines
manual beamAutomatic beams
manual beamManual beams
manual beam, direction shorthand forManual beams
manual beam, grace notesManual beams
manual engraving of tiesUsing ties with arpeggios
manual line break4.3.1 Line breaking
manual measure lineBar lines
manual rehearsal markRehearsal marks
manual repeat markManual repeat marks
manual staff changeChanging staff manually
ManualsLilyPond — Notation Reference
ManualsLilyPond — Notation Reference
maqamSee also
maqamReferences for Arabic music
maracasA.17 Percussion notes
marcatoArticulations and ornamentations
margin, text running overSee also
mark, on every staffSelected Snippets
mark, phrasingPhrasing slurs
mark, rehearsalRehearsal marks
mark, rehearsal, below staffSelected Snippets
mark, rehearsal, formatRehearsal marks
mark, rehearsal, manualRehearsal marks
mark, rehearsal, styleRehearsal marks
mark, textText marks
markupText markup introduction
Markup construction in SchemeNew dynamic marks
Markup construction in SchemeSee also
Markup construction in Scheme3.3.6 Table of contents
markup expressionText markup introduction
Markup functionsText markup introduction
Markup functionsSee also
markup listText markup introduction
markup mode, quoted textText markup introduction
markup mode, special charactersText markup introduction
markup objectText objects overview
markup syntaxText markup introduction
markup textText markup introduction
markup text, aligningText alignment
markup text, alignment commandText alignment
markup text, decoratingGraphic notation inside markup
markup text, framingGraphic notation inside markup
markup text, justifiedText alignment
markup text, line widthText alignment
markup text, multi-pageText markup introduction
markup text, paddingGraphic notation inside markup
markup text, wordwrappedText alignment
markup, aligningText alignment
markup, centering on pageText alignment
markup, conditionalCustom layout for headers and footers
markup, in lyricsSelected Snippets
markup, multi-lineText alignment
markup, multi-measure restPositioning multi-measure rests
markup, multi-pageText markup introduction
markup, music notation insideMusic notation inside markup
markup, on multi-measure restFull measure rests
markup, rhythmA.12.4 Music
markup, score insideMusic notation inside markup
markup, text, inside slursUsing double slurs for legato chords
markup, two-columnSelected Snippets
markup-markup-spacingList of flexible vertical spacing \paper variables
markup-system-spacingList of flexible vertical spacing \paper variables
Mark_engraverSelected Snippets
max-systems-per-page\paper variables for line breaking
maximaSee also
maximaSee also
maxima restRests
measure checkBar and bar number checks
measure counterMeasure counts
measure groupingStrict beat beaming
measure lineBar lines
measure lineAutomatic bar lines
measure line, invisibleBar lines
measure line, manualBar lines
measure numberBar numbers
measure numberTime administration
measure number checkBar and bar number checks
measure number, and repeatsKnown issues and warnings
measure number, stylePrinting bar numbers using modulo-bar-number-visible
measure repeatPercent repeats
measure subgroupingStrict beat beaming
measure, partialUpbeats
measure, partial, in hymnsPartial measures in hymn tunes
measure, pickupUpbeats
measure-counter-interfaceSee also
measure-spanner-interfaceSee also
measureBarTypeBar lines
MeasureCounterSee also
measureLengthSetting automatic beam behavior
measureLengthTime administration
measurePositionUpbeats
measurePositionTime administration
MeasureSpannerSee also
Measure_counter_engraverSee also
Measure_grouping_engraverStrict beat beaming
Measure_spanner_engraverSee also
measuring units5.4.2 Distances and measurements
Medicaea, Editio2.9 Ancient notation
Medicaea, Editio2.9.1 Overview of the supported styles
medium intervalReferences for Arabic music
melismaMultiple notes to one syllable
melismaSee also
melisma, with beamsAutomatic beams
melismataMultiple notes to one syllable
melody rhythm, showingShowing melody rhythms
mensural2.9 Ancient notation
mensural2.9.1 Overview of the supported styles
mensural clefMensural clefs
mensural clefA.11 Clef styles
mensural flagMensural flags
mensural ligatureWhite mensural ligatures
mensural music, transcription ofDisplay bracket with only one staff in a system
mensural notationSee also
mensural notationSee also
mensural notationSee also
mensural notationSee also
mensural notationSee also
mensural notationSee also
mensural notationSee also
mensural notationSee also
mensural notationSee also
mensural notationSee also
mensural notation, signum congruentiaeRepeat sign scripts
MensuralStaffInstantiating new staves
MensuralStaffMensural contexts
MensuralVoiceMensural contexts
mensuration signMensural time signatures
mensurstrichSee also
MensurstricheMensurstriche layout
mensurstriche layoutDisplay bracket with only one staff in a system
merging notesCollision resolution
merging textA.12.2 Align
merging textA.12.2 Align
meterSee also
meter styleTime signature
meter, polymetricPolymetric notation
metronomeSee also
metronome markSee also
metronome mark, below staffSelected Snippets
metronome mark, custom markupChanging the tempo without a metronome mark
MetronomeMarkSee also
metronomic indicationSee also
mezzosoprano clefClef
mezzosoprano clefA.11 Clef styles
microtoneNote names in other languages
microtone, tabCustom tablatures
mid tom tomA.17 Percussion notes
MIDIInstrument transpositions
MIDI3.6 Creating MIDI output
MIDI, balance3.6.8 Context properties for MIDI effects
MIDI, block3.6.3 The MIDI block
MIDI, channels3.6.7 MIDI channel mapping
MIDI, chorus level3.6.8 Context properties for MIDI effects
MIDI, context definitionsSetting MIDI block properties
MIDI, custom dynamicsSelected Snippets
MIDI, dynamics3.6.4 Controlling MIDI dynamics
MIDI, effects3.6.8 Context properties for MIDI effects
MIDI, equalization3.6.4 Controlling MIDI dynamics
MIDI, expression3.6.8 Context properties for MIDI effects
MIDI, instrument3.6.9 Enhancing MIDI output
MIDI, metadata3.3.3 Creating output file metadata
MIDI, one channel per voiceSelected Snippets
MIDI, pan position3.6.8 Context properties for MIDI effects
MIDI, replacing default instrument equalizationSelected Snippets
MIDI, reverb3.6.8 Context properties for MIDI effects
MIDI, stereo balance3.6.8 Context properties for MIDI effects
MIDI, supported notation3.6 Creating MIDI output
MIDI, tracks3.6.7 MIDI channel mapping
MIDI, transpositionInstrument transpositions
MIDI, unsupported notation3.6.1 Supported notation for MIDI
MIDI, using repeats3.6.6 Using repeats with MIDI
MIDI, volume3.6.4 Controlling MIDI dynamics
midiBalance3.6.8 Context properties for MIDI effects
midiChannelMapping3.6.7 MIDI channel mapping
midiChorusLevel3.6.8 Context properties for MIDI effects
midiDrumPitchesCustom percussion staves
midiExpression3.6.8 Context properties for MIDI effects
midiPanPosition3.6.8 Context properties for MIDI effects
midiReverbLevel3.6.8 Context properties for MIDI effects
millimeter (mm)5.4.2 Distances and measurements
min-systems-per-page\paper variables for line breaking
minimum length, hairpinSetting hairpin behavior at bar lines
minimum-Y-extentWithin-system spacing properties
minimumFretDefault tablatures
minimumFretAutomatic fret diagrams
minimumPageTurnLengthOptimal page turning
minimumRepeatLengthForPageTurnOptimal page turning
minorKey signature
minorChordModifierCustomizing chord names
mirroring markupA.12.3 Graphic
mixedPiano pedals
mixolydianKey signature
modal inversion Modal inversion
modal transformationModal transformations
modal transposition Modal transposition
modeparser variable
modernAutomatic accidentals
modern accidentalAutomatic accidentals
modern accidental styleAutomatic accidentals
modern accidental styleAutomatic accidentals
modern style accidentalAutomatic accidentals
modern transcription of Gregorian musicChant or psalms notation
modern-cautionaryAutomatic accidentals
modern-cautionary accidental styleAutomatic accidentals
modern-cautionary accidental styleAutomatic accidentals
modern-voiceAutomatic accidentals
modern-voice-cautionaryAutomatic accidentals
modern-voice-cautionary accidental styleAutomatic accidentals
moderntab clefCustom tablatures
modifier, in chordCommon chords
Modifying context propertiesSee also
movements, multiple3.2.2 Multiple scores in a book
Moving objectsText alignment
Moving objectsSee also
multi-line comment3.2.1 Structure of a score
multi-line comment3.2.5 File structure
multi-line markupText alignment
multi-line textText alignment
multi-measure notes, contractingCompressing empty measures
multi-measure notes, expandingCompressing empty measures
multi-measure restSee also
multi-measure rest, and fingeringsSee also
multi-measure rest, attaching fermataFull measure rests
multi-measure rest, attaching textFull measure rests
multi-measure rest, lengthSelected Snippets
multi-measure rest, markupPositioning multi-measure rests
multi-measure rest, numberingSelected Snippets
multi-measure rest, positioningMulti-measure rest length control
multi-measure rest, scriptFull measure rests
multi-measure rest, styleNumbering single measure rests
multi-measure rest, with markupFull measure rests
multi-measure rest, within text, by durationA.12.4 Music
multi-measure rest, within text, by duration-scaleA.12.4 Music
multi-measure rests, contractingCompressing empty measures
multi-measure rests, expandingCompressing empty measures
multi-note acciaccaturaKnown issues and warnings
multi-page markupText markup introduction
multi-voice accidentalAutomatic accidentals
MultiMeasureRestSee also
MultiMeasureRestSee also
MultiMeasureRestNumberSee also
MultiMeasureRestNumberSee also
MultiMeasureRestScriptFull measure rests
MultiMeasureRestScriptSee also
MultiMeasureRestScriptSee also
MultiMeasureRestTextFull measure rests
MultiMeasureRestTextSee also
multiple dynamic marks, on one noteDynamics
Multiple notes at onceSee also
multiple phrasing slursPhrasing slurs
multiple slursSlurs
multiple voicesCollision resolution
Music classesSee also
Music definitions5.2.1 Navigating the program reference
Music expressions explainedSee also
music fragment3.5 Controlling output
Music functions3.4.3 Using music functions
Music functionsSee also
music, beginners’Easy notation note heads
music, inside markupMusic notation inside markup
music, unmeteredTime administration
musica fictaAnnotational accidentals (musica ficta)
musical cueMusical cues
musical item4.5.4.1 Overview of object-specific horizontal spacing tweaks
musical theater2.1.6 Opera and stage musicals
musicological analysisAnalysis brackets
musicQuotesparser variable
mutable objectmutable
mutable propertymutable
mute bongoA.17 Percussion notes
mute congaA.17 Percussion notes
mute timbaleA.17 Percussion notes
muted note, percussionGhost notes

N
N.C. symbolPrinting chord names
N.C. symbol, customizingSimple lead sheet
name of singerAdding singers’ names to stanzas
name, characterCharacter names
natural harmonicsHarmonics
natural pitchAccidentals
natural signAccidentals
natural sign, extra, preventingHiding accidentals on tied notes at the start of a new system
natural sign, preventing in key signaturesSelected Snippets
neo-modernAutomatic accidentals
neo-modern accidental styleAutomatic accidentals
neo-modern-cautionaryAutomatic accidentals
neo-modern-cautionary accidental styleAutomatic accidentals
neo-modern-voiceAutomatic accidentals
neo-modern-voice accidental styleAutomatic accidentals
neo-modern-voice-cautionaryAutomatic accidentals
neo-modern-voice-cautionary accidental styleAutomatic accidentals
neomensural2.9.1 Overview of the supported styles
nested repeatKnown issues and warnings
nested staff bracketNested staff groups
Nesting music expressionsOssia staves
Nesting music expressionsSee also
Nesting music expressions5.1.7 Context layout order
Nesting music expressionsSee also
nesting of stavesNested staff groups
new context5.1.2 Creating and referencing contexts
new dynamic markNew dynamic marks
New markup command definitionA.12.1 Font
new spacing section4.5.2 New spacing section
new staffInstantiating new staves
New_fingering_engraverSee also
New_fingering_engraver5.2.1 Navigating the program reference
niente, al, hairpinMoving the ends of hairpins
no-chord symbolPrinting chord names
no-chord symbol, customizingSimple lead sheet
no-resetAutomatic accidentals
no-reset accidental styleAutomatic accidentals
noChordSymbolSimple lead sheet
non-ASCII character3.4.4 Special characters
non-default tuplet numbersChanging the tuplet number
non-empty textText scripts
non-musical item4.5.4.1 Overview of object-specific horizontal spacing tweaks
non-musical symbolGraphic notation inside markup
non-text font, in markupMusic fonts
NonMusicalPaperColumnSee also
nonstaff-nonstaff-spacingWithin-system spacing properties
nonstaff-relatedstaff-spacingWithin-system spacing properties
nonstaff-unrelatedstaff-spacingWithin-system spacing properties
notation, explainingBalloon help
notation, font sizeSelecting notation font size
notation, graphicGraphic notation inside markup
notation, inside markupMusic notation inside markup
note clusterClusters
note collisionCollision resolution
note continuation2.8.3 Graphical notation
note durationDurations
note duration, defaultDurations
note grouping bracketAnalysis brackets
note headSee also
note headSee also
note head styleSpecial note heads
note head styleA.9 Note head styles
note head, AikenShape note heads
note head, Aiken, thin variantSelected Snippets
note head, ancientMensural note heads
note head, ancientKievan notes
note head, Christian HarmonyShape note heads
note head, crossSpecial note heads
note head, diamondSpecial note heads
note head, diamond-shapedHarmonics
note head, easy notationEasy notation note heads
note head, easy playEasy notation note heads
note head, funkShape note heads
note head, guitarSpecial note heads
note head, Harmonia SacraShape note heads
note head, harmonicSpecial note heads
note head, improvisationImprovisation
note head, parlatoSpecial note heads
note head, practiceEasy notation note heads
note head, Sacred HarpShape note heads
note head, shapeShape note heads
note head, shape, mergingAiken head thin variant noteheads
note head, slashedImprovisation
note head, Southern HarmonyShape note heads
note head, specialSpecial note heads
note head, WalkerShape note heads
note lengthDurations
note name, ArabicArabic note names
note name, defaultAccidentals
note name, DutchAccidentals
note name, Hel-arabicArabic note names
note name, other languagesNote names in other languages
note name, printingNote names
note pitch, defaultDurations
note valueSee also
note, coloredColoring objects
note, colored in chordsSee also
note, cross-staffChanging staff manually
note, cross-staffSelected Snippets
note, dottedDurations
note, dotted, moving horizontallyAdditional voices to avoid collisions
note, double-dottedDurations
note, ghostParentheses
note, hiddenHidden notes
note, horizontal shiftMoving dotted notes in polyphony
note, invisibleHidden notes
note, parenthesizedParentheses
note, smallerFormatting cue notes
note, spacing horizontally4.5.2 New spacing section
note, splittingAutomatic note splitting
note, transparentHidden notes
note, transposition ofTranspose
note, within text, by durationA.12.4 Music
note, within text, by log and dot-countA.12.4 Music
note-eventQuoting other voices
note-eventSee also
note-eventSee also
note-head-interfaceSee also
note-head-interfaceSee also
note-head-interfaceSee also
NoteCollisionSee also
NoteColumnSee also
NoteHeadSee also
NoteHeadSee also
NoteHeadSee also
NoteNameSee also
noteNameFunctionNote names
NoteNamesNote names
noteNameSeparatorNote names
NoteSpacingSee also
NoteSpacing4.5.1 Horizontal spacing overview
NoteSpacingSee also
Note_heads_engraverAutomatic note splitting
Note_heads_engraverSee also
Note_heads_engraverSee also
Note_heads_engraverSee also
Note_head_line_engraverSee also
Note_name_engraverNote names
Note_spacing_engraverSee also
NullVoicePolyphony with shared lyrics
number, barBar numbers
number, in easy notationSelected Snippets
number, measureBar numbers

O
object, coloredColoring objects
object, coloringPainting objects white
object, markupText objects overview
object, overwritingPainting objects white
object, rotatingRotating layout objects
object, visibility of5.4.7 Visibility of objects
Objects and interfacesSee also
Objects and interfacesSee also
Objects and interfacesSee also
octavationSee also
octave changing markAbsolute octave entry
octave checkOctave checks
octave correctionOctave checks
octave entry, absoluteAbsolute octave entry
octave entry, relativeRelative octave entry
octave specification, absoluteAbsolute octave entry
octave specification, relativeRelative octave entry
octave transpositionClef
octave transposition, optionalClef
offsetting5.3.6 The \offset command
On the un-nestedness of brackets and tiesSee also
On the un-nestedness of brackets and tiesSee also
OneStaffGrouping staves
open bongoA.17 Percussion notes
open congaA.17 Percussion notes
open high hatArticulations and ornamentations
open high hatA.17 Percussion notes
open string indicationBowing indications
open timbaleA.17 Percussion notes
OpenType, font featureFont features
OpenType, font featureA.12.1 Font
opera2.1.6 Opera and stage musicals
operation, inversionInversion
operation, modalModal transformations
operation, modal inversion Modal inversion
operation, retrogradeRetrograde
operation, transposition Modal transposition
Optical spacing4.5.1 Horizontal spacing overview
Optical spacingSee also
optional octave transpositionClef
oratorio2.1.5 Choral
orchestra, notation forReferences for opera and stage musicals
orchestral musicReferences for opera and stage musicals
orchestral strings2.3 Unfretted string instruments
ordering, vertical, of scriptsModifying default values for articulation shorthand notation
organ pedal markArticulations and ornamentations
organ pedal markFermata scripts
OrganizingUsing variables
Organizing pieces with variablesSee also
Organizing pieces with variablesSee also
Organizing pieces with variablesSee also
Organizing pieces with variablesSee also
Organizing pieces with variables5.1.2 Creating and referencing contexts
Organizing pieces with variablesSee also
orientation of fret diagram, changingSelected Snippets
orientation, of fingeringsSelected Snippets
orientation, of string numbersSelected Snippets
orientation, of stroke fingerSelected Snippets
ornamentGrace notes
ornament, down pralltrillerArticulations and ornamentations
ornament, down pralltrillerArticulation scripts
ornament, Haydn turnArticulations and ornamentations
ornament, Haydn turnArticulation scripts
ornament, lower mordentArticulations and ornamentations
ornament, lower mordentArticulation scripts
ornament, mordentArticulations and ornamentations
ornament, mordentArticulation scripts
ornament, mordent, lowerArticulations and ornamentations
ornament, mordent, lowerArticulation scripts
ornament, mordent, upperArticulations and ornamentations
ornament, mordent, upperArticulation scripts
ornament, pralltrillerArticulations and ornamentations
ornament, pralltrillerArticulation scripts
ornament, pralltriller, downArticulations and ornamentations
ornament, pralltriller, downArticulation scripts
ornament, pralltriller, longArticulations and ornamentations
ornament, pralltriller, longArticulation scripts
ornament, pralltriller, upArticulations and ornamentations
ornament, pralltriller, upArticulation scripts
ornament, reverse turnArticulations and ornamentations
ornament, reverse turnArticulation scripts
ornament, signum congruentiaeArticulations and ornamentations
ornament, slash turnArticulations and ornamentations
ornament, slash turnArticulation scripts
ornament, trillArticulations and ornamentations
ornament, trillArticulation scripts
ornament, turnArticulations and ornamentations
ornament, turnArticulation scripts
ornament, up pralltrillerArticulations and ornamentations
ornament, up pralltrillerArticulation scripts
ornament, upper mordentArticulations and ornamentations
ornament, upper mordentArticulation scripts
ornamentation, turn, delayedControlling the vertical ordering of scripts
ossiaSee also
ossiaHiding staves
ossia, positioningSelected Snippets
Other sources of informationSee also
Other sources of informationExtending notation and tuning systems
Other sources of informationSee also
Other sources of information3.4.1 Including LilyPond files
Other sources of information3.4.1 Including LilyPond files
Other sources of informationSee also
Other sources of informationInstallation Instructions
Other sources of informationSee also
Other sources of informationSee also
Other sources of informationSee also
Other sources of informationKnown issues and warnings
Other sources of informationSee also
Other sources of informationSee also
Other sources of information5.2.2 Layout interfaces
Other sources of informationSee also
Other uses for tweaksReferences for keyboards
Other uses for tweaksSee also
ottavaOttava brackets
ottava spanner, modify slopeAdding an ottava marking to a single voice
ottava textSelected Snippets
ottava, for single voiceChanging ottava text
ottava-bracket-interfaceSee also
OttavaBracketSee also
ottavationSelected Snippets
ottavation-numbersOttava brackets
ottavation-ordinalsOttava brackets
ottavation-simple-ordinalsOttava brackets
ottavationMarkupsOttava brackets
Ottava_spanner_engraverSee also
Ottoman musicReferences for Turkish classical music
Ottoman, classical musicExtending notation and tuning systems
outer-margin\paper variables for two-sided mode
output definitionOutput definitions – blueprints for contexts
output-countparser variable
output-defoutput-def
output-suffixparser variable
outside-staff-horizontal-padding4.4.3 Vertical collision avoidance
outside-staff-padding4.4.3 Vertical collision avoidance
outside-staff-priority4.4.3 Vertical collision avoidance
overlaying contextsGrouping staves
override, reverting5.3.3 The \override command
OverridePropertySee also
overriding for only one moment5.3.3 The \override command
overriding property within text markupA.12.8 Other
overtie-ing textA.12.1 Font
overwriting grobTies
overwriting objectPainting objects white

P
padding5.2.3 Determining the grob property
padding around textGraphic notation inside markup
padding in markup, horizontalText alignment
padding in markup, verticalText alignment
padding textA.12.2 Align
padding text horizontallyA.12.2 Align
page break4.5.5 Line width
page break, cadenzasUnmetered music
page break, managing with extra voiceSelected Snippets
page break, unmetered musicUnmetered music
page breaking, manualManual page breaking
page breaks, within markupText markup introduction
page footerDefault layout of headers and footers
page headerDefault layout of headers and footers
page layout4.5.5 Line width
page number, auto-numbering\paper variables for page numbering
page number, in roman numerals\paper variables for page numbering
page number, specify first\paper variables for page numbering
page number, suppress\paper variables for page numbering
page numbers, independent for introduction\paper variables for page numbering
page numbers, per bookpart\paper variables for page numbering
page numbers, referencing3.3.5 Reference to page numbers
page size4.1.2 Paper size and automatic scaling
page, orientationSetting the paper size
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-number-type\paper variables for page numbering
page-spacing-weight\paper variables for page breaking
pan position in MIDI3.6.8 Context properties for MIDI effects
Pango1.8.3 Fonts
paper column4.5.4.1 Overview of object-specific horizontal spacing tweaks
paper size4.1.2 Paper size and automatic scaling
paper size, landscapeSetting the paper size
paper size, orientationSetting the paper size
paper-height4.1.3 Fixed vertical spacing \paper variables
paper-width\paper variables for widths and margins
parallel musicWriting music in parallel
ParenthesesSee also
parentheses-interfaceSee also
parenthesisParentheses
Parenthesis_engraverSee also
parenthesized accidentalAccidentals
parlatoSpoken music
parlato note headSpecial note heads
Parmesan fontA.8 The Emmentaler font
parserparser
parser variableparser variable
partSee also
part combinerAutomatic part combining
part combiner, changing textCombining two parts on the same staff
part song2.1.5 Choral
partCombineListenerparser variable
PartCombineMusicSee also
partial measureUpbeats
partial measure, in hymnsPartial measures in hymn tunes
parts, desk1.6.3 Writing parts
parts, individual1.6.3 Writing parts
parts, section1.6.3 Writing parts
path, drawingA.12.3 Graphic
pause markCaesuras
pause markBreath marks
PDF metadata3.3.3 Creating output file metadata
pedal diagram, harpHarp pedals
pedal high hatArticulations and ornamentations
pedal high hatCustom percussion staves
pedal high hatA.17 Percussion notes
pedal indication stylePiano pedals
pedal indication, bracketPiano pedals
pedal indication, mixedPiano pedals
pedal indication, textPiano pedals
pedal mark, heelArticulations and ornamentations
pedal mark, heelFermata scripts
pedal mark, organArticulations and ornamentations
pedal mark, organFermata scripts
pedal mark, toeArticulations and ornamentations
pedal mark, toeFermata scripts
pedal sustain stylePiano pedals
pedal, harpHarp pedals
pedal, pianoPiano pedals
pedal, sostenutoPiano pedals
pedal, sustainPiano pedals
pedalSustainStylePiano pedals
percentPercent repeats
percent repeatSee also
percent repeat counterSelected Snippets
percent repeat, count visibilityPercent repeat counter
percent repeat, isolatedPercent repeat count visibility
PercentRepeatSee also
PercentRepeatCounterSee also
PercentRepeatedMusicSee also
Percent_repeat_engraverSee also
percussionBasic percussion notation
percussionPercussion staves
percussion clefBasic percussion notation
percussion clefA.11 Clef styles
percussion staffInstantiating new staves
percussion, customCustom percussion staves
percussion, dead noteGhost notes
percussion, false noteGhost notes
percussion, ghost noteGhost notes
percussion, muted noteGhost notes
percussion, silenced noteGhost notes
Performer_groupNew contexts in MIDI
Persian accidentals (sori, koron)Persian music notation
Persian classical music2.10.4 Persian classical music
Persian makamExtending notation and tuning systems
Persian makamExtending notation and tuning systems
Petrucci2.9 Ancient notation
Petrucci2.9.1 Overview of the supported styles
Petrucci clefMensural clefs
Petrucci clefA.11 Clef styles
phrase bar lineAutomatic bar lines
phrase bar lineAutomatic bar lines
phrase bar line, in Gregorian chantDivisiones
phrase bar line, in hymnsPhrase bar lines in hymn tunes
phrase bar line, in Kievan chantKievan bar lines
phrasing bracketAnalysis brackets
phrasing markPhrasing slurs
phrasing slurSlurs
phrasing slurPhrasing slurs
phrasing slur, dashedPhrasing slurs
phrasing slur, defining dash patternsPhrasing slurs
phrasing slur, dottedPhrasing slurs
phrasing slur, half solid and half dashedPhrasing slurs
phrasing slur, multiplePhrasing slurs
phrasing slur, simultaneousPhrasing slurs
phrasing, in lyricsMultiple notes to one syllable
PhrasingSlurSee also
phrygianKey signature
pianoAutomatic accidentals
piano accidental styleAutomatic accidentals
piano music, centering dynamicsReferences for keyboards
piano pedalPiano pedals
piano staffGrouping staves
piano staffReferences for keyboards
piano-cautionaryAutomatic accidentals
piano-cautionary accidental styleAutomatic accidentals
PianoPedalBracketSee also
PianoStaffReferences for keyboards
PianoStaffChanging staff automatically
PianoStaffSee also
PianoStaffSee also
PianoStaffSee also
PianoStaffSee also
Piano_pedal_engraverSee also
pickup measureUpbeats
pickup, in a repeatSimple repeats
pitchAbsolute octave entry
pitch nameAbsolute octave entry
pitch name, other languagesNote names in other languages
Pitch namesSee also
Pitch namesSee also
Pitch namesSee also
Pitch namesSee also
Pitch namesSee also
pitch rangeAmbitus
pitch, defaultDurations
pitch, isolatedDurations
pitch, transposition ofTranspose
pitched trillTrills
pitched trill, with accidentalTrills
Pitched_trill_engraverSee also
Pitches and key signaturesAccidentals
Pitches and key signaturesSee also
Pitches and key signaturesKey signature
Pitches and key signaturesSee also
Pitches and key signaturesSee also
pitches, ‘smart’ transpositionSelected Snippets
pitchnamesparser variable
Pitch_squash_engraverShowing melody rhythms
Pitch_squash_engraverSee also
pizzicato, BartókSnap (Bartók) pizzicato
pizzicato, snapSnap (Bartók) pizzicato
placeholder eventChorded notes
Placement of objectsArticulations and ornamentations
Placement of objectsSee also
Placement of objectsText scripts
Placement of objectsSee also
placement, lyricsPlacing lyrics vertically
placement, right-hand fingeringSelected Snippets
placing horizontal brackets, around textA.12.3 Graphic
placing parentheses, around textA.12.3 Graphic
placing vertical brackets, around textA.12.3 Graphic
point (pt)5.4.2 Distances and measurements
point, big (bp)5.4.2 Distances and measurements
polymetricSee also
polymetricSee also
polymetric meter, with beams Different time signatures with equal-length measures
polymetric signaturesPolymetric notation
polymetric time signatureSee also
polyphonic musicCollision resolution
polyphonySee also
polyphony, additional voicesSelected Snippets
polyphony, in tablaturesStem and beam behavior in tablature
polyphony, shared lyricsPolyphony with shared lyrics
polyphony, single-staffSingle-staff polyphony
portatoSee also
position, figured bass alterationSelected Snippets
position, lyricsSelected Snippets
position, multi-measure restMulti-measure rest length control
position, ossiaSelected Snippets
position, vertical, of grobsArticulation direction indicators
post-eventsA.15 List of articulations
postscriptGraphic notation inside markup
power chordSee also
practice note headEasy notation note heads
predefined string tuning, for fretted instrumentsCustom tablatures
predefinedDiagramTableChordChanges for FretBoards
prefatory material4.5.4.1 Overview of object-specific horizontal spacing tweaks
prima voltaAlternative endings
print-all-headers\paper variables concerning headers and markups
print-first-page-number\paper variables for page numbering
print-page-number\paper variables for page numbering
printAccidentalNamesNote names
printing chord namePrinting chord names
printing orderPainting objects white
printing reserved characterText markup introduction
printing special characterText markup introduction
printNotesLanguageNote names
printOctaveNamesNote names
probprob
Properties found in interfacesSee also
Properties of layout objectsSee also
property5.3.2 The \set command
property objectprob
property, grob5.3.3 The \override command
PropertySetSee also
psalm2.1.7 Chants psalms and hymns
psalmSelected Snippets
PsalmsPointing a psalm
PsalmsSee also
pull offChord glissando in tablature
punctuation, in lyricsEntering lyrics
putting space around textA.12.2 Align

Q
q, chord repetitionChord repetition
q, chord repetitionDefault tablatures
quarter toneSee also
quarter tone accidentalSee also
quarter tone, tabCustom tablatures
quote, in lyricsEntering lyrics
quote, in lyricsMultiple syllables to one note
quote, voicesQuoting other voices
quoted textText scripts
quoted text, in markup modeText markup introduction
quotedCueEventTypesQuoting other voices
quotedEventTypesQuoting other voices
QuoteMusicSee also

R
rRests
RFull measure rests
ragged-bottom4.1.3 Fixed vertical spacing \paper variables
ragged-last\paper variables for widths and margins
ragged-last4.5.5 Line width
ragged-last-bottom4.1.3 Fixed vertical spacing \paper variables
ragged-right\paper variables for widths and margins
ragged-right4.5.5 Line width
raising textA.12.2 Align
range of pitchesAmbitus
rastSee also
Ratisbona, Editio2.9.1 Overview of the supported styles
Real music exampleCollision resolution
Real music exampleSee also
Real music exampleReferences for keyboards
Real music exampleSee also
referencing context5.1.2 Creating and referencing contexts
referencing page label, in textA.12.8 Other
referencing page number, in textA.12.8 Other
referencing page number, in textA.12.8 Other
register symbol, accordionDiscant symbols
regular line break4.3.1 Line breaking
rehearsal markRehearsal marks
rehearsal mark, below staffSelected Snippets
rehearsal mark, formatRehearsal marks
rehearsal mark, manualRehearsal marks
rehearsal mark, styleRehearsal marks
RehearsalMarkSee also
RehearsalMarkEventSee also
relativeRelative octave entry
relative music, and \autoChangeChanging staff automatically
relative octave entryRelative octave entry
relative octave entry, and chordsRelative octave entry
relative octave entry, and transpositionSee also
relative octave specificationRelative octave entry
relative pitch, chordsChorded notes
RelativeOctaveCheckSee also
RelativeOctaveMusicSee also
religious music2.1.7 Chants psalms and hymns
reminder accidentalAccidentals
removal, in chordExtended and altered chords
remove tagged musicUsing tags
remove-emptyHiding staves
remove-firstHiding staves
remove-grace-propertyUsing grace note slashes with normal heads
remove-layerHiding staves
removing bar numbersAligning bar numbers
removing cue notesFormatting cue notes
renaissance musicDisplay bracket with only one staff in a system
repeatSee also
repeat barBar lines
repeat bar lineAutomatic bar lines
repeat bar line, underlyingAutomatic bar lines
repeat number, changingManual repeat marks
repeat volta, changingManual repeat marks
repeat, al fineSegno repeat structure
repeat, alla codaSegno repeat structure
repeat, alternative bar numbersAdding volta brackets to additional staves
repeat, ambiguousKnown issues and warnings
repeat, and glissandiMaking glissandi breakable
repeat, and glissandiKnown issues and warnings
repeat, and lyricsLyrics and repeats
repeat, and measure numberKnown issues and warnings
repeat, and slurKnown issues and warnings
repeat, bar numbers with lettersAdding volta brackets to additional staves
repeat, beatPercent repeats
repeat, D.C.Segno repeat structure
repeat, D.C., manualManual repeat marks
repeat, D.S.Segno repeat structure
repeat, D.S., forced at startSegno repeat appearance
repeat, D.S., manualManual repeat marks
repeat, da capoSegno repeat structure
repeat, da capo, manualManual repeat marks
repeat, dal segnoSegno repeat structure
repeat, dal segno, forced at startSegno repeat appearance
repeat, dal segno, manualManual repeat marks
repeat, double, style for voltaSelected Snippets
repeat, e poi la codaSegno repeat structure
repeat, endManual repeat marks
repeat, manualManual repeat marks
repeat, measurePercent repeats
repeat, nestedKnown issues and warnings
repeat, percentPercent repeats
repeat, percent counterSelected Snippets
repeat, percent, count visibilityPercent repeat counter
repeat, percent, isolatedPercent repeat count visibility
repeat, shortPercent repeats
repeat, simpleSee also
repeat, slashPercent repeats
repeat, startManual repeat marks
repeat, timing informationKnown issues and warnings
repeat, tremoloTremolo repeats
repeat, unfold1.4.1 Long repeats
repeat, with alternative endingsAlternative endings
repeat, with anacrusisSimple repeats
repeat, with bar checksSimple repeats
repeat, with pickupSimple repeats
repeat, with segnoSegno repeat appearance
repeat, with tiesTies
repeat, with upbeatSimple repeats
repeat, written-out1.4.1 Long repeats
repeatCommandsManual repeat marks
repeatCountVisibilityPercent repeat counter
repeated chords, suppressingDefining predefined fretboards for other instruments
repeated chords, suppressingSelected Snippets
RepeatedMusicSee also
RepeatedMusicSee also
repeating lyrics, with alternative endingsRepeats with alternative endings
repeating tieTies
repeats in MIDI3.6.6 Using repeats with MIDI
RepeatSlashSee also
RepeatSlashEventSee also
Repeat_acknowledge_engraverSee also
repetition, using qChord repetition
repetition, using qDefault tablatures
reserved character, printingText markup introduction
reset-footnotes-on-new-page\paper variables concerning headers and markups
resizing of stavesOssia staves
RestSee also
restRests
rest, ancientMensural rests
rest, churchNumbering single measure rests
rest, collisions ofKnown issues and warnings
rest, condensing ordinaryKnown issues and warnings
rest, entering durationsRests
rest, full-measureFull measure rests
rest, invisibleInvisible rests
rest, multi-measureRests
rest, multi-measureFull measure rests
rest, specifying vertical positionRests
rest, splittingAutomatic note splitting
rest, styleSelected Snippets
rest, whole, for a full measureFull measure rests
rest, whole-measureRests
rest, within text, by durationA.12.4 Music
rest, within text, by log and dot-countA.12.4 Music
rest-eventQuoting other voices
RestCollisionSee also
restNumberThresholdSelected Snippets
restoring default properties for time signaturesTime signature
restrainOpenStringsDefault tablatures
Rest_engraverSee also
retrograde transformationRetrograde
reverb in MIDI3.6.8 Context properties for MIDI effects
reverting override5.3.3 The \override command
RevertPropertySee also
rgb colorColoring objects
rgb-colorColoring objects
rhythm, in textA.12.4 Music
rhythm, showing melodyShowing melody rhythms
rhythmic staffInstantiating new staves
RhythmicStaffInstantiating new staves
RhythmicStaffSee also
RhythmicStaffSee also
ride bellA.17 Percussion notes
ride cymbalA.17 Percussion notes
right-aligning textA.12.2 Align
right-hand fingering, for fretted instrumentsRight-hand fingerings
right-hand fingering, placementSelected Snippets
right-margin\paper variables for widths and margins
root of chordCommon chords
rotating objectRotating layout objects
rotating textA.12.2 Align

S
sInvisible rests
Sacred Harp note headShape note heads
SATB2.1.5 Choral
scalable vector graphics output3.5.3 Alternative output formats
scaling durationScaling durations
scaling markupA.12.3 Graphic
scaling textA.12.2 Align
Scheme functionsCustom tablatures
Scheme functionsSee also
Scheme objectsmob
Scheme tutorial5. Changing defaults
Scheme variableparser variable
scordaturaSee also
ScoreSee also
Score context, replacingReplacing the Score context
Score is a (single) compound musical expressionSee also
score, inside markupMusic notation inside markup
score, vocal, adding cuesSelected Snippets
score-markup-spacingList of flexible vertical spacing \paper variables
score-system-spacingList of flexible vertical spacing \paper variables
Scores and parts3.4.1 Including LilyPond files
Scores and partsSee also
scoreTitleMarkupCustom layout for titles
Score_engraverReplacing the Score context
Score_performerReplacing the Score context
Scottish highland bagpipeBagpipe definitions
ScriptSee also
ScriptSee also
script, on multi-measure restFull measure rests
script, vertical orderingModifying default values for articulation shorthand notation
ScriptEventSee also
scriptsA.15 List of articulations
Script_engraverSee also
seconda voltaAlternative endings
section bar lineAutomatic bar lines
section bar lineSection divisions
section bar line, in Gregorian chantDivisiones
section bar line, in Kievan chantKievan bar lines
section labelSection labels
section parts1.6.3 Writing parts
SectionEventSee also
SectionLabelSee also
SectionLabelSee also
SectionLabelEventSee also
segnoSegno repeat structure
segno bar lineBar lines
segno bar lineAutomatic bar lines
segno bar lineSegno repeat appearance
segno, forced at startSegno repeat appearance
segno, forced at startManual repeat marks
SegnoMarkSee also
SegnoMarkSee also
SegnoRepeatedMusicSee also
selecting font size (notation)Selecting notation font size
self-alignment-interface5.2.2 Layout interfaces
self-alignment-interface5.4.9 Aligning objects
self-alignment-XWithin-system spacing properties
semaiSee also
semai formArabic time signatures
semi-flatAccidentals
semi-flatNote names in other languages
semi-flat symbol, appearanceArabic note names
semi-flat symbol, Persian (koron)Persian music notation
semi-sharpAccidentals
semi-sharpNote names in other languages
semi-sharp symbol, Persian (sori)Persian music notation
semi-transparent colorsColoring objects
separate textSeparate text
separation-item-interfaceSee also
sesqui-flatNote names in other languages
sesqui-sharpNote names in other languages
set-global-fontsEntire document fonts
set-global-staff-size4.2.2 Setting the staff size
setting extent of text objectA.12.8 Other
setting extent of text objectA.12.8 Other
setting extent of text objectA.12.8 Other
setting extent of text objectA.12.8 Other
setting extent of text objectA.12.8 Other
setting horizontal text alignmentA.12.2 Align
Setting simple songsReferences for vocal music
Setting simple songsSee also
setting subscript, in standard font sizeA.12.1 Font
setting superscript, in standard font sizeA.12.1 Font
seventh chordCommon chords
shape noteShape note heads
shape note, mergingAiken head thin variant noteheads
shaping slurs and ties Specifying displacements from current control points
shared propertyimmutable
sharpSee also
sharp, doubleAccidentals
shift noteCollision resolution
shift rest, automaticCollision resolution
shift symbol, accordionDiscant symbols
shifting voiceCollision resolution
short bar lineBar lines
short bar line, in Gregorian chantDivisiones
short fermataArticulations and ornamentations
short fermataOrnament scripts
short-indentInstrument names
short-indent\paper variables for shifts and indents
shortened volta bracketsSelected Snippets
show-available-fontsSingle entry fonts
showFirstLength3.5.2 Skipping corrected music
showFirstLengthparser variable
showLastLength3.5.2 Skipping corrected music
showLastLengthparser variable
side-position-interface5.2.2 Layout interfaces
side-position-interface5.4.9 Aligning objects
sidestickA.17 Percussion notes
sidestickA.17 Percussion notes
sign, codaArticulations and ornamentations
sign, codaInstrument-specific scripts
sign, coda, manualManual repeat marks
sign, coda, variantArticulations and ornamentations
sign, coda, variantSegno repeat appearance
sign, coda, variantInstrument-specific scripts
sign, coda, with repeatsSegno repeat structure
sign, conductingStrict beat beaming
sign, segnoArticulations and ornamentations
sign, segnoInstrument-specific scripts
sign, segno, bar lineBar lines
sign, segno, bar lineSegno repeat appearance
sign, segno, manualManual repeat marks
sign, segno, with repeatsSegno repeat structure
sign, segno, with repeatsSegno repeat appearance
sign, snappizzicatoArticulations and ornamentations
sign, snappizzicatoFermata scripts
sign, variant codaArticulations and ornamentations
sign, variant codaSegno repeat appearance
sign, variant codaInstrument-specific scripts
signature, polymetricPolymetric notation
sikahSee also
silenced note, percussionGhost notes
simileSee also
simple repeatSee also
simple text string, with tie charactersA.12.4 Music
simultaneous notes and accidentalsSee also
simultaneous phrasing slursPhrasing slurs
simultaneous slursSlurs
singer nameAdding singers’ names to stanzas
single bar lineAutomatic bar lines
single staff with bracket or braceUse square bracket at the start of a staff group
single-line comment3.2.1 Structure of a score
single-line comment3.2.5 File structure
single-staff polyphonySingle-staff polyphony
Size of objectsSee also
skipInvisible rests
skip typesetting3.5.2 Skipping corrected music
skipBarsCompressing empty measures
SkipMusicSee also
skipping notes in lyricsRepeats with alternative endings
skipTypesetting3.5.2 Skipping corrected music
slash repeatPercent repeats
slashChordSeparatorCustomizing chord names
slashed digitA.12.8 Other
slashed note headImprovisation
slashed stemSelected Snippets
Slash_repeat_engraverSee also
slide, in tablature notationFretted-string harmonics in tablature
slope, ottava spanner, modificationAdding an ottava marking to a single voice
slurSee also
SlurSee also
SlurSee also
slur styleSlurs
slur, above notesSlurs
slur, and repeatsKnown issues and warnings
slur, below notesSlurs
slur, dashedSlurs
slur, dashed phrasingPhrasing slurs
slur, defining dash patternsSlurs
slur, defining dash patternsPositioning text markups inside slurs
slur, defining dash patterns for phrasingPhrasing slurs
slur, dottedSlurs
slur, dotted phrasingPhrasing slurs
slur, for tupletsTuplets
slur, half dashed and half solidSlurs
slur, half solid and half dashed phrasingPhrasing slurs
slur, manual placementSlurs
slur, modifyingModifying ties and slurs
slur, multipleSlurs
slur, multiple phrasingPhrasing slurs
slur, phrasingSlurs
slur, phrasingPhrasing slurs
slur, phrasing, defining dash patternsPhrasing slurs
slur, simultaneousSlurs
slur, simultaneous phrasingPhrasing slurs
slur, solidSlurs
slur, text markup insideUsing double slurs for legato chords
slur-eventQuoting other voices
slurs, double, for legato chordsSelected Snippets
smaller noteFormatting cue notes
smobsmob
snap pizzicatoSnap (Bartók) pizzicato
snareA.17 Percussion notes
Solesmes2.9.1 Overview of the supported styles
solid slurSlurs
solo partAutomatic part combining
SongsSee also
SongsSee also
soprano clefClef
soprano clefA.11 Clef styles
soriPersian music notation
sos.Piano pedals
sostenuto pedalPiano pedals
SostenutoEventSee also
SostenutoPedalSee also
SostenutoPedalLineSpannerSee also
sound3.6 Creating MIDI output
Southern Harmony note headShape note heads
space, between staves4.4.1 Flexible vertical spacing within systems
space, in lyricsEntering lyrics
space, in lyricsMultiple syllables to one note
space, inside systems4.4.1 Flexible vertical spacing within systems
space-alist4.5.4.2 Spacing between adjacent non-musical items
spacer noteInvisible rests
spacer restInvisible rests
spacing4.5.1 Horizontal spacing overview
spacing lyricsPlacing syllables horizontally
spacing section, new4.5.2 New spacing section
spacing, display of layout4.6.1 Displaying spacing
spacing, horizontal4.5 Horizontal spacing
spacing, vertical4.4 Vertical spacing
SpacingSpanner4.5.1 Horizontal spacing overview
SpacingSpanner4.5.1 Horizontal spacing overview
SpacingSpannerSee also
SpacingSpannerSee also
span barBar lines
SpanBarSee also
spanner5.4.4 Spanners
spannerspanner
spanner, modifyingModifying broken spanners
spanner-interfaceSee also
Span_stem_engraverSelected Snippets
special arpeggio symbolArpeggio
special character3.4.4 Special characters
special character, in markup modeText markup introduction
special note headSpecial note heads
splash cymbalA.17 Percussion notes
splice into tagged musicUsing tags
splitting notesAutomatic note splitting
splitting restsAutomatic note splitting
SprechgesangSpoken music
square bracket, at start of staff groupSelected Snippets
square neumes ligatureGregorian square neume ligatures
staccatissimoArticulations and ornamentations
staccatoSee also
stacking text in a columnA.12.2 Align
staffSee also
StaffSee also
StaffSee also
staffSee also
staffSee also
StaffSee also
StaffSee also
StaffSee also
StaffSee also
StaffSee also
StaffSee also
Staff4.5.1 Horizontal spacing overview
staff change, automaticChanging staff automatically
staff change, manualChanging staff manually
staff distance4.4.1 Flexible vertical spacing within systems
staff groupGrouping staves
staff group, with square bracket at startSelected Snippets
staff initiationInstantiating new staves
staff instantiationInstantiating new staves
staff line, modifyingStaff symbol
staff line, stopping and startingStaff symbol
staff size, setting4.2.2 Setting the staff size
staff switchingStaff-change lines
staff symbolStaff symbol
staff, choirGrouping staves
staff, drumInstantiating new staves
staff, emptyHiding staves
staff, FrenchedOssia staves
staff, grandGrouping staves
staff, hidingHiding staves
staff, highlightStaff highlights
staff, keyboard instrumentsReferences for keyboards
staff, keyed instrumentsReferences for keyboards
staff, metronome mark belowSelected Snippets
staff, multipleGrouping staves
staff, nestedNested staff groups
staff, newInstantiating new staves
staff, percussionInstantiating new staves
staff, pianoGrouping staves
staff, pianoReferences for keyboards
staff, resizing ofOssia staves
staff, singleInstantiating new staves
staff, single, with bracket or braceUse square bracket at the start of a staff group
staff-affinityWithin-system spacing properties
staff-change lineStaff-change lines
staff-highlight-eventSee also
staff-highlight-interfaceSee also
staff-paddingControlling the placement of chord fingerings
staff-staff-spacingWithin-system spacing properties
staff-symbol-interfaceSee also
Staff.midiInstrument3.6.9 Enhancing MIDI output
StaffGroupKnown issues and warnings
StaffGroupSee also
StaffGroupSee also
staffgroup-staff-spacingWithin-system spacing properties
StaffGrouperSee also
StaffGrouperWithin-system spacing properties
StaffGrouperSee also
StaffGrouperSee also
StaffGrouper5.3.7 Modifying alists
StaffHighlightSee also
StaffHighlightEventSee also
StaffSpacingSee also
StaffSymbolSee also
StaffSymbolSee also
StaffSymbolSee also
Staff_collecting_engraverSelected Snippets
Staff_collecting_engraverSelected Snippets
Staff_highlight_engraverSee also
Staff_symbol_engraverHiding staves
stand-alone textSeparate text
standard font size (notation) Understanding the fontSize property
stanza numberAdding stanza numbers
StanzaNumberSee also
start of systemGrouping staves
start repeatManual repeat marks
start-repeatManual repeat marks
startAcciaccaturaMusicTweaking grace layout within music
startAppoggiaturaMusicTweaking grace layout within music
startGraceMusicTweaking grace layout within music
stavesSee also
staves, divisiHiding staves
stemStems
StemSee also
StemSee also
Stem Properties which may be offset
stem, automatic direction on center lineDefault direction of stems on the center line of the staff
stem, cross-staffSelected Snippets
stem, default direction on center lineSelected Snippets
stem, directionStems
stem, downStems
stem, in tablatureSelected Snippets
stem, invisibleStems
stem, neutralStems
stem, upStems
stem, with slashSelected Snippets
stem-interfaceSee also
stem-spacing-correction4.5.1 Horizontal spacing overview
stemLeftBeamCountManual beams
stemLeftBeamCountSelected Snippets
stemRightBeamCountManual beams
stemRightBeamCountSelected Snippets
Stem_engraverSee also
Stem_engraverSee also
stencilstencil
stencil, removingRemoving the stencil
stereo balance in MIDI3.6.8 Context properties for MIDI effects
stopAcciaccaturaMusicTweaking grace layout within music
stopAppoggiaturaMusicTweaking grace layout within music
stopGraceMusicTweaking grace layout within music
strict spacing and grace notesRedefining grace note global defaults
strict-beat beamingSubdividing beams
strictBeatBeamingSubdividing beams
string bending, in tablature notationDefault tablatures
string numberBowing indications
string numberString number indications
string numbers, orientationSelected Snippets
String quartet templatesReferences for unfretted strings
String quartet templatesSee also
string vs. fingering numberString number indications
string, indicating openBowing indications
StringNumberSee also
stringNumberOrientationsSelected Snippets
strings, orchestral2.3 Unfretted string instruments
strings, writing for2.3 Unfretted string instruments
stringTuningsCustom tablatures
stringTuningsPredefined fret diagrams
stroke finger, orientationSelected Snippets
StrokeFingerSee also
strokeFingerOrientationsSelected Snippets
strokeFingerOrientationsSelected Snippets
Structure of a note entryA.15 List of articulations
strumming rhythm, showingShowing melody rhythms
strumming rhythm, showingSelected Snippets
Style sheetsUsing global settings
Style sheetsSee also
style, bar numberPrinting bar numbers using modulo-bar-number-visible
style, double repeat for voltaSelected Snippets
style, measure numberPrinting bar numbers using modulo-bar-number-visible
style, multi-measure restsNumbering single measure rests
style, note headsSpecial note heads
style, rehearsal markRehearsal marks
style, restsSelected Snippets
style, slurSlurs
style, text dynamicsHiding the extender line for text dynamics
style, voiceVoice styles
subbass clefClef
subbass clefA.11 Clef styles
subdivideBeamsSelected Snippets
subdividing beamsSelected Snippets
subscriptSelecting font and font size
subscript textA.12.1 Font
suggestAccidentalsControlling the vertical ordering of scripts
suggestAccidentalsAnnotational accidentals (musica ficta)
superscriptSelecting font and font size
superscript textA.12.1 Font
suppressing repeated chordsDefining predefined fretboards for other instruments
suppressing repeated chordsSelected Snippets
susExtended and altered chords
sustain pedalPiano pedals
sustain pedal stylePiano pedals
SustainEventSee also
SustainPedalSee also
SustainPedalLineSpannerSee also
SVG output3.5.3 Alternative output formats
swingA.12.4 Music
swing scriptThe ‘swing’ script
swing.lyThe ‘swing’ script
switching fontSelecting font and font size
syllable duration, automaticAutomatic syllable durations
symbol, breath mark, changingBreath marks
symbol, major sevenPredefined commands
symbol, non-musicalGraphic notation inside markup
syntax, markupText markup introduction
systemGrouping staves
system separator markSeparating systems
system start delimiterGrouping staves
system start delimiter, nestedNested staff groups
system-count\paper variables for line breaking
system-separator-markup\paper variables concerning headers and markups
system-system-spacingList of flexible vertical spacing \paper variables
systems-per-page\paper variables for line breaking
SystemStartBarSee also
SystemStartBarSee also
SystemStartBraceSee also
SystemStartBraceSee also
SystemStartBracketSee also
SystemStartBracketSee also
SystemStartSquareSee also
SystemStartSquareSee also

T
tab clefCustom tablatures
tab clefA.11 Clef styles
tab microtonesCustom tablatures
tab quarter tonesCustom tablatures
tablatureInstantiating new staves
tablature2.4 Fretted string instruments
tablature, and beamsSelected Snippets
tablature, and harmonic indicationsDefault tablatures
tablature, and harmonicsPolyphony in tablature
tablature, and polyphonyStem and beam behavior in tablature
tablature, and slidesFretted-string harmonics in tablature
tablature, and stemsSelected Snippets
tablature, and string bendingDefault tablatures
tablature, banjo2.4 Fretted string instruments
tablature, banjoCustom tablatures
tablature, banjoBanjo tablatures
tablature, basicDefault tablatures
tablature, bassCustom tablatures
tablature, bass guitarCustom tablatures
tablature, celloCustom tablatures
tablature, chord glissandoSlides in tablature
tablature, customCustom tablatures
tablature, custom string tuningsCustom tablatures
tablature, defaultDefault tablatures
tablature, double bassCustom tablatures
tablature, guitar2.4 Fretted string instruments
tablature, guitarCustom tablatures
tablature, hammer onChord glissando in tablature
tablature, luteLute tablatures
tablature, mandolinCustom tablatures
tablature, predefined string tuningsCustom tablatures
tablature, pull offChord glissando in tablature
tablature, ukuleleCustom tablatures
tablature, violaCustom tablatures
tablature, violinCustom tablatures
table of contents3.3.6 Table of contents
table of contents, customized functions3.3.6 Table of contents
TabNoteHeadSee also
TabStaffInstantiating new staves
TabStaffDefault tablatures
TabVoiceDefault tablatures
Tab_note_heads_engraverSee also
tagUsing tags
tag groupsUsing tags
tam tamA.17 Percussion notes
tambourineA.17 Percussion notes
taqasimSee also
teachingAutomatic accidentals
teaching accidental styleAutomatic accidentals
template, Arabic musicArabic music example
tempoMetronome marks
tempo indicationSee also
tempo, change, without metronome markPrinting metronome and rehearsal marks below the staff
tempo, with rhythmA.12.4 Music
tenor clefClef
tenor clefA.11 Clef styles
tenor clef, choralClef
tenor G clefA.11 Clef styles
tenor varC clefA.11 Clef styles
tenutoSee also
textPiano pedals
text alignment commandText alignment
text column, left-alignedA.12.2 Align
text column, right-alignedA.12.2 Align
text dynamics, styleHiding the extender line for text dynamics
text item, non-emptyText scripts
text markText marks
text mark, alignmentText marks
text mark, below staffText marks
text mark, on every staffSelected Snippets
text mark, vertical stackingText marks
text markupText markup introduction
text markup, inside slursUsing double slurs for legato chords
text objectText objects overview
text scriptText scripts
text script, vertical alignmentPrinting hairpins in various styles
text sizeSelecting font and font size
text spannerText spanners
text spanner, dynamics, customizeSelected Snippets
text spanner, formattingText spanners
text, aligningText alignment
text, at beginning of lineText marks
text, at end of scoreText marks
text, between notesText marks
text, centering on pageText alignment
text, decoratingGraphic notation inside markup
text, framingGraphic notation inside markup
text, horizontal alignmentText alignment
text, in columnsSelected Snippets
text, in columnsText alignment
text, in volta bracketManual repeat marks
text, justifiedText alignment
text, keeping inside marginSee also
text, line widthText alignment
text, multi-lineText alignment
text, on bar lineSection labels
text, on bar lineText marks
text, on multi-measure restFull measure rests
text, other languages1.8.1 Writing text
text, ottavationSelected Snippets
text, outside marginSee also
text, paddingGraphic notation inside markup
text, separateSeparate text
text, spread over multiple pagesText markup introduction
text, stand-aloneSeparate text
text, top-levelSeparate text
text, vertical alignmentText alignment
text, wordwrappedText alignment
text-interface5.2.2 Layout interfaces
text-interfaceA.12.8 Other
text-script-interface5.2.2 Layout interfaces
TextMarkSee also
TextMarkEventSee also
TextScriptSee also
TextScriptSee also
TextScriptSee also
TextScriptSee also
TextScriptSee also
TextScriptSee also
TextScriptSee also
TextScriptSee also
TextScriptSee also
TextSpannerSee also
TextSpannerSee also
Text_mark_engraverSelected Snippets
The Emmentaler fontA.12.4 Music
thorough bassIntroduction to figured bass
tick bar lineBar lines
tick bar line, in Gregorian chantDivisiones
tick markBreath marks
tieSee also
TieSee also
tieSee also
tie, alternative endingsTies
tie, and volta bracketTies
tie, appearanceTies
tie, dashedTies
tie, dottedTies
tie, from nothingTies
tie, in chordTies
tie, in lyricsMultiple syllables to one note
tie, in repeatsTies
tie, laissez vibrerTies
tie, manual engravingUsing ties with arpeggios
tie, modifyingModifying ties and slurs
tie, placementTies
tie, repeatingTies
tie, to nothingTies
tie, with arpeggiosSelected Snippets
tie-ing textA.12.1 Font
TieColumnUsing ties with arpeggios
TieColumnSee also
tied note, accidentalAccidentals
tieWaitForNoteSelected Snippets
timbaleA.17 Percussion notes
time administrationTime administration
time signatureSee also
time signature styleTime signature
time signature styleMensural time signatures
time signature, compound Different time signatures with unequal-length measures
time signature, default settingsTime signature
time signature, doublePolymetric notation
time signature, mensuralMensural time signatures
time signature, mid-measureUpbeats
time signature, polymetricPolymetric notation
time signature, printing only numeratorSelected Snippets
time signature, properties, restoring default valuesTime signature
time signature, visibilityTime signature
TimeScaledMusicSee also
TimeSignatureSee also
TimeSignatureSee also
timeSignatureFractionPolymetric notation
TimingTime administration
timing information and repeatsKnown issues and warnings
timing mark, for glissandoContemporary glissando
timing, within scoreTime administration
Timing_translatorSee also
Timing_translatorSee also
Timing_translatorSee also
Timing_translatorSee also
Timing_translatorSee also
title3.3 Titles and headers
toc3.3.6 Table of contents
tocFormatMarkupPredefined commands
tocIndentMarkupPredefined commands
tocItemMarkupPredefined commands
tocTitleMarkupPredefined commands
tom tomA.17 Percussion notes
TopLilyPond — Notation Reference
TopLilyPond — Notation Reference
Top5. Changing defaults
top-level textSeparate text
top-margin4.1.3 Fixed vertical spacing \paper variables
top-markup-spacingList of flexible vertical spacing \paper variables
top-system-spacingList of flexible vertical spacing \paper variables
toplevel-bookpartsparser variable
toplevel-scoresparser variable
transcription of mensural musicDisplay bracket with only one staff in a system
transcription, mensural to modernAncient and modern from one source
transcription, modern of Gregorian musicChant or psalms notation
transformation, modalModal transformations
transformation, retrogradeRetrograde
translating textA.12.2 Align
translating textA.12.2 Align
Translation5.2.1 Navigating the program reference
transparency, semiColoring objects
transparent noteHidden notes
transparent, making objectsMaking objects transparent
transposeTranspose
transposed clef, visibility of Transposed clefs
TransposedMusicSee also
transposingTranspose
transposing clefClef
transposing fret diagramPredefined fret diagrams
transposing instrumentSee also
transposing instrumentSee also
transpositionTranspose
transposition, and relative octave entrySee also
transposition, instrumentInstrument transpositions
transposition, MIDIInstrument transpositions
transposition, modal Modal transposition
transposition, of notesTranspose
transposition, of pitchesTranspose
transposition, pitches, ‘smart’Selected Snippets
tre cordePiano pedals
treble clefClef
treble clefA.11 Clef styles
tremoloTremolo repeats
tremolo beamTremolo repeats
tremolo markTremolo repeats
tremolo, cross-staffSelected Snippets
triadCommon chords
triangleA.17 Percussion notes
trillSee also
trill, pitchedTrills
trill, with accidentalTrills
TrillPitchAccidentalSee also
TrillPitchGroupSee also
TrillPitchHeadSee also
TrillPitchParenthesesSee also
TrillSpannerSee also
TrillSpannerSee also
tripletSee also
triplet, formattingSelected Snippets
Tunable context propertiesMultiple notes to one syllable
Tunable context propertiesSee also
Tunable context properties5.3.2 The \set command
Tunable context propertiesSee also
tuning, banjoBanjo tablatures
tuning, luteLute tablatures
tuning, non-WesternExtending notation and tuning systems
tupletSee also
tuplet bracket, note head sideControlling tuplet bracket visibility
tuplet bracket, placementTuplets
tuplet bracket, visibilityTuplets
tuplet bracket, visibilityNon-default tuplet numbers
tuplet number , visibilityTuplets
tuplet number, changeEntering several tuplets using only one tuplet command
tuplet number, non-defaultChanging the tuplet number
tuplet slurTuplets
tuplet, beamed, line break withinPrinting tuplet brackets on the note head side
tuplet, entering multipleSelected Snippets
tuplet, formattingSelected Snippets
tuplet, groupingTuplets
tuplet-slurTuplets
TupletBracketSee also
TupletNumberEntering several tuplets using only one tuplet command
tupletSpannerDurationSelected Snippets
Turkish makamExtending notation and tuning systems
Turkish makam, exampleSelected Snippets
Turkish musicReferences for Turkish classical music
Turkish note nameTurkish note names
Turkish, classical musicExtending notation and tuning systems
turn ornamentation, delayedControlling the vertical ordering of scripts
tweak, relation to \override5.3.5 \set vs. \override
tweaking5.3.4 The \tweak command
tweaking control pointKnown issues and warnings
tweaking grace noteGrace notes
tweaking grace noteUsing grace note slashes with normal heads
Tweaking methodsSee also
Tweaking methods5.3.4 The \tweak command
Tweaking methodsSee also
Tweaking output5. Changing defaults
Tweaking outputSee also
two-column textSelected Snippets
two-sided\paper variables for two-sided mode
typefaceglyph
typeset textText markup introduction
typesetting, skip3.5.2 Skipping corrected music

U
U.C.Piano pedals
ukuleleFret diagram markups
ultima voltaAlternative endings
una cordaPiano pedals
UnaCordaEventSee also
UnaCordaPedalSee also
UnaCordaPedalLineSpannerSee also
unbreakable-spanner-interfaceSee also
underlining textA.12.1 Font
underlying repeat bar lineAutomatic bar lines
undertie-ing textA.12.1 Font
unfold1.4.1 Long repeats
unfold repeat1.4.1 Long repeats
UnfoldedRepeatedMusicSee also
UnfoldedRepeatedMusicSee also
UnicodeUnicode
units, of measuring5.4.2 Distances and measurements
universal-colorColoring objects
universal-colorColor-blind-safe colors
unmetered musicUnmetered music
unmetered musicTime administration
unmetered music, accidentalsUnmetered music
unmetered music, bar linesUnmetered music
unmetered music, bar numbersUnmetered music
unmetered music, beamsUnmetered music
unmetered music, line breaksUnmetered music
unmetered music, page breaksUnmetered music
up direction (^)Articulation direction indicators
up-bow indicationBowing indications
upbeatUpbeats
upbeat, in a repeatSimple repeats
UTF-8Text encoding

V
varbaritone clefClef
varC clefA.11 Clef styles
variables3.2.5 File structure
variables, use ofUsing variables
variant ‘coda’ signArticulations and ornamentations
variant ‘coda’ signSegno repeat appearance
variant ‘coda’ signInstrument-specific scripts
Vaticana, Editio2.9 Ancient notation
Vaticana, Editio2.9.1 Overview of the supported styles
VaticanaStaffInstantiating new staves
VaticanaStaffGregorian chant contexts
VaticanaVoiceGregorian chant contexts
vertical alignment, dynamicsPrinting hairpins in various styles
vertical alignment, textText alignment
vertical alignment, text scriptsPrinting hairpins in various styles
vertical direction, default, of grobsArticulation direction indicators
vertical direction, forced, of grobsArticulation direction indicators
vertical distance, figured bass elementsDisplaying figured bass
vertical lines between stavesGrid lines
vertical ordering, of scriptsModifying default values for articulation shorthand notation
vertical padding in markupText alignment
vertical positioning of dynamicsDynamics
vertical spacing4.4 Vertical spacing
vertical spacing4.5.5 Line width
VerticalAxisGroupWithin-system spacing properties
VerticalAxisGroupSee also
VerticalAxisGroupWithin-system spacing properties
VerticalAxisGroupSee also
VerticalAxisGroupSee also
VerticalAxisGroupSee also
VerticalAxisGroupSee also
VerticalAxisGroupA.22 Context modification identifiers
VerticalAxisGroupA.22 Context modification identifiers
VerticalAxisGroupA.22 Context modification identifiers
vertically centering textA.12.2 Align
vibraslapA.17 Percussion notes
violin clefClef
violin clefA.11 Clef styles
Visibility and color of objectsSee also
Visibility and color of objectsSee also
Visibility and color of objectsSee also
Visibility and color of objectsSee also
Visibility and color of objects5.1.4 Modifying context plug-ins
Visibility and color of objects5.4.7 Visibility of objects
Visibility and color of objectsUsing break-visibility
Visibility and color of objectsSee also
visibility of object5.4.7 Visibility of objects
visibility of transposed clef Transposed clefs
visibility of tuplet bracketsNon-default tuplet numbers
visibility of tupletsTuplets
Vocal ensembles templatesPlacing lyrics vertically
Vocal ensembles templatesSee also
Vocal ensembles templatesReferences for choral
Vocal ensembles templatesSee also
Vocal ensembles templatesSee also
Vocal ensembles templatesSee also
Vocal ensembles templates5.1.2 Creating and referencing contexts
vocal score2.1.6 Opera and stage musicals
vocal score, adding cuesSelected Snippets
VoiceSingle-staff polyphony
voiceAutomatic accidentals
VoiceSee also
voiceAutomatic accidentals
VoiceSee also
VoiceSee also
VoiceSee also
VoiceSee also
Voice4.5.1 Horizontal spacing overview
Voice5.2.3 Determining the grob property
voice accidental styleAutomatic accidentals
voice styleVoice styles
voice, additional, in polyphonic musicSelected Snippets
voice, ambitusSelected Snippets
voice, dividedSelected Snippets
voice, extra, for handling breaksSelected Snippets
voice, followingStaff-change lines
voice, multipleCollision resolution
voice, quotingQuoting other voices
voice, quotingFormatting cue notes
voice, shiftingCollision resolution
voice, with ottavationChanging ottava text
voice, \partCombine with \autoBeamOffChanging beam knee gap
VoiceFollowerSee also
VoiceFollowerSee also
Voices contain musicSee also
Voices contain musicSee also
voltaSee also
voltaAlternative endings
volta bracketManual repeat marks
volta bracket, and tieTies
volta bracket, in additional stavesShortening volta brackets
volta bracket, shortenedSelected Snippets
volta bracket, with textManual repeat marks
volta repeat, below chordsAdding bar lines to ChordNames context
volta, double repeat styleSelected Snippets
volta, primaAlternative endings
volta, secondaAlternative endings
volta, ultimaAlternative endings
VoltaBracketSee also
VoltaBracketSee also
VoltaRepeatedMusicSee also
VoltaRepeatedMusicSee also
Volta_engraverShortening volta brackets
vowel transitionSee also
VowelTransitionSee also

W
Walker shape note headShape note heads
whistleA.17 Percussion notes
white mensural ligatureWhite mensural ligatures
whiteoutTies
whiteoutPainting objects white
whitespace3.2.5 File structure
whole rest, for a full measureFull measure rests
wind instrumentReferences for wind instruments
wind instruments, fingering symbolsSelected Snippets
Within-staff objectsThe direction property
Within-staff objectsSee also
woodblockA.17 Percussion notes
woodwind diagram, key listsChanging the size of woodwind diagrams
woodwind diagram, listSelected Snippets
woodwind diagrams, modifyingWoodwind diagrams listing
wordwrapped textText alignment
Working on input filesSee also
writing music in parallelWriting music in parallel
written-out repeat1.4.1 Long repeats

X
X-offsetWithin-system spacing properties
x11 colorColoring objects
x11 colorSee also
x11-colorColoring objects
x11-colorSee also
x11-colorX color names

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] In its simplest form, a font family usually contains fonts in roman, italic, bold, and bold italic styles.

[2] Selecting OpenType font scripts and languages is not supported yet.

[3] The data is taken from the Pango reference for version 1.46.1; the syntax supported by LilyPond is actually a subset of what Pango provides.

[4] This implies that, contrary to single fonts, a trailing comma is never necessary.

[5] To be more precise, ‘emmentaler’ (with a lowercase ‘e’, which is mandatory in the argument to #:music and #:brace) is a set of fonts (but not a font family in the FontConfig sense) that LilyPond accesses and manages directly. Instead of various styles, however, it comes with different design sizes, see Music fonts and Replacing the notation font. The corresponding FontConfig font names are ‘Emmentaler-size’, where size is one of the numbers 11, 13, 14, 16, 18, 20, 23, and 26.

For braces, the FontConfig font name is ‘Emmentaler-Brace’.

[6] LilyPond’s Emmentaler fonts contain three glyph sets: Feta (for modern notation), Parmesan (for ancient notation), and braces. Both Feta and Parmesan are accessed with the ‘fetaMusic’ encoding.

[7] There exists another, older support file for Persian classical music also called ‘persian.ly’ (written by Kees van den Doel) that no longer works with the current LilyPond version; while note names are compatible, the selection of key signatures is not.

[8] If the interval defined by the note before the koron and after the koron is a minor third. The same is true for the note below the finalis in the ‘Esfahan’ dastgah according to some (but not all) Persian musicians.

[9] \should-print-page-numbers-global can differ from \should-print-page-number for the first page in the book, depending on the print-first-page-number setting of the \paper block.

[10] Scheme tutorial, contains a short tutorial on entering numbers, lists, strings, and symbols in Scheme.

[11] Internally, this works by activating the ‘dlig’ OpenType feature of the Emmentaler font.

[12] For historical reasons, some but not all of the functions defined by LilyPond start with the ly: prefix.


Table of Contents


LilyPond — Notation Reference v2.24.3 (stable-branch).