]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/notation/repeats.itely
Merge branch 'lilypond/translation'
[lilypond.git] / Documentation / notation / repeats.itely
1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @ignore
3     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
4
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..
8 @end ignore
9
10 @c \version "2.12.0"
11
12 @node Repeats
13 @section Repeats
14
15 @lilypondfile[quote]{repeats-headword.ly}
16
17 Repetition is a central concept in music, and multiple notations
18 exist for repetitions.  LilyPond supports the following kinds of
19 repeats:
20
21
22 @table @code
23 @item volta
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.
29
30 @item unfold
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.
34
35 @item percent
36 These are beat or measure repeats.  They look like single slashes or
37 percent signs.
38
39 @item tremolo
40 This is used to write tremolo beams.
41
42 @end table
43
44
45 @menu
46 * Long repeats::
47 * Short repeats::
48 @end menu
49
50 @node Long repeats
51 @subsection Long repeats
52
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.
57
58 @menu
59 * Normal repeats::
60 * Manual repeat marks::
61 * Written-out repeats::
62 @end menu
63
64 @cindex volta
65 @cindex prima volta
66 @cindex seconda volta
67 @cindex volta, prima
68 @cindex volta, seconda
69 @cindex repeat, normal
70 @cindex normal repeat
71 @cindex repeat with alternate endings
72 @cindex alternate endings
73 @funindex \repeat
74 @funindex \alternative
75 @funindex \partial
76
77 @node Normal repeats
78 @unnumberedsubsubsec Normal repeats
79
80 The syntax for a normal repeat is
81
82 @example
83 \repeat volta @var{repeatcount} @var{musicexpr}
84 @end example
85
86 @noindent
87 where @var{musicexpr} is a music expression.
88
89 A single repeat without an alternate ending:
90
91 @lilypond[verbatim,quote,relative=2]
92 \repeat volta 2 { c4 d e f }
93 c2 d
94 \repeat volta 2 { d4 e f g }
95 @end lilypond
96
97 Alternative endings can be produced using @code{\alternative}.  Each
98 group of alternatives must be themselves, enclosed in a set of braces.
99
100 @example
101 \repeat volta @var{repeatcount} @var{musicexpr}
102 \alternative @{
103   @{ @var{musicexpr} @}
104 @}
105 @end example
106
107 @noindent
108 where @var{musicexpr} is a music expression.
109
110 If there are more repeats than there are alternate endings, the earliest
111 repeats are given the first alternative.
112
113 A single repeat with one alternate ending:
114
115 @lilypond[verbatim,quote,relative=2]
116 \repeat volta 2 { c4 d e f }
117 \alternative {
118   { c2 e }
119   { f2 g }
120 }
121 c1
122 @end lilypond
123
124 A single repeat with more than one alternate ending:
125
126 @lilypond[verbatim,quote,relative=2]
127 \repeat volta 4 { c4 d e f }
128 \alternative {
129   { c2 e }
130   { f2 g }
131 }
132 c1
133 @end lilypond
134
135 Multiple repeats with more than one alternate ending:
136
137 @lilypond[verbatim,quote,relative=2]
138 \repeat volta 3 { c4 d e f }
139 \alternative {
140   { c2 e }
141   { f2 g }
142   { a2 g }
143 }
144 c1
145 @end lilypond
146
147 @warning{If you include @code{@bs{}relative} inside a
148 @code{@bs{}repeat} without explicitly instantiating the
149 @code{Voice} context, extra (unwanted) staves will appear.  See
150 @rprogram{An extra staff appears}.}
151
152 @cindex repeat with upbeat
153 @cindex upbeat in a repeat
154 @cindex anacrucis in a repeat
155 @cindex repeat with anacrucis
156 @cindex repeat with pickup
157 @cindex pickup in a repeat
158 @funindex \partial
159
160
161 If a repeat starts in the middle of a measure and has no alternate
162 endings, normally the end of the repeat will also fall in the
163 middle of a measure, so that the two ends add up to one complete
164 measure.  In such cases, the repeat signs do not constitute true
165 bar lines.  Do not use @code{\partial} commands or bar checks
166 where these repeat signs are printed:
167
168 @lilypond[verbatim,quote,relative=1]
169 % no \partial here
170 c4 e g  % no bar check here
171 % no \partial here
172 \repeat volta 4 {
173   e4 |
174   c2 e |
175   % no \partial here
176   g4 g g  % no bar check here
177 }
178 % no \partial here
179 g4 |
180 a2 a |
181 g1 |
182 @end lilypond
183
184 Similarly, if a repeat begins with the initial partial measure of
185 a score and has no alternate endings, the same conditions apply as
186 in the above example, except that in this case the @code{\partial}
187 command is required at the beginning of the score:
188
189 @lilypond[verbatim,quote,relative=1]
190 \partial 4  % required
191 \repeat volta 4 {
192   e4 |
193   c2 e |
194   % no \partial here
195   g4 g g  % no bar check here
196 }
197 % no \partial here
198 g4 |
199 a2 a |
200 g1 |
201 @end lilypond
202
203 When alternate endings are added to a repeat that begins with an
204 incomplete measure, it becomes necessary to set the
205 @code{Timing.measureLength} context property manually, in the
206 following specific places:
207
208 @itemize
209 @item
210 at the start of any incomplete measures in the @code{\alternative}
211 block, which normally occur at the end of each alternative, except
212 (in most cases) the last.
213
214 @item
215 at the start of each alternative, except the first.
216 @end itemize
217
218 @lilypond[verbatim,quote,relative=1]
219 \partial 4
220 \repeat volta 2 { e4 | c2 e | }
221 \alternative {
222   {
223     f2 d |
224     \set Timing.measureLength = #(ly:make-moment 3 4)
225     g4 g g  % optional bar check is allowed here
226   }
227   {
228     \set Timing.measureLength = #(ly:make-moment 4 4)
229     a2 a |
230   }
231 }
232 g1 |
233 @end lilypond
234
235 The @code{measureLength} property is described in @ref{Time
236 administration}.
237
238 @cindex repeats with ties
239 @cindex alternative endings with ties
240 @cindex ties in repeats
241 @cindex ties in alternative endings
242 @funindex \repeatTie
243
244 Ties may be added to a second ending:
245
246 @lilypond[verbatim,quote,relative=2]
247 c1
248 \repeat volta 2 { c4 d e f~ }
249 \alternative {
250   { f2 d }
251   { f2\repeatTie f, }
252 }
253 @end lilypond
254
255 @snippets
256
257 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
258 {shortening-volta-brackets.ly}
259
260 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
261 {adding-volta-brackets-to-additional-staves.ly}
262
263 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
264 {setting-the-double-repeat-default-for-volte.ly}
265
266 @seealso
267 Music Glossary:
268 @rglos{repeat},
269 @rglos{volta}.
270
271 Notation Reference:
272 @ref{Bar lines},
273 @ref{Modifying context plug-ins},
274 @ref{Time administration}.
275
276 Snippets:
277 @rlsr{Repeats}.
278
279 Internals Reference:
280 @rinternals{VoltaBracket},
281 @rinternals{RepeatedMusic},
282 @rinternals{VoltaRepeatedMusic},
283 @rinternals{UnfoldedRepeatedMusic}.
284
285
286 @knownissues
287
288 @cindex repeat, ambiguous
289 @cindex nested repeat
290 @cindex repeat, nested
291 @cindex repeat timing information
292 @cindex repeat and measure number
293 @cindex timing information and repeats
294 @cindex measure number and repeats
295 @cindex repeat and slur
296 @cindex slur and repeat
297
298 Slurs that span from a @code{\repeat} block into an
299 @code{\alternative} block will only work for the first alternate
300 ending.  Also, slurs cannot wrap around from the end of one
301 alternative back to the beginning of the repeat.
302
303 If a repeat that begins with an incomplete measure has an
304 @code{\alternative} block that contains modifications to the
305 @code{measureLength} property, using @code{\unfoldRepeats} will
306 result in wrongly-placed bar lines and bar check warnings.
307
308 A nested repeat like
309
310 @example
311 \repeat @dots{}
312 \repeat @dots{}
313 \alternative
314 @end example
315
316 @noindent
317 is ambiguous, since it is not clear to which @code{\repeat} the
318 @code{\alternative} belongs.  This ambiguity is resolved by always
319 having the @code{\alternative} belong to the inner @code{\repeat}.
320 For clarity, it is advisable to use braces in such situations.
321
322
323 @node Manual repeat marks
324 @unnumberedsubsubsec Manual repeat marks
325
326 @cindex manual repeat mark
327 @cindex repeat, manual
328 @cindex start repeat
329 @cindex repeat, start
330 @cindex end repeat
331 @cindex repeat, end
332 @cindex repeat number, changing
333 @cindex repeat volta, changing
334 @cindex volta bracket
335 @cindex bracket, volta
336 @funindex repeatCommands
337 @funindex start-repeat
338
339 @warning{These methods are only used for displaying unusual repeat
340 constructs, and may produce unexpected behavior.  In most cases,
341 repeats should be created using the standard @code{@bs{}repeat} command
342 or by printing the relevant bar lines.  For more information, see
343 @ref{Bar lines}.}
344
345 The property @code{repeatCommands} can be used to control the
346 layout of repeats.  Its value is a Scheme list of repeat commands.
347
348 @table @code
349 @item start-repeat
350 Print a @code{|:} bar line.
351
352 @lilypond[verbatim,quote,relative=2]
353 c1
354 \set Score.repeatCommands = #'(start-repeat)
355 d4 e f g
356 c1
357 @end lilypond
358
359 As per standard engraving practice, repeat signs are not printed
360 at the beginning of a piece.
361
362 @item end-repeat
363 Print a @code{:|} bar line:
364
365 @lilypond[verbatim,quote,relative=2]
366 c1
367 d4 e f g
368 \set Score.repeatCommands = #'(end-repeat)
369 c1
370 @end lilypond
371
372 @item (volta @var{number}) ... (volta #f)
373 Create a new volta with the specified number.  The volta bracket must
374 be explicitly terminated, or it will not be printed.
375
376 @lilypond[verbatim,quote,relative=2]
377 f4 g a b
378 \set Score.repeatCommands = #'((volta "2"))
379 g4 a g a
380 \set Score.repeatCommands = #'((volta #f))
381 c1
382 @end lilypond
383
384 @end table
385
386 Multiple repeat commands may occur at the same point:
387
388 @lilypond[verbatim,quote,relative=2]
389 f4 g a b
390 \set Score.repeatCommands = #'((volta "2, 5") end-repeat)
391 g4 a g a
392 c1
393 \set Score.repeatCommands = #'((volta #f) (volta "95") end-repeat)
394 b1
395 \set Score.repeatCommands = #'((volta #f))
396 @end lilypond
397
398 @cindex volta bracket with text
399 @cindex text in volta bracket
400
401 Text can be included with the volta bracket.  The text can be a
402 number or numbers or markup text, see @ref{Formatting text}.  The
403 simplest way to use markup text is to define the markup first,
404 then include the markup in a Scheme list.
405
406 @lilypond[verbatim,quote]
407 voltaAdLib = \markup { 1. 2. 3... \text \italic { ad lib. } }
408 \relative c'' {
409   c1
410   \set Score.repeatCommands = #(list(list 'volta voltaAdLib) 'start-repeat)
411   c4 b d e
412   \set Score.repeatCommands = #'((volta #f) (volta "4.") end-repeat)
413   f1
414   \set Score.repeatCommands = #'((volta #f))
415 }
416 @end lilypond
417
418
419 @snippets
420
421 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
422 {printing-a-repeat-sign-at-the-beginning-of-a-piece.ly}
423
424
425 @seealso
426 Notation Reference:
427 @ref{Bar lines},
428 @ref{Formatting text}.
429
430 Snippets:
431 @rlsr{Repeats}.
432
433 Internals Reference:
434 @rinternals{VoltaBracket},
435 @rinternals{RepeatedMusic},
436 @rinternals{VoltaRepeatedMusic}.
437
438
439 @node Written-out repeats
440 @unnumberedsubsubsec Written-out repeats
441
442 @cindex written-out repeats
443 @cindex repetitious music
444 @cindex repeats, written-out
445 @cindex repeat, unfold
446 @cindex unfold music
447 @cindex unfold repeat
448 @cindex unfold repeat with alternate endings
449 @cindex unfold music with alternate endings
450 @cindex alternate ending in written-out repeats
451 @funindex unfold
452
453 By using the @code{unfold} command, repeats can be used to simplify
454 the writing out of repetitious music.  The syntax is
455
456 @example
457 \repeat unfold @var{repeatcount} @var{musicexpr}
458 @end example
459
460 @noindent
461 where @var{musicexpr} is a music expression and @var{repeatcount} is
462 the number of times @var{musicexpr} is repeated.
463
464 @lilypond[verbatim,quote,relative=2]
465 \repeat unfold 2 { c4 d e f }
466 c1
467 @end lilypond
468
469 Unfold repeats can be made with alternate endings.
470
471 @lilypond[verbatim,quote,relative=2]
472 \repeat unfold 2 { c4 d e f }
473 \alternative {
474   { c2 g' }
475   { c,2 b }
476 }
477 c1
478 @end lilypond
479
480 If there are more repeats than there are alternate endings, the first
481 alternative is applied multiple times until the remaining alternatives
482 make up the total number of repeats.
483
484 @lilypond[verbatim,quote,relative=2]
485 \repeat unfold 4 { c4 d e f }
486 \alternative {
487   { c2 g' }
488   { c,2 b }
489   { e2 d }
490  }
491 c1
492 @end lilypond
493
494 If there are more alternate endings than repeats then the first
495 alternatives are applied, LilyPond will ignore the remaining
496 alternatives which will not be printed.
497
498 @lilypond[verbatim,quote,relative=2]
499 \repeat unfold 2 { c4 d e f }
500 \alternative {
501   { c2 g' }
502   { c,2 b }
503   { e2 d }
504 }
505 c1
506 @end lilypond
507
508 It is also possible to nest multiple @code{unfold} functions (with or
509 without alternate endings).
510
511 @lilypond[verbatim,quote,relative=2]
512 \repeat unfold 2 {
513   \repeat unfold 2 { c4 d e f }
514   \alternative {
515     { c2 g' }
516     { c,2 b }
517   }
518 }
519 c1
520 @end lilypond
521
522
523 @warning{If you include @code{@bs{}relative} inside a
524 @code{@bs{}repeat} without explicitly instantiating the
525 @code{Voice} context, extra (unwanted) staves will appear.  See
526 @rprogram{An extra staff appears}.}
527
528
529 @seealso
530 Snippets:
531 @rlsr{Repeats}.
532
533 Internals Reference:
534 @rinternals{RepeatedMusic},
535 @rinternals{UnfoldedRepeatedMusic}.
536
537
538 @node Short repeats
539 @subsection Short repeats
540
541 This section discusses how to input short repeats.  Short repeats can
542 take two forms: slashes or percent signs to represent repeats of a
543 single note, a single measure or two measures, and tremolos otherwise.
544
545 @menu
546 * Percent repeats::
547 * Tremolo repeats::
548 @end menu
549
550 @node Percent repeats
551 @unnumberedsubsubsec Percent repeats
552
553 @cindex percent repeats
554 @cindex measure repeats
555 @cindex repeat, percent
556 @cindex repeat, measure
557 @cindex repeat, short
558 @funindex \repeat percent
559 @funindex percent
560
561 Repeated short patterns are printed once, and the repeated pattern
562 is replaced with a special sign.
563
564 The syntax is
565
566 @example
567 @code{\repeat percent @var{number} @var{musicexpr}}
568 @end example
569
570 @noindent
571 where @var{musicexpr} is a music expression.
572
573 Patterns that are shorter than one measure are replaced by slashes.
574
575 @lilypond[verbatim,quote,relative=2]
576 \repeat percent 4 { c8 d }
577 \repeat percent 4 { c4 }
578 \repeat percent 2 { c2 }
579 @end lilypond
580
581 Patterns of one or two measures are replaced by percent-like signs.
582
583 @lilypond[verbatim,quote,relative=2]
584 \repeat percent 3 { c4 d e f }
585 \repeat percent 4 { c2 d }
586 @end lilypond
587
588 @lilypond[verbatim,quote,relative=2]
589 \repeat percent 3 { c4 d e f | c2 g' }
590 @end lilypond
591
592 @snippets
593
594 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
595 {percent-repeat-counter.ly}
596
597 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
598 {percent-repeat-count-visibility.ly}
599
600 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
601 {isolated-percent-repeats.ly}
602
603
604 @seealso
605 Music Glossary:
606 @rglos{percent repeat},
607 @rglos{simile}.
608
609 Snippets:
610 @rlsr{Repeats}.
611
612 Internals Reference:
613 @rinternals{RepeatSlash},
614 @rinternals{PercentRepeat},
615 @rinternals{DoublePercentRepeat},
616 @rinternals{DoublePercentRepeatCounter},
617 @rinternals{PercentRepeatCounter},
618 @rinternals{PercentRepeatedMusic}.
619
620
621 @knownissues
622
623 Only three kinds of percent repeats are supported: a single slash
624 representing a single beat (regardless of the duration of the repeated
625 notes); a single slash with dots representing one full measure; and
626 two slashes with dots crossing a bar line representing two full
627 measures.  Neither multiple slashes representing single beat repeats
628 consisting of sixteenth or shorter notes, nor two slashes with dots
629 representing single beat repeats consisting of notes of varying
630 durations, are supported.
631
632
633 @node Tremolo repeats
634 @unnumberedsubsubsec Tremolo repeats
635
636 @cindex tremolo beams
637 @cindex tremolo
638 @cindex repeat, tremolo
639 @funindex \repeat tremolo
640 @funindex tremolo
641
642 Tremolos can take two forms: alternation between two chords or two
643 notes, and rapid repetition of a single note or chord.  Tremolos
644 consisting of an alternation are indicated by adding beams between the
645 notes or chords being alternated, while tremolos consisting of the
646 rapid repetition of a single note are indicated by adding beams or
647 slashes to a single note.
648
649 To place tremolo marks between notes, use @code{\repeat} with
650 tremolo style:
651
652 @lilypond[quote,verbatim,relative=2]
653 \repeat tremolo 8 { c16 d }
654 \repeat tremolo 6 { c16 d }
655 \repeat tremolo 2 { c16 d }
656 @end lilypond
657
658 The @code{\repeat tremolo} syntax expects exactly two notes within
659 the braces, and the number of repetitions must correspond to a
660 note value that can be expressed with plain or dotted notes.  Thus,
661 @code{\repeat tremolo 7} is valid and produces a double dotted
662 note, but @code{\repeat tremolo 9} is not.
663
664 The duration of the tremolo equals the duration of the
665 braced expression multiplied by the number of repeats:
666 @code{\repeat tremolo 8 @{ c16 d16 @}} gives a whole note tremolo,
667 notated as two whole notes joined by tremolo beams.
668
669 There are two ways to put tremolo marks on a single note.  The
670 @code{\repeat tremolo} syntax is also used here, in which case
671 the note should not be surrounded by braces:
672
673 @lilypond[quote,verbatim,ragged-right]
674 \repeat tremolo 4 c'16
675 @end lilypond
676
677 @cindex tremolo marks
678 @funindex tremoloFlags
679 @funindex :
680
681 The same output can be obtained by adding
682 @q{@code{:}[@var{number}]} after the note.  The number indicates
683 the duration of the subdivision, and it must be at least 8.  A
684 @var{number} value of 8 gives one line across the note stem.  If
685 the length is omitted, the last value (stored in
686 @code{tremoloFlags}) is used:
687
688 @lilypond[quote,verbatim,relative=2]
689 c2:8 c:32
690 c: c:
691 @end lilypond
692
693 @snippets
694
695 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
696 {cross-staff-tremolos.ly}
697
698
699 @seealso
700 Snippets:
701 @rlsr{Repeats}.
702
703 @cindex tremolo, cross-staff
704 @cindex cross-staff tremolo
705