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