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 @node Repeats
  10 @section Repeats
  11
  12 Repetition is a central concept in music, and multiple notations
  13 exist for repetitions.
  14
  15 @menu
  16 * Writing repeats::
  17 * Other repeats::
  18 @end menu
  19
  20 @node Writing repeats
  21 @subsection Writing repeats
  22
  23 Blah blah
  24
  25 @menu
  26 * Normal repeats::
  27 * Repeat syntax::
  28 * Manual repeat commands::
  29 * Repeats and MIDI::
  30 @end menu
  31
  32 @node Normal repeats
  33 @unnumberedsubsubsec Normal repeats
  34
  35 @cindex volta
  36 @cindex prima volta
  37 @cindex seconda volta
  38 @funindex \repeat
  39
  40 Normal repeats, with or without alternate repeats, may be printed:
  41
  42 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
  43 \repeat volta 2 { c4 d e f }
  44 \repeat volta 2 { g f e d }
  45   \alternative {
  46     { cis2 g' }
  47     { cis,2 b }
  48   }
  49 c1
  50 @end lilypond
  51
  52 Repeats with upbeats may be created.
  53
  54 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
  55 \new Staff {
  56   \partial 4 e |
  57   \repeat volta 4 { c2 d2 | e2 f2 | }
  58   \alternative { { g4 g g e } { a a a a | b2. } }
  59 }
  60 @end lilypond
  61
  62 @noindent
  63 or
  64
  65 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
  66 \new Staff {
  67   \partial 4
  68   \repeat volta 4 { e | c2 d2 | e2 f2 | }
  69   \alternative { { \partial 4*3 g4 g g } { a a a a | b2. } }
  70 }
  71 @end lilypond
  72
  73
  74 @funindex \repeatTie
  75
  76 Ties may be added to a second ending,
  77
  78 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
  79 c1
  80 \repeat volta 2 {c4 d e f ~ }
  81 \alternative { {f2 d} {f\repeatTie f,} }
  82 @end lilypond
  83
  84 It is possible to shorten volta brackets by setting
  85 @code{voltaSpannerDuration}.  In the next example, the bracket
  86 only lasts one measure, which is a duration of 3/4.
  87
  88 @lilypond[verbatim,ragged-right,quote]
  89 \relative c''{
  90   \time 3/4
  91   c c c
  92   \set Score.voltaSpannerDuration = #(ly:make-moment 3 4)
  93   \repeat volta 5 { d d d }
  94   \alternative { { e e e f f f }
  95   { g g g } }
  96 }
  97 @end lilypond
  98
  99 If you want to start a repeat at the beginning of a line and have
 100 a double bar at the end of the previous line, use
 101
 102 @example
 103 @dots{} \bar "||:" \break
 104 \repeat volta 2 @{ @dots{}
 105 @end example
 106
 107 see @ref{Bar lines} for more information.
 108
 109 @seealso
 110
 111 Internals Reference: @internalsref{VoltaBracket},
 112 @internalsref{RepeatedMusic},
 113 @internalsref{VoltaRepeatedMusic}, and
 114 @internalsref{UnfoldedRepeatedMusic}.
 115
 116 Examples:
 117
 118 Brackets for the repeat are normally only printed over the topmost
 119 staff.  This can be adjusted by moving @code{Volta_engraver} to
 120 the Staff context where you want the brackets to appear; see
 121 @ref{Modifying context plug-ins} and
 122 @lsr{repeats,volta@/-multi@/-staff@/.ly}.
 123
 124
 125 @refbugs
 126
 127 @cindex repeat, ambiguous
 128
 129 A nested repeat like
 130
 131 @example
 132 \repeat @dots{}
 133 \repeat @dots{}
 134 \alternative
 135 @end example
 136
 137 @noindent
 138 is ambiguous, since it is is not clear to which @code{\repeat} the
 139 @code{\alternative} belongs.  This ambiguity is resolved by always
 140 having the @code{\alternative} belong to the inner @code{\repeat}.
 141 For clarity, it is advisable to use braces in such situations.
 142
 143 Timing information is not remembered at the start of an
 144 alternative, so after a repeat timing information must be reset by
 145 hand; for example, by setting @code{Score.measurePosition} or
 146 entering @code{\partial}.  Similarly, slurs or ties are also not
 147 repeated.
 148
 149
 150
 151 @node Repeat syntax
 152 @unnumberedsubsubsec Repeat syntax
 153
 154 @cindex repeats
 155
 156 LilyPond has one syntactic construct for specifying different
 157 types of repeats.  The syntax is
 158
 159 @example
 160 \repeat @var{variant} @var{repeatcount} @var{repeatbody}
 161 @end example
 162
 163 If you have alternative endings, you may add
 164 @funindex \alternative
 165 @example
 166 \alternative @{
 167   @var{alternative1}
 168   @var{alternative2}
 169   @var{alternative3}
 170   @dots{}
 171 @}
 172 @end example
 173
 174 @noindent
 175 where each @var{alternative} is a music expression.  If you do not
 176 give enough alternatives for all of the repeats, the first
 177 alternative is assumed to be played more than once.
 178
 179 The following types of repetition are supported
 180
 181 @table @code
 182 @item unfold
 183 Repeated music is fully written (played) out.  This is useful when
 184 entering repetitious music.  This is the only kind of repeat that
 185 is included in MIDI output.
 186
 187 @item volta
 188 Repeats are not written out, but alternative endings (volte) are
 189 printed, left to right with brackets.  This is the standard
 190 notation for repeats with alternatives.  These are not played in
 191 MIDI output by default.
 192
 193
 194 @item tremolo
 195 Make tremolo beams.  These are not played in MIDI output by
 196 default.
 197
 198 @item percent
 199 Make beat or measure repeats.  These look like percent signs.
 200 These are not played in MIDI output by default.  Percent repeats
 201 must be declared within a @code{Voice} context.
 202
 203 @end table
 204
 205
 206 @node Manual repeat commands
 207 @unnumberedsubsubsec Manual repeat commands
 208
 209 @funindex repeatCommands
 210
 211 The property @code{repeatCommands} can be used to control the
 212 layout of repeats.  Its value is a Scheme list of repeat commands.
 213
 214 @table @asis
 215 @item @code{start-repeat}
 216 Print a @code{|:} bar line.
 217
 218 @item @code{end-repeat}
 219 Print a @code{:|} bar line.
 220
 221 @item @code{(volta @var{text})}
 222 Print a volta bracket saying @var{text}: The text can be specified
 223 as a text string or as a markup text, see @ref{Text markup}.  Do
 224 not forget to change the font, as the default number font does not
 225 contain alphabetic characters;
 226
 227 @item @code{(volta #f)}
 228 Stop a running volta bracket.
 229 @end table
 230
 231 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 232 c4
 233   \set Score.repeatCommands = #'((volta "93") end-repeat)
 234 c4 c4
 235   \set Score.repeatCommands = #'((volta #f))
 236 c4 c4
 237 @end lilypond
 238
 239
 240 @seealso
 241
 242 Internals Reference: @internalsref{VoltaBracket},
 243 @internalsref{RepeatedMusic}, @internalsref{VoltaRepeatedMusic},
 244 and @internalsref{UnfoldedRepeatedMusic}.
 245
 246 @node Repeats and MIDI
 247 @unnumberedsubsubsec Repeats and MIDI
 248
 249 @cindex expanding repeats
 250 @funindex \unfoldRepeats
 251
 252 With a little bit of tweaking, all types of repeats can be present
 253 in the MIDI output.  This is achieved by applying the
 254 @code{\unfoldRepeats} music function.  This function changes all
 255 repeats to unfold repeats.
 256
 257 @lilypond[quote,verbatim,fragment,line-width=8.0\cm]
 258 \unfoldRepeats {
 259   \repeat tremolo 8 {c'32 e' }
 260   \repeat percent 2 { c''8 d'' }
 261   \repeat volta 2 {c'4 d' e' f'}
 262   \alternative {
 263     { g' a' a' g' }
 264     {f' e' d' c' }
 265   }
 266 }
 267 \bar "|."
 268 @end lilypond
 269
 270 When creating a score file using @code{\unfoldRepeats} for MIDI,
 271 it is necessary to make two @code{\score} blocks: one for MIDI
 272 (with unfolded repeats) and one for notation (with volta, tremolo,
 273 and percent repeats).  For example,
 274
 275 @example
 276 \score @{
 277   @var{..music..}
 278   \layout @{ .. @}
 279 @}
 280 \score @{
 281   \unfoldRepeats @var{..music..}
 282   \midi @{ .. @}
 283 @}
 284 @end example
 285
 286
 287 @node Other repeats
 288 @subsection Other repeats
 289
 290 @menu
 291 * Tremolo repeats::
 292 * Tremolo subdivisions::
 293 * Measure repeats::
 294 @end menu
 295
 296 @node Tremolo repeats
 297 @unnumberedsubsubsec Tremolo repeats
 298
 299 @cindex tremolo beams
 300
 301 To place tremolo marks between notes, use @code{\repeat} with
 302 tremolo style
 303
 304 @lilypond[quote,verbatim,ragged-right]
 305 \new Voice \relative c' {
 306   \repeat tremolo 8 { c16 d16 }
 307   \repeat tremolo 4 { c16 d16 }
 308   \repeat tremolo 2 { c16 d16 }
 309 }
 310 @end lilypond
 311
 312 Tremolo marks can also be put on a single note.  In this case, the
 313 note should not be surrounded by braces.
 314
 315 @lilypond[quote,verbatim,ragged-right]
 316 \repeat tremolo 4 c'16
 317 @end lilypond
 318
 319 Similar output is obtained using the tremolo subdivision,
 320 described in @ref{Tremolo subdivisions}.
 321
 322
 323 @seealso
 324
 325 In this manual: @ref{Tremolo subdivisions}, @ref{Repeats}.
 326
 327 Internals Reference: @internalsref{Beam},
 328 @internalsref{StemTremolo}.
 329
 330
 331 @node Tremolo subdivisions
 332 @unnumberedsubsubsec Tremolo subdivisions
 333
 334 @cindex tremolo marks
 335 @funindex tremoloFlags
 336
 337 Tremolo marks can be printed on a single note by adding
 338 @q{@code{:}[@var{number}]} after the note.  The number indicates
 339 the duration of the subdivision, and it must be at least 8.  A
 340 @var{length} value of 8 gives one line across the note stem.  If
 341 the length is omitted, the last value (stored in
 342 @code{tremoloFlags}) is used
 343
 344 @lilypond[quote,ragged-right,verbatim,fragment]
 345 c'2:8 c':32 | c': c': |
 346 @end lilypond
 347
 348
 349 @refbugs
 350
 351 Tremolos entered in this way do not carry over into the MIDI
 352 output.
 353
 354
 355 @seealso
 356
 357 In this manual: @ref{Tremolo repeats}.
 358
 359 Elsewhere: @internalsref{StemTremolo}.
 360
 361
 362 @node Measure repeats
 363 @unnumberedsubsubsec Measure repeats
 364
 365 @cindex percent repeats
 366 @cindex measure repeats
 367
 368 In the @code{percent} style, a note pattern can be repeated.  It
 369 is printed once, and then the pattern is replaced with a special
 370 sign.  Patterns of one and two measures are replaced by
 371 percent-like signs, patterns that divide the measure length are
 372 replaced by slashes.  Percent repeats must be declared within a
 373 @code{Voice} context.
 374
 375 @lilypond[quote,verbatim,ragged-right]
 376 \new Voice \relative c' {
 377   \repeat percent 4 { c4 }
 378   \repeat percent 2 { c2 es2 f4 fis4 g4 c4 }
 379 }
 380 @end lilypond
 381
 382 Measure repeats of more than 2 measures get a counter, if you
 383 switch on the @code{countPercentRepeats} property,
 384
 385 @lilypond[relative=2,fragment,quote,verbatim,ragged-right]
 386 \new Voice {
 387 \set countPercentRepeats = ##t
 388   \repeat percent 4 { c1 }
 389 }
 390 @end lilypond
 391
 392
 393
 394 Isolated percents can also be printed.  This is done by putting a
 395 multi-measure rest with a different print function,
 396
 397 @lilypond[fragment,verbatim,quote]
 398 \override MultiMeasureRest #'stencil
 399   = #ly:multi-measure-rest::percent
 400 R1
 401 @end lilypond
 402
 403
 404
 405
 406 @seealso
 407
 408 Internals Reference: @internalsref{RepeatSlash},
 409 @internalsref{PercentRepeat}, @internalsref{DoublePercentRepeat},
 410 @internalsref{DoublePercentRepeatCounter},
 411 @internalsref{PercentRepeatCounter},
 412 @internalsref{PercentRepeatedMusic}.
 413
 414
 415