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