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]
93 \repeat volta 2 { c''4 d e f }
95 \repeat volta 2 { d4 e f g }
99 An @q{opening} repeat mark is not, by default, printed in the first full
100 measure. However it is possible to add one by using @code{\bar ".|:"}
101 before the first note.
103 @lilypond[verbatim,fragment,quote]
105 \repeat volta 2 { \bar ".|:" c''4 d e f }
107 \repeat volta 2 { d4 e f g }
111 Alternative endings can be produced using @code{\alternative}. Each
112 group of alternatives must be themselves, enclosed in a set of braces.
115 \repeat volta @var{repeatcount} @var{musicexpr}
117 @{ @var{musicexpr} @}
122 where @code{@var{musicexpr}} is a music expression.
124 If there are more repeats than there are alternate endings, the earliest
125 repeats are given the first alternative.
127 A single repeat with one alternate ending:
129 @lilypond[verbatim,quote]
131 \repeat volta 2 { c''4 d e f | }
140 Multiple repeats with one alternate ending:
142 @lilypond[verbatim,quote]
144 \repeat volta 4 { c''4 d e f | }
153 Multiple repeats with more than one alternate ending:
155 @lilypond[verbatim,quote]
157 \repeat volta 3 { c''4 d e f | }
167 @warning{If there are two or more alternatives, nothing should appear
168 between the closing brace of one and the opening brace of the next
169 in an @code{@bs{}alternative} block, otherwise you will not get the
170 expected number of endings.}
172 @warning{If you include @code{@bs{}relative} inside a
173 @code{@bs{}repeat} without explicitly instantiating the
174 @code{Voice} context, extra (unwanted) staves will appear. See
175 @rprogram{An extra staff appears}.}
177 @cindex repeat with upbeat
178 @cindex upbeat in a repeat
179 @cindex anacrusis in a repeat
180 @cindex repeat with anacrusis
181 @cindex repeat with pickup
182 @cindex pickup in a repeat
185 If a repeat starts in the middle of a measure and has no alternate
186 endings, normally the end of the repeat will also fall in the
187 middle of a measure, so that the two ends add up to one complete
188 measure. In such cases, the repeat signs do not constitute true
189 bar lines. Do not use @code{\partial} commands or bar checks
190 where these repeat signs are printed:
192 @lilypond[verbatim,quote]
193 \relative { % no \partial here
194 c'4 e g % no bar check here
200 g4 g g % no bar check here
209 Similarly, if a repeat begins with the initial partial measure of
210 a score and has no alternate endings, the same conditions apply as
211 in the above example, except that in this case the @code{\partial}
212 command is required at the beginning of the score:
214 @lilypond[verbatim,quote]
216 \partial 4 % required
221 g4 g g % no bar check here
230 @cindex repeats, with ties
231 @cindex alternative endings, with ties
232 @cindex ties, in repeats
233 @cindex ties, alternative endings
236 Ties may be added to a second ending:
238 @lilypond[verbatim,quote]
241 \repeat volta 2 { c4 d e f~ }
249 @funindex \inStaffSegno
250 @cindex repeats, with segno
251 @cindex segno, with repeats
253 The @code{\inStaffSegno} command can be used to generate a composite
254 bar line incorporating the segno symbol with the appropriate repeat
255 bar line when used with the @code{\repeat volta} command. The
256 correct type of repeat bar line, viz. start repeat, end repeat or
257 double repeat, is selected automatically. Note that the
258 corresponding @qq{D.S.} mark must be added manually.
262 @lilypond[verbatim,quote]
271 At the start of a repeat:
273 @lilypond[verbatim,quote]
277 \inStaffSegno % start repeat
284 At the end of a repeat:
286 @lilypond[verbatim,quote]
291 \inStaffSegno % end repeat
300 @lilypond[verbatim,quote]
306 \inStaffSegno % double repeat
314 Alternative bar line symbols can be obtained by setting (in the Score
315 context) the properties @code{segnoType}, @code{startRepeatSegnoType},
316 @code{endRepeatSegnoType} or @code{doubleRepeatSegnoType} to the
317 required bar line type. The alternative bar line types must be
318 selected from the pre-defined types or types previously defined
319 with the @code{\defineBarLine} command (see @ref{Bar lines}).
321 @lilypond[verbatim,quote]
322 \defineBarLine ":|.S[" #'(":|." "S[" "")
323 \defineBarLine "]" #'("]" "" "")
328 \once \set Score.endRepeatSegnoType = ":|.S["
337 @lilypondfile[verbatim,quote,texidoc,doctitle]
338 {shortening-volta-brackets.ly}
340 @lilypondfile[verbatim,quote,texidoc,doctitle]
341 {adding-volta-brackets-to-additional-staves.ly}
343 @lilypondfile[verbatim,quote,texidoc,doctitle]
344 {setting-the-double-repeat-default-for-volte.ly}
346 @cindex repeats, bar numbers letters
347 @cindex repeats, alternative bar numbers
349 @lilypondfile[verbatim,quote,texidoc,doctitle]
350 {alternative-bar-numbering.ly}
359 @ref{Modifying context plug-ins},
360 @ref{Modifying ties and slurs},
361 @ref{Time administration}.
364 @file{ly/engraver-init.ly}.
370 @rinternals{VoltaBracket},
371 @rinternals{RepeatedMusic},
372 @rinternals{VoltaRepeatedMusic},
373 @rinternals{UnfoldedRepeatedMusic}.
376 @cindex repeat, ambiguous
377 @cindex nested repeat
378 @cindex repeat, nested
379 @cindex repeat timing information
380 @cindex repeat and measure number
381 @cindex timing information and repeats
382 @cindex measure number and repeats
383 @cindex repeats and slur
384 @cindex slur and repeats
385 @cindex glissandi and repeats
386 @cindex repeats and glissandi
388 Slurs that span from a @code{\repeat} block into an
389 @code{\alternative} block will only work for the first alternative
390 ending. The visual appearance of a continuing slur in other
391 alternative blocks may be simulated with @code{\repeatTie} if the
392 slur extends into only one note in the alternative block, although
393 this method does not work in @code{TabStaff}. Other methods which
394 may be tailored to indicate continuing slurs over several notes in
395 alternative blocks, and which also work in @code{TabStaff} contexts,
396 are shown in @ref{Modifying ties and slurs}.
398 Also, slurs cannot wrap around from the end of one
399 alternative back to the beginning of the repeat.
401 Glissandi that span from a @code{\repeat} block into an
402 @code{\alternative} block will only work for the first alternative
403 ending. The visual appearance of a continuing glissando in other
404 alternative blocks may be indicated by coding a glissando starting
405 on a hidden grace note. For an example, see
406 @qq{Extending glissandi across repeats} under Selected Snippets
409 If a repeat that begins with an incomplete measure has an
410 @code{\alternative} block that contains modifications to the
411 @code{measureLength} property, using @code{\unfoldRepeats} will
412 result in wrongly-placed bar lines and bar check warnings.
423 is ambiguous, since it is not clear to which @code{\repeat} the
424 @code{\alternative} belongs. This ambiguity is resolved by always
425 having the @code{\alternative} belong to the inner @code{\repeat}.
426 For clarity, it is advisable to use braces in such situations.
429 @node Manual repeat marks
430 @unnumberedsubsubsec Manual repeat marks
432 @cindex manual repeat mark
433 @cindex repeat, manual
435 @cindex repeat, start
438 @cindex repeat number, changing
439 @cindex repeat volta, changing
440 @cindex volta bracket
441 @cindex bracket, volta
442 @funindex repeatCommands
443 @funindex start-repeat
445 @warning{These methods are only used for displaying unusual repeat
446 constructs, and may produce unexpected behavior. In most cases,
447 repeats should be created using the standard @code{@bs{}repeat} command
448 or by printing the relevant bar lines. For more information, see
451 The property @code{repeatCommands} can be used to control the
452 layout of repeats. Its value is a Scheme list of repeat commands.
456 Print a @code{.|:} bar line.
458 @lilypond[verbatim,quote]
461 \set Score.repeatCommands = #'(start-repeat)
467 As per standard engraving practice, repeat signs are not printed
468 at the beginning of a piece.
471 Print a @code{:|.} bar line:
473 @lilypond[verbatim,quote]
477 \set Score.repeatCommands = #'(end-repeat)
482 @item (volta @var{number}) @dots{} (volta #f)
483 Create a new volta with the specified number. The volta bracket must
484 be explicitly terminated, or it will not be printed.
486 @lilypond[verbatim,quote]
489 \set Score.repeatCommands = #'((volta "2"))
491 \set Score.repeatCommands = #'((volta #f))
498 Multiple repeat commands may occur at the same point:
500 @lilypond[verbatim,quote]
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))
512 @cindex volta bracket with text
513 @cindex text in volta bracket
515 Text can be included with the volta bracket. The text can be a
516 number or numbers or markup text, see @ref{Formatting text}. The
517 simplest way to use markup text is to define the markup first,
518 then include the markup in a Scheme list.
520 @lilypond[verbatim,quote]
521 voltaAdLib = \markup { 1. 2. 3... \text \italic { ad lib. } }
524 \set Score.repeatCommands =
525 #(list(list 'volta voltaAdLib) 'start-repeat)
527 \set Score.repeatCommands = #'((volta #f) (volta "4.") end-repeat)
529 \set Score.repeatCommands = #'((volta #f))
536 @ref{Formatting text}.
542 @rinternals{VoltaBracket},
543 @rinternals{RepeatedMusic},
544 @rinternals{VoltaRepeatedMusic}.
547 @node Written-out repeats
548 @unnumberedsubsubsec Written-out repeats
550 @cindex written-out repeats
551 @cindex repeats, written-out
552 @cindex repeats, unfold
553 @cindex repeats, alternative
554 @cindex unfold repeat
555 @cindex unfold repeat, alternate endings
556 @cindex alternate repeats
557 @cindex alternate endings, repeats
560 By using the @code{unfold} command, repeats can be used to simplify the
561 writing out of repetitious music. The syntax is
564 \repeat unfold @var{repeatcount} @var{musicexpr}
568 where @code{@var{musicexpr}} is a music expression and
569 @code{@var{repeatcount}} is the number of times
570 @code{@var{musicexpr}} is repeated.
572 @lilypond[verbatim,quote]
574 \repeat unfold 2 { c''4 d e f }
579 In some cases, especially in a @code{\relative} context, the
580 @code{\repeat unfold} function is not the same as writing out the
581 music expression multiple times. E.g,
584 \repeat unfold 2 @{ a'4 b c @}
593 Unfold repeats can be made with alternate endings.
595 @lilypond[verbatim,quote]
597 \repeat unfold 2 { c''4 d e f }
606 If there are more repeats than there are alternate endings, the first
607 alternative is applied multiple times until the remaining alternatives
608 make up the total number of repeats.
610 @lilypond[verbatim,quote]
612 \repeat unfold 4 { c''4 d e f }
622 If there are more alternate endings than repeats then only the first
623 alternatives are applied. The remaining alternatives will be ignored
626 @lilypond[verbatim,quote]
628 \repeat unfold 2 { c''4 d e f }
638 It is also possible to nest multiple @code{unfold} functions (with or
639 without alternate endings).
641 @lilypond[verbatim,quote]
644 \repeat unfold 2 { c''4 d e f }
654 Chord constructs can be repeated by the chord repetition symbol
655 @code{q}. See @ref{Chord repetition}.
657 @warning{If you include @code{@bs{}relative} inside a @code{@bs{}repeat}
658 without explicitly instantiating the @code{Voice} context, extra
659 (unwanted) staves will appear. See @rprogram{An extra staff appears}.}
663 @ref{Chord repetition}.
669 @rinternals{RepeatedMusic},
670 @rinternals{UnfoldedRepeatedMusic}.
674 @subsection Short repeats
676 This section discusses how to input short repeats. Short repeats can
677 take two forms: slashes or percent signs to represent repeats of a
678 single note, a single measure or two measures, and tremolos otherwise.
685 @node Percent repeats
686 @unnumberedsubsubsec Percent repeats
688 @cindex percent repeats
689 @cindex measure repeats
690 @cindex repeat, percent
691 @cindex repeat, measure
692 @cindex repeat, short
693 @funindex \repeat percent
696 Repeated short patterns are printed once, and the repeated pattern
697 is replaced with a special sign.
702 \repeat percent @var{number} @var{musicexpr}
706 where @code{@var{musicexpr}} is a music expression.
708 Patterns that are shorter than one measure are replaced by slashes.
710 @lilypond[verbatim,quote]
712 \repeat percent 4 { c128 d e f }
713 \repeat percent 4 { c64 d e f }
714 \repeat percent 5 { c32 d e f }
715 \repeat percent 4 { c16 d e f }
716 \repeat percent 4 { c8 d }
717 \repeat percent 4 { c4 }
718 \repeat percent 2 { c2 }
722 Patterns of one or two measures are replaced by percent-like symbols.
724 @lilypond[verbatim,quote]
726 \repeat percent 2 { c4 d e f }
727 \repeat percent 2 { c2 d }
728 \repeat percent 2 { c1 }
732 @lilypond[verbatim,quote]
734 \repeat percent 3 { c''4 d e f | c2 g' }
738 Patterns that are shorter than one measure but contain mixed durations
739 use a double-percent symbol.
741 @lilypond[verbatim,quote]
743 \repeat percent 4 { c''8. <d f>16 }
744 \repeat percent 2 { \tuplet 3/2 { r8 c d } e4 }
750 @lilypondfile[verbatim,quote,texidoc,doctitle]
751 {percent-repeat-counter.ly}
753 @lilypondfile[verbatim,quote,texidoc,doctitle]
754 {percent-repeat-count-visibility.ly}
756 @lilypondfile[verbatim,quote,texidoc,doctitle]
757 {isolated-percent-repeats.ly}
761 @rglos{percent repeat},
768 @rinternals{RepeatSlash},
769 @rinternals{RepeatSlashEvent},
770 @rinternals{DoubleRepeatSlash},
771 @rinternals{PercentRepeat},
772 @rinternals{PercentRepeatCounter},
773 @rinternals{PercentRepeatedMusic},
774 @rinternals{Percent_repeat_engraver},
775 @rinternals{DoublePercentEvent},
776 @rinternals{DoublePercentRepeat},
777 @rinternals{DoublePercentRepeatCounter},
778 @rinternals{Double_percent_repeat_engraver},
779 @rinternals{Slash_repeat_engraver}.
782 Percent repeats will not contain anything else apart from the percent
783 sign itself; in particular, timing changes will not be repeated.
785 @lilypond[quote,verbatim,relative=2]
786 \repeat percent 3 { \time 5/4 c2. 2 \time 4/4 2 2 }
790 Any meter changes or @code{\partial} commands need to occur in parallel
791 passages @emph{outside} of any percent repeat, e.g in a separate
794 @lilypond[quote,verbatim,relative=2]
796 \repeat percent 3 { c2. 2 2 2 }
797 \repeat unfold 3 { \time 5/4 s4*5 \time 4/4 s1 }
802 @node Tremolo repeats
803 @unnumberedsubsubsec Tremolo repeats
805 @cindex tremolo beams
807 @cindex repeat, tremolo
808 @funindex \repeat tremolo
811 Tremolos can take two forms: alternation between two chords or two
812 notes, and rapid repetition of a single note or chord. Tremolos
813 consisting of an alternation are indicated by adding beams between the
814 notes or chords being alternated, while tremolos consisting of the
815 rapid repetition of a single note are indicated by adding beams or
816 slashes to a single note.
818 To place tremolo marks between notes, use @code{\repeat} with
821 @lilypond[quote,verbatim]
823 \repeat tremolo 8 { c16 d }
824 \repeat tremolo 6 { c16 d }
825 \repeat tremolo 2 { c16 d }
829 The @code{\repeat tremolo} syntax expects exactly two notes within
830 the braces, and the number of repetitions must correspond to a
831 note value that can be expressed with plain or dotted notes. Thus,
832 @code{\repeat tremolo 7} is valid and produces a double dotted
833 note, but @code{\repeat tremolo 9} is not.
835 The duration of the tremolo equals the duration of the
836 braced expression multiplied by the number of repeats:
837 @code{\repeat tremolo 8 @{ c16 d16 @}} gives a whole note tremolo,
838 notated as two whole notes joined by tremolo beams.
840 There are two ways to put tremolo marks on a single note. The
841 @code{\repeat tremolo} syntax is also used here, in which case
842 the note should not be surrounded by braces:
844 @lilypond[quote,verbatim,ragged-right]
845 \repeat tremolo 4 c'16
848 @cindex tremolo marks
851 The same output can be obtained by adding @code{:@var{N}} after
852 the note, where @code{@var{N}} indicates the duration of the
853 subdivision (it must be at least 8). If @code{@var{N}} is 8, one
854 beam is added to the note's stem. If @code{@var{N}} is omitted,
855 the last value is used:
857 @lilypond[quote,verbatim]
866 @lilypondfile[verbatim,quote,texidoc,doctitle]
867 {cross-staff-tremolos.ly}
873 @cindex tremolo, cross-staff
874 @cindex cross-staff tremolo