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.
89 A single repeat without an alternate ending:
91 @lilypond[verbatim,quote,relative=2]
92 \repeat volta 2 { c4 d e f }
94 \repeat volta 2 { d4 e f g }
97 Alternative endings can be produced using @code{\alternative}. Each
98 group of alternatives must be themselves, enclosed in a set of braces.
101 \repeat volta @var{repeatcount} @var{musicexpr}
103 @{ @var{musicexpr} @}
108 where @var{musicexpr} is a music expression.
110 If there are more repeats than there are alternate endings, the earliest
111 repeats are given the first alternative.
113 A single repeat with one alternate ending:
115 @lilypond[verbatim,quote,relative=2]
116 \repeat volta 2 { c4 d e f }
124 A single repeat with more than one alternate ending:
126 @lilypond[verbatim,quote,relative=2]
127 \repeat volta 4 { c4 d e f }
135 Multiple repeats with more than one alternate ending:
137 @lilypond[verbatim,quote,relative=2]
138 \repeat volta 3 { c4 d e f }
147 @warning{If you include @code{@bs{}relative} inside a
148 @code{@bs{}repeat} without explicitly instantiating the
149 @code{Voice} context, extra (unwanted) staves will appear. See
150 @rprogram{An extra staff appears}.}
152 @cindex repeat with upbeat
153 @cindex upbeat in a repeat
154 @cindex anacrucis in a repeat
155 @cindex repeat with anacrucis
156 @cindex repeat with pickup
157 @cindex pickup in a repeat
161 If a repeat starts in the middle of a measure and has no alternate
162 endings, normally the end of the repeat will also fall in the
163 middle of a measure, so that the two ends add up to one complete
164 measure. In such cases, the repeat signs do not constitute true
165 bar lines. Do not use @code{\partial} commands or bar checks
166 where these repeat signs are printed:
168 @lilypond[verbatim,quote,relative=1]
170 c4 e g % no bar check here
176 g4 g g % no bar check here
184 Similarly, if a repeat begins with the initial partial measure of
185 a score and has no alternate endings, the same conditions apply as
186 in the above example, except that in this case the @code{\partial}
187 command is required at the beginning of the score:
189 @lilypond[verbatim,quote,relative=1]
190 \partial 4 % required
195 g4 g g % no bar check here
203 When alternate endings are added to a repeat that begins with an
204 incomplete measure, it becomes necessary to set the
205 @code{Timing.measureLength} context property manually, in the
206 following specific places:
210 at the start of any incomplete measures in the @code{\alternative}
211 block, which normally occur at the end of each alternative, except
212 (in most cases) the last.
215 at the start of each alternative, except the first.
218 @lilypond[verbatim,quote,relative=1]
220 \repeat volta 2 { e4 | c2 e | }
224 \set Timing.measureLength = #(ly:make-moment 3 4)
225 g4 g g % optional bar check is allowed here
228 \set Timing.measureLength = #(ly:make-moment 4 4)
235 The @code{measureLength} property is described in @ref{Time
238 @cindex repeats with ties
239 @cindex alternative endings with ties
240 @cindex ties in repeats
241 @cindex ties in alternative endings
244 Ties may be added to a second ending:
246 @lilypond[verbatim,quote,relative=2]
248 \repeat volta 2 { c4 d e f~ }
257 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
258 {shortening-volta-brackets.ly}
260 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
261 {adding-volta-brackets-to-additional-staves.ly}
263 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
264 {setting-the-double-repeat-default-for-volte.ly}
273 @ref{Modifying context plug-ins},
274 @ref{Time administration}.
280 @rinternals{VoltaBracket},
281 @rinternals{RepeatedMusic},
282 @rinternals{VoltaRepeatedMusic},
283 @rinternals{UnfoldedRepeatedMusic}.
288 @cindex repeat, ambiguous
289 @cindex nested repeat
290 @cindex repeat, nested
291 @cindex repeat timing information
292 @cindex repeat and measure number
293 @cindex timing information and repeats
294 @cindex measure number and repeats
295 @cindex repeat and slur
296 @cindex slur and repeat
298 Slurs that span from a @code{\repeat} block into an
299 @code{\alternative} block will only work for the first alternate
300 ending. Also, slurs cannot wrap around from the end of one
301 alternative back to the beginning of the repeat.
303 If a repeat that begins with an incomplete measure has an
304 @code{\alternative} block that contains modifications to the
305 @code{measureLength} property, using @code{\unfoldRepeats} will
306 result in wrongly-placed bar lines and bar check warnings.
317 is ambiguous, since it is not clear to which @code{\repeat} the
318 @code{\alternative} belongs. This ambiguity is resolved by always
319 having the @code{\alternative} belong to the inner @code{\repeat}.
320 For clarity, it is advisable to use braces in such situations.
323 @node Manual repeat marks
324 @unnumberedsubsubsec Manual repeat marks
326 @cindex manual repeat mark
327 @cindex repeat, manual
329 @cindex repeat, start
332 @cindex repeat number, changing
333 @cindex repeat volta, changing
334 @cindex volta bracket
335 @cindex bracket, volta
336 @funindex repeatCommands
337 @funindex start-repeat
339 @warning{These methods are only used for displaying unusual repeat
340 constructs, and may produce unexpected behavior. In most cases,
341 repeats should be created using the standard @code{\\repeat} command
342 or by printing the relevant bar lines. For more information, see
345 The property @code{repeatCommands} can be used to control the
346 layout of repeats. Its value is a Scheme list of repeat commands.
350 Print a @code{|:} bar line.
352 @lilypond[verbatim,quote,relative=2]
354 \set Score.repeatCommands = #'(start-repeat)
359 As per standard engraving practice, repeat signs are not printed
360 at the beginning of a piece.
363 Print a @code{:|} bar line:
365 @lilypond[verbatim,quote,relative=2]
368 \set Score.repeatCommands = #'(end-repeat)
372 @item (volta @var{number}) ... (volta #f)
373 Create a new volta with the specified number. The volta bracket must
374 be explicitly terminated, or it will not be printed.
376 @lilypond[verbatim,quote,relative=2]
378 \set Score.repeatCommands = #'((volta "2"))
380 \set Score.repeatCommands = #'((volta #f))
386 Multiple repeat commands may occur at the same point:
388 @lilypond[verbatim,quote,relative=2]
390 \set Score.repeatCommands = #'((volta "2, 5") end-repeat)
393 \set Score.repeatCommands = #'((volta #f) (volta "95") end-repeat)
395 \set Score.repeatCommands = #'((volta #f))
398 @cindex volta bracket with text
399 @cindex text in volta bracket
401 Text can be included with the volta bracket. The text can be a
402 number or numbers or markup text, see @ref{Formatting text}. The
403 simplest way to use markup text is to define the markup first,
404 then include the markup in a Scheme list.
406 @lilypond[verbatim,quote]
407 voltaAdLib = \markup { 1. 2. 3... \text \italic { ad lib. } }
410 \set Score.repeatCommands = #(list(list 'volta voltaAdLib) 'start-repeat)
412 \set Score.repeatCommands = #'((volta #f) (volta "4.") end-repeat)
414 \set Score.repeatCommands = #'((volta #f))
421 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
422 {printing-a-repeat-sign-at-the-beginning-of-a-piece.ly}
428 @ref{Formatting text}.
434 @rinternals{VoltaBracket},
435 @rinternals{RepeatedMusic},
436 @rinternals{VoltaRepeatedMusic}.
439 @node Written-out repeats
440 @unnumberedsubsubsec Written-out repeats
442 @cindex written-out repeats
443 @cindex repetitious music
444 @cindex repeats, written-out
445 @cindex repeat, unfold
447 @cindex unfold repeat
448 @cindex unfold repeat with alternate endings
449 @cindex unfold music with alternate endings
450 @cindex alternate ending in written-out repeats
453 By using the @code{unfold} command, repeats can be used to simplify
454 the writing out of repetitious music. The syntax is
457 \repeat unfold @var{repeatcount} @var{musicexpr}
461 where @var{musicexpr} is a music expression and @var{repeatcount} is
462 the number of times @var{musicexpr} is repeated.
464 @lilypond[verbatim,quote,relative=2]
466 \repeat unfold 2 { c4 d e f }
470 Unfold repeats can be made with alternate endings. If there are
471 more repeats than there are alternate endings, the first
472 alternative ending is applied to the earliest endings.
474 @lilypond[verbatim,quote,relative=2]
476 \repeat unfold 2 { g4 f e d }
484 @warning{If you include @code{@bs{}relative} inside a
485 @code{@bs{}repeat} without explicitly instantiating the
486 @code{Voice} context, extra (unwanted) staves will appear. See
487 @rprogram{An extra staff appears}.}
495 @rinternals{RepeatedMusic},
496 @rinternals{UnfoldedRepeatedMusic}.
500 @subsection Short repeats
502 This section discusses how to input short repeats. Short repeats can
503 take two basic forms: repeats of a single note to two measures,
504 represented by slashes or percent signs; and tremolos.
511 @node Percent repeats
512 @unnumberedsubsubsec Percent repeats
514 @cindex percent repeats
515 @cindex measure repeats
516 @cindex repeat, percent
517 @cindex repeat, measure
518 @cindex repeat, short
519 @funindex \repeat percent
522 Repeated short patterns of notes are supported. The music is printed
523 once, and the pattern is replaced with a special sign. Patterns that
524 are shorter than one measure are replaced by slashes, and patterns of
525 one or two measures are replaced by percent-like signs. The syntax is
528 @code{\repeat percent @var{number} @var{musicexpr}}
532 where @var{musicexpr} is a music expression.
534 @lilypond[verbatim,quote,relative=2]
535 \repeat percent 4 { c4 }
536 \repeat percent 2 { b4 a g f }
537 \repeat percent 2 { c2 es | f4 fis g c | }
542 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
543 {percent-repeat-counter.ly}
545 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
546 {percent-repeat-count-visibility.ly}
548 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
549 {isolated-percent-repeats.ly}
554 @rglos{percent repeat},
561 @rinternals{RepeatSlash},
562 @rinternals{PercentRepeat},
563 @rinternals{DoublePercentRepeat},
564 @rinternals{DoublePercentRepeatCounter},
565 @rinternals{PercentRepeatCounter},
566 @rinternals{PercentRepeatedMusic}.
571 Only three kinds of percent repeats are supported: a single slash
572 representing a single beat (regardless of the duration of the repeated
573 notes); a single slash with dots representing one full measure; and
574 two slashes with dots crossing a bar line representing two full
575 measures. Neither multiple slashes representing single beat repeats
576 consisting of sixteenth or shorter notes, nor two slashes with dots
577 representing single beat repeats consisting of notes of varying
578 durations, are supported.
581 @node Tremolo repeats
582 @unnumberedsubsubsec Tremolo repeats
584 @cindex tremolo beams
586 @cindex repeat, tremolo
587 @funindex \repeat tremolo
590 Tremolos can take two forms: alternation between two chords or two
591 notes, and rapid repetition of a single note or chord. Tremolos
592 consisting of an alternation are indicated by adding beams between the
593 notes or chords being alternated, while tremolos consisting of the
594 rapid repetition of a single note are indicated by adding beams or
595 slashes to a single note.
597 To place tremolo marks between notes, use @code{\repeat} with
600 @lilypond[quote,verbatim,relative=2]
601 \repeat tremolo 8 { c16 d }
602 \repeat tremolo 6 { c16 d }
603 \repeat tremolo 2 { c16 d }
606 The @code{\repeat tremolo} syntax expects exactly two notes within
607 the braces, and the number of repetitions must correspond to a
608 note value that can be expressed with plain or dotted notes. Thus,
609 @code{\repeat tremolo 7} is valid and produces a double dotted
610 note, but @code{\repeat tremolo 9} is not.
612 The duration of the tremolo equals the duration of the
613 braced expression multiplied by the number of repeats:
614 @code{\repeat tremolo 8 @{ c16 d16 @}} gives a whole note tremolo,
615 notated as two whole notes joined by tremolo beams.
617 There are two ways to put tremolo marks on a single note. The
618 @code{\repeat tremolo} syntax is also used here, in which case
619 the note should not be surrounded by braces:
621 @lilypond[quote,verbatim,ragged-right]
622 \repeat tremolo 4 c'16
625 @cindex tremolo marks
626 @funindex tremoloFlags
629 The same output can be obtained by adding
630 @q{@code{:}[@var{number}]} after the note. The number indicates
631 the duration of the subdivision, and it must be at least 8. A
632 @var{number} value of 8 gives one line across the note stem. If
633 the length is omitted, the last value (stored in
634 @code{tremoloFlags}) is used:
636 @lilypond[quote,verbatim,relative=2]
643 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
644 {cross-staff-tremolos.ly}
651 @cindex tremolo, cross-staff
652 @cindex cross-staff tremolo