GNU LilyPond — Notation Reference

The music typesetter

This document is also available as a PDF and as a HTML indexed multiple pages.

This file documents GNU LilyPond.

Copyright 1999–2009 by the authors

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections. A copy of the license is included in the section entitled “GNU Free Documentation License”.

This is the Notation Reference (NR) for GNU LilyPond version 2.12.3. For more information about how this fits with the other documentation, see About the documentation.

More information can be found at http://www.lilypond.org/. The website contains on-line copies of this and other documentation.

We want to dedicate this program to all the friends that we met through music.

Han-Wen and Jan

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
c d e f
g a b c
d 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' c'' e' g
d'' d' d c
\clef bass
c, c,, e, g
d,, d, d c

See also

Music Glossary: Pitch names.

Snippets: Pitches.

Relative octave entry

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

\relative startpitch musicexpr

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

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

Here is the relative mode shown in action:

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

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

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

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

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

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

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

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

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

See also

Music Glossary: fifth, interval, Pitch names.

Notation Reference: Octave checks.

Snippets: Pitches.

Internals Reference: RelativeOctaveMusic.

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.

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

Accidentals

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

ais1 aes aisis aeses

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

a4 aes a2

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

ceseh1 ces ceh c cih cis cisih

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

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

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

cis1 ~ cis ~
\break
cis

Selected Snippets

Preventing extra naturals from being automatically added

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

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

Makam example

Makam is a type of melody from Turkey using 1/9th-tone microtonal alterations. Consult the initialization file ‘ly/makam.ly’ for details of pitch names and alterations.

% Initialize makam settings
\include "makam.ly"

\relative c' {
  \set Staff.keySignature = #`((3 . ,BAKIYE) (6 . ,(- KOMA)))
  c4 cc db fk
  gbm4 gfc gfb efk
  fk4 db cc c
}

See also

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

Learning Manual: Accidentals and key signatures.

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

Snippets: Pitches.

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

Known issues and warnings

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

Note names in other languages

There are predefined sets of note and accidental names for various other languages. To use them, include the language-specific init file listed below. For example, to use English note names, add \include "english.ly" to the input file.

The available language files and the note names they define are:

Language File	Note Names
‘nederlands.ly’	c d e f g a bes b
‘arabic.ly’	do re mi fa sol la sib si
‘catalan.ly’	do re mi fa sol la sib si
‘deutsch.ly’	c d e f g a b h
‘english.ly’	c d e f g a bf b
‘espanol.ly’	do re mi fa sol la sib si
‘italiano.ly’	do re mi fa sol la sib si
‘norsk.ly’	c d e f g a b h
‘portugues.ly’	do re mi fa sol la sib si
‘suomi.ly’	c d e f g a b h
‘svenska.ly’	c d e f g a b h
‘vlaams.ly’	do re mi fa sol la sib si

and the accidental suffixes they define are:

Language File	sharp	flat	double sharp	double flat
‘nederlands.ly’	-is	-es	-isis	-eses
‘arabic.ly’	-d	-b	-dd	-bb
‘catalan.ly’	-d/-s	-b	-dd/-ss	-bb
‘deutsch.ly’	-is	-es	-isis	-eses
‘english.ly’	-s/-sharp	-f/-flat	-ss/-x/-sharpsharp	-ff/-flatflat
‘espanol.ly’	-s	-b	-ss	-bb
‘italiano.ly’	-d	-b	-dd	-bb
‘norsk.ly’	-iss/-is	-ess/-es	-ississ/-isis	-essess/-eses
‘portugues.ly’	-s	-b	-ss	-bb
‘suomi.ly’	-is	-es	-isis	-eses
‘svenska.ly’	-iss	-ess	-ississ	-essess
‘vlaams.ly’	-k	-b	-kk	-bb

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

a2 as e es a ases e eses

Some music uses microtones whose alterations are fractions of a ‘normal’ sharp or flat. The note names for quarter-tones defined in the various language files are listed in the following table. Here the prefixes semi- and sesqui- mean ‘half’ and ‘one and a half’, respectively. For the other languages, no special names have been defined yet.

Language File	semi-sharp	semi-flat	sesqui-sharp	sesqui-flat
‘nederlands.ly’	-ih	-eh	-isih	-eseh
‘arabic.ly’	-sd	-sb	-dsd	-bsb
‘deutsch.ly’	-ih	-eh	-isih	-eseh
‘english.ly’	-qs	-qf	-tqs	-tqf
‘italiano.ly’	-sd	-sb	-dsd	-bsb
‘portugues.ly’	-sqt	-bqt	-stqt	-btqt

See also

Music Glossary: Pitch names.

Snippets: Pitches.

1.1.2 Changing multiple pitches

This section discusses how to modify pitches.

Octave checks

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

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

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

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

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

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

\relative c'' {
  c4 f g f

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

See also

Snippets: Pitches.

Internals Reference: RelativeOctaveCheck.

Transpose

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

\transpose frompitch topitch musicexpr

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

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

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

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

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

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

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

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

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

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

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

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

For more information about transposing instruments, see Instrument transpositions.

Selected Snippets

Transposing pitches with minimum accidentals ("Smart" transpose)

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

Double accidentals should be removed

B sharp -> C

E sharp -> F

C flat -> B

F flat -> E

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

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

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

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

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

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

See also

Notation Reference: Instrument transpositions.

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.

1.1.3 Displaying pitches

This section discusses how to alter the output of pitches.

Clef

The clef may be altered. Middle C is shown in every example.

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

Other clefs include:

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

\break

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

Further supported clefs are described under Mensural clefs and Gregorian clefs.

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. The clef name must be enclosed in quotes when it contains underscores or digits.

\clef treble
c2 c
\clef "treble_8"
c2 c
\clef "bass^15"
c2 c

Selected Snippets

Tweaking clef properties

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

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

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

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

\layout { ragged-right = ##t }

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

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

  \set Staff.clefGlyph = #"clefs.F"
  \set Staff.clefPosition = #2
  c'1
  \set Staff.clefGlyph = #"clefs.G"
  c'1
  \set Staff.clefGlyph = #"clefs.C"
  c'1
  \set Staff.clefOctavation = #7
  c'1
  \set Staff.clefOctavation = #0
  \set Staff.clefPosition = #0
  c'1
  
  % Return to the normal clef:

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

See also

Notation Reference: Mensural clefs, Gregorian clefs.

Snippets: Pitches.

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

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.

\key g \major
fis1
f
fis

Selected Snippets

Preventing natural signs from being printed when the key signature changes

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

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

Non-traditional key signatures

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

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

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

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

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

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

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

See also

Music Glossary: church mode, scordatura.

Learning Manual: Accidentals and key signatures.

Snippets: Pitches.

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

Ottava brackets

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

a'2 b
\ottava #1
a b
\ottava #0
a b

The ottava function also takes -1 (for 8va bassa), 2 (for 15ma), and -2 (for 15ma bassa) as arguments.

Selected Snippets

Ottava text

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

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

See also

Music Glossary: octavation.

Snippets: Pitches.

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

Instrument transpositions

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

\transposition pitch

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

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

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

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

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

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

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

\key bes \major
\transposition bes
c2 g

See also

Music Glossary: concert pitch, transposing instrument.

Notation Reference: Quoting other voices, Transpose.

Snippets: Pitches.

Automatic accidentals

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

\new Staff <<
  #(set-accidental-style 'voice)
  { … }
>>

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

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

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

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

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

\new PianoStaff {
  <<
    \context Staff = "up" {
      #(set-accidental-style 'default)
      \musicA
    }
    \context Staff = "down" {
      #(set-accidental-style 'default)
      \musicB
    }
  >>
}

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

\new PianoStaff {
  <<
    \context Staff = "up" {
      %%% change the next line as desired:
      #(set-accidental-style 'default 'Score)
      \musicA
    }
    \context Staff = "down" {
      \musicB
    }
  >>
}

default

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

voice

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

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

modern

This rule corresponds to the common practice in the twentieth century. It prints the same accidentals as default, with two exceptions that serve to avoid ambiguity: after temporary accidentals, cancellation marks are printed also in the following measure (for notes in the same octave) and, in the same measure, for notes in other octaves. Hence the naturals before the b and the c in the second measure of the upper staff:

modern-cautionary

This rule is similar to modern, but the ‘extra’ accidentals (the ones not typeset by default) are typeset as cautionary accidentals. They are by default printed with parentheses, but they can also be printed in reduced size by defining the cautionary-style property of AccidentalSuggestion.

modern-voice

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

modern-voice-cautionary

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

piano

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

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

piano-cautionary

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

neo-modern

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

neo-modern-cautionary

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

dodecaphonic

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

teaching

This rule is intended for students, and makes it easy to create scale sheets with automagically 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. Unlike dodecaphonic, this rule never prints any naturals.

Selected Snippets

Dodecaphonic-style accidentals for each note including naturals

In early 20th century works, starting with Schoenberg, Berg and Webern (the "Second" Viennese school), every pitch in the twelve-tone scale has to be regarded as equal, without any hierarchy such as the classical (tonal) degrees. Therefore, these composers print one accidental for each note, even at natural pitches, to emphasize their new approach to music theory and language.

This snippet shows how to achieve such notation rules.

\score {
  \new Staff {
    #(set-accidental-style 'dodecaphonic)
    c'4 dis' cis' cis'
    c'4 dis' cis' cis'
    c'4 c' dis' des'
  }
  \layout {
    \context {
      \Staff
      \remove "Key_engraver"
    }
  }
}

See also

Snippets: Pitches.

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

Known issues and warnings

Simultaneous notes are considered to be entered in sequential mode. This means that in a chord the accidentals are typeset as if the notes in the chord happen one at a time, in the order in which they appear in the input file. This is a problem when accidentals in a chord depend on each other, which does not happen for the default accidental style. The problem can be solved by manually inserting ! and ? for the problematic notes.

Ambitus

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

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

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

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

Selected Snippets

Adding ambitus per voice

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

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

Ambitus with multiple voices

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

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

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

Note heads may be altered:

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

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

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

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

See also

Snippets: Pitches.

Notation Reference: Note head styles, Chorded 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.

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:

\aikenHeads
c, d e f g a b c
\sacredHarpHeads
c, d e f g a b c

Shapes are typeset according to the step in the scale, where the base of the scale is determined by the \key command.

Predefined commands

\aikenHeads, \sacredHarpHeads.

Selected Snippets

Applying note head styles depending on the step of the scale

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

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

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

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

\score {
  \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
    }
  }
  \layout { ragged-right = ##t }
}

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

See also

Snippets: Pitches.

Notation Reference: Note head styles.

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

Improvisation

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

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

Predefined commands

\improvisationOn, \improvisationOff.

See also

Snippets: Pitches.

Internals Reference: Pitch_squash_engraver, Voice, RhythmicStaff.

1.2 Rhythms

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

1.2.1 Writing rhythms

Durations

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

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

Here are the same durations with automatic beaming turned off.

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

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

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

a a a2 a a4 a a1 a

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

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

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

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

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

Dots are normally moved up to avoid staff lines, except in polyphonic situations. Predefined commands are available to force a particular direction manually, for details see Direction and placement.

Predefined commands

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

See also

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

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

Snippets: Rhythms.

Internals Reference: Dots, DotColumn.

Known issues and warnings

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

Tuplets

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

\times fraction { music }

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

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

The automatic placement of the tuplet bracket above or below the notes may be overridden manually with predefined commands, for details see Direction and placement.

Tuplets may be nested:

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

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

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

Predefined commands

\tupletUp, \tupletDown, \tupletNeutral.

Selected Snippets

Entering several tuplets using only one \times command

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

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

For more information about make-moment, see "Time administration".

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

Changing the tuplet number

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

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

Permitting line breaks within beamed tuplets

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

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

See also

Music Glossary: triplet, tuplet, polymetric.

Learning Manual: Tweaking methods.

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

Snippets: Rhythms.

Internals Reference: TupletBracket, TupletNumber, TimeScaledMusic.

Known issues and warnings

When the first note on a staff is a grace note followed by a tuplet the grace note must be placed before the \times command to avoid errors. Anywhere else, grace notes may be placed within tuplet brackets.

Scaling durations

You can alter the duration of single notes, rests or chords by a fraction N/M by appending *N/M (or *N if M is 1) to the duration. This will not affect the appearance of the notes or rests produced, but the altered duration will be used in calculating the position within the measure and setting the duration in the MIDI output. Multiplying factors may be combined such as *L*M/N.

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

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

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

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

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

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

See also

Notation Reference: Tuplets, Invisible rests, Polymetric notation.

Snippets: Rhythms.

Ties

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

A tie is entered using the tilde symbol ~

a2 ~ a

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

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

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

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

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

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

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

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

<c f g>1\laissezVibrer

The vertical placement of ties may be controlled, see Predefined commands, or for details, see Direction and placement.

Solid, dotted or dashed ties may be specified, see Predefined commands.

Predefined commands

\tieUp, \tieDown, \tieNeutral, \tieDotted, \tieDashed, \tieSolid.

Selected Snippets

Using ties with arpeggios

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

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

Engraving ties manually

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

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

See also

Music Glossary: tie, laissez vibrer.

Notation Reference: Automatic note splitting.

Snippets: Rhythms.

Internals Reference: LaissezVibrerTie, LaissezVibrerTieColumn, TieColumn, Tie.

Known issues and warnings

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

Changing clefs or octavations 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 predefined commands shown:

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

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

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

a4\rest d4\rest

Selected Snippets

Rest styles

Rests may be used in various styles.

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

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

See also

Music Glossary: breve, longa, maxima.

Notation Reference: Full measure rests.

Snippets: Rhythms.

Internals Reference: Rest.

Known issues and warnings

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

Invisible rests

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

c4 c s c
s2 c

Spacer rests are available only in note mode and chord mode. In other situations, for example, when entering lyrics, \skip is used to skip a musical moment. \skip requires an explicit duration.

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

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

s1 s s

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

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

See also

Snippets: Rhythms.

Internals Reference: SkipMusic

Full measure rests

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

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

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

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

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

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

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

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

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

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

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

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

Predefined commands

\textLengthOn, \textLengthOff, \fermataMarkup, \compressFullBarRests, \expandFullBarRests.

Selected Snippets

Changing form of multi-measure rests

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

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

Positioning multi-measure rests

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

\relative c'' {
  % Multi-measure rests by default are set under the fourth line
  R1
  % They can be moved with an override
  \override MultiMeasureRest #'staff-position = #-2
  R1
  % A value of 0 is the default position;
  % the following trick moves the rest to the center line
  \override MultiMeasureRest #'staff-position = #-0.01
  R1
  % Multi-measure rests in odd-numbered voices are under the top line
  << { R1 } \\ { a1 } >>
  % Multi-measure rests in even-numbered voices are under the bottom line
  << { c1 } \\ { R1 } >>
  % They remain separated even in empty measures
  << { R1 } \\ { R1 } >>
  % This brings them together even though there are two voices
  \compressFullBarRests
  <<
    \revert MultiMeasureRest #'staff-position
    { R1*3 }
    \\
    \revert MultiMeasureRest #'staff-position
    { R1*3 }
  >>
}

Multi-measure rest markup

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

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

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

See also

Music Glossary: multi-measure rest.

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

Snippets: Rhythms.

Internals Reference: MultiMeasureRest, MultiMeasureRestNumber, MultiMeasureRestText.

Known issues and warnings

If an attempt is made to use fingerings (e.g., R1*10-4) to put numbers over multi-measure rests, the fingering numeral (4) may collide with the bar counter numeral (10).

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

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

1.2.3 Displaying rhythms

Time signature

The time signature is set as follows:

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

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

\time 2/4
c2 c
\break
c c
\break
\time 4/4
c c c c

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

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

Mensural time signatures are covered in Mensural time signatures.

Predefined commands

\numericTimeSignature, \defaultTimeSignature.

Selected Snippets

Changing the time signature without affecting the beaming

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

\relative c'' {
  \time 3/4
  a16 a a a a a a a a a a a

  % Change time signature symbol but keep 3/4 beaming
  % due to unchanged underlying time signature
  \set Score.timeSignatureFraction = #'(12 . 16)
  a16 a a a a a a a a a a a

  \time 12/16
  % Lose 3/4 beaming now \time has been changed
  a16 a a a a a a a a a a a
}

Compound time signatures

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

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

\relative c' {
  \override Staff.TimeSignature #'stencil = #(compound-time "2" "3" "8")
  \time 5/8
  #(override-auto-beam-setting '(end 1 8 5 8) 1 4)
  c8 d e fis gis
  c8 fis, gis e d
  c8 d e4 gis8
}

See also

Music Glossary: time signature

Notation Reference: Mensural time signatures, Time administration.

Snippets: Rhythms.

Internals Reference: TimeSignature, Timing_translator.

Upbeats

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

\partial duration

where duration is the rhythmic length of the interval before the start of the first complete measure:

\partial 4 e4 |
a2. c,4 |

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

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

Internally, this is translated into

\set Timing.measurePosition = -duration

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

See also

Music Glossary: anacrusis.

Notation Reference: Grace notes.

Snippets: Rhythms.

Internal Reference: Timing_translator.

Known issues and warnings

The \partial command is intended to be used only at the beginning of a piece. If you use it after the beginning, some odd warnings may occur.

Unmetered music

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

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

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

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

Predefined commands

\cadenzaOn, \cadenzaOff.

See also

Music Glossary: cadenza.

Notation Reference: Visibility of objects.

Snippets: Rhythms.

Known issues and warnings

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

\bar ""

to indicate where breaks can occur.

Polymetric notation

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

Staves with different time signatures, equal measure lengths

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

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

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

Staves with different time signatures, unequal bar lengths

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

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

% Now each staff has its own time signature.

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

Selected Snippets

Compound time signatures

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

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

\relative c' {
  \override Staff.TimeSignature #'stencil = #(compound-time "2" "3" "8")
  \time 5/8
  #(override-auto-beam-setting '(end 1 8 5 8) 1 4)
  c8 d e fis gis
  c8 fis, gis e d
  c8 d e4 gis8
}

See also

Music Glossary: polymetric, polymetric time signature, meter.

Notation Reference: Time signature, Scaling durations.

Snippets: Rhythms.

Internals Reference: TimeSignature, Timing_translator, Default_bar_line_engraver, Staff.

Known issues and warnings

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

Automatic note splitting

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

\new Voice \with {
  \remove "Note_heads_engraver"
  \consists "Completion_heads_engraver"
}

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

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

See also

Music Glossary: tie

Learning Manual: Engravers explained, Adding and removing engravers.

Snippets: Rhythms.

Internals Reference: Note_heads_engraver, Completion_heads_engraver, Forbid_line_break_engraver.

Known issues and warnings

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

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

Showing melody rhythms

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

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

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

<<
  \new ChordNames {
    \chordmode {
      c1 f g c
    }
  }

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

Predefined commands

\improvisationOn, \improvisationOff.

Selected Snippets

Guitar strum rhythms

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

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

See also

Snippets: Rhythms.

Internals Reference: RhythmicStaff, Pitch_squash_engraver.

1.2.4 Beams

Automatic beams

By default, beams are inserted automatically:

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

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

It is possible to define beaming patterns that differ from the defaults. The default beaming rules for most common time signatures are defined in ‘scm/auto-beam.scm’. If there are no beaming rules defined for a particular beam’s duration in the time signature being used, its beaming is controlled by the values of three context properties, measureLength, beatLength and beatGrouping. Both the beaming rules and the context properties can be overridden, see Setting automatic beam behavior.

Automatic beaming may be turned off and on with \autoBeamOff and \autoBeamOn commands:

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

Predefined commands

\autoBeamOff, \autoBeamOn.

Selected Snippets

Beams across line breaks

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

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

Changing beam knee gap

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

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

See also

Notation Reference: Manual beams, Setting automatic beam behavior.

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

Snippets: Rhythms.

Internals Reference: Beam.

Known issues and warnings

Automatically kneed cross-staff beams cannot be used together with hidden staves. See Hiding staves.

Beams can collide with note heads and accidentals in other voices

Setting automatic beam behavior

The placement of automatic beams is determined by the rules described in Automatic beams. There are two mutually exclusive ways in which these rules may be modified. The first, modifying the grouping of beats, applies to uncommon time signatures, i.e. those for which there are no predefined rules defining the beam end points. The second method, modifying the specification of the beam end points, can be used for any time signature. This second method must be used for those time signatures and beam durations combinations for which beam ending rules are pre-defined, unless these have all been reverted. There are predefined rules for time signatures of 3/2, 3/4, 4/4, 2/4, 4/8, 4/16, 6/8, 9/8 and 12/8.

Modifying the grouping of beats

If there are no beam-ending rules defined for the beam duration of a particular beam in the time signature in use, its beaming is controlled by three context properties: measureLength, beatLength and beatGrouping. These properties may be set in the Score, Staff or Voice contexts to delimit their scope. The default values are set while processing \time commands, so the \set commands must be placed after all \time commands.

These determine the beaming as follows:

Beams may begin anywhere (unless a beam is already active). Beams end at a time determined by the values of beatGrouping and beatLength, as follows:

• If beatGrouping and beatLength are consistent with measureLength, beatGrouping is used to determine the end points of beams.
• If beatGrouping and beatLength are inconsistent with measureLength, beatLength is used to determine the end points of beams.

By default the measureLength and beatLength are derived from the time signature set by the \time command. The measureLength is set to be exactly the same length as the measure length given by the time signature, and the beatLength is set to be the same as one over the denominator of the time signature.

The default value of beatGrouping is taken from a table in ‘scm/music-functions.scm’. To find this, see Other sources of information. It defines the beat grouping for 5/8, 6/8, 8/8, 9/8 and 12/8 time signatures.

Both measureLength and beatLength are moments, units 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.

beatGrouping is a list of integers giving the number of beats in each group.

Selected Snippets

Grouping beats

Beaming patterns may be altered with the beatGrouping property:

\relative c'' {
  \time 5/16
  #(override-auto-beam-setting '(end * * 5 16) 5 16)
  \set beatGrouping = #'(2 3)
  c8^"(2+3)" c16 c8
  \set beatGrouping = #'(3 2)
  c8^"(3+2)" c16 c8
}

Specifying context with beatGrouping

By specifying the context, the effect of beatGrouping can be limited to the context specified, and the values which may have been set in higher-level contexts can be overridden. The \set commands must be placed after all \time commands:

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

Using beatLength and beatGrouping

The property measureLength determines where bar lines should be inserted and, with beatLength and beatGrouping, how automatic beams should be generated for beam durations and time signatures for which no beam-ending rules are defined. This example shows several ways of controlling beaming by setting these properties. The explanations are shown as comments in the code.

\relative c'' {
  \time 3/4
  % The default in 3/4 time is to beam in three groups
  % each of a quarter note length
  a16 a a a a a a a a a a a

  \time 12/16
  % No auto-beaming is defined for 12/16
  a16 a a a a a a a a a a a

  \time 3/4
  % Change time signature symbol, but retain underlying 3/4 beaming
  \set Score.timeSignatureFraction = #'(12 . 16)
  a16 a a a a a a a a a a a

  % The 3/4 time default grouping of (1 1 1) and beatLength of 1/8
  % are not consistent with a measureLength of 3/4, so the beams
  % are grouped at beatLength intervals
  \set Score.beatLength = #(ly:make-moment 1 8)
  a16 a a a a a a a a a a a

  % Specify beams in groups of (3 3 2 3) 1/16th notes
  % 3+3+2+3=11, and 11*1/16<>3/4, so beatGrouping does not apply,
  % and beams are grouped at beatLength (1/16) intervals
  \set Score.beatLength = #(ly:make-moment 1 16)
  \set Score.beatGrouping = #'(3 3 2 3)
  a16 a a a a a a a a a a a

  % Specify beams in groups of (3 4 2 3) 1/16th notes
  % 3+4+2+3=12, and 12*1/16=3/4, so beatGrouping applies
  \set Score.beatLength = #(ly:make-moment 1 16)
  \set Score.beatGrouping = #'(3 4 2 3)
  a16 a a a a a a a a a a a
}

Sub-dividing beams

The beams of consecutive 16th (or shorter) notes are, by default, not sub-divided. That is, the three (or more) beams stretch unbroken over entire groups of notes. This behavior can be modified to sub-divide the beams into sub-groups by setting the property subdivideBeams. When set, multiple beams will be sub-divided at intervals defined by the current value of beatLength by reducing the multiple beams to just one beam between the sub-groups. Note that beatLength 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 make-moment function, as shown here:

\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 beatLength = #(ly:make-moment 1 8)
  c32[ c c c c c c c]

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

Conducting signs, measure grouping signs

Options to group beats within a bar are available through the Scheme function set-time-signature, which takes three arguments: the number of beats, the beat length, and the internal grouping of beats in the measure. If the Measure_grouping_engraver is included, the function will also create MeasureGrouping signs. Such signs ease reading rhythmically complex modern music. In the example, the 9/8 measure is subdivided in 2, 2, 2 and 3. This is passed to set-time-signature as the third argument: '(2 2 2 3):

\score {
  \relative c'' {
    #(set-time-signature 9 8 '(2 2 2 3))
    #(revert-auto-beam-setting '(end * * 9 8) 3 8)
    #(override-auto-beam-setting '(end 1 8 9 8) 1 4)
    #(override-auto-beam-setting '(end 1 8 9 8) 2 4)
    #(override-auto-beam-setting '(end 1 8 9 8) 3 4)
    g8 g d d g g a( bes g) |
    #(set-time-signature 5 8 '(3 2))
    a4. g4
  }
  \layout {
    \context {
      \Staff
      \consists "Measure_grouping_engraver"
    }
  }
}

Modifying the beam end points

In common time signatures, automatic beams can start on any note but can end at only a few positions within the measure, namely at durations specified by the properties in autoBeamSettings. These properties consist of a list of rules defining where beams can end. The default autoBeamSettings rules are defined in ‘scm/auto-beam.scm’. To find this, see Other sources of information.

This method must be used for the time signatures for which beam-ending rules are defined by default, unless these have all been reverted. It is also particularly suitable for many other time signatures if the time signature of the measures changes frequently, or if the beaming should be different for different beam durations.

In order to add a rule to the list, use

#(override-auto-beam-setting
  '(beam-limit
    beam-numerator  beam-denominator
    time-signature-numerator time-signature-denominator)
  moment-numerator moment-denominator [context])

where

• beam-limit is the type of automatic beam limit defined. This can be either begin or end but only end is effective.
• beam-numerator/beam-denominator is the beam duration to which the rule is to apply. A beam is considered to have the duration of its shortest note. Set beam-numerator and beam-denominator to '*' to have this rule apply to beams of any duration.
• time-signature-numerator/time-signature-denominator specifies the time signature to which this rule should apply. If time-signature-numerator and time-signature-denominator are set to '*' this rule will apply in any time signature.
• monent-numerator/moment-denominator is the position in the bar at which the beam should end.
• context is optional, and it specifies the context at which the change should be made. The default is 'Voice.

  #(score-override-auto-beam-setting '(A B C D) E F) is equivalent to #(override-auto-beam-setting '(A B C D) E F 'Score).

For example, if automatic beams should always end on the first quarter note, whatever the time signature or beam duration, use

a8 a a a a a a a
#(override-auto-beam-setting '(end * * * *) 1 4)
a8 a a a a a a a

You can force the beam settings to take effect only on beams whose shortest note is a certain duration

\time 2/4
% end 1/16 beams for all time signatures at the 1/16 moment
#(override-auto-beam-setting '(end 1 16 * *) 1 16)
a16 a a a a a a a |
a32 a a a a16 a a a a a |
% end 1/32 beams for all time signatures at the 1/16 moment
#(override-auto-beam-setting '(end 1 32 * *) 1 16)
a32 a a a a16 a a a a a |

You can force the beam settings to take effect only in certain time signatures

\time 5/8
% end beams of all durations in 5/8 time signature at the 2/8 moment
#(override-auto-beam-setting '(end * * 5 8) 2 8)
c8 c d d d
\time 4/4
e8 e f f e e d d
\time 5/8
c8 c d d d

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
% Context not specified - does not work correctly
#(override-auto-beam-setting '(end * * 7 8) 3 8)
#(override-auto-beam-setting '(end * * 7 8) 4 8)
#(override-auto-beam-setting '(end * * 7 8) 5 8)
<< {a8 a a a16 a a a a8 a} \\ {f4. f8 f f f} >>

% Works correctly with context specified
#(override-auto-beam-setting '(end * * 7 8) 3 8 'Staff)
#(override-auto-beam-setting '(end * * 7 8) 4 8 'Staff)
#(override-auto-beam-setting '(end * * 7 8) 5 8 'Staff)
<< {a8 a a a16 a a a a8 a} \\ {f4. f8 f f f} >>

Any unwanted or conflicting default endings must be reverted for your time signature(s). Existing auto-beam rules are removed by using

#(revert-auto-beam-setting
  '(beam-limit
    beam-numerator  beam-denominator
    time-signature-numerator time-signature-denominator)
  moment-numerator moment-denominator [context])

beam-limit, beam-numerator, beam-denominator, time-signature-numerator, time-signature-denominator, moment-numerator, moment-denominator and context are the same as above.

\time 4/4
a16 a a a a a a a a a a a a a a a
% undo a rule ending 1/16 beams in 4/4 time at 1/4 moment
#(revert-auto-beam-setting '(end 1 16 4 4) 1 4)
a16 a a a a a a a a a a a a a a a

The rule in a revert-auto-beam-setting statement must exactly match the original rule. That is, no wildcard expansion is taken into account.

\time 1/4
#(override-auto-beam-setting '(end 1 16 1 4) 1 8)
a16 a a a
#(revert-auto-beam-setting '(end 1 16 * *) 1 8) % this won't revert it!
a a a a
#(revert-auto-beam-setting '(end 1 16 1 4) 1 8) % this will
a a a a

Selected Snippets

Beam grouping in 7/8 time

There are no default automatic beam groupings specified for 7/8 time, so if automatic beams are required the grouping must be specified. For example, to group all beams 2-3-2 in 7/8 time, specify beam endings at 2/8 and 5/8:

\relative c'' {
  \time 7/8
  % rhythm 2-3-2
  a8 a a a a a a
  #(override-auto-beam-setting '(end * * 7 8) 2 8)
  #(override-auto-beam-setting '(end * * 7 8) 5 8)
  a8 a a a a a a
}

Reverting default beam endings

To typeset beams grouped 3-4-3-2 in 12/8 it is necessary first to override the default beam endings in 12/8, and then to set up the new beaming endings:

\relative c'' {
  \time 12/8

  % Default beaming
  a8 a a a a a a a a a a a

  % Revert default values in scm/auto-beam.scm for 12/8 time
  #(revert-auto-beam-setting '(end * * 12 8) 3 8)
  #(revert-auto-beam-setting '(end * * 12 8) 3 4)
  #(revert-auto-beam-setting '(end * * 12 8) 9 8)
  a8 a a a a a a a a a a a

  % Set new values for beam endings
  #(override-auto-beam-setting '(end * * 12 8) 3 8)
  #(override-auto-beam-setting '(end * * 12 8) 7 8)
  #(override-auto-beam-setting '(end * * 12 8) 10 8)
  a8 a a a a a a a a a a a
}

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
  #(score-override-auto-beam-setting '(end * * 5 4) 3 8)
  #(score-override-auto-beam-setting '(end * * 5 4) 7 8)
  <<
    \new Staff {
      c8 c c c c c c c c c
    }
    \new Staff {
      % Modify beaming for just this staff
      #(override-auto-beam-setting '(end * * 5 4) 6 8 'Staff)
      #(revert-auto-beam-setting '(end * * 5 4) 7 8 'Staff)
      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
          #(override-auto-beam-setting '(end * * 5 4) 6 8)
          #(revert-auto-beam-setting '(end * * 5 4) 7 8)
          a8 a a a a a a a a a
        }
      >>
    }
  >>
}

Predefined commands

\autoBeamOff, \autoBeamOn.

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.

See also

Snippets: Rhythms.

Manual beams

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

{
  r4 r8[ g' a r8] r8 g[ | a] r8
}

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

\time 2/4 c8 c\noBeam c c

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

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

Selected Snippets

Flat flags and beam nibs

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

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

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

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

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

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

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

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 featheredDurations command which specifies the ratio between the durations of the first and last notes in the group.

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

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

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

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

Known issues and warnings

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

See also

Snippets: Rhythms.

1.2.5 Bars

Bar lines

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

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

e4 d c2 \bar "|."

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

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

\bar ""

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

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

The simple bar line and five types of double bar line are available for manual insertion:

f1 \bar "|" g \bar "||" a \bar ".|" b \bar ".|." c \bar "|.|" d \bar "|." e

together with dotted and dashed bar lines:

f1 \bar ":" g \bar "dashed" a

and five types of repeat bar line:

f1 \bar "|:" g \bar ":|:" a \bar ":|.|:" b \bar ":|.:" c \bar ":|" d

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

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

\override Score.RehearsalMark #'padding = #3
c c c c
\bar "||:"
c c c c \break
\bar "||:"
c c c c

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 {
      e'4 d'
      \bar "||"
      f' e'
    }
    \new Staff { \clef bass c4 g e g }
  >>
  \new Staff { \clef bass c2 c2 }
>>

Selected Snippets

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

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

See also

Notation Reference: Line breaking, Repeats, Grouping staves.

Snippets: Rhythms.

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

Bar numbers

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

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

Selected Snippets

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

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

and here the bar numbers are printed every two measures except at the end of the line:

\override Score.BarNumber #'break-visibility = #'#(#f #t #t)
\set Score.currentBarNumber = #11
\bar ""  % Permit first bar number to be printed
% Print a bar number every second measure
\set Score.barNumberVisibility = #(every-nth-bar-number-visible 2)
c1 c c c c
\break
c c c c c

The size of the bar number may be changed. This is illustrated in the following example, which also shows how to enclose bar numbers in boxes and circles, and shows an alternative way of specifying #(#f #t #t) for break-visibility.

% Prevent bar numbers at the end of a line and permit them elsewhere
\override Score.BarNumber #'break-visibility
  = #end-of-line-invisible

% Increase the size of the bar number by 2
\override Score.BarNumber #'font-size = #2
\repeat unfold 3 { c1 } \bar "|"

% 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 3 { c1 } \bar "|"

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

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

\set Score.currentBarNumber = #111
\override Score.BarNumber #'break-visibility = #'#(#t #t #t)
% 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 = #0
c1 c1
% Right-align bar numbers
\override Score.BarNumber #'self-alignment-X = #-1
c1 c1

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

\layout {
  \context {
    \Score
    \remove "Bar_number_engraver"
  }
}
\relative c''{
  c4 c c c \break
  c4 c c c
}

See also

Snippets: Rhythms.

Internals Reference: BarNumber.

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.

Bar and bar number checks

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

\time 3/4 c2 e4 | g2 |

Bar checks can also be used in lyrics, for example

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

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

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

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

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

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

\barNumberCheck #123

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

See also

Snippets: Rhythms.

Rehearsal marks

To print a rehearsal mark, use the \mark command

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

The letter ‘I’ is skipped in accordance with engraving traditions. If you wish to include the letter ‘I’, then use

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

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.

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

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

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

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

Other styles of rehearsal mark can be specified manually

\mark "A1"

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

\mark \markup{ \box A1 }

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

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

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

For common tweaks to the positioning of rehearsal marks, see Formatting text.

See also

Notation Reference: The Feta font, Formatting text.

Installed Files: ‘scm/translation-functions.scm’ contains the definition of format-mark-numbers and format-mark-letters. They can be used as inspiration for other formatting functions.

Snippets: Rhythms.

Internals Reference: RehearsalMark.

1.2.6 Special rhythmic concerns

Grace notes

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

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

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

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

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

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

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

c1 \afterGrace d1 { c16[ d] } c1

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

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

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

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

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

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

Selected Snippets

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

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

The layout of grace expressions can be changed throughout the music using the function add-grace-property. The following example undefines the Stem direction for this grace, so that stems do not always point up.

\relative c'' {
  \new Staff {
    #(add-grace-property 'Voice 'Stem 'direction ly:stem::calc-direction)
    #(remove-grace-property 'Voice 'Stem 'direction)
    \new Voice {
       \acciaccatura { f16 } g4
       \grace { d16[ e] } f4
       \appoggiatura { a,32[ b c d] } e2
    }
  }
}

Another option is to change the variables startGraceMusic, stopGraceMusic, startAcciaccaturaMusic, stopAcciaccaturaMusic, startAppoggiaturaMusic, stopAppoggiaturaMusic. The default values of these can be seen in the file ly/grace-init.ly. By redefining them other effects may be obtained.

Grace notes may be forced to align with regular notes in other staves:

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

See also

Music Glossary: grace notes, acciaccatura, appoggiatura.

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

Snippets: Rhythms.

Internals Reference: GraceMusic.

Known issues and warnings

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

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

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

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

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

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.

Aligning to cadenzas

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

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

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

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

See also

Music Glossary: cadenza.

Snippets: Rhythms.

Time administration

Time is administered by the Timing_translator, which by default is to be found in the Score context. An alias, Timing, is added to the context in which the Timing_translator is placed.

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.

\set Score.measureLength = #(ly:make-moment 5 4)
c1 c4
c1 c4
c4 c4
\set Score.measurePosition = #(ly:make-moment 5 8)
b4 b4 b8
c4 c1

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

See also

This manual: Bar numbers, Unmetered music

Snippets: Rhythms.

Internals Reference: Timing_translator, Score

1.3 Expressive marks

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

1.3.1 Attached to notes

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

Articulations and ornamentations

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

note\name

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

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

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

c4-^  c-+  c--  c-|
c4->  c-.  c2-_

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

Selected Snippets

Modifying default values for articulation shorthand notation

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

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

Controlling the vertical ordering of scripts

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

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

Creating a delayed turn

Creating a delayed turn, where the lower note of the turn uses the accidental, requires several overrides. The outside-staff-priority property must be set to #f, as otherwise this would take precedence over the avoid-slur property. The value of halign is used to position the turn horizontally.

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

See also

Music Glossary: tenuto, accent, staccato, portato.

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

Installed Files: ‘scm/script.scm’.

Snippets: Expressive marks.

Internals Reference: Script, TextScript.

Dynamics

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

c2\ppp c\mp
c2\rfz c^\mf
c2_\spp c^\ff

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

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

Spacer rests are needed to engrave multiple marks on one note.

c4\< c\! d\> e\!
<< f1 { s4 s4\< s4\> s4\! } >>

In some situations the \espressivo articulation mark may be the appropriate choice to indicate a crescendo and decrescendo on one note:

c2 b4 a
g1\espressivo

Crescendos and decrescendos can be engraved as textual markings instead of hairpins. Dashed lines are printed to indicate their extent. The built-in commands that enable these text modes are \crescTextCresc, \dimTextDecresc, \dimTextDecr, and \dimTextDim. The corresponding \crescHairpin and \dimHairpin commands will revert to hairpins again:

\crescTextCresc
c2\< d | e f\!
\dimTextDecresc
e2\> d | c b\!
\crescHairpin
c2\< d | e f\!
\dimHairpin
e2\> d\!

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

Vertical positioning of dynamics is handled by DynamicLineSpanner.

Predefined commands

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

Selected Snippets

Setting hairpin behavior at bar lines

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

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

Setting the minimum length of hairpins

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

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

Printing hairpins using al niente notation

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

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

Vertically aligned dynamics and textscripts

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

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

music = \relative c'' {
  c2\p^\markup { gorgeous } c\f^\markup { fantastic }
  c4\p c\f\> c c\!\p
}

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

Hiding the extender line for text dynamics

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

\relative c'' {
  \override DynamicTextSpanner #'dash-period = #-1.0
  \crescTextCresc
  c1\< | d | b | c\!
}

Changing text and spanner styles for text dynamics

The text used for crescendos and decrescendos can be changed by modifying the context properties crescendoText and decrescendoText. The style of the spanner line can be changed by modifying the 'style property of DynamicTextSpanner. The default value is 'hairpin, and other possible values include 'line, 'dashed-line and 'dotted-line.

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

See also

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

Learning Manual: Articulation and dynamics.

Notation Reference: Direction and placement, New dynamic marks, What goes into the MIDI output?, Controlling MIDI dynamics.

Snippets: Expressive marks.

Internals Reference: DynamicText, Hairpin, DynamicLineSpanner.

New dynamic marks

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

moltoF = \markup { molto \dynamic f }

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

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

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

Simple, centered dynamic marks are easily created with the make-dynamic-script function. The dynamic font only contains the characters f,m,p,r,s and z.

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

In general, make-dynamic-script takes any markup object as its argument. In the following example, using make-dynamic-script ensures 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 } }
roundFdynamic = #(make-dynamic-script roundF)
boxFdynamic = #(make-dynamic-script boxF)
\relative c' {
  c4_\roundFdynamic\< d e f
  g,1_\boxFdynamic
}

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

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

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

See also

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

Snippets: Expressive marks.

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

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

Slurs may be manually placed above or below the notes, see Direction and placement.

c2( d)
\slurDown
c2( d)
\slurNeutral
c2( d)

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

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

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

Predefined commands

\slurUp, \slurDown, \slurNeutral, \slurDashed, \slurDotted, \slurSolid.

Selected Snippets

Using double slurs for legato chords

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

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

Positioning text markups inside slurs

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

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

See also

Music Glossary: slur.

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

Notation Reference: Direction and placement, Phrasing slurs.

Snippets: Expressive marks.

Internals Reference: Slur.

Phrasing slurs

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

c4\( d( e) f(
e2) d\)

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

c4\( g' c,( b) | c1\)
\phrasingSlurUp
c4\( g' c,( b) | c1\)

Simultaneous or overlapping phrasing slurs are not permitted.

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

c4\( e g2\)
\phrasingSlurDashed
g4\( e c2\)
\phrasingSlurDotted
c4\( e g2\)
\phrasingSlurSolid
g4\( e c2\)

Predefined commands

\phrasingSlurUp, \phrasingSlurDown, \phrasingSlurNeutral, \phrasingSlurDashed, \phrasingSlurDotted, \phrasingSlurSolid.

See also

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

Notation Reference: Direction and placement.

Snippets: Expressive marks.

Internals Reference: PhrasingSlur.

Breath marks

Breath marks are entered using \breathe:

c2. \breathe d4

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

Selected Snippets

Changing the breath mark symbol

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

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

Inserting a caesura

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

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

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

See also

Music Glossary: caesura.

Notation Reference: Divisiones.

Snippets: Expressive marks.

Internals Reference: BreathingSign.

Falls and doits

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

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

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

Selected Snippets

Adjusting the shape of falls and doits

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

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

See also

Music Glossary: fall, doit.

Snippets: Expressive marks.

1.3.3 Lines

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

Glissando

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

g2\glissando g'
c2\glissando c,

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

Selected Snippets

Contemporary glissando

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

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

See also

Music Glossary: glissando.

Notation Reference: Line styles.

Snippets: Expressive marks.

Internals Reference: Glissando.

Known issues and warnings

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

Arpeggio

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

<c e g c>1\arpeggio

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

<c e g c>2\arpeggio
\arpeggioArrowUp
<c e g c>2\arpeggio
\arpeggioArrowDown
<c e g c>2\arpeggio
\arpeggioNormal
<c e g c>2\arpeggio

Special bracketed arpeggio symbols can be created:

<c e g c>2
\arpeggioBracket
<c e g c>2\arpeggio
\arpeggioParenthesis
<c e g c>2\arpeggio
\arpeggioNormal
<c e g c>2\arpeggio

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

Predefined commands

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

Selected Snippets

Creating cross-staff arpeggios in a piano staff

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

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

Creating cross-staff arpeggios in other contexts

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

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

Creating arpeggios across notes in different voices

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

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

See also

Music Glossary: arpeggio.

Notation Reference: Ties.

Snippets: Expressive marks.

Internals Reference: Arpeggio, PianoStaff.

Known issues and warnings

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

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

Trills

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

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

d1~\startTrillSpan
d1
c2\stopTrillSpan r2

In the following example, a trill is combined with grace notes. The syntax of this construct and the method to precisely position the grace notes are described in Grace notes.

c1 \afterGrace
d1\startTrillSpan { c32[ d]\stopTrillSpan }
e2 r2

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

\pitchedTrill e2\startTrillSpan fis
d\stopTrillSpan

In the following example, the second pitched trill is ambiguous; the accidental of the trilled note is not printed. As a workaround, the accidentals of the trilled notes can be forced. The second measure illustrates this method:

\pitchedTrill eis4\startTrillSpan fis
g\stopTrillSpan
\pitchedTrill eis4\startTrillSpan fis
g\stopTrillSpan
\pitchedTrill eis4\startTrillSpan fis
g\stopTrillSpan
\pitchedTrill eis4\startTrillSpan fis!
g\stopTrillSpan

Predefined commands

\startTrillSpan, \stopTrillSpan.

See also

Music Glossary: trill.

Notation Reference: Articulations and ornamentations, Grace notes.

Snippets: Expressive marks.

Internals Reference: TrillSpanner.

1.4 Repeats

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

volta

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

unfold

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

percent

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

tremolo

This is used to write tremolo beams.

1.4.1 Long repeats

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

Normal repeats

The syntax for a normal repeat is

\repeat volta repeatcount musicexpr

where musicexpr is a music expression. Alternate endings can be produced using \alternative. In order to delimit the alternate endings, the group of alternatives must be enclosed in a set of braces. If there are more repeats than there are alternate endings, the earliest repeats are given the first alternative.

Normal repeats without alternate endings:

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

Normal repeats with alternate endings:

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

Repeats with upbeats can be entered in two ways:

\partial 4
e |
\repeat volta 4 { c2 d | e2 f | }
\alternative {
  { g4 g g e }
  { a4 a a a | b2. }
}

or

\partial 4
\repeat volta 4 { e4 | c2 d | e2 f | }
\alternative {
  { \partial 4*3 g4 g g }
  { a4 a a a | b2. }
}

Ties may be added to a second ending:

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

Selected Snippets

Shortening volta brackets

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

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

Adding volta brackets to additional staves

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

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

See also

Music Glossary: repeat, volta.

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

Snippets: Repeats.

Internals Reference: VoltaBracket, RepeatedMusic, VoltaRepeatedMusic, UnfoldedRepeatedMusic.

Known issues and warnings

A nested repeat like

\repeat …
\repeat …
\alternative

is ambiguous, since it is 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.

Timing information is not remembered at the start of an alternative, so after a repeat timing information must be reset by hand; for example, by setting Score.measurePosition or entering \partial. Similarly, slurs are also not repeated.

Manual repeat marks

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

start-repeat

Print a |: bar line.

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

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

end-repeat

Print a :| bar line:

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

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

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

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

Multiple repeat commands may occur at the same point:

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

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

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

Selected Snippets

Printing a repeat sign at the beginning of a piece

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

\relative c'' {
  \once \override Score.BreakAlignment #'break-align-orders =
        #(make-vector 3 '(instrument-name
                          left-edge
                          ambitus
                          span-bar
                          breathing-sign
                          clef
                          key-signature
                          time-signature
                          staff-bar
                          custos
                          span-bar))
  \bar "|:"
  c1
  d1
  d4 e f g
}

See also

Notation Reference: Bar lines, Formatting text.

Snippets: Repeats.

Internals Reference: VoltaBracket, RepeatedMusic, VoltaRepeatedMusic.

Written-out repeats

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

\repeat unfold repeatcount musicexpr

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

c1
\repeat unfold 2 { c4 d e f }
c1

Unfold repeats can be made with alternate endings. If there are more repeats than there are alternate endings, the first alternative ending is applied to the earliest endings.

c1
\repeat unfold 2 { g4 f e d }
  \alternative {
    { cis2 g' }
    { cis,2 b }
  }
c1

See also

Snippets: Repeats.

Internals Reference: RepeatedMusic, UnfoldedRepeatedMusic.

1.4.2 Short repeats

This section discusses how to input short repeats. Short repeats can take two basic forms: repeats of a single note to two measures, represented by slashes or percent signs; and tremolos.

Percent repeats

Repeated short patterns of notes are supported. The music is printed once, and the pattern is replaced with a special sign. Patterns that are shorter than one measure are replaced by slashes, and patterns of one or two measures are replaced by percent-like signs. The syntax is

\repeat percent number musicexpr

where musicexpr is a music expression.

\repeat percent 4 { c4 }
\repeat percent 2 { b4 a g f }
\repeat percent 2 { c2 es | f4 fis g c | }

Selected Snippets

Percent repeat counter

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

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

Percent repeat count visibility

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

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

Isolated percent repeats

Isolated percents can also be printed. This is done by entering a multi-measure rest with a different print function:

\relative c'' {
  \override MultiMeasureRest #'stencil
    = #ly:multi-measure-rest::percent
  \override MultiMeasureRest #'thickness = #0.48
  R1
}

See also

Music Glossary: percent repeat, simile.

Snippets: Repeats.

Internals Reference: RepeatSlash, PercentRepeat, DoublePercentRepeat, DoublePercentRepeatCounter, PercentRepeatCounter, PercentRepeatedMusic.

Known issues and warnings

Only three kinds of percent repeats are supported: a single slash representing a single beat (regardless of the duration of the repeated notes); a single slash with dots representing one full measure; and two slashes with dots crossing a bar line representing two full measures. Neither multiple slashes representing single beat repeats consisting of sixteenth or shorter notes, nor two slashes with dots representing single beat repeats consisting of notes of varying durations, are supported.

Tremolo repeats

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

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

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

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

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

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

\repeat tremolo 4 c'16

The same output can be obtained by adding ‘:[number]’ after the note. The number indicates the duration of the subdivision, and it must be at least 8. A number value of 8 gives one line across the note stem. If the length is omitted, the last value (stored in tremoloFlags) is used

c2:8 c:32
c: c:

See also

Snippets: Repeats.

Known issues and warnings

Cross-staff tremolos do not work well.

1.5 Simultaneous notes

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

1.5.1 Single voice

This section discusses simultaneous notes inside the same voice.

Chorded notes

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

<c e g>2 <c f a>4-> <e g c>-.

Relative mode can be used for pitches in chords. The octave of each pitch is chosen using the preceding pitch as a reference except in the case of the first pitch in a chord: the reference for the first pitch is the first pitch of the preceding chord.

For more information about chords, see Chord notation.

See also

Music Glossary: chord.

Learning Manual: Combining notes into chords.

Notation Reference: Chord notation.

Snippets: Simultaneous notes.

Simultaneous expressions

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

The following examples show simultaneous expressions on one staff:

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

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

This can be useful if the simultaneous sections have identical rhythms, but attempts to attach notes with different durations to the same stem will cause errors.

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

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

Here different rhythms cause no problems.

Clusters

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

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

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

See also

Music Glossary: cluster.

Snippets: Simultaneous notes.

Internals Reference: ClusterSpanner, ClusterSpannerBeacon, Cluster_spanner_engraver.

Known issues and warnings

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

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

Clusters do not produce MIDI output.

1.5.2 Multiple voices

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

Single-staff polyphony

Explicitly instantiating voices

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

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

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

Temporary polyphonic passages

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

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

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

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

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

The double backslash construct

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

The first example could be typeset as follows:

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

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

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

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

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

Identical rhythms

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

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

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

Predefined commands

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

See also

Learning Manual: Voices contain music, Explicitly instantiating voices.

Notation Reference: Percussion staves, Invisible rests, Stems.

Snippets: Simultaneous notes.

Voice styles

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

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

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

Predefined commands

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

See also

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

Snippets: Simultaneous notes.