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 @code{@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 @code{@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 An @q{opening} repeat mark is not, by default, printed in the first full
98 measure. However it is possible to add one by using @code{\bar ".|:"}
99 before the first note.
101 @lilypond[verbatim,fragment,quote,relative=2]
102 \repeat volta 2 { \bar ".|:" c4 d e f }
104 \repeat volta 2 { d4 e f g }
107 Alternative endings can be produced using @code{\alternative}. Each
108 group of alternatives must be themselves, enclosed in a set of braces.
111 \repeat volta @var{repeatcount} @var{musicexpr}
113 @{ @var{musicexpr} @}
118 where @code{@var{musicexpr}} is a music expression.
120 If there are more repeats than there are alternate endings, the earliest
121 repeats are given the first alternative.
123 A single repeat with one alternate ending:
125 @lilypond[verbatim,quote,relative=2]
126 \repeat volta 2 { c4 d e f | }
134 Multiple repeats with one alternate ending:
136 @lilypond[verbatim,quote,relative=2]
137 \repeat volta 4 { c4 d e f | }
145 Multiple repeats with more than one alternate ending:
147 @lilypond[verbatim,quote,relative=2]
148 \repeat volta 3 { c4 d e f | }
157 @warning{If there are two or more alternatives, nothing should appear
158 between the closing brace of one and the opening brace of the next
159 in an @code{@bs{}alternative} block, otherwise you will not get the
160 expected number of endings.}
162 @warning{If you include @code{@bs{}relative} inside a
163 @code{@bs{}repeat} without explicitly instantiating the
164 @code{Voice} context, extra (unwanted) staves will appear. See
165 @rprogram{An extra staff appears}.}
167 @cindex repeat with upbeat
168 @cindex upbeat in a repeat
169 @cindex anacrusis in a repeat
170 @cindex repeat with anacrusis
171 @cindex repeat with pickup
172 @cindex pickup in a repeat
175 If a repeat starts in the middle of a measure and has no alternate
176 endings, normally the end of the repeat will also fall in the
177 middle of a measure, so that the two ends add up to one complete
178 measure. In such cases, the repeat signs do not constitute true
179 bar lines. Do not use @code{\partial} commands or bar checks
180 where these repeat signs are printed:
182 @lilypond[verbatim,quote,relative=1]
184 c4 e g % no bar check here
190 g4 g g % no bar check here
198 Similarly, if a repeat begins with the initial partial measure of
199 a score and has no alternate endings, the same conditions apply as
200 in the above example, except that in this case the @code{\partial}
201 command is required at the beginning of the score:
203 @lilypond[verbatim,quote,relative=1]
204 \partial 4 % required
209 g4 g g % no bar check here
217 When alternate endings are added to a repeat that begins with an
218 incomplete measure, it becomes necessary to set the
219 @code{Timing.measureLength} context property manually, in the
220 following specific places:
224 at the start of any incomplete measures in the @code{\alternative}
225 block, which normally occur at the end of each alternative, except
226 (in most cases) the last.
229 at the start of each alternative, except the first.
232 @lilypond[verbatim,quote,relative=1]
234 \repeat volta 2 { e4 | c2 e | }
238 \set Timing.measureLength = #(ly:make-moment 3/4)
239 g4 g g % optional bar check is allowed here
242 \set Timing.measureLength = #(ly:make-moment 4/4)
249 The @code{measureLength} property is described in @ref{Time
252 @cindex repeats, with ties
253 @cindex alternative endings, with ties
254 @cindex ties, in repeats
255 @cindex ties, alternative endings
258 Ties may be added to a second ending:
260 @lilypond[verbatim,quote,relative=2]
262 \repeat volta 2 { c4 d e f~ }
269 @funindex \inStaffSegno
270 @cindex repeats, with segno
271 @cindex segno, with repeats
273 The @code{\inStaffSegno} command can be used to generate a composite
274 bar line incorporating the segno symbol with the appropriate repeat
275 bar line when used with the @code{\repeat volta} command. The
276 correct type of repeat bar line, viz. start repeat, end repeat or
277 double repeat, is selected automatically. Note that the
278 corresponding @qq{D.S.} mark must be added manually.
282 @lilypond[verbatim,quote,relative=1]
289 At the start of a repeat:
291 @lilypond[verbatim,quote,relative=1]
294 \inStaffSegno % start repeat
300 At the end of a repeat:
302 @lilypond[verbatim,quote,relative=1]
306 \inStaffSegno % end repeat
314 @lilypond[verbatim,quote,relative=1]
319 \inStaffSegno % double repeat
326 Alternative bar line symbols can be obtained by setting (in the Score
327 context) the properties @code{segnoType}, @code{startRepeatSegnoType},
328 @code{endRepeatSegnoType} or @code{doubleRepeatSegnoType} to the
329 required bar line type. The alternative bar line types must be
330 selected from the pre-defined types or types previously defined
331 with the @code{\defineBarLine} command (see @ref{Bar lines}).
333 @lilypond[verbatim,quote,relative=1]
334 \defineBarLine ":|.S[" #'(":|." "S[" "")
335 \defineBarLine "]" #'("]" "" "")
339 \once \set Score.endRepeatSegnoType = ":|.S["
347 @lilypondfile[verbatim,quote,texidoc,doctitle]
348 {shortening-volta-brackets.ly}
350 @lilypondfile[verbatim,quote,texidoc,doctitle]
351 {adding-volta-brackets-to-additional-staves.ly}
353 @lilypondfile[verbatim,quote,texidoc,doctitle]
354 {setting-the-double-repeat-default-for-volte.ly}
356 @cindex repeats, bar numbers letters
357 @cindex repeats, alternative bar numbers
359 @lilypondfile[verbatim,quote,texidoc,doctitle]
360 {alternative-bar-numbering.ly}
369 @ref{Modifying context plug-ins},
370 @ref{Modifying ties and slurs},
371 @ref{Time administration}.
377 @rinternals{VoltaBracket},
378 @rinternals{RepeatedMusic},
379 @rinternals{VoltaRepeatedMusic},
380 @rinternals{UnfoldedRepeatedMusic}.
383 @cindex repeat, ambiguous
384 @cindex nested repeat
385 @cindex repeat, nested
386 @cindex repeat timing information
387 @cindex repeat and measure number
388 @cindex timing information and repeats
389 @cindex measure number and repeats
390 @cindex repeats and slur
391 @cindex slur and repeats
392 @cindex glissandi and repeats
393 @cindex repeats and glissandi
395 Slurs that span from a @code{\repeat} block into an
396 @code{\alternative} block will only work for the first alternative
397 ending. The visual appearance of a continuing slur in other
398 alternative blocks may be simulated with @code{\repeatTie} if the
399 slur extends into only one note in the alternative block, although
400 this method does not work in @code{TabStaff}. Other methods which
401 may be tailored to indicate continuing slurs over several notes in
402 alternative blocks, and which also work in @code{TabStaff} contexts,
403 are shown in @ref{Modifying ties and slurs}.
405 Also, slurs cannot wrap around from the end of one
406 alternative back to the beginning of the repeat.
408 Glissandi that span from a @code{\repeat} block into an
409 @code{\alternative} block will only work for the first alternative
410 ending. The visual appearance of a continuing glissando in other
411 alternative blocks may be indicated by coding a glissando starting
412 on a hidden grace note. For an example, see
413 @qq{Extending glissandi across repeats} under Selected Snippets
416 If a repeat that begins with an incomplete measure has an
417 @code{\alternative} block that contains modifications to the
418 @code{measureLength} property, using @code{\unfoldRepeats} will
419 result in wrongly-placed bar lines and bar check warnings.
430 is ambiguous, since it is not clear to which @code{\repeat} the
431 @code{\alternative} belongs. This ambiguity is resolved by always
432 having the @code{\alternative} belong to the inner @code{\repeat}.
433 For clarity, it is advisable to use braces in such situations.
436 @node Manual repeat marks
437 @unnumberedsubsubsec Manual repeat marks
439 @cindex manual repeat mark
440 @cindex repeat, manual
442 @cindex repeat, start
445 @cindex repeat number, changing
446 @cindex repeat volta, changing
447 @cindex volta bracket
448 @cindex bracket, volta
449 @funindex repeatCommands
450 @funindex start-repeat
452 @warning{These methods are only used for displaying unusual repeat
453 constructs, and may produce unexpected behavior. In most cases,
454 repeats should be created using the standard @code{@bs{}repeat} command
455 or by printing the relevant bar lines. For more information, see
458 The property @code{repeatCommands} can be used to control the
459 layout of repeats. Its value is a Scheme list of repeat commands.
463 Print a @code{.|:} bar line.
465 @lilypond[verbatim,quote,relative=2]
467 \set Score.repeatCommands = #'(start-repeat)
472 As per standard engraving practice, repeat signs are not printed
473 at the beginning of a piece.
476 Print a @code{:|.} bar line:
478 @lilypond[verbatim,quote,relative=2]
481 \set Score.repeatCommands = #'(end-repeat)
485 @item (volta @var{number}) @dots{} (volta #f)
486 Create a new volta with the specified number. The volta bracket must
487 be explicitly terminated, or it will not be printed.
489 @lilypond[verbatim,quote,relative=2]
491 \set Score.repeatCommands = #'((volta "2"))
493 \set Score.repeatCommands = #'((volta #f))
499 Multiple repeat commands may occur at the same point:
501 @lilypond[verbatim,quote,relative=2]
503 \set Score.repeatCommands = #'((volta "2, 5") end-repeat)
506 \set Score.repeatCommands = #'((volta #f) (volta "95") end-repeat)
508 \set Score.repeatCommands = #'((volta #f))
511 @cindex volta bracket with text
512 @cindex text in volta bracket
514 Text can be included with the volta bracket. The text can be a
515 number or numbers or markup text, see @ref{Formatting text}. The
516 simplest way to use markup text is to define the markup first,
517 then include the markup in a Scheme list.
519 @lilypond[verbatim,quote]
520 voltaAdLib = \markup { 1. 2. 3... \text \italic { ad lib. } }
523 \set Score.repeatCommands =
524 #(list(list 'volta voltaAdLib) 'start-repeat)
526 \set Score.repeatCommands = #'((volta #f) (volta "4.") end-repeat)
528 \set Score.repeatCommands = #'((volta #f))
535 @ref{Formatting text}.
541 @rinternals{VoltaBracket},
542 @rinternals{RepeatedMusic},
543 @rinternals{VoltaRepeatedMusic}.
546 @node Written-out repeats
547 @unnumberedsubsubsec Written-out repeats
549 @cindex written-out repeats
550 @cindex repeats, written-out
551 @cindex repeats, unfold
552 @cindex repeats, alternative
553 @cindex unfold repeat
554 @cindex unfold repeat, alternate endings
555 @cindex alternate repeats
556 @cindex alternate endings, repeats
559 By using the @code{unfold} command, repeats can be used to simplify the
560 writing out of repetitious music. The syntax is
563 \repeat unfold @var{repeatcount} @var{musicexpr}
567 where @code{@var{musicexpr}} is a music expression and
568 @code{@var{repeatcount}} is the number of times
569 @code{@var{musicexpr}} is repeated.
571 @lilypond[verbatim,quote,relative=2]
572 \repeat unfold 2 { c4 d e f }
576 In some cases, especially in a @code{\relative} context, the
577 @code{\repeat unfold} function is not the same as writing out the
578 music expression multiple times. E.g,
581 \repeat unfold 2 @{ a'4 b c @}
590 Unfold repeats can be made with alternate endings.
592 @lilypond[verbatim,quote,relative=2]
593 \repeat unfold 2 { c4 d e f }
601 If there are more repeats than there are alternate endings, the first
602 alternative is applied multiple times until the remaining alternatives
603 make up the total number of repeats.
605 @lilypond[verbatim,quote,relative=2]
606 \repeat unfold 4 { c4 d e f }
615 If there are more alternate endings than repeats then only the first
616 alternatives are applied. The remaining alternatives will be ignored
619 @lilypond[verbatim,quote,relative=2]
620 \repeat unfold 2 { c4 d e f }
629 It is also possible to nest multiple @code{unfold} functions (with or
630 without alternate endings).
632 @lilypond[verbatim,quote,relative=2]
634 \repeat unfold 2 { c4 d e f }
643 Chord constructs can be repeated by the chord repetition symbol
644 @code{q}. See @ref{Chord repetition}.
646 @warning{If you include @code{@bs{}relative} inside a @code{@bs{}repeat}
647 without explicitly instantiating the @code{Voice} context, extra
648 (unwanted) staves will appear. See @rprogram{An extra staff appears}.}
652 @ref{Chord repetition}.
658 @rinternals{RepeatedMusic},
659 @rinternals{UnfoldedRepeatedMusic}.
663 @subsection Short repeats
665 This section discusses how to input short repeats. Short repeats can
666 take two forms: slashes or percent signs to represent repeats of a
667 single note, a single measure or two measures, and tremolos otherwise.
674 @node Percent repeats
675 @unnumberedsubsubsec Percent repeats
677 @cindex percent repeats
678 @cindex measure repeats
679 @cindex repeat, percent
680 @cindex repeat, measure
681 @cindex repeat, short
682 @funindex \repeat percent
685 Repeated short patterns are printed once, and the repeated pattern
686 is replaced with a special sign.
691 \repeat percent @var{number} @var{musicexpr}
695 where @code{@var{musicexpr}} is a music expression.
697 Patterns that are shorter than one measure are replaced by slashes.
699 @lilypond[verbatim,quote,relative=2]
700 \repeat percent 4 { c128 d e f }
701 \repeat percent 4 { c64 d e f }
702 \repeat percent 5 { c32 d e f }
703 \repeat percent 4 { c16 d e f }
704 \repeat percent 4 { c8 d }
705 \repeat percent 4 { c4 }
706 \repeat percent 2 { c2 }
709 Patterns of one or two measures are replaced by percent-like symbols.
711 @lilypond[verbatim,quote,relative=2]
712 \repeat percent 2 { c4 d e f }
713 \repeat percent 2 { c2 d }
714 \repeat percent 2 { c1 }
717 @lilypond[verbatim,quote,relative=2]
718 \repeat percent 3 { c4 d e f | c2 g' }
721 Patterns that are shorter than one measure but contain mixed durations
722 use a double-percent symbol.
724 @lilypond[verbatim,quote,relative=2]
725 \repeat percent 4 { c8. <d f>16 }
726 \repeat percent 2 { \tuplet 3/2 { r8 c d } e4 }
731 @lilypondfile[verbatim,quote,texidoc,doctitle]
732 {percent-repeat-counter.ly}
734 @lilypondfile[verbatim,quote,texidoc,doctitle]
735 {percent-repeat-count-visibility.ly}
737 @lilypondfile[verbatim,quote,texidoc,doctitle]
738 {isolated-percent-repeats.ly}
742 @rglos{percent repeat},
749 @rinternals{RepeatSlash},
750 @rinternals{RepeatSlashEvent},
751 @rinternals{DoubleRepeatSlash},
752 @rinternals{PercentRepeat},
753 @rinternals{PercentRepeatCounter},
754 @rinternals{PercentRepeatedMusic},
755 @rinternals{Percent_repeat_engraver},
756 @rinternals{DoublePercentEvent},
757 @rinternals{DoublePercentRepeat},
758 @rinternals{DoublePercentRepeatCounter},
759 @rinternals{Double_percent_repeat_engraver},
760 @rinternals{Slash_repeat_engraver}.
763 @node Tremolo repeats
764 @unnumberedsubsubsec Tremolo repeats
766 @cindex tremolo beams
768 @cindex repeat, tremolo
769 @funindex \repeat tremolo
772 Tremolos can take two forms: alternation between two chords or two
773 notes, and rapid repetition of a single note or chord. Tremolos
774 consisting of an alternation are indicated by adding beams between the
775 notes or chords being alternated, while tremolos consisting of the
776 rapid repetition of a single note are indicated by adding beams or
777 slashes to a single note.
779 To place tremolo marks between notes, use @code{\repeat} with
782 @lilypond[quote,verbatim,relative=2]
783 \repeat tremolo 8 { c16 d }
784 \repeat tremolo 6 { c16 d }
785 \repeat tremolo 2 { c16 d }
788 The @code{\repeat tremolo} syntax expects exactly two notes within
789 the braces, and the number of repetitions must correspond to a
790 note value that can be expressed with plain or dotted notes. Thus,
791 @code{\repeat tremolo 7} is valid and produces a double dotted
792 note, but @code{\repeat tremolo 9} is not.
794 The duration of the tremolo equals the duration of the
795 braced expression multiplied by the number of repeats:
796 @code{\repeat tremolo 8 @{ c16 d16 @}} gives a whole note tremolo,
797 notated as two whole notes joined by tremolo beams.
799 There are two ways to put tremolo marks on a single note. The
800 @code{\repeat tremolo} syntax is also used here, in which case
801 the note should not be surrounded by braces:
803 @lilypond[quote,verbatim,ragged-right]
804 \repeat tremolo 4 c'16
807 @cindex tremolo marks
810 The same output can be obtained by adding @code{:@var{N}} after
811 the note, where @code{@var{N}} indicates the duration of the
812 subdivision (it must be at least 8). If @code{@var{N}} is 8, one
813 beam is added to the note's stem. If @code{@var{N}} is omitted,
814 the last value is used:
816 @lilypond[quote,verbatim,relative=2]
823 @lilypondfile[verbatim,quote,texidoc,doctitle]
824 {cross-staff-tremolos.ly}
830 @cindex tremolo, cross-staff
831 @cindex cross-staff tremolo