[ << Musical notation ]	[Top][Contents][Index]	[ Specialist notation >> ]
[ < Repeats ]	[ Up : Repeats ]	[ Written-out repeats > ]

1.4.1 Long repeats

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

Written-out repeats
Simple repeats
Alternative endings
Other variation in repeated sections
Al-fine repeats
Segno repeat structure
Segno repeat appearance
Manual repeat marks

---

[ << Musical notation ]	[Top][Contents][Index]	[ Specialist notation >> ]
[ < Long repeats ]	[ Up : Long repeats ]	[ Simple 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.

See also

Snippets: Repeats.

Internals Reference: RepeatedMusic, UnfoldedRepeatedMusic.

---

[ << Musical notation ]	[Top][Contents][Index]	[ Specialist notation >> ]
[ < Written-out repeats ]	[ Up : Long repeats ]	[ Alternative endings > ]

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

---

[ << Musical notation ]	[Top][Contents][Index]	[ Specialist notation >> ]
[ < Simple repeats ]	[ Up : Long repeats ]	[ Other variation in repeated sections > ]

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 }

---

[ << Musical notation ]	[Top][Contents][Index]	[ Specialist notation >> ]
[ < Alternative endings ]	[ Up : Long repeats ]	[ Al-fine repeats > ]

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 }

---

[ << Musical notation ]	[Top][Contents][Index]	[ Specialist notation >> ]
[ < Other variation in repeated sections ]	[ Up : Long repeats ]	[ Segno repeat structure > ]

Al-fine repeats

The \fine command marks the end of the music but does not enforce it. When a repeat containing \fine is unfolded, the \fine command is unfolded like any other music. For correct unfolding, it is necessary to specify the volta in which the Fine should be performed and the volte in which any following music should be performed (see Other variation in repeated sections).

music = \fixed c' {
  \repeat volta 2 {
    f1
    \volta 2 \fine
    \volta 1 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
    \volta 1 b1
  }
}

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.

---

[ << Musical notation ]	[Top][Contents][Index]	[ Specialist notation >> ]
[ < Al-fine repeats ]	[ Up : Long repeats ]	[ Segno repeat appearance > ]

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

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.

---

[ << Musical notation ]	[Top][Contents][Index]	[ Specialist notation >> ]
[ < Segno repeat structure ]	[ Up : Long repeats ]	[ Manual repeat marks > ]

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

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

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

---

[ << Musical notation ]	[Top][Contents][Index]	[ Specialist notation >> ]
[ < Segno repeat appearance ]	[ Up : Long repeats ]	[ Short repeats > ]

Manual repeat marks

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

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
}

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.

---

[ << Musical notation ]	[Top][Contents][Index]	[ Specialist notation >> ]
[ < Segno repeat appearance ]	[ Up : Long repeats ]	[ Short repeats > ]

<< Back to Documentation Index

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