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