LilyPond — Notation Reference

Appendices

1 Musical notation

This chapter explains how to create musical notation.

1.1 Pitches

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

1.1.1 Writing pitches

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

Absolute octave entry

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

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

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

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

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

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:

• If no octave changing mark is used on a pitch, its octave is calculated so that the interval with the previous note is less than a fifth. This interval is determined without considering accidentals.
• An octave changing mark ' or , can be added to respectively raise or lower a pitch by an extra octave, relative to the pitch calculated without an octave mark.
• Multiple octave changing marks can be used. For example, '' and ,, will alter the pitch by two octaves.
• The pitch of the first note is relative to startpitch. startpitch is specified in absolute octave mode. Which choices are meaningful?

  an octave of c

  Identifying middle C with c' is quite basic, so finding octaves of c tends to be straightforward. If your music starts with gis above c''', you’d write something like \relative c''' { gis' … }

  an octave of the first note inside

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

  no explicit starting pitch

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

  The documentation will usually employ the last option.

Here is the relative mode shown in action:

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

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

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

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

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

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

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

To use absolute mode inside of \relative, put the absolute music inside \fixed c { … } and the absolute pitches will not affect the octaves of the relative music:

\relative {
  c'4 \fixed c { f'' g'' } c |
  c4 \fixed c'' { f g } c
}

\relative has no effect on \chordmode blocks.

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

\relative is not allowed inside of \chordmode blocks.

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

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

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

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

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

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

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
}

See also

Music Glossary: fifth, interval, Pitch names.

Notation Reference: Octave checks.

Snippets: Pitches.

Internals Reference: RelativeOctaveMusic.

Accidentals

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

\relative c'' { ais1 aes aisis aeses }

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

\relative c'' { a4 aes a2 }

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

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

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

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

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

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

Selected Snippets

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

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

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

\paper { tagline = ##f }

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
}

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
}

The available languages and the note names they define are:

Language	Note Names
nederlands	c d e f g a bes b
català or  catalan	do re mi fa sol la sib si
deutsch	c d e f g a b h
english	c d e f g a bf/b-flat b
español or  espanol	do re mi fa sol la sib si
français	do ré/re mi fa sol la sib si
italiano	do re mi fa sol la sib si
norsk	c d e f g a b h
português or  portugues	do re mi fa sol la sib si
suomi	c d e f g a b h
svenska	c d e f g a b h
vlaams	do re mi fa sol la sib si

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

Language	sharp	flat	double sharp	double flat
nederlands	is	es	isis	eses
català or  catalan	d/s	b	dd/ss	bb
deutsch	is	es	isis	eses
english	s/-sharp	f/-flat	ss/x/-sharpsharp	ff/-flatflat
español or  espanol	s	b	ss/x	bb
français	d	b	dd/x	bb
italiano	d	b	dd	bb
norsk	iss/is	ess/es	ississ/isis	essess/eses
português or  portugues	s	b	ss	bb
suomi	is	es	isis	eses
svenska	iss	ess	ississ	essess
vlaams	k	b	kk	bb

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 }

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

Language	semi-sharp	semi-flat	sesqui-sharp	sesqui-flat
nederlands	ih	eh	isih	eseh
català or  catalan	qd/qs	qb	tqd/tqs	tqb
deutsch	ih	eh	isih	eseh
english	qs	qf	tqs	tqf
español or  espanol	cs	cb	tcs	tcb
français	sd	sb	dsd	bsb
italiano	sd	sb	dsd	bsb
norsk	ih	eh	issih/isih	esseh/eseh
português or  portugues	sqt	bqt	stqt	btqt
suomi	ih	eh	isih	eseh
svenska	ih	eh	issih	esseh
vlaams	hk	hb	khk	bhb

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

\language "deutsch"

\relative c'' { asah2 eh aih eisih }

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
}

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

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

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

\relative {
  c''4 f g f

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

See also

Snippets: Pitches.

Internals Reference: RelativeOctaveCheck.

Transpose

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

\transpose frompitch topitch musicexpr

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

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

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

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

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

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

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

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

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

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

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

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

For more information about transposing instruments, see Instrument transpositions.

Selected Snippets

Transposing pitches with minimum accidentals ("Smart" transpose)

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

Double accidentals should be removed

B sharp -> C

E sharp -> F

C flat -> B

F flat -> E

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

#(define (naturalize-pitch p)
   (let ((o (ly:pitch-octave p))
         (a (* 4 (ly:pitch-alteration p)))
         ;; alteration, a, in quarter tone steps,
         ;; for historical reasons
         (n (ly:pitch-notename p)))
     (cond
      ((and (> a 1) (or (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 { }
}

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
}

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
}

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.

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
}

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
}

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
}

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
}

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
}

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
}

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'

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'

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'

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

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

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

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

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

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

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

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
}

\paper { tagline = ##f }

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

Key signature

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
}

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
}

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

Selected Snippets

Preventing natural signs from being printed when the key signature changes

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

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

Non-traditional key signatures

The commonly used \key command sets the 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 |
}

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
}

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 = #'normal
  \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
}

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
}

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

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
}

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

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

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

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:

voice

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

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

modern

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

modern-cautionary

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

modern-voice

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

modern-voice-cautionary

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

piano

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

This accidental style applies to the current GrandStaff or PianoStaff unless qualified with a second argument.

piano-cautionary

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

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.

choral-cautionary

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

neo-modern

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

neo-modern-cautionary

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

neo-modern-voice

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

neo-modern-voice-cautionary

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

dodecaphonic

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

dodecaphonic-no-repeat

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

dodecaphonic-first

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

teaching

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

no-reset

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

forget

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

See also

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 taken into account. Forcing accidentals with ‘!’ or ‘?’ may be required when the same note name occurs simultaneously with different alterations, as in <f! fis!>.

\relative c' <<
  { fis8 g } \\
  { f! f }
>>

A more sophisticated solution is given in LSR snippet 1172.

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:

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

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

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

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

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
}

Selected Snippets

Adding ambitus per voice

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

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

Ambitus with multiple voices

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

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

Changing the ambitus gap

It is possible to change the default gap 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''
}

\paper { tagline = ##f }

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
}

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
}

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
}

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

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

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

There is also a similar shorthand for diamond shapes:

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

Predefined commands

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

See also

Snippets: Pitches.

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

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

Easy notation note heads

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

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

Predefined commands

\easyHeadsOn, \easyHeadsOff.

Selected Snippets

Numbers as easy note heads

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

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

#(define Ez_numbers_engraver
   (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)

\paper { tagline = ##f }

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