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 @cindex repeats, with ties
218 @cindex alternative endings, with ties
219 @cindex ties, in repeats
220 @cindex ties, alternative endings
223 Ties may be added to a second ending:
225 @lilypond[verbatim,quote,relative=2]
227 \repeat volta 2 { c4 d e f~ }
234 @funindex \inStaffSegno
235 @cindex repeats, with segno
236 @cindex segno, with repeats
238 The @code{\inStaffSegno} command can be used to generate a composite
239 bar line incorporating the segno symbol with the appropriate repeat
240 bar line when used with the @code{\repeat volta} command. The
241 correct type of repeat bar line, viz. start repeat, end repeat or
242 double repeat, is selected automatically. Note that the
243 corresponding @qq{D.S.} mark must be added manually.
247 @lilypond[verbatim,quote,relative=1]
254 At the start of a repeat:
256 @lilypond[verbatim,quote,relative=1]
259 \inStaffSegno % start repeat
265 At the end of a repeat:
267 @lilypond[verbatim,quote,relative=1]
271 \inStaffSegno % end repeat
279 @lilypond[verbatim,quote,relative=1]
284 \inStaffSegno % double repeat
291 Alternative bar line symbols can be obtained by setting (in the Score
292 context) the properties @code{segnoType}, @code{startRepeatSegnoType},
293 @code{endRepeatSegnoType} or @code{doubleRepeatSegnoType} to the
294 required bar line type. The alternative bar line types must be
295 selected from the pre-defined types or types previously defined
296 with the @code{\defineBarLine} command (see @ref{Bar lines}).
298 @lilypond[verbatim,quote,relative=1]
299 \defineBarLine ":|.S[" #'(":|." "S[" "")
300 \defineBarLine "]" #'("]" "" "")
304 \once \set Score.endRepeatSegnoType = ":|.S["
312 @lilypondfile[verbatim,quote,texidoc,doctitle]
313 {shortening-volta-brackets.ly}
315 @lilypondfile[verbatim,quote,texidoc,doctitle]
316 {adding-volta-brackets-to-additional-staves.ly}
318 @lilypondfile[verbatim,quote,texidoc,doctitle]
319 {setting-the-double-repeat-default-for-volte.ly}
321 @cindex repeats, bar numbers letters
322 @cindex repeats, alternative bar numbers
324 @lilypondfile[verbatim,quote,texidoc,doctitle]
325 {alternative-bar-numbering.ly}
334 @ref{Modifying context plug-ins},
335 @ref{Modifying ties and slurs},
336 @ref{Time administration}.
339 @file{ly/engraver-init.ly}.
345 @rinternals{VoltaBracket},
346 @rinternals{RepeatedMusic},
347 @rinternals{VoltaRepeatedMusic},
348 @rinternals{UnfoldedRepeatedMusic}.
351 @cindex repeat, ambiguous
352 @cindex nested repeat
353 @cindex repeat, nested
354 @cindex repeat timing information
355 @cindex repeat and measure number
356 @cindex timing information and repeats
357 @cindex measure number and repeats
358 @cindex repeats and slur
359 @cindex slur and repeats
360 @cindex glissandi and repeats
361 @cindex repeats and glissandi
363 Slurs that span from a @code{\repeat} block into an
364 @code{\alternative} block will only work for the first alternative
365 ending. The visual appearance of a continuing slur in other
366 alternative blocks may be simulated with @code{\repeatTie} if the
367 slur extends into only one note in the alternative block, although
368 this method does not work in @code{TabStaff}. Other methods which
369 may be tailored to indicate continuing slurs over several notes in
370 alternative blocks, and which also work in @code{TabStaff} contexts,
371 are shown in @ref{Modifying ties and slurs}.
373 Also, slurs cannot wrap around from the end of one
374 alternative back to the beginning of the repeat.
376 Glissandi that span from a @code{\repeat} block into an
377 @code{\alternative} block will only work for the first alternative
378 ending. The visual appearance of a continuing glissando in other
379 alternative blocks may be indicated by coding a glissando starting
380 on a hidden grace note. For an example, see
381 @qq{Extending glissandi across repeats} under Selected Snippets
384 If a repeat that begins with an incomplete measure has an
385 @code{\alternative} block that contains modifications to the
386 @code{measureLength} property, using @code{\unfoldRepeats} will
387 result in wrongly-placed bar lines and bar check warnings.
398 is ambiguous, since it is not clear to which @code{\repeat} the
399 @code{\alternative} belongs. This ambiguity is resolved by always
400 having the @code{\alternative} belong to the inner @code{\repeat}.
401 For clarity, it is advisable to use braces in such situations.
404 @node Manual repeat marks
405 @unnumberedsubsubsec Manual repeat marks
407 @cindex manual repeat mark
408 @cindex repeat, manual
410 @cindex repeat, start
413 @cindex repeat number, changing
414 @cindex repeat volta, changing
415 @cindex volta bracket
416 @cindex bracket, volta
417 @funindex repeatCommands
418 @funindex start-repeat
420 @warning{These methods are only used for displaying unusual repeat
421 constructs, and may produce unexpected behavior. In most cases,
422 repeats should be created using the standard @code{@bs{}repeat} command
423 or by printing the relevant bar lines. For more information, see
426 The property @code{repeatCommands} can be used to control the
427 layout of repeats. Its value is a Scheme list of repeat commands.
431 Print a @code{.|:} bar line.
433 @lilypond[verbatim,quote,relative=2]
435 \set Score.repeatCommands = #'(start-repeat)
440 As per standard engraving practice, repeat signs are not printed
441 at the beginning of a piece.
444 Print a @code{:|.} bar line:
446 @lilypond[verbatim,quote,relative=2]
449 \set Score.repeatCommands = #'(end-repeat)
453 @item (volta @var{number}) @dots{} (volta #f)
454 Create a new volta with the specified number. The volta bracket must
455 be explicitly terminated, or it will not be printed.
457 @lilypond[verbatim,quote,relative=2]
459 \set Score.repeatCommands = #'((volta "2"))
461 \set Score.repeatCommands = #'((volta #f))
467 Multiple repeat commands may occur at the same point:
469 @lilypond[verbatim,quote,relative=2]
471 \set Score.repeatCommands = #'((volta "2, 5") end-repeat)
474 \set Score.repeatCommands = #'((volta #f) (volta "95") end-repeat)
476 \set Score.repeatCommands = #'((volta #f))
479 @cindex volta bracket with text
480 @cindex text in volta bracket
482 Text can be included with the volta bracket. The text can be a
483 number or numbers or markup text, see @ref{Formatting text}. The
484 simplest way to use markup text is to define the markup first,
485 then include the markup in a Scheme list.
487 @lilypond[verbatim,quote]
488 voltaAdLib = \markup { 1. 2. 3... \text \italic { ad lib. } }
491 \set Score.repeatCommands =
492 #(list(list 'volta voltaAdLib) 'start-repeat)
494 \set Score.repeatCommands = #'((volta #f) (volta "4.") end-repeat)
496 \set Score.repeatCommands = #'((volta #f))
503 @ref{Formatting text}.
509 @rinternals{VoltaBracket},
510 @rinternals{RepeatedMusic},
511 @rinternals{VoltaRepeatedMusic}.
514 @node Written-out repeats
515 @unnumberedsubsubsec Written-out repeats
517 @cindex written-out repeats
518 @cindex repeats, written-out
519 @cindex repeats, unfold
520 @cindex repeats, alternative
521 @cindex unfold repeat
522 @cindex unfold repeat, alternate endings
523 @cindex alternate repeats
524 @cindex alternate endings, repeats
527 By using the @code{unfold} command, repeats can be used to simplify the
528 writing out of repetitious music. The syntax is
531 \repeat unfold @var{repeatcount} @var{musicexpr}
535 where @code{@var{musicexpr}} is a music expression and
536 @code{@var{repeatcount}} is the number of times
537 @code{@var{musicexpr}} is repeated.
539 @lilypond[verbatim,quote,relative=2]
540 \repeat unfold 2 { c4 d e f }
544 In some cases, especially in a @code{\relative} context, the
545 @code{\repeat unfold} function is not the same as writing out the
546 music expression multiple times. E.g,
549 \repeat unfold 2 @{ a'4 b c @}
558 Unfold repeats can be made with alternate endings.
560 @lilypond[verbatim,quote,relative=2]
561 \repeat unfold 2 { c4 d e f }
569 If there are more repeats than there are alternate endings, the first
570 alternative is applied multiple times until the remaining alternatives
571 make up the total number of repeats.
573 @lilypond[verbatim,quote,relative=2]
574 \repeat unfold 4 { c4 d e f }
583 If there are more alternate endings than repeats then only the first
584 alternatives are applied. The remaining alternatives will be ignored
587 @lilypond[verbatim,quote,relative=2]
588 \repeat unfold 2 { c4 d e f }
597 It is also possible to nest multiple @code{unfold} functions (with or
598 without alternate endings).
600 @lilypond[verbatim,quote,relative=2]
602 \repeat unfold 2 { c4 d e f }
611 Chord constructs can be repeated by the chord repetition symbol
612 @code{q}. See @ref{Chord repetition}.
614 @warning{If you include @code{@bs{}relative} inside a @code{@bs{}repeat}
615 without explicitly instantiating the @code{Voice} context, extra
616 (unwanted) staves will appear. See @rprogram{An extra staff appears}.}
620 @ref{Chord repetition}.
626 @rinternals{RepeatedMusic},
627 @rinternals{UnfoldedRepeatedMusic}.
631 @subsection Short repeats
633 This section discusses how to input short repeats. Short repeats can
634 take two forms: slashes or percent signs to represent repeats of a
635 single note, a single measure or two measures, and tremolos otherwise.
642 @node Percent repeats
643 @unnumberedsubsubsec Percent repeats
645 @cindex percent repeats
646 @cindex measure repeats
647 @cindex repeat, percent
648 @cindex repeat, measure
649 @cindex repeat, short
650 @funindex \repeat percent
653 Repeated short patterns are printed once, and the repeated pattern
654 is replaced with a special sign.
659 \repeat percent @var{number} @var{musicexpr}
663 where @code{@var{musicexpr}} is a music expression.
665 Patterns that are shorter than one measure are replaced by slashes.
667 @lilypond[verbatim,quote,relative=2]
668 \repeat percent 4 { c128 d e f }
669 \repeat percent 4 { c64 d e f }
670 \repeat percent 5 { c32 d e f }
671 \repeat percent 4 { c16 d e f }
672 \repeat percent 4 { c8 d }
673 \repeat percent 4 { c4 }
674 \repeat percent 2 { c2 }
677 Patterns of one or two measures are replaced by percent-like symbols.
679 @lilypond[verbatim,quote,relative=2]
680 \repeat percent 2 { c4 d e f }
681 \repeat percent 2 { c2 d }
682 \repeat percent 2 { c1 }
685 @lilypond[verbatim,quote,relative=2]
686 \repeat percent 3 { c4 d e f | c2 g' }
689 Patterns that are shorter than one measure but contain mixed durations
690 use a double-percent symbol.
692 @lilypond[verbatim,quote,relative=2]
693 \repeat percent 4 { c8. <d f>16 }
694 \repeat percent 2 { \tuplet 3/2 { r8 c d } e4 }
699 @lilypondfile[verbatim,quote,texidoc,doctitle]
700 {percent-repeat-counter.ly}
702 @lilypondfile[verbatim,quote,texidoc,doctitle]
703 {percent-repeat-count-visibility.ly}
705 @lilypondfile[verbatim,quote,texidoc,doctitle]
706 {isolated-percent-repeats.ly}
710 @rglos{percent repeat},
717 @rinternals{RepeatSlash},
718 @rinternals{RepeatSlashEvent},
719 @rinternals{DoubleRepeatSlash},
720 @rinternals{PercentRepeat},
721 @rinternals{PercentRepeatCounter},
722 @rinternals{PercentRepeatedMusic},
723 @rinternals{Percent_repeat_engraver},
724 @rinternals{DoublePercentEvent},
725 @rinternals{DoublePercentRepeat},
726 @rinternals{DoublePercentRepeatCounter},
727 @rinternals{Double_percent_repeat_engraver},
728 @rinternals{Slash_repeat_engraver}.
731 @node Tremolo repeats
732 @unnumberedsubsubsec Tremolo repeats
734 @cindex tremolo beams
736 @cindex repeat, tremolo
737 @funindex \repeat tremolo
740 Tremolos can take two forms: alternation between two chords or two
741 notes, and rapid repetition of a single note or chord. Tremolos
742 consisting of an alternation are indicated by adding beams between the
743 notes or chords being alternated, while tremolos consisting of the
744 rapid repetition of a single note are indicated by adding beams or
745 slashes to a single note.
747 To place tremolo marks between notes, use @code{\repeat} with
750 @lilypond[quote,verbatim,relative=2]
751 \repeat tremolo 8 { c16 d }
752 \repeat tremolo 6 { c16 d }
753 \repeat tremolo 2 { c16 d }
756 The @code{\repeat tremolo} syntax expects exactly two notes within
757 the braces, and the number of repetitions must correspond to a
758 note value that can be expressed with plain or dotted notes. Thus,
759 @code{\repeat tremolo 7} is valid and produces a double dotted
760 note, but @code{\repeat tremolo 9} is not.
762 The duration of the tremolo equals the duration of the
763 braced expression multiplied by the number of repeats:
764 @code{\repeat tremolo 8 @{ c16 d16 @}} gives a whole note tremolo,
765 notated as two whole notes joined by tremolo beams.
767 There are two ways to put tremolo marks on a single note. The
768 @code{\repeat tremolo} syntax is also used here, in which case
769 the note should not be surrounded by braces:
771 @lilypond[quote,verbatim,ragged-right]
772 \repeat tremolo 4 c'16
775 @cindex tremolo marks
778 The same output can be obtained by adding @code{:@var{N}} after
779 the note, where @code{@var{N}} indicates the duration of the
780 subdivision (it must be at least 8). If @code{@var{N}} is 8, one
781 beam is added to the note's stem. If @code{@var{N}} is omitted,
782 the last value is used:
784 @lilypond[quote,verbatim,relative=2]
791 @lilypondfile[verbatim,quote,texidoc,doctitle]
792 {cross-staff-tremolos.ly}
798 @cindex tremolo, cross-staff
799 @cindex cross-staff tremolo