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
184 @cindex bar checks with repeats
185 @cindex repeats with bar checks
187 If a repeat that has no alternate endings starts in the middle of a
188 measure, it will usually end at a corresponding place in the middle of a
189 later measure (so that the two ends add up to one complete measure). In
190 this case the repeat signs are not @q{true} bar lines so neither bar
191 checks nor @code{\partial} commands should be placed there:
193 @lilypond[verbatim,quote,relative=1]
205 If a repeat that has no alternate endings starts with a partial measure,
206 then the same principles apply, except that a @code{\partial} command is
207 required at the start of the measure:
209 @lilypond[verbatim,quote,relative=1]
221 @cindex repeats, with ties
222 @cindex alternative endings, with ties
223 @cindex ties, in repeats
224 @cindex ties, alternative endings
227 Ties may be added to a second ending:
229 @lilypond[verbatim,quote]
232 \repeat volta 2 { c4 d e f~ }
240 @funindex \inStaffSegno
241 @cindex repeats, with segno
242 @cindex segno, with repeats
244 The @code{\inStaffSegno} command can be used to generate a composite
245 bar line incorporating the segno symbol with the appropriate repeat
246 bar line when used with the @code{\repeat volta} command. The
247 correct type of repeat bar line, viz. start repeat, end repeat or
248 double repeat, is selected automatically. Note that the
249 corresponding @qq{D.S.} mark must be added manually.
253 @lilypond[verbatim,quote]
262 At the start of a repeat:
264 @lilypond[verbatim,quote]
268 \inStaffSegno % start repeat
275 At the end of a repeat:
277 @lilypond[verbatim,quote]
282 \inStaffSegno % end repeat
291 @lilypond[verbatim,quote]
297 \inStaffSegno % double repeat
305 Alternative bar line symbols can be obtained by setting (in the Score
306 context) the properties @code{segnoType}, @code{startRepeatSegnoType},
307 @code{endRepeatSegnoType} or @code{doubleRepeatSegnoType} to the
308 required bar line type. The alternative bar line types must be
309 selected from the pre-defined types or types previously defined
310 with the @code{\defineBarLine} command (see @ref{Bar lines}).
312 @lilypond[verbatim,quote]
313 \defineBarLine ":|.S[" #'(":|." "S[" "")
314 \defineBarLine "]" #'("]" "" "")
319 \once \set Score.endRepeatSegnoType = ":|.S["
328 @lilypondfile[verbatim,quote,texidoc,doctitle]
329 {shortening-volta-brackets.ly}
331 @lilypondfile[verbatim,quote,texidoc,doctitle]
332 {adding-volta-brackets-to-additional-staves.ly}
334 @lilypondfile[verbatim,quote,texidoc,doctitle]
335 {setting-the-double-repeat-default-for-volte.ly}
337 @cindex repeats, bar numbers letters
338 @cindex repeats, alternative bar numbers
340 @lilypondfile[verbatim,quote,texidoc,doctitle]
341 {alternative-bar-numbering.ly}
350 @ref{Modifying context plug-ins},
351 @ref{Modifying ties and slurs},
352 @ref{Time administration}.
355 @file{ly/engraver-init.ly}.
361 @rinternals{VoltaBracket},
362 @rinternals{RepeatedMusic},
363 @rinternals{VoltaRepeatedMusic},
364 @rinternals{UnfoldedRepeatedMusic}.
367 @cindex repeat, ambiguous
368 @cindex nested repeat
369 @cindex repeat, nested
370 @cindex repeat timing information
371 @cindex repeat and measure number
372 @cindex timing information and repeats
373 @cindex measure number and repeats
374 @cindex repeats and slur
375 @cindex slur and repeats
376 @cindex glissandi and repeats
377 @cindex repeats and glissandi
379 Slurs that span from a @code{\repeat} block into an
380 @code{\alternative} block will only work for the first alternative
381 ending. The visual appearance of a continuing slur in other
382 alternative blocks may be simulated with @code{\repeatTie} if the
383 slur extends into only one note in the alternative block, although
384 this method does not work in @code{TabStaff}. Other methods which
385 may be tailored to indicate continuing slurs over several notes in
386 alternative blocks, and which also work in @code{TabStaff} contexts,
387 are shown in @ref{Modifying ties and slurs}.
389 Also, slurs cannot wrap around from the end of one
390 alternative back to the beginning of the repeat.
392 Glissandi that span from a @code{\repeat} block into an
393 @code{\alternative} block will only work for the first alternative
394 ending. The visual appearance of a continuing glissando in other
395 alternative blocks may be indicated by coding a glissando starting
396 on a hidden grace note. For an example, see
397 @qq{Extending glissandi across repeats} under Selected Snippets
400 If a repeat that begins with an incomplete measure has an
401 @code{\alternative} block that contains modifications to the
402 @code{measureLength} property, using @code{\unfoldRepeats} will
403 result in wrongly-placed bar lines and bar check warnings.
414 is ambiguous, since it is not clear to which @code{\repeat} the
415 @code{\alternative} belongs. This ambiguity is resolved by always
416 having the @code{\alternative} belong to the inner @code{\repeat}.
417 For clarity, it is advisable to use braces in such situations.
420 @node Manual repeat marks
421 @unnumberedsubsubsec Manual repeat marks
423 @cindex manual repeat mark
424 @cindex repeat, manual
426 @cindex repeat, start
429 @cindex repeat number, changing
430 @cindex repeat volta, changing
431 @cindex volta bracket
432 @cindex bracket, volta
433 @funindex repeatCommands
434 @funindex start-repeat
436 @warning{These methods are only used for displaying unusual repeat
437 constructs, and may produce unexpected behavior. In most cases,
438 repeats should be created using the standard @code{@bs{}repeat} command
439 or by printing the relevant bar lines. For more information, see
442 The property @code{repeatCommands} can be used to control the
443 layout of repeats. Its value is a Scheme list of repeat commands.
447 Print a @code{.|:} bar line.
449 @lilypond[verbatim,quote]
452 \set Score.repeatCommands = #'(start-repeat)
458 As per standard engraving practice, repeat signs are not printed
459 at the beginning of a piece.
462 Print a @code{:|.} bar line:
464 @lilypond[verbatim,quote]
468 \set Score.repeatCommands = #'(end-repeat)
473 @item (volta @var{number}) @dots{} (volta #f)
474 Create a new volta with the specified number. The volta bracket must
475 be explicitly terminated, or it will not be printed.
477 @lilypond[verbatim,quote]
480 \set Score.repeatCommands = #'((volta "2"))
482 \set Score.repeatCommands = #'((volta #f))
489 Multiple repeat commands may occur at the same point:
491 @lilypond[verbatim,quote]
494 \set Score.repeatCommands = #'((volta "2, 5") end-repeat)
497 \set Score.repeatCommands = #'((volta #f) (volta "95") end-repeat)
499 \set Score.repeatCommands = #'((volta #f))
503 @cindex volta bracket with text
504 @cindex text in volta bracket
506 Text can be included with the volta bracket. The text can be a
507 number or numbers or markup text, see @ref{Formatting text}. The
508 simplest way to use markup text is to define the markup first,
509 then include the markup in a Scheme list.
511 @lilypond[verbatim,quote]
512 voltaAdLib = \markup { 1. 2. 3... \text \italic { ad lib. } }
515 \set Score.repeatCommands =
516 #(list(list 'volta voltaAdLib) 'start-repeat)
518 \set Score.repeatCommands = #'((volta #f) (volta "4.") end-repeat)
520 \set Score.repeatCommands = #'((volta #f))
527 @ref{Formatting text}.
533 @rinternals{VoltaBracket},
534 @rinternals{RepeatedMusic},
535 @rinternals{VoltaRepeatedMusic}.
538 @node Written-out repeats
539 @unnumberedsubsubsec Written-out repeats
541 @cindex written-out repeats
542 @cindex repeats, written-out
543 @cindex repeats, unfold
544 @cindex repeats, alternative
545 @cindex unfold repeat
546 @cindex unfold repeat, alternate endings
547 @cindex alternate repeats
548 @cindex alternate endings, repeats
551 By using the @code{unfold} command, repeats can be used to simplify the
552 writing out of repetitious music. The syntax is
555 \repeat unfold @var{repeatcount} @var{musicexpr}
559 where @code{@var{musicexpr}} is a music expression and
560 @code{@var{repeatcount}} is the number of times
561 @code{@var{musicexpr}} is repeated.
563 @lilypond[verbatim,quote]
565 \repeat unfold 2 { c''4 d e f }
570 In some cases, especially in a @code{\relative} context, the
571 @code{\repeat unfold} function is not the same as writing out the
572 music expression multiple times. E.g,
575 \repeat unfold 2 @{ a'4 b c @}
584 Unfold repeats can be made with alternate endings.
586 @lilypond[verbatim,quote]
588 \repeat unfold 2 { c''4 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]
603 \repeat unfold 4 { c''4 d e f }
613 If there are more alternate endings than repeats then only the first
614 alternatives are applied. The remaining alternatives will be ignored
617 @lilypond[verbatim,quote]
619 \repeat unfold 2 { c''4 d e f }
629 It is also possible to nest multiple @code{unfold} functions (with or
630 without alternate endings).
632 @lilypond[verbatim,quote]
635 \repeat unfold 2 { c''4 d e f }
645 Chord constructs can be repeated by the chord repetition symbol
646 @code{q}. See @ref{Chord repetition}.
648 @warning{If you include @code{@bs{}relative} inside a @code{@bs{}repeat}
649 without explicitly instantiating the @code{Voice} context, extra
650 (unwanted) staves will appear. See @rprogram{An extra staff appears}.}
654 @ref{Chord repetition}.
660 @rinternals{RepeatedMusic},
661 @rinternals{UnfoldedRepeatedMusic}.
665 @subsection Short repeats
667 This section discusses how to input short repeats. Short repeats can
668 take two forms: slashes or percent signs to represent repeats of a
669 single note, a single measure or two measures, and tremolos otherwise.
676 @node Percent repeats
677 @unnumberedsubsubsec Percent repeats
679 @cindex percent repeats
680 @cindex measure repeats
681 @cindex repeat, percent
682 @cindex repeat, measure
683 @cindex repeat, short
684 @funindex \repeat percent
687 Repeated short patterns are printed once, and the repeated pattern
688 is replaced with a special sign.
693 \repeat percent @var{number} @var{musicexpr}
697 where @code{@var{musicexpr}} is a music expression.
699 Patterns that are shorter than one measure are replaced by slashes.
701 @lilypond[verbatim,quote]
703 \repeat percent 4 { c128 d e f }
704 \repeat percent 4 { c64 d e f }
705 \repeat percent 5 { c32 d e f }
706 \repeat percent 4 { c16 d e f }
707 \repeat percent 4 { c8 d }
708 \repeat percent 4 { c4 }
709 \repeat percent 2 { c2 }
713 Patterns of one or two measures are replaced by percent-like symbols.
715 @lilypond[verbatim,quote]
717 \repeat percent 2 { c4 d e f }
718 \repeat percent 2 { c2 d }
719 \repeat percent 2 { c1 }
723 @lilypond[verbatim,quote]
725 \repeat percent 3 { c''4 d e f | c2 g' }
729 Patterns that are shorter than one measure but contain mixed durations
730 use a double-percent symbol.
732 @lilypond[verbatim,quote]
734 \repeat percent 4 { c''8. <d f>16 }
735 \repeat percent 2 { \tuplet 3/2 { r8 c d } e4 }
741 @lilypondfile[verbatim,quote,texidoc,doctitle]
742 {percent-repeat-counter.ly}
744 @lilypondfile[verbatim,quote,texidoc,doctitle]
745 {percent-repeat-count-visibility.ly}
747 @lilypondfile[verbatim,quote,texidoc,doctitle]
748 {isolated-percent-repeats.ly}
752 @rglos{percent repeat},
759 @rinternals{RepeatSlash},
760 @rinternals{RepeatSlashEvent},
761 @rinternals{DoubleRepeatSlash},
762 @rinternals{PercentRepeat},
763 @rinternals{PercentRepeatCounter},
764 @rinternals{PercentRepeatedMusic},
765 @rinternals{Percent_repeat_engraver},
766 @rinternals{DoublePercentEvent},
767 @rinternals{DoublePercentRepeat},
768 @rinternals{DoublePercentRepeatCounter},
769 @rinternals{Double_percent_repeat_engraver},
770 @rinternals{Slash_repeat_engraver}.
773 Percent repeats will not contain anything else apart from the percent
774 sign itself; in particular, timing changes will not be repeated.
776 @lilypond[quote,verbatim,relative=2]
777 \repeat percent 3 { \time 5/4 c2. 2 \time 4/4 2 2 }
781 Any meter changes or @code{\partial} commands need to occur in parallel
782 passages @emph{outside} of any percent repeat, e.g in a separate
785 @lilypond[quote,verbatim,relative=2]
787 \repeat percent 3 { c2. 2 2 2 }
788 \repeat unfold 3 { \time 5/4 s4*5 \time 4/4 s1 }
793 @node Tremolo repeats
794 @unnumberedsubsubsec Tremolo repeats
796 @cindex tremolo beams
798 @cindex repeat, tremolo
799 @funindex \repeat tremolo
802 Tremolos can take two forms: alternation between two chords or two
803 notes, and rapid repetition of a single note or chord. Tremolos
804 consisting of an alternation are indicated by adding beams between the
805 notes or chords being alternated, while tremolos consisting of the
806 rapid repetition of a single note are indicated by adding beams or
807 slashes to a single note.
809 To place tremolo marks between notes, use @code{\repeat} with
812 @lilypond[quote,verbatim]
814 \repeat tremolo 8 { c16 d }
815 \repeat tremolo 6 { c16 d }
816 \repeat tremolo 2 { c16 d }
820 The @code{\repeat tremolo} syntax expects exactly two notes within
821 the braces, and the number of repetitions must correspond to a
822 note value that can be expressed with plain or dotted notes. Thus,
823 @code{\repeat tremolo 7} is valid and produces a double dotted
824 note, but @code{\repeat tremolo 9} is not.
826 The duration of the tremolo equals the duration of the
827 braced expression multiplied by the number of repeats:
828 @code{\repeat tremolo 8 @{ c16 d16 @}} gives a whole note tremolo,
829 notated as two whole notes joined by tremolo beams.
831 There are two ways to put tremolo marks on a single note. The
832 @code{\repeat tremolo} syntax is also used here, in which case
833 the note should not be surrounded by braces:
835 @lilypond[quote,verbatim,ragged-right]
836 \repeat tremolo 4 c'16
839 @cindex tremolo marks
842 The same output can be obtained by adding @code{:@var{N}} after
843 the note, where @code{@var{N}} indicates the duration of the
844 subdivision (it must be at least 8). If @code{@var{N}} is 8, one
845 beam is added to the note's stem. If @code{@var{N}} is omitted,
846 the last value is used:
848 @lilypond[quote,verbatim]
857 @lilypondfile[verbatim,quote,texidoc,doctitle]
858 {cross-staff-tremolos.ly}
864 @cindex tremolo, cross-staff
865 @cindex cross-staff tremolo