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