Documentation/user/repeats.itely

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