]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/notation/repeats.itely
Build: run makelsr.py
[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.  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.
92
93 Normal repeats without alternate endings:
94
95 @lilypond[verbatim,quote,relative=2]
96 \repeat volta 2 { c4 d e f }
97 c2 d
98 \repeat volta 2 { d4 e f g }
99 @end lilypond
100
101 Normal repeats with alternate endings:
102
103 @lilypond[verbatim,quote,relative=2]
104 \repeat volta 4 { c4 d e f }
105 \alternative {
106   { d2 e }
107   { f2 g }
108 }
109 c1
110 @end lilypond
111
112 @warning{Do not include @code{@bs{}relative} inside a
113 @code{@bs{}repeat}.  It will cause unwanted staves to appear.
114 See @rprogram{An extra staff appears}.}
115
116 @cindex repeat with upbeat
117 @cindex upbeat in a repeat
118 @cindex anacrucis in a repeat
119 @cindex repeat with anacrucis
120 @cindex repeat with pickup
121 @cindex pickup in a repeat
122 @funindex \partial
123
124 Repeats with upbeats can be entered in two ways:
125
126 @lilypond[verbatim,quote,relative=2]
127 \partial 4
128 e |
129 \repeat volta 4 { c2 d | e2 f | }
130 \alternative {
131   { g4 g g e }
132   { a4 a a a | b2. }
133 }
134 @end lilypond
135
136 @noindent
137 or
138
139 @lilypond[verbatim,quote,relative=2]
140 \partial 4
141 \repeat volta 4 { e4 | c2 d | e2 f | }
142 \alternative {
143   { \partial 4*3 g4 g g }
144   { a4 a a a | b2. }
145 }
146 @end lilypond
147
148
149 @cindex repeats with ties
150 @cindex alternative endings with ties
151 @cindex ties in repeats
152 @cindex ties in alternative endings
153 @funindex \repeatTie
154
155 Ties may be added to a second ending:
156
157 @lilypond[verbatim,quote,relative=2]
158 c1
159 \repeat volta 2 { c4 d e f ~ }
160 \alternative {
161   { f2 d }
162   { f2\repeatTie f, }
163 }
164 @end lilypond
165
166 @snippets
167
168 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
169 {shortening-volta-brackets.ly}
170
171 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
172 {adding-volta-brackets-to-additional-staves.ly}
173
174
175 @seealso
176 Music Glossary:
177 @rglos{repeat},
178 @rglos{volta}.
179
180 Notation Reference:
181 @ref{Bar lines},
182 @ref{Modifying context plug-ins}.
183
184 Snippets:
185 @rlsr{Repeats}.
186
187 Internals Reference:
188 @rinternals{VoltaBracket},
189 @rinternals{RepeatedMusic},
190 @rinternals{VoltaRepeatedMusic},
191 @rinternals{UnfoldedRepeatedMusic}.
192
193
194 @knownissues
195
196 @cindex repeat, ambiguous
197 @cindex nested repeat
198 @cindex repeat, nested
199 @cindex repeat timing information
200 @cindex repeat and measure number
201 @cindex timing information and repeats
202 @cindex measure number and repeats
203 @cindex repeat and slur
204 @cindex slur and repeat
205
206 A nested repeat like
207
208 @example
209 \repeat @dots{}
210 \repeat @dots{}
211 \alternative
212 @end example
213
214 @noindent
215 is ambiguous, since it is is not clear to which @code{\repeat} the
216 @code{\alternative} belongs.  This ambiguity is resolved by always
217 having the @code{\alternative} belong to the inner @code{\repeat}.
218 For clarity, it is advisable to use braces in such situations.
219
220 Timing information is not remembered at the start of an alternative,
221 so after a repeat timing information must be reset by hand; for
222 example, by setting @code{Score.measurePosition} or entering
223 @code{\partial}.  Similarly, slurs are also not repeated.
224
225
226
227 @node Manual repeat marks
228 @unnumberedsubsubsec Manual repeat marks
229
230 @cindex manual repeat mark
231 @cindex repeat, manual
232 @cindex start repeat
233 @cindex repeat, start
234 @cindex end repeat
235 @cindex repeat, end
236 @cindex repeat number, changing
237 @cindex repeat volta, changing
238 @cindex volta bracket
239 @cindex bracket, volta
240 @funindex repeatCommands
241 @funindex start-repeat
242
243 @warning{These methods are only used for displaying unusual repeat
244 constructs, and may produce unexpected behavior.  In most cases,
245 repeats should be created using the standard @code{\\repeat} command
246 or by printing the relevant bar lines.  For more information, see
247 @ref{Bar lines}.}
248
249 The property @code{repeatCommands} can be used to control the
250 layout of repeats.  Its value is a Scheme list of repeat commands.
251
252 @table @code
253 @item start-repeat
254 Print a @code{|:} bar line.
255
256 @lilypond[verbatim,quote,relative=2]
257 c1
258 \set Score.repeatCommands = #'(start-repeat)
259 d4 e f g
260 c1
261 @end lilypond
262
263 As per standard engraving practice, repeat signs are not printed
264 at the beginning of a piece.
265
266 @item end-repeat
267 Print a @code{:|} bar line:
268
269 @lilypond[verbatim,quote,relative=2]
270 c1
271 d4 e f g
272 \set Score.repeatCommands = #'(end-repeat)
273 c1
274 @end lilypond
275
276 @item (volta @var{number}) ... (volta #f)
277 Create a new volta with the specified number.  The volta bracket must
278 be explicitly terminated, or it will not be printed.
279
280 @lilypond[verbatim,quote,relative=2]
281 f4 g a b
282 \set Score.repeatCommands = #'((volta "2"))
283 g4 a g a
284 \set Score.repeatCommands = #'((volta #f))
285 c1
286 @end lilypond
287
288 @end table
289
290 Multiple repeat commands may occur at the same point:
291
292 @lilypond[verbatim,quote,relative=2]
293 f4 g a b
294 \set Score.repeatCommands = #'((volta "2, 5") end-repeat)
295 g4 a g a
296 c1
297 \set Score.repeatCommands = #'((volta #f) (volta "95") end-repeat)
298 b1
299 \set Score.repeatCommands = #'((volta #f))
300 @end lilypond
301
302 @cindex volta bracket with text
303 @cindex text in volta bracket
304
305 Text can be included with the volta bracket.  The text can be a
306 number or numbers or markup text, see @ref{Formatting text}.  The
307 simplest way to use markup text is to define the markup first,
308 then include the markup in a Scheme list.
309
310 @lilypond[verbatim,quote]
311 voltaAdLib = \markup { 1. 2. 3... \text \italic { ad lib. } }
312 \relative c'' {
313   c1
314   \set Score.repeatCommands = #(list(list 'volta voltaAdLib) 'start-repeat)
315   c4 b d e
316   \set Score.repeatCommands = #'((volta #f) (volta "4.") end-repeat)
317   f1
318   \set Score.repeatCommands = #'((volta #f))
319 }
320 @end lilypond
321
322
323 @snippets
324
325 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
326 {printing-a-repeat-sign-at-the-beginning-of-a-piece.ly}
327
328
329 @seealso
330 Notation Reference:
331 @ref{Bar lines},
332 @ref{Formatting text}.
333
334 Snippets:
335 @rlsr{Repeats}.
336
337 Internals Reference:
338 @rinternals{VoltaBracket},
339 @rinternals{RepeatedMusic},
340 @rinternals{VoltaRepeatedMusic}.
341
342
343 @node Written-out repeats
344 @unnumberedsubsubsec Written-out repeats
345
346 @cindex written-out repeats
347 @cindex repetitious music
348 @cindex repeats, written-out
349 @cindex repeat, unfold
350 @cindex unfold music
351 @cindex unfold repeat
352 @cindex unfold repeat with alternate endings
353 @cindex unfold music with alternate endings
354 @cindex alternate ending in written-out repeats
355 @funindex unfold
356
357 By using the @code{unfold} command, repeats can be used to simplify
358 the writing out of repetitious music.  The syntax is
359
360 @example
361 \repeat unfold @var{repeatcount} @var{musicexpr}
362 @end example
363
364 @noindent
365 where @var{musicexpr} is a music expression and @var{repeatcount} is
366 the number of times @var{musicexpr} is repeated.
367
368 @lilypond[verbatim,quote,relative=2]
369 c1
370 \repeat unfold 2 { c4 d e f }
371 c1
372 @end lilypond
373
374 Unfold repeats can be made with alternate endings.  If there are
375 more repeats than there are alternate endings, the first
376 alternative ending is applied to the earliest endings.
377
378 @lilypond[verbatim,quote,relative=2]
379 c1
380 \repeat unfold 2 { g4 f e d }
381   \alternative {
382     { cis2 g' }
383     { cis,2 b }
384   }
385 c1
386 @end lilypond
387
388
389 @seealso
390 Snippets:
391 @rlsr{Repeats}.
392
393 Internals Reference:
394 @rinternals{RepeatedMusic},
395 @rinternals{UnfoldedRepeatedMusic}.
396
397
398 @node Short repeats
399 @subsection Short repeats
400
401 This section discusses how to input short repeats.  Short repeats can
402 take two basic forms: repeats of a single note to two measures,
403 represented by slashes or percent signs; and tremolos.
404
405 @menu
406 * Percent repeats::
407 * Tremolo repeats::
408 @end menu
409
410 @node Percent repeats
411 @unnumberedsubsubsec Percent repeats
412
413 @cindex percent repeats
414 @cindex measure repeats
415 @cindex repeat, percent
416 @cindex repeat, measure
417 @cindex repeat, short
418 @funindex \repeat percent
419 @funindex percent
420
421 Repeated short patterns of notes are supported.  The music is printed
422 once, and the pattern is replaced with a special sign.  Patterns that
423 are shorter than one measure are replaced by slashes, and patterns of
424 one or two measures are replaced by percent-like signs.  The syntax is
425
426 @example
427 @code{\repeat percent @var{number} @var{musicexpr}}
428 @end example
429
430 @noindent
431 where @var{musicexpr} is a music expression.
432
433 @lilypond[verbatim,quote,relative=2]
434 \repeat percent 4 { c4 }
435 \repeat percent 2 { b4 a g f }
436 \repeat percent 2 { c2 es | f4 fis g c | }
437 @end lilypond
438
439 @snippets
440
441 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
442 {percent-repeat-counter.ly}
443
444 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
445 {percent-repeat-count-visibility.ly}
446
447 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
448 {isolated-percent-repeats.ly}
449
450
451 @seealso
452 Music Glossary:
453 @rglos{percent repeat},
454 @rglos{simile}.
455
456 Snippets:
457 @rlsr{Repeats}.
458
459 Internals Reference:
460 @rinternals{RepeatSlash},
461 @rinternals{PercentRepeat},
462 @rinternals{DoublePercentRepeat},
463 @rinternals{DoublePercentRepeatCounter},
464 @rinternals{PercentRepeatCounter},
465 @rinternals{PercentRepeatedMusic}.
466
467
468 @knownissues
469
470 Only three kinds of percent repeats are supported: a single slash
471 representing a single beat (regardless of the duration of the repeated
472 notes); a single slash with dots representing one full measure; and
473 two slashes with dots crossing a bar line representing two full
474 measures.  Neither multiple slashes representing single beat repeats
475 consisting of sixteenth or shorter notes, nor two slashes with dots
476 representing single beat repeats consisting of notes of varying
477 durations, are supported.
478
479
480 @node Tremolo repeats
481 @unnumberedsubsubsec Tremolo repeats
482
483 @cindex tremolo beams
484 @cindex tremolo
485 @cindex repeat, tremolo
486 @funindex \repeat tremolo
487 @funindex tremolo
488
489 Tremolos can take two forms: alternation between two chords or two
490 notes, and rapid repetition of a single note or chord. Tremolos
491 consisting of an alternation are indicated by adding beams between the
492 notes or chords being alternated, while tremolos consisting of the
493 rapid repetition of a single note are indicated by adding beams or
494 slashes to a single note.
495
496 To place tremolo marks between notes, use @code{\repeat} with
497 tremolo style:
498
499 @lilypond[quote,verbatim,relative=2]
500 \repeat tremolo 8 { c16 d }
501 \repeat tremolo 6 { c16 d }
502 \repeat tremolo 2 { c16 d }
503 @end lilypond
504
505 The @code{\repeat tremolo} syntax expects exactly two notes within
506 the braces, and the number of repetitions must correspond to a
507 note value that can be expressed with plain or dotted notes.  Thus,
508 @code{\repeat tremolo 7} is valid and produces a double dotted
509 note, but @code{\repeat tremolo 9} is not.
510
511 The duration of the tremolo equals the duration of the
512 braced expression multiplied by the number of repeats:
513 @code{\repeat tremolo 8 @{ c16 d16 @}} gives a whole note tremolo,
514 notated as two whole notes joined by tremolo beams.
515
516 There are two ways to put tremolo marks on a single note.  The
517 @code{\repeat tremolo} syntax is also used here, in which case
518 the note should not be surrounded by braces:
519
520 @lilypond[quote,verbatim,ragged-right]
521 \repeat tremolo 4 c'16
522 @end lilypond
523
524 @cindex tremolo marks
525 @funindex tremoloFlags
526 @funindex :
527
528 The same output can be obtained by adding
529 @q{@code{:}[@var{number}]} after the note.  The number indicates
530 the duration of the subdivision, and it must be at least 8.  A
531 @var{number} value of 8 gives one line across the note stem.  If
532 the length is omitted, the last value (stored in
533 @code{tremoloFlags}) is used:
534
535 @lilypond[quote,verbatim,relative=2]
536 c2:8 c:32
537 c: c:
538 @end lilypond
539
540 @snippets
541
542 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
543 {cross-staff-tremolos.ly}
544
545
546 @seealso
547 Snippets:
548 @rlsr{Repeats}.
549
550 @cindex tremolo, cross-staff
551 @cindex cross-staff tremolo
552
553 @knownissues
554
555 Cross-staff tremolos do not work well.
556