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