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

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


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


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


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


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
}


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


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


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 }


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 }


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 }


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
}


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


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

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 }


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 }


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 }


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 }


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 }


Music Glossary: da capo, dal segno, fine.

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
}


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
}


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
}


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
}


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


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


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


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


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


Music Glossary: repeat, volta.

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
}


start-repeat

Start a repeated section.

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

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
}


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


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 =
c4 b d e
\set Score.repeatCommands = #'((volta #f) (volta "4.") end-repeat)
f1
\set Score.repeatCommands = #'((volta #f))
}


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
}


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
}


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
}


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
}