1.4.1 Long repeats

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


Written-out repeats

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

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

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

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

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

differs from the following by an octave change:

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

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

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

See also

Snippets: Repeats.

Internals Reference: RepeatedMusic, UnfoldedRepeatedMusic.


Simple repeats

This is the syntax for a repeat without variation:

\repeat volta repeatcount musicexpr

where musicexpr is the music expression to be repeated.

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

[image of music]

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

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

[image of music]

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

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

[image of music]


Alternative endings

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

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

where musicexpr is a music expression, musicexpr… is any number of them, and numberlist is a comma-separated list of volta numbers chosen from the range 1 to repeatcount.

\fixed c'' {
  \repeat volta 6 {
    c4 d e f
    \alternative {
      \volta 1,2,3 { c2 e }
      \volta 4,5 { f2 d }
      \volta 6 { e2 f }
    }
  }
  c1
}

[image of music]

An older syntax where the \alternative block follows outside the repeated music expression is still supported and has the same effect.

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

\volta specifications within an \alternative block are optional on an all-or-none basis. If they are omitted, alternatives are used once each, but the first is repeated as needed to satisfy the repeat count.

\fixed c'' {
  \repeat volta 6 {
    c4 d e f
    \alternative {
      { c2 e }
      { f2 d }
      { e2 f }
    }
  }
  c1
}

[image of music]

\alternative blocks can be nested.

music = \fixed c' {
  \repeat volta 3 {
    s1_"A"
    \alternative {
      \volta 1 { s1_"B" }
      \volta 2,3 {
        s1_"C"
        \once \set Score.voltaSpannerDuration = #(ly:make-moment 1)
        s1_"D"
        \alternative {
          \volta 2 { s1_"E" }
          \volta 3 { s1_"F" }
        }
      }
    }
  }
  \fine
}

\score { \music }
\score { \unfoldRepeats \music }

[image of music]

Note: Every element in an alternative block is treated as an alternative ending. Something as simple as a bar check on the wrong side of a bracket can produce unexpected results.

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

Note: When alternative bar numbering is enabled, it is applied to the outermost bracketed alternatives.


Other variation in repeated sections

An \alternative block can be used within a \repeat block to produce notation similar to alternative endings (see Alternative endings).

\fixed c'' {
  \repeat volta 2 {
    R1
    \alternative {
      \volta 1 { c1 }
      \volta 2 { d1 }
    }
    R1
  }
}

[image of music]

The \volta command is not limited to use on the elements of an \alternative block. It can be used anywhere within a \repeat to designate music for particular volte, though it does not create brackets in other cases.

When a \repeat is unfolded, volta-specific music is omitted from every volta to which it does not apply. Providing an empty Scheme list in place of volta numbers removes the music entirely.

music = \repeat volta 3 {
  \volta #'() { s1*0^\markup { \bold "3×" } }
  \volta 1 { s1*0_\markup { \italic dolce } }
  g''1
}

\score { \music }
\score { \unfoldRepeats \music }

[image of music]

When a \repeat is unfolded, it may be desirable not only to filter out volta-specific music, but also to add music that was not present in the folded form. The \unfolded command designates music to be ignored until the enclosing \repeat is unfolded.

music = \fixed c' {
  \repeat volta 2 {
    c1
    <<
      \volta #'() {
        \once \override TextSpanner.bound-details.left.text =
          "2nd time tacet"
        s4*7\startTextSpan s4\stopTextSpan
      }
      \volta 1 { f4 f f f | f f f f }
      \volta 2 { \unfolded { R1*2 } }
    >>
    c'1
  }
  \fine
}

\score { \music }
\score { \unfoldRepeats \music }

[image of music]

Note: The volta and unfolded commands function with respect to the innermost repeat enclosing them.


Al-fine repeats

The \fine command ends the music, but placing it inside a folded repeat suspends its effect. When a repeat containing \fine is unfolded, the \fine command is unfolded like any other music and is performed wherever it first appears in the unfolded music. Therefore, it is necessary to specify the volta in which the Fine should be performed (see Other variation in repeated sections).

music = \fixed c' {
  \repeat volta 2 {
    f1
    \volta 2 \fine
    b1
  }
}

\score { \music }
\score { \unfoldRepeats \music }

[image of music]

As shown immediately above, at the written end of the music, \fine creates a final bar line without a Fine instruction. To force Fine to appear in such cases, set the finalFineTextVisibility context property.

\fixed c' {
  \set Score.finalFineTextVisibility = ##t
  f1
  \fine
}

[image of music]

To change the text that \fine prints, set the fineText context property.

\fixed c' {
  \set Score.fineText = "Fine."
  \repeat volta 2 {
    f1
    \volta 2 \fine
    b1
  }
}

[image of music]

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

See also

Music Glossary: fine.

Notation Reference: Automatic bar lines, Other variation in repeated sections, Section divisions.

Snippets: Repeats.

Internals Reference: FineEvent, Jump_engraver, JumpScript.


Segno repeat structure

\repeat segno differs from \repeat volta only in the resulting notation. Refer to the preceding sections for general information on entering music with repetition, alternatives, and variation. This section covers particulars of segno notation without fully reiterating the input syntax.

\repeat segno notates repetition with D.C. or D.S. instructions. It marks the beginning of the repeated section with a segno mark when it is not the beginning of the piece. It also marks alternative endings with coda marks in lieu of volta brackets, provided that the endings are intended to be performed in order, e.g., not \volta 1,3 then \volta 2,4.

When alternative bar numbering is enabled, it is applied to alternatives notated with volta brackets whether they are created by \repeat segno or \repeat volta, but it is not applied to alternative endings notated with coda marks.

Demonstrations of common uses follow.

al fine

Repeat instructions include al Fine if a \fine command appears at any prior point (see Al-fine repeats).

music = \fixed c' {
  f1
  \repeat segno 2 {
    g1
    \volta 2 \fine
    a1
  }
  \section
}

\score { \music }
\score { \unfoldRepeats \music }

[image of music]

alla coda

The beginning of each alternative ending is marked with an implied \codaMark \default. Repeat instructions in alternatives include ‘al … e poi la …’ referring to the mark at the first alternative and the mark to skip to. Provided that the duration of the final alternative is zero, the automatic mark is suppressed, allowing a section label to be set instead.

music = \fixed c' {
  f1
  \repeat segno 2 {
    g1
    \alternative {
      \volta 1 { \repeat unfold 4 { a2 } }
      \volta 2 \volta #'() {
        \section
        \sectionLabel "Coda"
      }
    }
  }
  b1
  \fine
}

\score { \music }
\score { \unfoldRepeats \music }

[image of music]

The return instruction can be abbreviated by setting an alternative formatting procedure (see Segno repeat appearance).

da capo

Repeat instructions include D.C. when the repeated section begins at the beginning of the score. The supported da capo cases parallel the supported dal segno cases.

music = \fixed c' {
  \repeat segno 2 {
    g1
  }
  \fine
}

\score { \music }
\score { \unfoldRepeats \music }

[image of music]

dal segno

Repeat instructions include D.S. when the repeated section begins after the beginning of the score. The beginning of the repeated section is marked with an implied \segnoMark \default.

music = \fixed c' {
  f1
  \repeat segno 2 {
    g1
  }
  \repeat segno 2 {
    a1
  }
  \fine
}

\score { \music }
\score { \unfoldRepeats \music }

[image of music]

A dal-segno repeat starting at the beginning of the score can be forced (see Segno repeat appearance).

multiple return

A repeat instruction to be performed more than once includes ‘… V.’. The number of times the instruction is performed is one less than the number of times the passage is performed.

music = \fixed c' {
  \repeat segno 3 {
    g1
  }
  \fine
}

\score { \music }
\score { \unfoldRepeats \music }

[image of music]

See also

Music Glossary: da capo, dal segno, fine.

Notation Reference: Al-fine repeats, Alternative endings, Automatic bar lines, Other variation in repeated sections, Section divisions, Section labels, Simple repeats.

Snippets: Repeats.

Internals Reference: CodaMark, JumpScript, SectionLabel, SegnoMark.


Segno repeat appearance

The marks and return instructions that \repeat segno creates are adjustable in some respects.

Return instructions are formatted with the Scheme procedure specified in the dalSegnoTextFormatter property. There is a predefined alternative formatter that creates shorter instructions.

\fixed c' {
  \set Score.dalSegnoTextFormatter = #format-dal-segno-text-brief
  f1
  \repeat segno 2 {
    g1
    \alternative {
      \volta 1 { a1 }
      \volta 2 \volta #'() {
        \section
        \sectionLabel "Coda"
      }
    }
  }
  b1
  \fine
}

[image of music]

The sequence numbers of the marks at the beginning of the repeated section and the beginning of the first alternative may be set explicitly without interfering with automatic return instructions (see Manual repeat marks).

\fixed c' {
  \repeat segno 2 {
    \volta #'() { \segnoMark 2 }
    g1
    \alternative {
      \volta 1 {
        \volta #'() { \codaMark 2 }
        \repeat unfold 8 { a4 }
      }
      \volta 2 \volta #'() {
        \section
        \sectionLabel "Coda"
      }
    }
  }
  b1
  \fine
}

[image of music]

Without the explicit \segnoMark 2, the above would have been rendered as a da-capo repeat.

As an alternative to printing a segno as a mark above the staff, it is possible to print it as a bar line by setting the segnoStyle property to bar-line. To avoid ambiguity, only the first segno bar remains unmarked.

\fixed c' {
  \set Score.segnoStyle = #'bar-line
  R1
  \repeat unfold 3 {
    \repeat segno 2 {
      R1*2
    }
  }
  \fine
}

[image of music]

Where a segno bar coincides with other special bar lines, a combination bar line is chosen automatically from a predetermined set. For each supported combination, the bar line can be customized by setting a context property (see Automatic bar lines).

Segno and coda marks are formatted with procedures specified in the segnoMarkFormatter and codaMarkFormatter properties. These are interchangeable with procedures used to format rehearsal marks (see Rehearsal marks).

\fixed c' {
  \set Score.segnoMarkFormatter = #format-mark-numbers
  \set Score.segnoStyle = #'bar-line
  R1
  \repeat unfold 3 {
    \repeat segno 2 {
      R1*2
    }
  }
  \fine
}

[image of music]

There is a predefined alternative segno formatter that prints a mark even over the first bar line:

\fixed c' {
  \set Score.segnoMarkFormatter = #format-segno-mark
  \set Score.segnoStyle = #'bar-line
  R1
  \repeat unfold 3 {
    \segnoMark \default
    R1*2
  }
}

[image of music]

There is a predefined alternative coda mark formatter that uses \varcoda signs.

\fixed c' {
  \set Score.codaMarkFormatter = #format-varcoda-mark
  R1
  \repeat unfold 3 {
    \codaMark \default
    R1*2
  }
}

[image of music]

Selected Snippets

Shortening volta brackets

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

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

[image of music]

Adding volta brackets to additional staves

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

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

[image of music]

Alternative bar numbering

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

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

[image of music]

See also

Music Glossary: repeat, volta.

Notation Reference: Automatic bar lines, Bar lines, Modifying context plug-ins, Modifying ties and slurs, Time administration.

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

Snippets: Repeats.

Internals Reference: VoltaBracket, RepeatedMusic, VoltaRepeatedMusic, UnfoldedRepeatedMusic.

Known issues and warnings

For repeats in volta form, spanners (slurs, etc.) that cross into alternatives work for the first alternative only. They likewise cannot wrap around from the end of an alternative back to the beginning of the repeated section.

The visual appearance of a continuing slur or tie in subsequent alternatives can be achieved with \repeatTie if the slur extends into only one note in the alternative block, although this method does not work in TabStaff; see Repeat tie. Other methods which may be tailored to indicate continuing slurs over several notes in alternative blocks, and which also work in TabStaff contexts, are shown in Modifying ties and slurs.

The visual appearance of a continuing glissando in subsequent alternatives can be achieved by coding a glissando starting on a hidden grace note. See Extending glissandi across repeats.

If a repeat that begins with an incomplete measure has an \alternative block that contains modifications to the measureLength property, using \unfoldRepeats will result in wrongly-placed bar lines and bar check warnings.

A nested repeat like

\repeat …
\repeat …
\alternative

is ambiguous, since it is not clear to which \repeat the \alternative belongs. This ambiguity is resolved by always having the \alternative belong to the inner \repeat. For clarity, it is advisable to use braces in such situations.


Manual repeat marks

Note: These methods are only used for displaying unusual repeat constructs, and may produce unexpected behavior. In most cases, repeats should be created using the standard repeat command or by printing the relevant bar lines. For more information, see Bar lines.

The property repeatCommands can be used to control the layout of volta-style repeats. Its value is a Scheme list. In general, each element is itself a list, '(command args…), but a command with no arguments may be abbreviated to a symbol; e.g., '((start-repeat)) may be given as '(start-repeat).

end-repeat

End a repeated section.

\relative {
  c''1
  d4 e f g
  \set Score.repeatCommands = #'(end-repeat)
  c1
}

[image of music]

start-repeat

Start a repeated section.

\relative {
  c''1
  \set Score.repeatCommands = #'(start-repeat)
  d4 e f g
  c1
}

[image of music]

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

volta text

If text is markup, start a volta bracket with that label; if text is #f, end a volta bracket. A volta bracket which is not ended explicitly will not be printed.

\relative {
  f''4 g a b
  \set Score.repeatCommands = #'((volta "2"))
  g4 a g a
  \set Score.repeatCommands = #'((volta #f))
  c1
}

[image of music]

Multiple repeat commands may occur at the same point:

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

[image of music]

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

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

[image of music]

Segno and coda marks can be created with the \segnoMark, \inStaffSegno, and \codaMark commands. This is the syntax for the mark commands:

\codaMark n
\segnoMark n

where n is a sequence number, or \default to use the next automatically. Rehearsal, segno, and coda marks are counted independently.

\fixed c' {
  e1
  \segnoMark \default
  e1
  \segnoMark \default
  g1
  \codaMark \default
  g1
  \codaMark \default
  b1
  \codaMark 96
  b1
  \segnoMark 96
}

[image of music]

At the beginning of a piece, \segnoMark \default and \codaMark \default create no mark. Specify ‘1’ to force a mark.

\fixed c' {
  \segnoMark 1
  f1
}

[image of music]

The \inStaffSegno command is equivalent to \segnoMark \default with the extra effect of temporarily setting the segnoStyle property to bar-line to force printing it as a bar line.

\fixed c' {
  e1
  \inStaffSegno
  g1
  \segnoMark \default
  b1
}

[image of music]

For more information on changing the appearance of segno and coda marks, see Segno repeat appearance.

To create arbitrary jump instructions, use the \jump command.

\fixed c' {
  \time 2/4
  f4 a
  b4 c'8 d'
  c'4 c
  \jump "Gavotte I D.C."
  \section
}

[image of music]

See also

Notation Reference: Bar lines, Formatting text, Rehearsal marks, Segno repeat appearance.

Snippets: Repeats.

Internals Reference: CodaMark, Jump_engraver, JumpScript, Mark_engraver, SegnoMark, SegnoRepeatedMusic, VoltaBracket, VoltaRepeatedMusic.


LilyPond — Notation Reference v2.23.11 (development-branch).