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 @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 @var{musicexpr} is a music expression. Alternate endings can be
88 produced using @code{\alternative}. In order to delimit the alternate
89 endings, the group of alternatives must be enclosed in a set of
90 braces. If there are more repeats than there are alternate endings,
91 the earliest repeats are given the first alternative.
93 Normal repeats without alternate endings:
95 @lilypond[verbatim,quote,relative=2]
96 \repeat volta 2 { c4 d e f }
98 \repeat volta 2 { d4 e f g }
101 Normal repeats with alternate endings:
103 @lilypond[verbatim,quote,relative=2]
104 \repeat volta 4 { c4 d e f }
112 @warning{If you include @code{@bs{}relative} inside a
113 @code{@bs{}repeat} without explicitly instantiating the
114 @code{Voice} context, extra (unwanted) staves will appear. See
115 @rprogram{An extra staff appears}.}
117 @cindex repeat with upbeat
118 @cindex upbeat in a repeat
119 @cindex anacrucis in a repeat
120 @cindex repeat with anacrucis
121 @cindex repeat with pickup
122 @cindex pickup in a repeat
126 If a repeat starts in the middle of a measure and has no alternate
127 endings, normally the end of the repeat will also fall in the
128 middle of a measure, so that the two ends add up to one complete
129 measure. In such cases, the repeat signs do not constitute true
130 bar lines. Do not use @code{\partial} commands or bar checks
131 where these repeat signs are printed:
133 @lilypond[verbatim,quote,relative=1]
135 c4 e g % no bar check here
141 g4 g g % no bar check here
149 Similarly, if a repeat begins with the initial partial measure of
150 a score and has no alternate endings, the same conditions apply as
151 in the above example, except that in this case the @code{\partial}
152 command is required at the beginning of the score:
154 @lilypond[verbatim,quote,relative=1]
155 \partial 4 % required
160 g4 g g % no bar check here
168 When alternate endings are added to a repeat that begins with an
169 incomplete measure, it becomes necessary to set the
170 @code{Timing.measureLength} context property manually, in the
171 following specific places:
175 at the start of any incomplete measures in the @code{\alternative}
176 block, which normally occur at the end of each alternative, except
177 (in most cases) the last.
180 at the start of each alternative, except the first.
183 @lilypond[verbatim,quote,relative=1]
185 \repeat volta 2 { e4 | c2 e | }
189 \set Timing.measureLength = #(ly:make-moment 3 4)
190 g4 g g % optional bar check is allowed here
193 \set Timing.measureLength = #(ly:make-moment 4 4)
200 The @code{measureLength} property is described in @ref{Time
203 @cindex repeats with ties
204 @cindex alternative endings with ties
205 @cindex ties in repeats
206 @cindex ties in alternative endings
209 Ties may be added to a second ending:
211 @lilypond[verbatim,quote,relative=2]
213 \repeat volta 2 { c4 d e f~ }
222 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
223 {shortening-volta-brackets.ly}
225 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
226 {adding-volta-brackets-to-additional-staves.ly}
236 @ref{Modifying context plug-ins},
237 @ref{Time administration}.
243 @rinternals{VoltaBracket},
244 @rinternals{RepeatedMusic},
245 @rinternals{VoltaRepeatedMusic},
246 @rinternals{UnfoldedRepeatedMusic}.
251 @cindex repeat, ambiguous
252 @cindex nested repeat
253 @cindex repeat, nested
254 @cindex repeat timing information
255 @cindex repeat and measure number
256 @cindex timing information and repeats
257 @cindex measure number and repeats
258 @cindex repeat and slur
259 @cindex slur and repeat
261 Slurs that span from a @code{\repeat} block into an
262 @code{\alternative} block will only work for the first alternate
263 ending. Also, slurs cannot wrap around from the end of one
264 alternative back to the beginning of the repeat.
266 If a repeat that begins with an incomplete measure has an
267 @code{\alternative} block that contains modifications to the
268 @code{measureLength} property, using @code{\unfoldRepeats} will
269 result in wrongly-placed bar lines and bar check warnings.
280 is ambiguous, since it is not clear to which @code{\repeat} the
281 @code{\alternative} belongs. This ambiguity is resolved by always
282 having the @code{\alternative} belong to the inner @code{\repeat}.
283 For clarity, it is advisable to use braces in such situations.
286 @node Manual repeat marks
287 @unnumberedsubsubsec Manual repeat marks
289 @cindex manual repeat mark
290 @cindex repeat, manual
292 @cindex repeat, start
295 @cindex repeat number, changing
296 @cindex repeat volta, changing
297 @cindex volta bracket
298 @cindex bracket, volta
299 @funindex repeatCommands
300 @funindex start-repeat
302 @warning{These methods are only used for displaying unusual repeat
303 constructs, and may produce unexpected behavior. In most cases,
304 repeats should be created using the standard @code{\\repeat} command
305 or by printing the relevant bar lines. For more information, see
308 The property @code{repeatCommands} can be used to control the
309 layout of repeats. Its value is a Scheme list of repeat commands.
313 Print a @code{|:} bar line.
315 @lilypond[verbatim,quote,relative=2]
317 \set Score.repeatCommands = #'(start-repeat)
322 As per standard engraving practice, repeat signs are not printed
323 at the beginning of a piece.
326 Print a @code{:|} bar line:
328 @lilypond[verbatim,quote,relative=2]
331 \set Score.repeatCommands = #'(end-repeat)
335 @item (volta @var{number}) ... (volta #f)
336 Create a new volta with the specified number. The volta bracket must
337 be explicitly terminated, or it will not be printed.
339 @lilypond[verbatim,quote,relative=2]
341 \set Score.repeatCommands = #'((volta "2"))
343 \set Score.repeatCommands = #'((volta #f))
349 Multiple repeat commands may occur at the same point:
351 @lilypond[verbatim,quote,relative=2]
353 \set Score.repeatCommands = #'((volta "2, 5") end-repeat)
356 \set Score.repeatCommands = #'((volta #f) (volta "95") end-repeat)
358 \set Score.repeatCommands = #'((volta #f))
361 @cindex volta bracket with text
362 @cindex text in volta bracket
364 Text can be included with the volta bracket. The text can be a
365 number or numbers or markup text, see @ref{Formatting text}. The
366 simplest way to use markup text is to define the markup first,
367 then include the markup in a Scheme list.
369 @lilypond[verbatim,quote]
370 voltaAdLib = \markup { 1. 2. 3... \text \italic { ad lib. } }
373 \set Score.repeatCommands = #(list(list 'volta voltaAdLib) 'start-repeat)
375 \set Score.repeatCommands = #'((volta #f) (volta "4.") end-repeat)
377 \set Score.repeatCommands = #'((volta #f))
384 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
385 {printing-a-repeat-sign-at-the-beginning-of-a-piece.ly}
391 @ref{Formatting text}.
397 @rinternals{VoltaBracket},
398 @rinternals{RepeatedMusic},
399 @rinternals{VoltaRepeatedMusic}.
402 @node Written-out repeats
403 @unnumberedsubsubsec Written-out repeats
405 @cindex written-out repeats
406 @cindex repetitious music
407 @cindex repeats, written-out
408 @cindex repeat, unfold
410 @cindex unfold repeat
411 @cindex unfold repeat with alternate endings
412 @cindex unfold music with alternate endings
413 @cindex alternate ending in written-out repeats
416 By using the @code{unfold} command, repeats can be used to simplify
417 the writing out of repetitious music. The syntax is
420 \repeat unfold @var{repeatcount} @var{musicexpr}
424 where @var{musicexpr} is a music expression and @var{repeatcount} is
425 the number of times @var{musicexpr} is repeated.
427 @lilypond[verbatim,quote,relative=2]
429 \repeat unfold 2 { c4 d e f }
433 Unfold repeats can be made with alternate endings. If there are
434 more repeats than there are alternate endings, the first
435 alternative ending is applied to the earliest endings.
437 @lilypond[verbatim,quote,relative=2]
439 \repeat unfold 2 { g4 f e d }
447 @warning{If you include @code{@bs{}relative} inside a
448 @code{@bs{}repeat} without explicitly instantiating the
449 @code{Voice} context, extra (unwanted) staves will appear. See
450 @rprogram{An extra staff appears}.}
458 @rinternals{RepeatedMusic},
459 @rinternals{UnfoldedRepeatedMusic}.
463 @subsection Short repeats
465 This section discusses how to input short repeats. Short repeats can
466 take two basic forms: repeats of a single note to two measures,
467 represented by slashes or percent signs; and tremolos.
474 @node Percent repeats
475 @unnumberedsubsubsec Percent repeats
477 @cindex percent repeats
478 @cindex measure repeats
479 @cindex repeat, percent
480 @cindex repeat, measure
481 @cindex repeat, short
482 @funindex \repeat percent
485 Repeated short patterns of notes are supported. The music is printed
486 once, and the pattern is replaced with a special sign. Patterns that
487 are shorter than one measure are replaced by slashes, and patterns of
488 one or two measures are replaced by percent-like signs. The syntax is
491 @code{\repeat percent @var{number} @var{musicexpr}}
495 where @var{musicexpr} is a music expression.
497 @lilypond[verbatim,quote,relative=2]
498 \repeat percent 4 { c4 }
499 \repeat percent 2 { b4 a g f }
500 \repeat percent 2 { c2 es | f4 fis g c | }
505 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
506 {percent-repeat-counter.ly}
508 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
509 {percent-repeat-count-visibility.ly}
511 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
512 {isolated-percent-repeats.ly}
517 @rglos{percent repeat},
524 @rinternals{RepeatSlash},
525 @rinternals{PercentRepeat},
526 @rinternals{DoublePercentRepeat},
527 @rinternals{DoublePercentRepeatCounter},
528 @rinternals{PercentRepeatCounter},
529 @rinternals{PercentRepeatedMusic}.
534 Only three kinds of percent repeats are supported: a single slash
535 representing a single beat (regardless of the duration of the repeated
536 notes); a single slash with dots representing one full measure; and
537 two slashes with dots crossing a bar line representing two full
538 measures. Neither multiple slashes representing single beat repeats
539 consisting of sixteenth or shorter notes, nor two slashes with dots
540 representing single beat repeats consisting of notes of varying
541 durations, are supported.
544 @node Tremolo repeats
545 @unnumberedsubsubsec Tremolo repeats
547 @cindex tremolo beams
549 @cindex repeat, tremolo
550 @funindex \repeat tremolo
553 Tremolos can take two forms: alternation between two chords or two
554 notes, and rapid repetition of a single note or chord. Tremolos
555 consisting of an alternation are indicated by adding beams between the
556 notes or chords being alternated, while tremolos consisting of the
557 rapid repetition of a single note are indicated by adding beams or
558 slashes to a single note.
560 To place tremolo marks between notes, use @code{\repeat} with
563 @lilypond[quote,verbatim,relative=2]
564 \repeat tremolo 8 { c16 d }
565 \repeat tremolo 6 { c16 d }
566 \repeat tremolo 2 { c16 d }
569 The @code{\repeat tremolo} syntax expects exactly two notes within
570 the braces, and the number of repetitions must correspond to a
571 note value that can be expressed with plain or dotted notes. Thus,
572 @code{\repeat tremolo 7} is valid and produces a double dotted
573 note, but @code{\repeat tremolo 9} is not.
575 The duration of the tremolo equals the duration of the
576 braced expression multiplied by the number of repeats:
577 @code{\repeat tremolo 8 @{ c16 d16 @}} gives a whole note tremolo,
578 notated as two whole notes joined by tremolo beams.
580 There are two ways to put tremolo marks on a single note. The
581 @code{\repeat tremolo} syntax is also used here, in which case
582 the note should not be surrounded by braces:
584 @lilypond[quote,verbatim,ragged-right]
585 \repeat tremolo 4 c'16
588 @cindex tremolo marks
589 @funindex tremoloFlags
592 The same output can be obtained by adding
593 @q{@code{:}[@var{number}]} after the note. The number indicates
594 the duration of the subdivision, and it must be at least 8. A
595 @var{number} value of 8 gives one line across the note stem. If
596 the length is omitted, the last value (stored in
597 @code{tremoloFlags}) is used:
599 @lilypond[quote,verbatim,relative=2]
606 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
607 {cross-staff-tremolos.ly}
614 @cindex tremolo, cross-staff
615 @cindex cross-staff tremolo