### 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 command, which is documented in following sections.

To avoid redundancy, unfolding is not demonstrated in detail here; however, some of the examples in following sections illustrate features in both volta and unfold forms using the \unfoldRepeats command to convert the volta 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 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 }
}


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

This is the syntax for a repeat with alternative endings:

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


where musicexpr is a music expression 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
}


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


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.

#### Other variation in repeated sections

An \alternative block can be used within a \repeat block to produce notation similar to alternative endings; however, it can not be used in this manner for alternative endings themselves (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 within \alternative blocks. It can be used anywhere within a \repeat to designate music that applies to particular volte. If the volta-specific music has a duration, it is by default printed under a bracket as if it were in an \alternative block; the bracket may need to be hidden (see Visibility of objects) or customized to suit other purposes.

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 1 { s1*0_\markup { \italic dolce } }
a''1
\volta #'() { \mark "3×" }
}

\new Score { \music }
\new 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 volta form. The \unfolded command designates music to be ignored until the enclosing \repeat is unfolded.

music = \fixed c' {
\repeat volta 2 {
c1
\once \override Score.VoltaBracket.text = "1st time only"
\once \override Score.VoltaBracket.font-name = "TeX Gyre Schola"
<<
\volta 1 { g4 g g g }
\volta 2 { \unfolded { R1 } }
>>
c'1
\volta 2 { \unfolded { \bar "|." } }
}
}

\new Score { \music }
\new Score { \unfoldRepeats \music }


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

#### In-staff segno

The \inStaffSegno command can be used to generate a composite bar line incorporating the segno symbol with the appropriate repeat bar line when used with the \repeat volta command. The correct type of repeat bar line, viz. start repeat, end repeat or double repeat, is selected automatically. Note that the corresponding “D.S.” mark must be added manually.

Away from a repeat:

\relative {
e'1
\inStaffSegno
f2 g a b
c1_"D.S." \bar "|."
}


At the start of a repeat:

\relative {
e'1
\repeat volta 2 {
\inStaffSegno  % start repeat
f2 g a b
}
c1_"D.S." \bar "|."
}


At the end of a repeat:

\relative {
e'1
\repeat volta 2 {
f2 g a b
\inStaffSegno  % end repeat
}
f2 g a b
c1_"D.S." \bar "|."
}


Between two repeats:

\relative {
e'1
\repeat volta 2 {
f2 g a b
}
\inStaffSegno  % double repeat
\repeat volta 2 {
f2 g a b
}
c1_"D.S." \bar "|."
}


Alternative bar line symbols can be obtained by setting (in the Score context) the properties segnoType, startRepeatSegnoType, endRepeatSegnoType or doubleRepeatSegnoType to the required bar line type. The alternative bar line types must be selected from the pre-defined types or types previously defined with the \defineBarLine command (see Bar lines).

\defineBarLine ":|.S[" #'(":|." "S[" "")
\defineBarLine "]" #'("]" "" "")
\relative {
e'1
\repeat volta 2 {
f2 g a b
\once \set Score.endRepeatSegnoType = ":|.S["
\inStaffSegno
}
f2 g \bar "]" a b
c1_"D.S." \bar "|."
}


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


#### Setting the double repeat default for volte

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

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


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


#### See also

Music Glossary: repeat, volta.

Notation Reference: 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 repeats. Its value is a Scheme list of repeat commands.

start-repeat

Print a .|: bar line.

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

end-repeat

Print a :|. bar line:

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

\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 =
#(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))
}


#### See also

Notation Reference: Bar lines, Formatting text.

Snippets: Repeats.

Internals Reference: VoltaBracket, RepeatedMusic, VoltaRepeatedMusic.