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