Doc: NR Clarify repeats w\ partials and barchecks

[lilypond.git] / Documentation / notation / repeats.itely

@c -*- coding: utf-8; mode: texinfo; -*-
@ignore
    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  For details, see the Contributors'
    Guide, node Updating translation committishes..
@end ignore

@c \version "2.19.21"

@node Repeats
@section Repeats

@lilypondfile[quote]{repeats-headword.ly}

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


@table @code
@item 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.

@item unfold
The repeated music is fully written out, as many times as
specified by @code{@var{repeatcount}}.  This is useful when
entering repetitious music.

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

@item tremolo
This is used to write tremolo beams.

@end table


@menu
* Long repeats::
* Short repeats::
@end menu

@node Long repeats
@subsection 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.

@menu
* Normal repeats::
* Manual repeat marks::
* Written-out repeats::
@end menu

@cindex volta
@cindex prima volta
@cindex seconda volta
@cindex volta, prima
@cindex volta, seconda
@cindex repeat, normal
@cindex normal repeat
@cindex repeat with alternate endings
@cindex alternate endings
@funindex \repeat
@funindex \alternative
@funindex \partial

@node Normal repeats
@unnumberedsubsubsec Normal repeats

The syntax for a normal repeat is

@example
\repeat volta @var{repeatcount} @var{musicexpr}
@end example

@noindent
where @code{@var{musicexpr}} is a music expression.

A single repeat without an alternate ending:

@lilypond[verbatim,quote]
\relative {
  \repeat volta 2 { c''4 d e f }
  c2 d
  \repeat volta 2 { d4 e f g }
}
@end lilypond

An @q{opening} repeat mark is not, by default, printed in the first full
measure.  However it is possible to add one by using @code{\bar ".|:"}
before the first note.

@lilypond[verbatim,fragment,quote]
\relative {
  \repeat volta 2 { \bar ".|:" c''4 d e f }
  c2 d
  \repeat volta 2 { d4 e f g }
}
@end lilypond

Alternative endings can be produced using @code{\alternative}.  Each
group of alternatives must be themselves, enclosed in a set of braces.

@example
\repeat volta @var{repeatcount} @var{musicexpr}
\alternative @{
  @{ @var{musicexpr} @}
@}
@end example

@noindent
where @code{@var{musicexpr}} is a music expression.

If there are more repeats than there are alternate endings, the earliest
repeats are given the first alternative.

A single repeat with one alternate ending:

@lilypond[verbatim,quote]
\relative {
  \repeat volta 2 { c''4 d e f | }
  \alternative {
    { c2 e | }
    { f2 g | }
  }
  c1
}
@end lilypond

Multiple repeats with one alternate ending:

@lilypond[verbatim,quote]
\relative {
  \repeat volta 4 { c''4 d e f | }
  \alternative {
    { c2 e | }
    { f2 g | }
  }
  c1
}
@end lilypond

Multiple repeats with more than one alternate ending:

@lilypond[verbatim,quote]
\relative {
  \repeat volta 3 { c''4 d e f | }
  \alternative {
    { c2 e | }
    { f2 g | }
    { a2 g | }
  }
  c1
}
@end lilypond

@warning{If there are two or more alternatives, nothing should appear
between the closing brace of one and the opening brace of the next
in an @code{@bs{}alternative} block, otherwise you will not get the
expected number of endings.}

@warning{If you include @code{@bs{}relative} inside a
@code{@bs{}repeat} without explicitly instantiating the
@code{Voice} context, extra (unwanted) staves will appear.  See
@rprogram{An extra staff appears}.}

@cindex repeat with upbeat
@cindex upbeat in a repeat
@cindex anacrusis in a repeat
@cindex repeat with anacrusis
@cindex repeat with pickup
@cindex pickup in a repeat
@funindex \partial
@cindex bar checks with repeats
@cindex repeats with bar checks

If a repeat that has no alternate endings starts in the middle of a
measure, it will usually end at a corresponding place in the middle of a
later measure (so that the two ends add up to one complete measure).  In
this case the repeat signs are not @q{true} bar lines so neither bar
checks nor @code{\partial} commands should be placed there:

@lilypond[verbatim,quote,relative=1]
c'4 e g
\repeat volta 4 {
  e4 |
  c2 e |
  g4 g g
}
  g4 |
  a2 a |
  g1 |
@end lilypond

If a repeat that has no alternate endings starts with a partial measure,
then the same principles apply, except that a @code{\partial} command is
required at the start of the measure:

@lilypond[verbatim,quote,relative=1]
\partial 4
\repeat volta 4 {
  e'4 |
  c2 e |
  g4 g g
}
  g4 |
  a2 a |
  g1 |
@end lilypond

@cindex repeats, with ties
@cindex alternative endings, with ties
@cindex ties, in repeats
@cindex ties, alternative endings
@funindex \repeatTie

Ties may be added to a second ending:

@lilypond[verbatim,quote]
\relative {
  c''1
  \repeat volta 2 { c4 d e f~ }
  \alternative {
    { f2 d }
    { f2\repeatTie f, }
  }
}
@end lilypond

@funindex \inStaffSegno
@cindex repeats, with segno
@cindex segno, with repeats

The @code{\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 @code{\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 @qq{D.S.} mark must be added manually.

Away from a repeat:

@lilypond[verbatim,quote]
\relative {
  e'1
  \inStaffSegno
  f2 g a b
  c1_"D.S." \bar "|."
}
@end lilypond

At the start of a repeat:

@lilypond[verbatim,quote]
\relative {
  e'1
  \repeat volta 2 {
    \inStaffSegno  % start repeat
    f2 g a b
  }
  c1_"D.S." \bar "|."
}
@end lilypond

At the end of a repeat:

@lilypond[verbatim,quote]
\relative {
  e'1
  \repeat volta 2 {
    f2 g a b
    \inStaffSegno  % end repeat
  }
  f2 g a b
  c1_"D.S." \bar "|."
}
@end lilypond

Between two repeats:

@lilypond[verbatim,quote]
\relative {
  e'1
  \repeat volta 2 {
    f2 g a b
  }
  \inStaffSegno  % double repeat
  \repeat volta 2 {
    f2 g a b
  }
  c1_"D.S." \bar "|."
}
@end lilypond

Alternative bar line symbols can be obtained by setting (in the Score
context) the properties @code{segnoType}, @code{startRepeatSegnoType},
@code{endRepeatSegnoType} or @code{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 @code{\defineBarLine} command (see @ref{Bar lines}).

@lilypond[verbatim,quote]
\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 "|."
}
@end lilypond

@snippets
@lilypondfile[verbatim,quote,texidoc,doctitle]
{shortening-volta-brackets.ly}

@lilypondfile[verbatim,quote,texidoc,doctitle]
{adding-volta-brackets-to-additional-staves.ly}

@lilypondfile[verbatim,quote,texidoc,doctitle]
{setting-the-double-repeat-default-for-volte.ly}

@cindex repeats, bar numbers letters
@cindex repeats, alternative bar numbers

@lilypondfile[verbatim,quote,texidoc,doctitle]
{alternative-bar-numbering.ly}

@seealso
Music Glossary:
@rglos{repeat},
@rglos{volta}.

Notation Reference:
@ref{Bar lines},
@ref{Modifying context plug-ins},
@ref{Modifying ties and slurs},
@ref{Time administration}.

Installed Files:
@file{ly/engraver-init.ly}.

Snippets:
@rlsr{Repeats}.

Internals Reference:
@rinternals{VoltaBracket},
@rinternals{RepeatedMusic},
@rinternals{VoltaRepeatedMusic},
@rinternals{UnfoldedRepeatedMusic}.

@knownissues
@cindex repeat, ambiguous
@cindex nested repeat
@cindex repeat, nested
@cindex repeat timing information
@cindex repeat and measure number
@cindex timing information and repeats
@cindex measure number and repeats
@cindex repeats and slur
@cindex slur and repeats
@cindex glissandi and repeats
@cindex repeats and glissandi

Slurs that span from a @code{\repeat} block into an
@code{\alternative} block will only work for the first alternative
ending.  The visual appearance of a continuing slur in other
alternative blocks may be simulated with @code{\repeatTie} if the
slur extends into only one note in the alternative block, although
this method does not work in @code{TabStaff}.  Other methods which
may be tailored to indicate continuing slurs over several notes in
alternative blocks, and which also work in @code{TabStaff} contexts,
are shown in @ref{Modifying ties and slurs}.

Also, slurs cannot wrap around from the end of one
alternative back to the beginning of the repeat.

Glissandi that span from a @code{\repeat} block into an
@code{\alternative} block will only work for the first alternative
ending.  The visual appearance of a continuing glissando in other
alternative blocks may be indicated by coding a glissando starting
on a hidden grace note.  For an example, see
@qq{Extending glissandi across repeats} under Selected Snippets
in @ref{Glissando}.

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

A nested repeat like

@example
\repeat @dots{}
\repeat @dots{}
\alternative
@end example

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


@node Manual repeat marks
@unnumberedsubsubsec Manual repeat marks

@cindex manual repeat mark
@cindex repeat, manual
@cindex start repeat
@cindex repeat, start
@cindex end repeat
@cindex repeat, end
@cindex repeat number, changing
@cindex repeat volta, changing
@cindex volta bracket
@cindex bracket, volta
@funindex repeatCommands
@funindex start-repeat

@warning{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 @code{@bs{}repeat} command
or by printing the relevant bar lines.  For more information, see
@ref{Bar lines}.}

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

@table @code
@item start-repeat
Print a @code{.|:} bar line.

@lilypond[verbatim,quote]
\relative {
  c''1
  \set Score.repeatCommands = #'(start-repeat)
  d4 e f g
  c1
}
@end lilypond

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

@item end-repeat
Print a @code{:|.} bar line:

@lilypond[verbatim,quote]
\relative {
  c''1
  d4 e f g
  \set Score.repeatCommands = #'(end-repeat)
  c1
}
@end lilypond

@item (volta @var{number}) @dots{} (volta #f)
Create a new volta with the specified number.  The volta bracket must
be explicitly terminated, or it will not be printed.

@lilypond[verbatim,quote]
\relative {
  f''4 g a b
  \set Score.repeatCommands = #'((volta "2"))
  g4 a g a
  \set Score.repeatCommands = #'((volta #f))
  c1
}
@end lilypond

@end table

Multiple repeat commands may occur at the same point:

@lilypond[verbatim,quote]
\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))
}
@end lilypond

@cindex volta bracket with text
@cindex text in volta bracket

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

@lilypond[verbatim,quote]
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))
}
@end lilypond

@seealso
Notation Reference:
@ref{Bar lines},
@ref{Formatting text}.

Snippets:
@rlsr{Repeats}.

Internals Reference:
@rinternals{VoltaBracket},
@rinternals{RepeatedMusic},
@rinternals{VoltaRepeatedMusic}.


@node Written-out repeats
@unnumberedsubsubsec Written-out repeats

@cindex written-out repeats
@cindex repeats, written-out
@cindex repeats, unfold
@cindex repeats, alternative
@cindex unfold repeat
@cindex unfold repeat, alternate endings
@cindex alternate repeats
@cindex alternate endings, repeats
@funindex unfold

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

@example
\repeat unfold @var{repeatcount} @var{musicexpr}
@end example

@noindent
where @code{@var{musicexpr}} is a music expression and
@code{@var{repeatcount}} is the number of times
@code{@var{musicexpr}} is repeated.

@lilypond[verbatim,quote]
\relative {
  \repeat unfold 2 { c''4 d e f }
  c1
}
@end lilypond

In some cases, especially in a @code{\relative} context, the
@code{\repeat unfold} function is not the same as writing out the
music expression multiple times. E.g,

@example
\repeat unfold 2 @{ a'4 b c @}
@end example

is not equivalent to

@example
a'4 b c | a'4 b c
@end example

Unfold repeats can be made with alternate endings.

@lilypond[verbatim,quote]
\relative {
  \repeat unfold 2 { c''4 d e f }
  \alternative {
    { c2 g' }
    { c,2 b }
  }
  c1
}
@end lilypond

If there are more repeats than there are alternate endings, the first
alternative is applied multiple times until the remaining alternatives
make up the total number of repeats.

@lilypond[verbatim,quote]
\relative {
  \repeat unfold 4 { c''4 d e f }
  \alternative {
    { c2 g' }
    { c,2 b }
    { e2 d }
   }
  c1
}
@end lilypond

If there are more alternate endings than repeats then only the first
alternatives are applied.  The remaining alternatives will be ignored
and not printed.

@lilypond[verbatim,quote]
\relative {
  \repeat unfold 2 { c''4 d e f }
  \alternative {
    { c2 g' }
    { c,2 b }
    { e2 d }
  }
  c1
}
@end lilypond

It is also possible to nest multiple @code{unfold} functions (with or
without alternate endings).

@lilypond[verbatim,quote]
\relative {
  \repeat unfold 2 {
    \repeat unfold 2 { c''4 d e f }
    \alternative {
      { c2 g' }
      { c,2 b }
    }
  }
  c1
}
@end lilypond

Chord constructs can be repeated by the chord repetition symbol
@code{q}.  See @ref{Chord repetition}.

@warning{If you include @code{@bs{}relative} inside a @code{@bs{}repeat}
without explicitly instantiating the @code{Voice} context, extra
(unwanted) staves will appear.  See @rprogram{An extra staff appears}.}

@seealso
Notation Reference:
@ref{Chord repetition}.

Snippets:
@rlsr{Repeats}.

Internals Reference:
@rinternals{RepeatedMusic},
@rinternals{UnfoldedRepeatedMusic}.


@node Short repeats
@subsection Short repeats

This section discusses how to input short repeats.  Short repeats can
take two forms: slashes or percent signs to represent repeats of a
single note, a single measure or two measures, and tremolos otherwise.

@menu
* Percent repeats::
* Tremolo repeats::
@end menu

@node Percent repeats
@unnumberedsubsubsec Percent repeats

@cindex percent repeats
@cindex measure repeats
@cindex repeat, percent
@cindex repeat, measure
@cindex repeat, short
@funindex \repeat percent
@funindex percent

Repeated short patterns are printed once, and the repeated pattern
is replaced with a special sign.

The syntax is

@example
\repeat percent @var{number} @var{musicexpr}
@end example

@noindent
where @code{@var{musicexpr}} is a music expression.

Patterns that are shorter than one measure are replaced by slashes.

@lilypond[verbatim,quote]
\relative c'' {
  \repeat percent 4 { c128 d e f }
  \repeat percent 4 { c64 d e f }
  \repeat percent 5 { c32 d e f }
  \repeat percent 4 { c16 d e f }
  \repeat percent 4 { c8 d }
  \repeat percent 4 { c4 }
  \repeat percent 2 { c2 }
}
@end lilypond

Patterns of one or two measures are replaced by percent-like symbols.

@lilypond[verbatim,quote]
\relative c'' {
  \repeat percent 2 { c4 d e f }
  \repeat percent 2 { c2 d }
  \repeat percent 2 { c1 }
}
@end lilypond

@lilypond[verbatim,quote]
\relative {
  \repeat percent 3 { c''4 d e f | c2 g' }
}
@end lilypond

Patterns that are shorter than one measure but contain mixed durations
use a double-percent symbol.

@lilypond[verbatim,quote]
\relative {
  \repeat percent 4 { c''8. <d f>16 }
  \repeat percent 2 { \tuplet 3/2 { r8 c d } e4 }
}
@end lilypond

@snippets

@lilypondfile[verbatim,quote,texidoc,doctitle]
{percent-repeat-counter.ly}

@lilypondfile[verbatim,quote,texidoc,doctitle]
{percent-repeat-count-visibility.ly}

@lilypondfile[verbatim,quote,texidoc,doctitle]
{isolated-percent-repeats.ly}

@seealso
Music Glossary:
@rglos{percent repeat},
@rglos{simile}.

Snippets:
@rlsr{Repeats}.

Internals Reference:
@rinternals{RepeatSlash},
@rinternals{RepeatSlashEvent},
@rinternals{DoubleRepeatSlash},
@rinternals{PercentRepeat},
@rinternals{PercentRepeatCounter},
@rinternals{PercentRepeatedMusic},
@rinternals{Percent_repeat_engraver},
@rinternals{DoublePercentEvent},
@rinternals{DoublePercentRepeat},
@rinternals{DoublePercentRepeatCounter},
@rinternals{Double_percent_repeat_engraver},
@rinternals{Slash_repeat_engraver}.

@knownissues
Percent repeats will not contain anything else apart from the percent
sign itself; in particular, timing changes will not be repeated.

@lilypond[quote,verbatim,relative=2]
\repeat percent 3 { \time 5/4 c2. 2 \time 4/4 2 2 }
@end lilypond

@noindent
Any meter changes or @code{\partial} commands need to occur in parallel
passages @emph{outside} of any percent repeat, e.g in a separate
timing track.

@lilypond[quote,verbatim,relative=2]
<<
  \repeat percent 3 { c2. 2 2 2 }
  \repeat unfold 3 { \time 5/4 s4*5 \time 4/4 s1 }
>>
@end lilypond


@node Tremolo repeats
@unnumberedsubsubsec Tremolo repeats

@cindex tremolo beams
@cindex tremolo
@cindex repeat, tremolo
@funindex \repeat tremolo
@funindex tremolo

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 @code{\repeat} with
tremolo style:

@lilypond[quote,verbatim]
\relative c'' {
  \repeat tremolo 8 { c16 d }
  \repeat tremolo 6 { c16 d }
  \repeat tremolo 2 { c16 d }
}
@end lilypond

The @code{\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,
@code{\repeat tremolo 7} is valid and produces a double dotted
note, but @code{\repeat tremolo 9} is not.

The duration of the tremolo equals the duration of the
braced expression multiplied by the number of repeats:
@code{\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
@code{\repeat tremolo} syntax is also used here, in which case
the note should not be surrounded by braces:

@lilypond[quote,verbatim,ragged-right]
\repeat tremolo 4 c'16
@end lilypond

@cindex tremolo marks
@funindex :

The same output can be obtained by adding @code{:@var{N}} after
the note, where @code{@var{N}} indicates the duration of the
subdivision (it must be at least 8).  If @code{@var{N}} is 8, one
beam is added to the note's stem.  If @code{@var{N}} is omitted,
the last value is used:

@lilypond[quote,verbatim]
\relative {
  c''2:8 c:32
  c: c:
}
@end lilypond

@snippets

@lilypondfile[verbatim,quote,texidoc,doctitle]
{cross-staff-tremolos.ly}

@seealso
Snippets:
@rlsr{Repeats}.

@cindex tremolo, cross-staff
@cindex cross-staff tremolo