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