1 @c -*- coding: utf-8; mode: texinfo; -*-
3 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
5 When revising a translation, copy the HEAD committish of the
6 version that you are working on. For details, see the Contributors'
7 Guide, node Updating translation committishes..
15 @lilypondfile[quote]{repeats-headword.ly}
17 Repetition is a central concept in music, and multiple notations
18 exist for repetitions. LilyPond supports the following kinds of
24 The repeated music is not written out but enclosed between repeat bar
25 lines. If the repeat is at the beginning of a piece, a repeat bar
26 line is only printed at the end of the repeat. Alternative endings
27 (volte) are printed left to right with brackets. This is the standard
28 notation for repeats with alternatives.
31 The repeated music is fully written out, as many times as
32 specified by @var{repeatcount}. This is useful when
33 entering repetitious music.
36 These are beat or measure repeats. They look like single slashes or
40 This is used to write tremolo beams.
51 @subsection Long repeats
53 This section discusses how to input long (usually multi-measure)
54 repeats. The repeats can take two forms: repeats enclosed between
55 repeat signs; or written out repeats, used to input repetitious music.
56 Repeat signs can also be controlled manually.
60 * Manual repeat marks::
61 * Written-out repeats::
68 @cindex volta, seconda
69 @cindex repeat, normal
71 @cindex repeat with alternate endings
72 @cindex alternate endings
74 @funindex \alternative
78 @unnumberedsubsubsec Normal repeats
80 The syntax for a normal repeat is
83 \repeat volta @var{repeatcount} @var{musicexpr}
87 where @var{musicexpr} is a music expression. Alternate endings can be
88 produced using @code{\alternative}. In order to delimit the alternate
89 endings, the group of alternatives must be enclosed in a set of
90 braces. If there are more repeats than there are alternate endings,
91 the earliest repeats are given the first alternative.
93 Normal repeats without alternate endings:
95 @lilypond[verbatim,quote,relative=2]
96 \repeat volta 2 { c4 d e f }
98 \repeat volta 2 { d4 e f g }
101 Normal repeats with alternate endings:
103 @lilypond[verbatim,quote,relative=2]
104 \repeat volta 4 { c4 d e f }
112 @warning{If you include @code{@bs{}relative} inside a
113 @code{@bs{}repeat} without explicitly instantiating the
114 @code{Voice} context, extra (unwanted) staves will appear. See
115 @rprogram{An extra staff appears}.}
117 @cindex repeat with upbeat
118 @cindex upbeat in a repeat
119 @cindex anacrucis in a repeat
120 @cindex repeat with anacrucis
121 @cindex repeat with pickup
122 @cindex pickup in a repeat
125 Repeats with upbeats can be entered in two ways:
127 @lilypond[verbatim,quote,relative=2]
130 \repeat volta 4 { c2 d | e2 f | }
140 @lilypond[verbatim,quote,relative=2]
142 \repeat volta 4 { e4 | c2 d | e2 f | }
144 { \partial 4*3 g4 g g }
150 @cindex repeats with ties
151 @cindex alternative endings with ties
152 @cindex ties in repeats
153 @cindex ties in alternative endings
156 Ties may be added to a second ending:
158 @lilypond[verbatim,quote,relative=2]
160 \repeat volta 2 { c4 d e f ~ }
169 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
170 {shortening-volta-brackets.ly}
172 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
173 {adding-volta-brackets-to-additional-staves.ly}
183 @ref{Modifying context plug-ins}.
189 @rinternals{VoltaBracket},
190 @rinternals{RepeatedMusic},
191 @rinternals{VoltaRepeatedMusic},
192 @rinternals{UnfoldedRepeatedMusic}.
197 @cindex repeat, ambiguous
198 @cindex nested repeat
199 @cindex repeat, nested
200 @cindex repeat timing information
201 @cindex repeat and measure number
202 @cindex timing information and repeats
203 @cindex measure number and repeats
204 @cindex repeat and slur
205 @cindex slur and repeat
216 is ambiguous, since it is not clear to which @code{\repeat} the
217 @code{\alternative} belongs. This ambiguity is resolved by always
218 having the @code{\alternative} belong to the inner @code{\repeat}.
219 For clarity, it is advisable to use braces in such situations.
221 Timing information is not remembered at the start of an alternative,
222 so after a repeat timing information must be reset by hand; for
223 example, by setting @code{Score.measurePosition} or entering
224 @code{\partial}. Similarly, slurs are also not repeated.
228 @node Manual repeat marks
229 @unnumberedsubsubsec Manual repeat marks
231 @cindex manual repeat mark
232 @cindex repeat, manual
234 @cindex repeat, start
237 @cindex repeat number, changing
238 @cindex repeat volta, changing
239 @cindex volta bracket
240 @cindex bracket, volta
241 @funindex repeatCommands
242 @funindex start-repeat
244 @warning{These methods are only used for displaying unusual repeat
245 constructs, and may produce unexpected behavior. In most cases,
246 repeats should be created using the standard @code{\\repeat} command
247 or by printing the relevant bar lines. For more information, see
250 The property @code{repeatCommands} can be used to control the
251 layout of repeats. Its value is a Scheme list of repeat commands.
255 Print a @code{|:} bar line.
257 @lilypond[verbatim,quote,relative=2]
259 \set Score.repeatCommands = #'(start-repeat)
264 As per standard engraving practice, repeat signs are not printed
265 at the beginning of a piece.
268 Print a @code{:|} bar line:
270 @lilypond[verbatim,quote,relative=2]
273 \set Score.repeatCommands = #'(end-repeat)
277 @item (volta @var{number}) ... (volta #f)
278 Create a new volta with the specified number. The volta bracket must
279 be explicitly terminated, or it will not be printed.
281 @lilypond[verbatim,quote,relative=2]
283 \set Score.repeatCommands = #'((volta "2"))
285 \set Score.repeatCommands = #'((volta #f))
291 Multiple repeat commands may occur at the same point:
293 @lilypond[verbatim,quote,relative=2]
295 \set Score.repeatCommands = #'((volta "2, 5") end-repeat)
298 \set Score.repeatCommands = #'((volta #f) (volta "95") end-repeat)
300 \set Score.repeatCommands = #'((volta #f))
303 @cindex volta bracket with text
304 @cindex text in volta bracket
306 Text can be included with the volta bracket. The text can be a
307 number or numbers or markup text, see @ref{Formatting text}. The
308 simplest way to use markup text is to define the markup first,
309 then include the markup in a Scheme list.
311 @lilypond[verbatim,quote]
312 voltaAdLib = \markup { 1. 2. 3... \text \italic { ad lib. } }
315 \set Score.repeatCommands = #(list(list 'volta voltaAdLib) 'start-repeat)
317 \set Score.repeatCommands = #'((volta #f) (volta "4.") end-repeat)
319 \set Score.repeatCommands = #'((volta #f))
326 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
327 {printing-a-repeat-sign-at-the-beginning-of-a-piece.ly}
333 @ref{Formatting text}.
339 @rinternals{VoltaBracket},
340 @rinternals{RepeatedMusic},
341 @rinternals{VoltaRepeatedMusic}.
344 @node Written-out repeats
345 @unnumberedsubsubsec Written-out repeats
347 @cindex written-out repeats
348 @cindex repetitious music
349 @cindex repeats, written-out
350 @cindex repeat, unfold
352 @cindex unfold repeat
353 @cindex unfold repeat with alternate endings
354 @cindex unfold music with alternate endings
355 @cindex alternate ending in written-out repeats
358 By using the @code{unfold} command, repeats can be used to simplify
359 the writing out of repetitious music. The syntax is
362 \repeat unfold @var{repeatcount} @var{musicexpr}
366 where @var{musicexpr} is a music expression and @var{repeatcount} is
367 the number of times @var{musicexpr} is repeated.
369 @lilypond[verbatim,quote,relative=2]
371 \repeat unfold 2 { c4 d e f }
375 Unfold repeats can be made with alternate endings. If there are
376 more repeats than there are alternate endings, the first
377 alternative ending is applied to the earliest endings.
379 @lilypond[verbatim,quote,relative=2]
381 \repeat unfold 2 { g4 f e d }
389 @warning{If you include @code{@bs{}relative} inside a
390 @code{@bs{}repeat} without explicitly instantiating the
391 @code{Voice} context, extra (unwanted) staves will appear. See
392 @rprogram{An extra staff appears}.}
400 @rinternals{RepeatedMusic},
401 @rinternals{UnfoldedRepeatedMusic}.
405 @subsection Short repeats
407 This section discusses how to input short repeats. Short repeats can
408 take two basic forms: repeats of a single note to two measures,
409 represented by slashes or percent signs; and tremolos.
416 @node Percent repeats
417 @unnumberedsubsubsec Percent repeats
419 @cindex percent repeats
420 @cindex measure repeats
421 @cindex repeat, percent
422 @cindex repeat, measure
423 @cindex repeat, short
424 @funindex \repeat percent
427 Repeated short patterns of notes are supported. The music is printed
428 once, and the pattern is replaced with a special sign. Patterns that
429 are shorter than one measure are replaced by slashes, and patterns of
430 one or two measures are replaced by percent-like signs. The syntax is
433 @code{\repeat percent @var{number} @var{musicexpr}}
437 where @var{musicexpr} is a music expression.
439 @lilypond[verbatim,quote,relative=2]
440 \repeat percent 4 { c4 }
441 \repeat percent 2 { b4 a g f }
442 \repeat percent 2 { c2 es | f4 fis g c | }
447 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
448 {percent-repeat-counter.ly}
450 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
451 {percent-repeat-count-visibility.ly}
453 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
454 {isolated-percent-repeats.ly}
459 @rglos{percent repeat},
466 @rinternals{RepeatSlash},
467 @rinternals{PercentRepeat},
468 @rinternals{DoublePercentRepeat},
469 @rinternals{DoublePercentRepeatCounter},
470 @rinternals{PercentRepeatCounter},
471 @rinternals{PercentRepeatedMusic}.
476 Only three kinds of percent repeats are supported: a single slash
477 representing a single beat (regardless of the duration of the repeated
478 notes); a single slash with dots representing one full measure; and
479 two slashes with dots crossing a bar line representing two full
480 measures. Neither multiple slashes representing single beat repeats
481 consisting of sixteenth or shorter notes, nor two slashes with dots
482 representing single beat repeats consisting of notes of varying
483 durations, are supported.
486 @node Tremolo repeats
487 @unnumberedsubsubsec Tremolo repeats
489 @cindex tremolo beams
491 @cindex repeat, tremolo
492 @funindex \repeat tremolo
495 Tremolos can take two forms: alternation between two chords or two
496 notes, and rapid repetition of a single note or chord. Tremolos
497 consisting of an alternation are indicated by adding beams between the
498 notes or chords being alternated, while tremolos consisting of the
499 rapid repetition of a single note are indicated by adding beams or
500 slashes to a single note.
502 To place tremolo marks between notes, use @code{\repeat} with
505 @lilypond[quote,verbatim,relative=2]
506 \repeat tremolo 8 { c16 d }
507 \repeat tremolo 6 { c16 d }
508 \repeat tremolo 2 { c16 d }
511 The @code{\repeat tremolo} syntax expects exactly two notes within
512 the braces, and the number of repetitions must correspond to a
513 note value that can be expressed with plain or dotted notes. Thus,
514 @code{\repeat tremolo 7} is valid and produces a double dotted
515 note, but @code{\repeat tremolo 9} is not.
517 The duration of the tremolo equals the duration of the
518 braced expression multiplied by the number of repeats:
519 @code{\repeat tremolo 8 @{ c16 d16 @}} gives a whole note tremolo,
520 notated as two whole notes joined by tremolo beams.
522 There are two ways to put tremolo marks on a single note. The
523 @code{\repeat tremolo} syntax is also used here, in which case
524 the note should not be surrounded by braces:
526 @lilypond[quote,verbatim,ragged-right]
527 \repeat tremolo 4 c'16
530 @cindex tremolo marks
531 @funindex tremoloFlags
534 The same output can be obtained by adding
535 @q{@code{:}[@var{number}]} after the note. The number indicates
536 the duration of the subdivision, and it must be at least 8. A
537 @var{number} value of 8 gives one line across the note stem. If
538 the length is omitted, the last value (stored in
539 @code{tremoloFlags}) is used:
541 @lilypond[quote,verbatim,relative=2]
548 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
549 {cross-staff-tremolos.ly}
556 @cindex tremolo, cross-staff
557 @cindex cross-staff tremolo
561 Cross-staff tremolos do not work well.