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