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 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 @code{@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 Multiple repeats with 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 there are two or more alternatives, nothing should appear
148 between the closing brace of one and the opening brace of the next
149 in an @code{@bs{}alternative} block, otherwise you will not get the
150 expected number of endings.}
152 @warning{If you include @code{@bs{}relative} inside a
153 @code{@bs{}repeat} without explicitly instantiating the
154 @code{Voice} context, extra (unwanted) staves will appear. See
155 @rprogram{An extra staff appears}.}
157 @cindex repeat with upbeat
158 @cindex upbeat in a repeat
159 @cindex anacrusis in a repeat
160 @cindex repeat with anacrusis
161 @cindex repeat with pickup
162 @cindex pickup in a repeat
165 If a repeat starts in the middle of a measure and has no alternate
166 endings, normally the end of the repeat will also fall in the
167 middle of a measure, so that the two ends add up to one complete
168 measure. In such cases, the repeat signs do not constitute true
169 bar lines. Do not use @code{\partial} commands or bar checks
170 where these repeat signs are printed:
172 @lilypond[verbatim,quote,relative=1]
174 c4 e g % no bar check here
180 g4 g g % no bar check here
188 Similarly, if a repeat begins with the initial partial measure of
189 a score and has no alternate endings, the same conditions apply as
190 in the above example, except that in this case the @code{\partial}
191 command is required at the beginning of the score:
193 @lilypond[verbatim,quote,relative=1]
194 \partial 4 % required
199 g4 g g % no bar check here
207 When alternate endings are added to a repeat that begins with an
208 incomplete measure, it becomes necessary to set the
209 @code{Timing.measureLength} context property manually, in the
210 following specific places:
214 at the start of any incomplete measures in the @code{\alternative}
215 block, which normally occur at the end of each alternative, except
216 (in most cases) the last.
219 at the start of each alternative, except the first.
222 @lilypond[verbatim,quote,relative=1]
224 \repeat volta 2 { e4 | c2 e | }
228 \set Timing.measureLength = #(ly:make-moment 3/4)
229 g4 g g % optional bar check is allowed here
232 \set Timing.measureLength = #(ly:make-moment 4/4)
239 The @code{measureLength} property is described in @ref{Time
242 @cindex repeats, with ties
243 @cindex alternative endings, with ties
244 @cindex ties, in repeats
245 @cindex ties, alternative endings
248 Ties may be added to a second ending:
250 @lilypond[verbatim,quote,relative=2]
252 \repeat volta 2 { c4 d e f~ }
259 @funindex \inStaffSegno
260 @cindex repeats, with segno
261 @cindex segno, with repeats
263 The @code{\inStaffSegno} command can be used to generate a composite
264 bar line incorporating the segno symbol with the appropriate repeat
265 bar line when used with the @code{\repeat volta} command. The
266 correct type of repeat bar line, viz. start repeat, end repeat or
267 double repeat, is selected automatically. Note that the
268 corresponding @qq{D.S.} mark must be added manually.
272 @lilypond[verbatim,quote,relative=1]
279 At the start of a repeat:
281 @lilypond[verbatim,quote,relative=1]
284 \inStaffSegno % start repeat
290 At the end of a repeat:
292 @lilypond[verbatim,quote,relative=1]
296 \inStaffSegno % end repeat
304 @lilypond[verbatim,quote,relative=1]
309 \inStaffSegno % double repeat
316 Alternative bar line symbols can be obtained by setting (in the Score
317 context) the properties @code{segnoType}, @code{startRepeatSegnoType},
318 @code{endRepeatSegnoType} or @code{doubleRepeatSegnoType} to the
319 required bar line type. The alternative bar line types must be
320 selected from the pre-defined types or types previously defined
321 with the @code{\defineBarLine} command (see @ref{Bar lines}).
323 @lilypond[verbatim,quote,relative=1]
324 \defineBarLine ":|.S[" #'(":|." "S[" "")
325 \defineBarLine "]" #'("]" "" "")
329 \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}.
367 @rinternals{VoltaBracket},
368 @rinternals{RepeatedMusic},
369 @rinternals{VoltaRepeatedMusic},
370 @rinternals{UnfoldedRepeatedMusic}.
373 @cindex repeat, ambiguous
374 @cindex nested repeat
375 @cindex repeat, nested
376 @cindex repeat timing information
377 @cindex repeat and measure number
378 @cindex timing information and repeats
379 @cindex measure number and repeats
380 @cindex repeats and slur
381 @cindex slur and repeats
382 @cindex glissandi and repeats
383 @cindex repeats and glissandi
385 Slurs that span from a @code{\repeat} block into an
386 @code{\alternative} block will only work for the first alternative
387 ending. The visual appearance of a continuing slur in other
388 alternative blocks may be simulated with @code{\repeatTie} if the
389 slur extends into only one note in the alternative block, although
390 this method does not work in @code{TabStaff}. Other methods which
391 may be tailored to indicate continuing slurs over several notes in
392 alternative blocks, and which also work in @code{TabStaff} contexts,
393 are shown in @ref{Modifying ties and slurs}.
395 Also, slurs cannot wrap around from the end of one
396 alternative back to the beginning of the repeat.
398 Glissandi that span from a @code{\repeat} block into an
399 @code{\alternative} block will only work for the first alternative
400 ending. The visual appearance of a continuing glissando in other
401 alternative blocks may be indicated by coding a glissando starting
402 on a hidden grace note. For an example, see
403 @qq{Extending glissandi across repeats} under Selected Snippets
406 If a repeat that begins with an incomplete measure has an
407 @code{\alternative} block that contains modifications to the
408 @code{measureLength} property, using @code{\unfoldRepeats} will
409 result in wrongly-placed bar lines and bar check warnings.
420 is ambiguous, since it is not clear to which @code{\repeat} the
421 @code{\alternative} belongs. This ambiguity is resolved by always
422 having the @code{\alternative} belong to the inner @code{\repeat}.
423 For clarity, it is advisable to use braces in such situations.
426 @node Manual repeat marks
427 @unnumberedsubsubsec Manual repeat marks
429 @cindex manual repeat mark
430 @cindex repeat, manual
432 @cindex repeat, start
435 @cindex repeat number, changing
436 @cindex repeat volta, changing
437 @cindex volta bracket
438 @cindex bracket, volta
439 @funindex repeatCommands
440 @funindex start-repeat
442 @warning{These methods are only used for displaying unusual repeat
443 constructs, and may produce unexpected behavior. In most cases,
444 repeats should be created using the standard @code{@bs{}repeat} command
445 or by printing the relevant bar lines. For more information, see
448 The property @code{repeatCommands} can be used to control the
449 layout of repeats. Its value is a Scheme list of repeat commands.
453 Print a @code{.|:} bar line.
455 @lilypond[verbatim,quote,relative=2]
457 \set Score.repeatCommands = #'(start-repeat)
462 As per standard engraving practice, repeat signs are not printed
463 at the beginning of a piece.
466 Print a @code{:|.} bar line:
468 @lilypond[verbatim,quote,relative=2]
471 \set Score.repeatCommands = #'(end-repeat)
475 @item (volta @var{number}) @dots{} (volta #f)
476 Create a new volta with the specified number. The volta bracket must
477 be explicitly terminated, or it will not be printed.
479 @lilypond[verbatim,quote,relative=2]
481 \set Score.repeatCommands = #'((volta "2"))
483 \set Score.repeatCommands = #'((volta #f))
489 Multiple repeat commands may occur at the same point:
491 @lilypond[verbatim,quote,relative=2]
493 \set Score.repeatCommands = #'((volta "2, 5") end-repeat)
496 \set Score.repeatCommands = #'((volta #f) (volta "95") end-repeat)
498 \set Score.repeatCommands = #'((volta #f))
501 @cindex volta bracket with text
502 @cindex text in volta bracket
504 Text can be included with the volta bracket. The text can be a
505 number or numbers or markup text, see @ref{Formatting text}. The
506 simplest way to use markup text is to define the markup first,
507 then include the markup in a Scheme list.
509 @lilypond[verbatim,quote]
510 voltaAdLib = \markup { 1. 2. 3... \text \italic { ad lib. } }
513 \set Score.repeatCommands =
514 #(list(list 'volta voltaAdLib) 'start-repeat)
516 \set Score.repeatCommands = #'((volta #f) (volta "4.") end-repeat)
518 \set Score.repeatCommands = #'((volta #f))
525 @lilypondfile[verbatim,quote,texidoc,doctitle]
526 {printing-a-repeat-sign-at-the-beginning-of-a-piece.ly}
531 @ref{Formatting text}.
537 @rinternals{VoltaBracket},
538 @rinternals{RepeatedMusic},
539 @rinternals{VoltaRepeatedMusic}.
542 @node Written-out repeats
543 @unnumberedsubsubsec Written-out repeats
545 @cindex written-out repeats
546 @cindex repeats, written-out
547 @cindex repeats, unfold
548 @cindex repeats, alternative
549 @cindex unfold repeat
550 @cindex unfold repeat, alternate endings
551 @cindex alternate repeats
552 @cindex alternate endings, repeats
555 By using the @code{unfold} command, repeats can be used to simplify the
556 writing out of repetitious music. The syntax is
559 \repeat unfold @var{repeatcount} @var{musicexpr}
563 where @code{@var{musicexpr}} is a music expression and
564 @code{@var{repeatcount}} is the number of times
565 @code{@var{musicexpr}} is repeated.
567 @lilypond[verbatim,quote,relative=2]
568 \repeat unfold 2 { c4 d e f }
572 In some cases, especially in a @code{\relative} context, the
573 @code{\repeat unfold} function is not the same as writing out the
574 music expression multiple times. E.g,
577 \repeat unfold 2 @{ a'4 b c @}
586 Unfold repeats can be made with alternate endings.
588 @lilypond[verbatim,quote,relative=2]
589 \repeat unfold 2 { c4 d e f }
597 If there are more repeats than there are alternate endings, the first
598 alternative is applied multiple times until the remaining alternatives
599 make up the total number of repeats.
601 @lilypond[verbatim,quote,relative=2]
602 \repeat unfold 4 { c4 d e f }
611 If there are more alternate endings than repeats then only the first
612 alternatives are applied. The remaining alternatives will be ignored
615 @lilypond[verbatim,quote,relative=2]
616 \repeat unfold 2 { c4 d e f }
625 It is also possible to nest multiple @code{unfold} functions (with or
626 without alternate endings).
628 @lilypond[verbatim,quote,relative=2]
630 \repeat unfold 2 { c4 d e f }
639 Chord constructs can be repeated by the chord repetition symbol
640 @code{q}. See @ref{Chord repetition}.
642 @warning{If you include @code{@bs{}relative} inside a @code{@bs{}repeat}
643 without explicitly instantiating the @code{Voice} context, extra
644 (unwanted) staves will appear. See @rprogram{An extra staff appears}.}
648 @ref{Chord repetition}.
654 @rinternals{RepeatedMusic},
655 @rinternals{UnfoldedRepeatedMusic}.
659 @subsection Short repeats
661 This section discusses how to input short repeats. Short repeats can
662 take two forms: slashes or percent signs to represent repeats of a
663 single note, a single measure or two measures, and tremolos otherwise.
670 @node Percent repeats
671 @unnumberedsubsubsec Percent repeats
673 @cindex percent repeats
674 @cindex measure repeats
675 @cindex repeat, percent
676 @cindex repeat, measure
677 @cindex repeat, short
678 @funindex \repeat percent
681 Repeated short patterns are printed once, and the repeated pattern
682 is replaced with a special sign.
687 \repeat percent @var{number} @var{musicexpr}
691 where @code{@var{musicexpr}} is a music expression.
693 Patterns that are shorter than one measure are replaced by slashes.
695 @lilypond[verbatim,quote,relative=2]
696 \repeat percent 4 { c128 d e f }
697 \repeat percent 4 { c64 d e f }
698 \repeat percent 5 { c32 d e f }
699 \repeat percent 4 { c16 d e f }
700 \repeat percent 4 { c8 d }
701 \repeat percent 4 { c4 }
702 \repeat percent 2 { c2 }
705 Patterns of one or two measures are replaced by percent-like symbols.
707 @lilypond[verbatim,quote,relative=2]
708 \repeat percent 2 { c4 d e f }
709 \repeat percent 2 { c2 d }
710 \repeat percent 2 { c1 }
713 @lilypond[verbatim,quote,relative=2]
714 \repeat percent 3 { c4 d e f | c2 g' }
717 Patterns that are shorter than one measure but contain mixed durations
718 use a double-percent symbol.
720 @lilypond[verbatim,quote,relative=2]
721 \repeat percent 4 { c8. <d f>16 }
722 \repeat percent 2 { \tuplet 3/2 { r8 c d } e4 }
727 @lilypondfile[verbatim,quote,texidoc,doctitle]
728 {percent-repeat-counter.ly}
730 @lilypondfile[verbatim,quote,texidoc,doctitle]
731 {percent-repeat-count-visibility.ly}
733 @lilypondfile[verbatim,quote,texidoc,doctitle]
734 {isolated-percent-repeats.ly}
738 @rglos{percent repeat},
745 @rinternals{RepeatSlash},
746 @rinternals{RepeatSlashEvent},
747 @rinternals{DoubleRepeatSlash},
748 @rinternals{PercentRepeat},
749 @rinternals{PercentRepeatCounter},
750 @rinternals{PercentRepeatedMusic},
751 @rinternals{Percent_repeat_engraver},
752 @rinternals{DoublePercentEvent},
753 @rinternals{DoublePercentRepeat},
754 @rinternals{DoublePercentRepeatCounter},
755 @rinternals{Double_percent_repeat_engraver},
756 @rinternals{Slash_repeat_engraver}.
759 @node Tremolo repeats
760 @unnumberedsubsubsec Tremolo repeats
762 @cindex tremolo beams
764 @cindex repeat, tremolo
765 @funindex \repeat tremolo
768 Tremolos can take two forms: alternation between two chords or two
769 notes, and rapid repetition of a single note or chord. Tremolos
770 consisting of an alternation are indicated by adding beams between the
771 notes or chords being alternated, while tremolos consisting of the
772 rapid repetition of a single note are indicated by adding beams or
773 slashes to a single note.
775 To place tremolo marks between notes, use @code{\repeat} with
778 @lilypond[quote,verbatim,relative=2]
779 \repeat tremolo 8 { c16 d }
780 \repeat tremolo 6 { c16 d }
781 \repeat tremolo 2 { c16 d }
784 The @code{\repeat tremolo} syntax expects exactly two notes within
785 the braces, and the number of repetitions must correspond to a
786 note value that can be expressed with plain or dotted notes. Thus,
787 @code{\repeat tremolo 7} is valid and produces a double dotted
788 note, but @code{\repeat tremolo 9} is not.
790 The duration of the tremolo equals the duration of the
791 braced expression multiplied by the number of repeats:
792 @code{\repeat tremolo 8 @{ c16 d16 @}} gives a whole note tremolo,
793 notated as two whole notes joined by tremolo beams.
795 There are two ways to put tremolo marks on a single note. The
796 @code{\repeat tremolo} syntax is also used here, in which case
797 the note should not be surrounded by braces:
799 @lilypond[quote,verbatim,ragged-right]
800 \repeat tremolo 4 c'16
803 @cindex tremolo marks
804 @funindex tremoloFlags
807 The same output can be obtained by adding @code{:@var{N}} after
808 the note, where @code{@var{N}} indicates the duration of the
809 subdivision (it must be at least 8). If @code{@var{N}} is 8, one
810 beam is added to the note's stem. If @code{@var{N}} is omitted,
811 the last value (stored in @code{tremoloFlags}) is used:
813 @lilypond[quote,verbatim,relative=2]
820 @lilypondfile[verbatim,quote,texidoc,doctitle]
821 {cross-staff-tremolos.ly}
827 @cindex tremolo, cross-staff
828 @cindex cross-staff tremolo