]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/user/basic-notation.itely
Fix @ref{}s to accomodate new chapter names.
[lilypond.git] / Documentation / user / basic-notation.itely
1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond.tely
3
4 @c A menu is needed before every deeper *section nesting of @node's; run
5 @c     M-x texinfo-all-menus-update
6 @c to automatically fill in these menus before saving changes
7
8 @node Basic notation
9 @chapter Basic notation
10
11 This chapter explains how to use basic notation features.
12
13 @menu
14 * Pitches::                     
15 * Rhythms::                     
16 * Multiple notes at once::      
17 * Staff notation::              
18 * Connecting notes::            
19 * Expressive marks::            
20 * Repeats::                     
21 @end menu
22
23
24
25 @node Pitches
26 @section Pitches
27
28 This section discusses how to specify the pitch of notes.
29
30 @menu
31 * Normal pitches::              
32 * Accidentals::                 
33 * Cautionary accidentals::      
34 * Micro tones::                 
35 * Notes names in other languages::  
36 * Relative octaves::            
37 * Octave check::                
38 * Transpose::                   
39 * Rests::                       
40 * Skips::                       
41 @end menu
42
43
44 @node Normal pitches
45 @subsection Normal pitches
46
47 @cindex Pitch names
48 @cindex pitches
49
50 A pitch name is specified using lowercase letters @code{a} through @code{g}.
51 An ascending C-major scale is engraved with
52
53 @lilypond[quote,fragment,verbatim,ragged-right]
54 \clef bass
55 c d e f g a b c'
56 @end lilypond
57
58 The note name @code{c} is engraved one octave below middle C.
59
60 @lilypond[quote,fragment,verbatim,ragged-right]
61 \clef treble
62 c1
63 \clef bass
64 c1
65 @end lilypond
66
67 @findex '
68 @findex ,
69
70 The optional octave specification takes the form of a series of
71 single quote (`@code{'}') characters or a series of comma
72 (`@code{,}') characters.  Each @code{'} raises the pitch by one
73 octave; each @code{,} lowers the pitch by an octave.
74
75 @lilypond[quote,ragged-right,fragment,verbatim]
76 \clef treble
77 c' c'' e' g d'' d' d c
78 \clef bass
79 c, c,, e, g d,, d, d c
80 @end lilypond
81
82 An alternate method may be used to declare which octave to
83 engrave a pitch; this method does not require as many
84 octave specifications (@code{'} and @code{,}).  See
85 @ref{Relative octaves}.
86
87
88 @node Accidentals
89 @subsection Accidentals
90
91 @cindex note names, Dutch
92 @cindex note names, default
93
94 A sharp is formed by adding @code{-is} to the end of a pitch name and
95 a flat is formed by adding @code{-es}
96
97 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
98 a2 ais a aes
99 @end lilypond
100
101 Double sharps and double flats
102 are obtained by adding @code{-isis} or @code{-eses} to a note name.  These
103 are the Dutch note names.  In Dutch, @code{aes} is contracted to
104 @code{as}, but both forms are accepted.  Similarly, both
105 @code{es} and @code{ees} are accepted
106
107 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
108 a2 aisis a aeses
109 @end lilypond
110
111 A natural will cancel the effect of an accidental or key signature.
112 However, naturals are not encoded into the note name syntax with a
113 suffix; a natural pitch is shown as a simple note name
114
115 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
116 a4 aes a2
117 @end lilypond
118
119
120 @commonprop
121
122 In accordance with standard typesetting rules, a natural sign is printed
123 before a sharp or flat if a previous accidental needs to be
124 cancelled.  To change this behavior, use
125 @code{\set Staff.extraNatural = ##f}
126
127 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
128 ceses4 ces cis c
129 \set Staff.extraNatural = ##f
130 ceses4 ces cis c
131 @end lilypond
132
133
134 @seealso
135
136 Program reference: @internalsref{LedgerLineSpanner},
137 @internalsref{NoteHead}.
138
139
140 @node Cautionary accidentals
141 @subsection Cautionary accidentals
142
143 @cindex accidental, reminder
144 @cindex accidental, cautionary
145 @cindex accidental, parenthesized
146 @cindex reminder accidental
147 @findex ?
148 @cindex cautionary accidental
149 @cindex parenthesized accidental
150 @findex !
151
152 Normally accidentals are printed automatically, but you may also
153 print them manually.  A reminder accidental
154 can be forced by adding an exclamation mark @code{!}
155 after the pitch.  A cautionary accidental
156 (i.e., an accidental within parentheses) can be obtained by adding the
157 question mark `@code{?}' after the pitch.  These extra accidentals
158 can be used to produce natural signs, too.
159
160 @lilypond[quote,ragged-right,fragment,verbatim,relative=1]
161 cis cis cis! cis? c c? c! c
162 @end lilypond
163
164
165 @seealso
166
167 The automatic production of accidentals can be tuned in many
168 ways.  For more information, see @ref{Automatic accidentals}.
169
170
171 @node Micro tones
172 @subsection Micro tones
173
174 @cindex quarter tones
175 @cindex semi-flats, semi-sharps
176
177 Half-flats and half-sharps are formed by adding @code{-eh} and
178 @code{-ih}; the following is a series of Cs with increasing pitches
179
180 @lilypond[verbatim,ragged-right,quote,relative=2,fragment]
181 \set Staff.extraNatural = ##f
182 ceseh ceh cih cisih
183 @end lilypond
184
185 Micro tones are also exported to the MIDI file.
186
187
188 @refbugs
189
190 There are no generally accepted standards for denoting
191 three-quarter flats, so LilyPond's symbol does not conform to any
192 standard.
193
194
195 @node Notes names in other languages
196 @subsection Notes names in other languages
197
198 There are predefined sets of note names for various other languages.
199 To use them, include the language specific init file.  For
200 example, add @code{\include "english.ly"} to the top of the input
201 file.  The available language files
202 and the note names they define are
203
204 @c  what about micro-tunes, double-sharps, and double-flats?  add
205 @c  more clumns to the table?
206 @c  Oh, and should this be made into a multitable?
207 @cindex note names, other languages
208 @example
209                         Note Names               sharp       flat
210 nederlands.ly  c   d   e   f   g   a   bes b   -is         -es
211 english.ly     c   d   e   f   g   a   bf  b   -s/-sharp   -f/-flat
212                                                -x (double)
213 deutsch.ly     c   d   e   f   g   a   b   h   -is         -es
214 norsk.ly       c   d   e   f   g   a   b   h   -iss/-is    -ess/-es
215 svenska.ly     c   d   e   f   g   a   b   h   -iss        -ess
216 italiano.ly    do  re  mi  fa  sol la  sib si  -d          -b
217 catalan.ly     do  re  mi  fa  sol la  sib si  -d/-s       -b
218 espanol.ly     do  re  mi  fa  sol la  sib si  -s          -b
219 @end example
220
221
222 @node Relative octaves
223 @subsection Relative octaves
224
225 @cindex Relative
226 @cindex Relative octave specification
227 @funindex \relative
228
229 Octaves are specified by adding @code{'} and @code{,} to pitch names.
230 When you copy existing music, it is easy to accidentally put a pitch
231 in the wrong octave and hard to find such an error.  The relative
232 octave mode prevents these errors by making the mistakes much
233 larger: a single error puts the rest of the piece off by one octave
234
235 @example
236 \relative @var{startpitch} @var{musicexpr}
237 @end example
238
239 @noindent
240 or
241
242 @example
243 \relative @var{musicexpr}
244 @end example
245
246 @noindent
247 @code{c'} is used as the default if no starting pitch is defined.
248
249 The octave of notes that appear in @var{musicexpr} are calculated as
250 follows: if no octave changing marks are used, the basic interval
251 between this and the last note is always taken to be a fourth or
252 less.  This distance is determined without regarding alterations; a
253 @code{fisis} following a @code{ceses} will be put above the
254 @code{ceses}.  In other words, a doubly-augmented fourth is considered
255 a smaller interval than a diminished fifth, even though the
256 doubly-augmented fourth spans seven semitones while the diminished
257 fifth only spans six semitones.
258
259 The octave changing marks @code{'} and @code{,} can be added to raise
260 or lower the pitch by an extra octave.  Upon entering relative mode,
261 an absolute starting pitch can be specified that will act as the
262 predecessor of the first note of @var{musicexpr}.  If no starting pitch
263 is specified, then middle C is used as a start.
264
265 Here is the relative mode shown in action
266 @lilypond[quote,fragment,ragged-right,verbatim]
267 \relative c'' {
268   b c d c b c bes a
269 }
270 @end lilypond
271
272 Octave changing marks are used for intervals greater than a fourth
273 @lilypond[quote,ragged-right,fragment,verbatim]
274 \relative c'' {
275   c g c f, c' a, e''
276 }
277 @end lilypond
278
279 If the preceding item is a chord, the first note of the chord is used
280 to determine the first note of the next chord
281
282 @lilypond[quote,ragged-right,fragment,verbatim]
283 \relative c' {
284   c <c e g>
285   <c' e g>
286   <c, e' g>
287 }
288 @end lilypond
289
290 The pitch after the @code{\relative} contains a note name.
291
292 The relative conversion will not affect @code{\transpose},
293 @code{\chordmode} or @code{\relative} sections in its argument.  To use
294 relative within transposed music, an additional @code{\relative} must
295 be placed inside @code{\transpose}.
296
297
298 @node Octave check
299 @subsection Octave check
300
301 @cindex Octave check
302
303 Octave checks make octave errors easier to correct: a note may be
304 followed by @code{=}@var{quotes} which indicates what its absolute
305 octave should be.  In the following example,
306
307 @example
308 \relative c'' @{ c='' b=' d,='' @}
309 @end example
310
311 @noindent
312 the @code{d} will generate a warning, because a @code{d''} is expected
313 (because @code{b'} to @code{d''} is only a third), but a @code{d'} is
314 found.  In the output, the octave is corrected to be a @code{d''} and
315 the next note is calculated relative to @code{d''} instead of @code{d'}.
316
317 There is also an octave check that produces no visible output.  The syntax
318
319 @example
320 \octave @var{pitch}
321 @end example
322
323 This checks that @var{pitch} (without quotes) yields @var{pitch} (with
324 quotes) in @code{\relative} mode.  If not, a warning is printed, and the
325 octave is corrected.  The @var{pitch} is not printed as a note.
326
327 In the example below, the first check passes without incident, since
328 the @code{e} (in relative mode) is within a fifth of @code{a'}.  However,
329 the second check produces a warning, since the @code{e} is not within
330 a fifth of @code{b'}.  The warning message is printed, and the octave
331 is adjusted so that the following notes are in the correct octave
332 once again.
333
334 @example
335 \relative c' @{
336   e
337   \octave a'
338   \octave b'
339 @}
340 @end example
341
342
343 The octave of a note following an octave check is determined with
344 respect to the note preceding it.  In the next fragment, the last note
345 is an @code{a'}, above middle C.  That means that the @code{\octave}
346 check passes successfully, so the check could be deleted without changing
347 the output of the piece.
348
349 @lilypond[quote,ragged-right,verbatim,fragment]
350 \relative c' {
351   e
352   \octave b
353   a
354 }
355 @end lilypond
356
357
358 @node Transpose
359 @subsection Transpose
360
361 @cindex Transpose
362 @cindex Transposition of pitches
363 @findex \transpose
364
365 A music expression can be transposed with @code{\transpose}.  The
366 syntax is
367 @example
368 \transpose @var{from} @var{to} @var{musicexpr}
369 @end example
370
371 This means that @var{musicexpr} is transposed by the interval between
372 the pitches @var{from} and @var{to}: any note with pitch @code{from}
373 is changed to @code{to}.
374
375 For example, consider a piece written in the key of D-major.  If
376 this piece is a little too low for its performer, it can be
377 transposed up to E-major with
378 @example
379 \transpose d e @dots{}
380 @end example
381
382 Consider a part written for violin (a C instrument).  If
383 this part is to be played on the A clarinet (for which an
384 A is notated as a C, and which sounds a minor third lower
385 than notated), the following
386 transposition will produce the appropriate part
387
388 @example
389 \transpose a c @dots{}
390 @end example
391
392 @code{\transpose} distinguishes between enharmonic pitches: both
393 @code{\transpose c cis} or @code{\transpose c des} will transpose up
394 half a tone.  The first version will print sharps and the second
395 version will print flats
396
397 @lilypond[quote,ragged-right,verbatim]
398 mus = { \key d \major cis d fis g }
399 \new Staff {
400   \clef "F" \mus
401   \clef "G"
402   \transpose c g' \mus
403   \transpose c f' \mus
404 }
405 @end lilypond
406
407 @code{\transpose} may also be used to input written notes for a
408 transposing instrument.  Pitches are normally entered into LilyPond
409 in C (or ``concert pitch''), but they may be entered in another
410 key.  For example, when entering music for a B-flat trumpet which
411 begins on concert D, one would write
412
413 @example
414 \transpose c bes @{ e4 @dots{} @}
415 @end example
416
417 To print this music in B-flat again (i.e. producing a trumpet part,
418 instead of a concert pitch conductor's score) you would wrap the
419 existing music with another @code{transpose}
420
421 @example
422 \transpose bes c @{ \transpose c bes @{ e4 @dots{} @} @}
423 @end example
424
425
426 @seealso
427
428 Program reference: @internalsref{TransposedMusic}.
429
430
431 @refbugs
432
433 If you want to use both @code{\transpose} and @code{\relative},
434 you must put @code{\transpose} outside of @code{\relative}, since
435 @code{\relative} will have no effect music that appears inside a
436 @code{\transpose}.
437
438
439 @node Rests
440 @subsection Rests
441 @cindex Rests
442
443 @findex \rest
444 @findex r
445
446 Rests are entered like notes with the note name @code{r}
447
448 @lilypond[fragment,quote,ragged-right,verbatim]
449 r1 r2 r4 r8
450 @end lilypond
451
452 Whole bar rests, centered in middle of the bar,
453 must be done with multi-measure rests.  They can be used for a
454 single bar as well as many bars, and are discussed in
455 @ref{Multi measure rests}.
456
457 To explicitly specify a rest's vertical position, write a note
458 followed by @code{\rest}.  A rest will be placed in the position
459 where the note would appear,
460
461 @lilypond[fragment,quote,ragged-right,verbatim]
462 a'4\rest d'4\rest
463 @end lilypond
464
465 @noindent
466 This makes manual formatting of
467 polyphonic music much easier, since the automatic rest collision
468 formatter will leave these rests alone.
469
470 @seealso
471
472 Program reference: @internalsref{Rest}.
473
474
475 @node Skips
476 @subsection Skips
477
478 @cindex Skip
479 @cindex Invisible rest
480 @cindex Space note
481 @findex \skip
482 @findex s
483
484 An invisible rest (also called a `skip') can be entered like a note
485 with note name `@code{s}' or with @code{\skip @var{duration}}
486
487 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
488 a4 a4 s4 a4 \skip 1 a4
489 @end lilypond
490
491 The @code{s} syntax is only available in note mode and chord mode.  In
492 other situations, for example, when entering lyrics, you should use
493 the @code{\skip} command
494
495 @lilypond[quote,ragged-right,verbatim]
496 <<
497   \relative { a'2 a2 }
498   \new Lyrics \lyricmode { \skip 2 bla2 }
499 >>
500 @end lilypond
501
502 The skip command is merely an empty musical placeholder.  It does not
503 produce any output, not even transparent output.
504
505 The @code{s} skip command does create @internalsref{Staff} and
506 @internalsref{Voice} when necessary, similar to note and rest
507 commands.  For example, the following results in an empty staff.
508
509 @lilypond[quote,ragged-right,verbatim]
510 { s4 }
511 @end lilypond
512
513 The fragment @code{@{ \skip 4 @} } would produce an empty page.
514
515 @seealso
516
517 Program reference: @internalsref{SkipMusic}.
518
519
520
521 @node Rhythms
522 @section Rhythms
523
524 This section discusses rhythms, durations, and bars.
525
526 @menu
527 * Durations::                   
528 * Augmentation dots::           
529 * Tuplets::                     
530 * Scaling durations::           
531 * Bar check::                   
532 * Barnumber check::             
533 * Automatic note splitting::    
534 @end menu
535
536
537 @node Durations
538 @subsection Durations
539
540 @cindex duration
541 @findex \longa
542 @findex \breve
543 @findex \maxima
544
545 In Note, Chord, and Lyrics mode, durations are designated by numbers and
546 dots: durations are entered as their reciprocal values.  For example, a
547 quarter note is entered using a @code{4} (since it is a 1/4 note), while
548 a half note is entered using a @code{2} (since it is a 1/2 note).  For
549 notes longer than a whole you must use the variables @code{\longa} and
550 @code{\breve}
551
552 @example
553 c'\breve
554 c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
555 r\longa r\breve
556 r1 r2 r4 r8 r16 r32 r64 r64
557 @end example
558
559 @lilypond[quote]
560 \score {
561 \relative c'' {
562     a\breve*1/2 \autoBeamOff
563     a1 a2 a4 a8 a16 a32 a64 a64
564    \bar "empty"
565    \break
566     r\longa*1/4 r\breve *1/2
567     r1 r2 r4 r8 r16 r32 r64 r64
568   }
569   \layout {
570     ragged-right = ##t
571     \context {
572       \Staff
573         \remove "Clef_engraver"
574         \override StaffSymbol #'transparent = ##t
575         \override TimeSignature #'transparent = ##t
576         \override BarLine #'transparent = ##t
577         \consists "Pitch_squash_engraver"
578     }
579   }
580 }
581 @end lilypond
582
583 If the duration is omitted then it is set to the previously entered
584 duration.  The default for the first note is a quarter note.
585
586 @lilypond[quote,ragged-right,verbatim,fragment]
587 { a a a2 a a4 a a1 a }
588 @end lilypond
589
590
591 @node Augmentation dots
592 @subsection Augmentation dots
593
594 @findex .
595
596 To obtain dotted note lengths, simply add a dot (`@code{.}') to
597 the number.  Double-dotted notes are produced in a similar way.
598
599 @lilypond[quote,ragged-right,fragment,verbatim]
600 a'4 b' c''4. b'8 a'4. b'4.. c''8.
601 @end lilypond
602
603 @refcommands
604
605 Dots are normally moved up to avoid staff lines, except in polyphonic
606 situations.  The following commands may be used to force a particular
607 direction manually
608
609 @findex \dotsUp
610 @code{\dotsUp},
611 @findex \dotsDown
612 @code{\dotsDown},
613 @findex \dotsNeutral
614 @code{\dotsNeutral}.
615
616 @seealso
617
618 Program reference: @internalsref{Dots}, and @internalsref{DotColumn}.
619
620
621 @node Tuplets
622 @subsection Tuplets
623
624 @cindex tuplets
625 @cindex triplets
626 @findex \times
627
628 Tuplets are made out of a music expression by multiplying all durations
629 with a fraction
630
631 @example
632 \times @var{fraction} @var{musicexpr}
633 @end example
634
635 @noindent
636 The duration of @var{musicexpr} will be multiplied by the fraction.
637 The fraction's denominator will be printed over the notes, optionally
638 with a bracket.  The most common tuplet is the triplet in which 3
639 notes have the length of 2, so the notes are 2/3 of their written
640 length
641
642 @lilypond[quote,ragged-right,fragment,verbatim]
643 g'4 \times 2/3 {c'4 c' c'} d'4 d'4
644 @end lilypond
645
646 Tuplets may be nested, for example,
647
648 @lilypond[fragment,ragged-right,verbatim,relative=2]
649 \set tupletNumberFormatFunction = #fraction-tuplet-formatter
650 \times 4/6 {
651   a4 a
652   \times 3/5 { a a a a a }
653 }
654 @end lilypond
655
656 @refcommands
657
658 @findex \tupletUp
659 @code{\tupletUp},
660 @findex \tupletDown
661 @code{\tupletDown},
662 @findex \tupletNeutral
663 @code{\tupletNeutral}.
664
665
666 @commonprop
667
668 @findex tupletNumberFormatFunction
669 @cindex tuplet formatting
670
671 The property @code{tupletSpannerDuration} specifies how long each
672 bracket should last.  With this, you can make lots of tuplets while
673 typing @code{\times} only once, thus saving lots of typing.  In the next
674 example, there are two triplets shown, while @code{\times} was only
675 used once
676
677 @lilypond[quote,fragment,relative=2,ragged-right,verbatim]
678 \set tupletSpannerDuration = #(ly:make-moment 1 4)
679 \times 2/3 { c8 c c c c c }
680 @end lilypond
681
682 @noindent
683 For more information about @code{make-moment}, see
684 @ref{Time administration}.
685
686 The format of the number is determined by the property
687 @code{tupletNumberFormatFunction}.  The default prints only the
688 denominator, but if it is set to the Scheme function
689 @code{fraction-tuplet-formatter}, @var{num}:@var{den} will be printed
690 instead.
691
692 To avoid printing tuplet numbers, use
693
694 @lilypond[quote,fragment,relative=2,ragged-right,verbatim]
695 \times 2/3 { c8 c c } \times 2/3 { c8 c c }
696 \override TupletNumber #'transparent = ##t
697 \times 2/3 { c8 c c } \times 2/3 { c8 c c }
698 @end lilypond
699
700
701 @seealso
702
703 Program reference: @internalsref{TupletBracket},
704 @internalsref{TupletNumber}, and @internalsref{TimeScaledMusic}.
705
706 Examples: @inputfileref{input/@/regression,tuplet@/-nest@/.ly}.
707
708
709
710 @node Scaling durations
711 @subsection Scaling durations
712
713 You can alter the length of duration by a fraction @var{N/M}
714 appending `@code{*}@var{N/M}' (or `@code{*}@var{N}' if @var{M=1}).  This
715 will not affect the appearance of the notes or rests produced.
716
717 In the following example, the first three notes take up exactly two
718 beats, but no triplet bracket is printed.
719 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
720 \time 2/4
721 a4*2/3 gis4*2/3 a4*2/3
722 a4 a4 a4*2
723 b16*4 c4
724 @end lilypond
725
726
727 @seealso
728
729 This manual: @ref{Tuplets}
730
731
732 @node Bar check
733 @subsection Bar check
734
735 @cindex Bar check
736 @findex barCheckSynchronize
737 @findex |
738
739 Bar checks help detect errors in the durations.  A bar check is
740 entered using the bar symbol, `@code{|}'.  Whenever it is encountered
741 during interpretation, it should fall on a measure boundary.  If it
742 does not, a warning is printed.  In the next example, the second bar
743 check will signal an error
744 @example
745 \time 3/4 c2 e4 | g2 |
746 @end example
747
748 Bar checks can also be used in lyrics, for example
749
750 @example
751 \lyricmode @{
752   \time 2/4
753   Twin -- kle | Twin -- kle
754 @}
755 @end example
756
757 Failed bar checks are caused by entering incorrect
758 durations.  Incorrect durations often completely garble up the score,
759 especially if the score is polyphonic, so a good place to start correcting
760 input is by scanning for failed bar checks and incorrect durations.
761
762 @findex |
763 @findex pipeSymbol
764
765 It is also possible to redefine the meaning of @code{|}.  This is done
766 by assigning a music expression to @code{pipeSymbol},
767
768 @lilypond[quote,ragged-right,verbatim]
769 pipeSymbol = \bar "||"
770
771 { c'2 c' | c'2 c' }
772 @end lilypond
773
774
775 @node Barnumber check
776 @subsection Barnumber check
777
778 When copying large pieces of music, it can be helpful to check that
779 the LilyPond bar number corresponds to the original that you are
780 entering from.  This can be checked with @code{\barNumberCheck}, for
781 example,
782
783 @verbatim
784 \barNumberCheck #123
785 @end verbatim
786
787 @noindent
788 will print a warning if the @code{currentBarNumber} is not 123 when it
789 is processed.
790
791
792 @node Automatic note splitting
793 @subsection Automatic note splitting
794
795 Long notes can be converted automatically to tied notes.  This is done
796 by replacing the @internalsref{Note_heads_engraver} by the
797 @internalsref{Completion_heads_engraver}.
798 In the following examples, notes crossing the bar line are split and tied.
799
800 @lilypond[quote,fragment,verbatim,relative=1,line-width=12\cm]
801 \new Voice \with {
802   \remove "Note_heads_engraver"
803   \consists "Completion_heads_engraver"
804 } {
805   c2. c8 d4 e f g a b c8 c2 b4 a g16 f4 e d c8. c2
806 }
807 @end lilypond
808
809 This engraver splits all running notes at the bar line, and inserts
810 ties.  One of its uses is to debug complex scores: if the measures are
811 not entirely filled, then the ties exactly show how much each measure
812 is off.
813
814
815 @refbugs
816
817 Not all durations (especially those containing tuplets) can be
818 represented exactly with normal notes and dots, but the engraver will
819 not insert tuplets.
820
821 @code{Completion_heads_engraver} only affects notes; it does not split
822 rests.
823
824
825 @seealso
826
827 Examples: @inputfileref{input/@/regression,completion@/-heads@/.ly}.
828
829 @noindent
830
831 Program reference: @internalsref{Completion_heads_engraver}.
832
833
834 @node Multiple notes at once
835 @section Multiple notes at once
836
837 Polyphony in music refers to having more than one voice occurring in
838 a piece of music.  Polyphony in LilyPond refers to having more than
839 one voice on the same staff.
840
841 @menu
842 * Chords::                      
843 * Stems::                       
844 * Basic polyphony::             
845 * Explicitly instantiating voices::  
846 * Collision Resolution::        
847 @end menu
848
849
850 @node Chords
851 @subsection Chords
852
853 @cindex Chords
854
855 A chord is formed by a enclosing a set of pitches in @code{<} and
856 @code{>}.  A chord may be followed by a duration, and a set of
857 articulations, just like simple notes
858
859 @lilypond[verbatim,ragged-right,fragment,quote,relative=1]
860 <c e g>4 <c>8
861 @end lilypond
862
863 For more information about chords, see @ref{Chord names}.
864
865
866 @node Stems
867 @subsection Stems
868
869 Whenever a note is found, a @internalsref{Stem} object is created
870 automatically.  For whole notes and rests, they are also created but
871 made invisible.
872
873 @refcommands
874
875 @findex \stemUp
876 @code{\stemUp},
877 @findex \stemDown
878 @code{\stemDown},
879 @findex \stemNeutral
880 @code{\stemNeutral}.
881
882
883 @commonprop
884
885 To change the direction of stems in the middle of the staff, use
886
887 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
888 a4 b c b
889 \override Stem #'neutral-direction = #up
890 a4 b c b
891 \override Stem #'neutral-direction = #down
892 a4 b c b
893 @end lilypond
894
895
896 @node Basic polyphony
897 @subsection Basic polyphony
898
899 @cindex polyphony
900
901 The easiest way to enter fragments with more than one voice on a staff
902 is to enter each voice as a sequence (with @code{@{...@}}), and combine
903 them simultaneously, separating the voices with @code{\\}
904
905 @findex \\
906
907 @lilypond[quote,verbatim,fragment]
908 \new Staff \relative c' {
909   c16 d e f
910   <<
911     { g4 f e | d2 e2 } \\
912     { r8 e4 d c8 ~ | c b16 a b8 g ~ g2 } \\
913     { s2. | s4 b4 c2 }
914   >>
915 }
916 @end lilypond
917
918 The separator causes @internalsref{Voice} contexts@footnote{Polyphonic
919 voices are sometimes called ``layers'' in other notation packages}
920 @cindex layers
921 to be instantiated.  They bear the names @code{"1"}, @code{"2"}, etc.  In
922 each of these contexts, vertical direction of slurs, stems, etc., is set
923 appropriately.
924
925 These voices are all separate from the voice that contains the notes just
926 outside the @code{<< \\ >>} construct.  This should be noted when making
927 changes at the voice level.  This also means that slurs and ties cannot go
928 into or out of a @code{<< \\ >>} construct.  Conversely, parallel voices
929 from separate @code{<< \\ >>} constructs on the same staff are the the
930 same voice.  Here is the same example, with different noteheads for each
931 voice.  Note that the change to the note-head style in the main voice does
932 not affect
933 the inside of the @code{<< \\ >>} constructs.  Also, the change to the
934 second
935 voice in the first @code{<< \\ >>} construct is effective in the second
936 @code{<< \\ >>}, and the voice is tied across the two constructs.
937
938 @lilypond[quote,verbatim,fragment]
939 \new Staff \relative c' {
940   \override NoteHead #'style = #'cross
941   c16 d e f
942   <<
943     { g4 f e } \\
944     { \override NoteHead #'style = #'triangle
945     r8 e4 d c8 ~ }
946   >> |
947   <<
948     { d2 e2 } \\
949     { c8 b16 a b8 g ~ g2 } \\
950     { \override NoteHead #'style = #'slash s4 b4 c2 }
951   >>
952 }
953 @end lilypond
954
955 Polyphony does not change the relationship of notes within a
956 @code{\relative @{ @}} block.  Each note is calculated relative
957 to the note immediately preceding it.
958
959 @example
960 \relative @{ noteA << noteB \\ noteC >> noteD @}
961 @end example
962
963 @code{noteC} is relative to @code{noteB}, not @code{noteA};
964 @code{noteD} is relative to @code{noteC}, not @code{noteB} or
965 @code{noteA}.
966
967 @node Explicitly instantiating voices
968 @subsection Explicitly instantiating voices
969
970 @internalsref{Voice} contexts can also be instantiated manually
971 inside a @code{<< >>} block to create polyphonic music, using
972 @code{\voiceOne}, up to @code{\voiceFour} to assign stem directions
973 and a horizontal shift for each part.
974
975 Specifically,
976 @example
977 << \upper \\ \lower >>
978 @end example
979
980 @noindent
981 is equivalent to
982
983 @example
984 <<
985   \new Voice = "1" @{ \voiceOne \upper @}
986   \new Voice = "2" @{ \voiceTwo \lower @}
987 >>
988 @end example
989
990 The @code{\voiceXXX} commands set the direction of stems, slurs, ties,
991 articulations, text annotations, augmentation dots of dotted
992 notes, and fingerings.  @code{\voiceOne} and @code{\voiceThree} make
993 these objects point upwards, while @code{\voiceTwo} and @code{\voiceFour}
994 make them point downwards.
995 The command @code{\oneVoice} will revert back to the normal setting.
996
997 An expression that appears directly inside a @code{<< >>} belongs to
998 the main voice.  This is useful when extra voices appear while the main
999 voice is playing.  Here is a more correct rendition of the example from
1000 the previous section.  The crossed noteheads demonstrate that the main
1001 melody is now in a single voice context.
1002
1003 @lilypond[quote,ragged-right,verbatim]
1004 \new Staff \relative c' {
1005   \override NoteHead #'style = #'cross
1006   c16 d e f
1007   \voiceOne
1008   <<
1009     { g4 f e | d2 e2 }
1010     \new Voice="1" { \voiceTwo
1011       r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
1012       \oneVoice
1013     }
1014     \new Voice { \voiceThree
1015       s2. | s4 b4 c2
1016       \oneVoice
1017     }
1018   >>
1019   \oneVoice
1020 }
1021 @end lilypond
1022
1023 The correct definition of the voices allows the melody to be slurred.
1024 @lilypond[quote,ragged-right,verbatim]
1025 \new Staff \relative c' {
1026   c16^( d e f
1027   \voiceOne
1028   <<
1029     { g4 f e | d2 e2) }
1030     \context Voice="1" { \voiceTwo
1031       r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
1032       \oneVoice
1033     }
1034     \new Voice { \voiceThree
1035       s2. s4 b4 c2
1036       \oneVoice
1037     }
1038   >>
1039   \oneVoice
1040 }
1041 @end lilypond
1042
1043 Avoiding the @code{\\} separator also allows nesting polyphony
1044 constructs, which in some case might be a more natural way to typeset
1045 the music.
1046
1047 @lilypond[quote,ragged-right,verbatim]
1048 \new Staff \relative c' {
1049   c16^( d e f
1050   \voiceOne
1051   <<
1052     { g4 f e | d2 e2) }
1053     \context Voice="1" { \voiceTwo
1054       r8 e4 d c8 ~ |
1055       <<
1056         {c8 b16 a b8 g ~ g2}
1057         \new Voice { \voiceThree
1058           s4 b4 c2
1059           \oneVoice
1060         }
1061       >>
1062     \oneVoice
1063     }
1064   >>
1065   \oneVoice
1066 }
1067 @end lilypond
1068
1069
1070 @node Collision Resolution
1071 @subsection Collision Resolution
1072
1073 Normally, note heads with a different number of dots are not merged, but
1074 when the object property @code{merge-differently-dotted} is set in
1075 the @internalsref{NoteCollision} object, they are merged
1076 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
1077 \new Voice << {
1078   g8 g8
1079   \override Staff.NoteCollision
1080     #'merge-differently-dotted = ##t
1081   g8 g8
1082 } \\ { g8.[ f16] g8.[ f16] } >>
1083 @end lilypond
1084
1085 Similarly, you can merge half note heads with eighth notes, by setting
1086 @code{merge-differently-headed}
1087 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
1088 \new Voice << {
1089   c8 c4.
1090   \override Staff.NoteCollision
1091     #'merge-differently-headed = ##t
1092 c8 c4. } \\ { c2 c2 } >>
1093 @end lilypond
1094
1095 LilyPond also vertically shifts rests that are opposite of a stem,
1096 for example
1097
1098 @lilypond[quote,ragged-right,fragment,verbatim]
1099 \new Voice << c''4 \\ r4 >>
1100 @end lilypond
1101
1102
1103 @refcommands
1104
1105 @findex \oneVoice
1106 @code{\oneVoice},
1107 @findex \voiceOne
1108 @code{\voiceOne},
1109 @findex \voiceTwo
1110 @code{\voiceTwo},
1111 @findex \voiceThree
1112 @code{\voiceThree},
1113 @findex \voiceFour
1114 @code{\voiceFour}.
1115
1116 @findex \shiftOn
1117 @code{\shiftOn},
1118 @findex \shiftOnn
1119 @code{\shiftOnn},
1120 @findex \shiftOnnn
1121 @code{\shiftOnnn},
1122 @findex \shiftOff
1123 @code{\shiftOff}: these commands specify in what chords of the current
1124 voice should be shifted.  The outer voices (normally: voice one and
1125 two) have @code{\shiftOff}, while the inner voices (three and four)
1126 have @code{\shiftOn}.  @code{\shiftOnn} and @code{\shiftOnnn} define
1127 further shift levels.
1128
1129 When LilyPond cannot cope, the @code{force-hshift}
1130 property of the @internalsref{NoteColumn} object and pitched rests can
1131 be used to override typesetting decisions.
1132
1133 @lilypond[quote,verbatim,ragged-right]
1134 \relative <<
1135 {
1136   <d g>
1137   <d g>
1138 } \\ {
1139   <b f'>
1140   \once \override NoteColumn #'force-hshift = #1.7
1141   <b f'>
1142 } >>
1143 @end lilypond
1144
1145
1146 @seealso
1147
1148 Program reference: the objects responsible for resolving collisions are
1149 @internalsref{NoteCollision} and @internalsref{RestCollision}.
1150
1151 Examples:
1152 @inputfileref{input/@/regression,collision@/-dots@/.ly},
1153 @inputfileref{input/@/regression,collision@/-head-chords@/.ly},
1154 @inputfileref{input/@/regression,collision@/-heads@/.ly},
1155 @inputfileref{input/@/regression,collision@/-mesh@/.ly}, and
1156 @inputfileref{input/@/regression,collisions@/.ly}.
1157
1158
1159 @refbugs
1160
1161 When using @code{merge-differently-headed} with an upstem eighth or a
1162 shorter note, and a downstem half note, the eighth note gets the wrong
1163 offset.
1164
1165 There is no support for clusters where the same note occurs with
1166 different accidentals in the same chord.  In this case, it is
1167 recommended to use enharmonic transcription, or to use special cluster
1168 notation (see @ref{Clusters}).
1169
1170
1171
1172 @node Staff notation
1173 @section Staff notation
1174
1175 @cindex Staff notation
1176
1177 This section describes music notation that occurs on staff level,
1178 such as key signatures, clefs and time signatures.
1179
1180 @menu
1181 * Clef::                        
1182 * Key signature::               
1183 * Time signature::              
1184 * Partial measures::            
1185 * Bar lines::                   
1186 * Unmetered music::             
1187 * System start delimiters::     
1188 * Staff symbol::                
1189 * Writing music in parallel::   
1190 @end menu
1191
1192
1193 @node Clef
1194 @subsection Clef
1195
1196 @findex \clef
1197
1198 The clef indicates which lines of the staff correspond to which
1199 pitches.  The clef is set with the @code{\clef} command
1200
1201 @lilypond[quote,ragged-right,fragment,verbatim]
1202 { c''2 \clef alto g'2 }
1203 @end lilypond
1204
1205 @cindex treble clef
1206 @cindex violin clef
1207 @cindex alto clef
1208 @cindex tenor clef
1209 @cindex bass clef
1210 @cindex french clef
1211 @cindex soprano clef
1212 @cindex mezzosoprano clef
1213 @cindex baritone clef
1214 @cindex varbaritone clef
1215 @cindex subbass clef
1216
1217 Supported clefs include
1218
1219 @multitable @columnfractions .33 .66
1220 @headitem Clef @tab Position
1221 @item @code{treble}, violin, G, G2 @tab
1222 G clef on 2nd line
1223 @item @code{alto, C} @tab
1224 C clef on 3rd line
1225 @item @code{tenor} @tab
1226 C clef on 4th line.
1227 @item @code{bass, F} @tab
1228 F clef on 4th line
1229 @item @code{french} @tab
1230 G clef on 1st line, so-called French violin clef
1231 @item @code{soprano} @tab
1232 C clef on 1st line
1233 @item @code{mezzosoprano} @tab
1234 C clef on 2nd line
1235 @item @code{baritone} @tab
1236 C clef on 5th line
1237 @item @code{varbaritone} @tab
1238 F clef on 3rd line
1239 @item @code{subbass} @tab
1240 F clef on 5th line
1241 @item @code{percussion} @tab
1242 percussion clef
1243 @item @code{tab} @tab
1244 tablature clef
1245 @end multitable
1246
1247 By adding @code{_8} or @code{^8} to the clef name, the clef is
1248 transposed one octave down or up, respectively, and @code{_15} and
1249 @code{^15} transposes by two octaves.  The argument @var{clefname}
1250 must be enclosed in quotes when it contains underscores or digits.  For
1251 example,
1252
1253 @cindex choral tenor clef
1254 @lilypond[quote,ragged-right,verbatim,fragment,relative=1]
1255 \clef "G_8" c4
1256 @end lilypond
1257
1258
1259 @commonprop
1260
1261 The command @code{\clef "treble_8"} is equivalent to setting
1262 @code{clefGlyph},
1263 @code{clefPosition} (which controls the Y position of the clef),
1264 @code{middleCPosition} and @code{clefOctavation}.  A clef is printed
1265 when any of these properties are changed.  The following example shows
1266 possibilities when setting properties manually.
1267
1268 @lilypond[quote,ragged-right,verbatim]
1269 {
1270   \set Staff.clefGlyph = #"clefs.F"
1271   \set Staff.clefPosition = #2
1272   c'4
1273   \set Staff.clefGlyph = #"clefs.G"
1274   c'4
1275   \set Staff.clefGlyph = #"clefs.C"
1276   c'4
1277   \set Staff.clefOctavation = #7
1278   c'4
1279   \set Staff.clefOctavation = #0
1280   \set Staff.clefPosition = #0
1281   c'4
1282   \clef "bass"
1283   c'4
1284   \set Staff.middleCPosition = #4
1285   c'4
1286 }
1287 @end lilypond
1288
1289
1290 @seealso
1291
1292 Program reference: @internalsref{Clef}.
1293
1294
1295 @node Key signature
1296 @subsection Key signature
1297
1298 @cindex Key signature
1299 @findex \key
1300
1301 The key signature indicates the tonality in which a piece is played.  It
1302 is denoted by a set of alterations (flats or sharps) at the start of the
1303 staff.
1304
1305 Setting or changing the key signature is done with the @code{\key}
1306 command
1307
1308 @example
1309 @code{\key} @var{pitch} @var{type}
1310 @end example
1311
1312 @findex \minor
1313 @findex \major
1314 @findex \minor
1315 @findex \ionian
1316 @findex \locrian
1317 @findex \aeolian
1318 @findex \mixolydian
1319 @findex \lydian
1320 @findex \phrygian
1321 @findex \dorian
1322 @cindex church modes
1323
1324 Here, @var{type} should be @code{\major} or @code{\minor} to get
1325 @var{pitch}-major or @var{pitch}-minor, respectively.  You may also
1326 use the standard mode names (also called ``church modes''): @code{\ionian},
1327 @code{\locrian}, @code{\aeolian}, @code{\mixolydian}, @code{\lydian},
1328 @code{\phrygian}, and @code{\dorian}.
1329
1330 This command sets the context property
1331 @code{Staff.keySignature}.  Non-standard key signatures
1332 can be specified by setting this property directly.
1333
1334 Accidentals and key signatures often confuse new users, because
1335 unaltered notes get natural signs depending on the key signature.  For
1336 more information, see @ref{More about pitches}.
1337
1338
1339 @commonprop
1340
1341 A natural sign is printed to cancel any previous accidentals.  This
1342 can be suppressed by setting the @code{Staff.printKeyCancellation}
1343 property.
1344
1345 @lilypond[quote,fragment,ragged-right,fragment,verbatim,relative=2]
1346 \key d \major
1347 a b cis d
1348 \key g \minor
1349 a bes c d
1350 \set Staff.printKeyCancellation = ##f
1351 \key d \major
1352 a b cis d
1353 \key g \minor
1354 a bes c d
1355 @end lilypond
1356
1357
1358 @seealso
1359
1360 Program reference: @internalsref{KeyCancellation},
1361 @internalsref{KeySignature}.
1362
1363
1364 @node Time signature
1365 @subsection Time signature
1366
1367 @cindex Time signature
1368 @cindex meter
1369 @findex \time
1370
1371 Time signature indicates the metrum of a piece: a regular pattern of
1372 strong and weak beats.  It is denoted by a fraction at the start of the
1373 staff.
1374
1375 The time signature is set with the @code{\time} command
1376
1377 @lilypond[quote,ragged-right,fragment,verbatim]
1378 \time 2/4 c'2 \time 3/4 c'2.
1379 @end lilypond
1380
1381 @commonprop
1382
1383 The symbol that is printed can be customized with the @code{style}
1384 property.  Setting it to @code{#'()} uses fraction style for 4/4 and
1385 2/2 time,
1386
1387 @lilypond[fragment,quote,ragged-right,verbatim]
1388 \time 4/4 c'1
1389 \time 2/2 c'1
1390 \override Staff.TimeSignature #'style = #'()
1391 \time 4/4 c'1
1392 \time 2/2 c'1
1393 @end lilypond
1394
1395 There are many more options for its layout.  See @ref{Ancient time
1396 signatures} for more examples.
1397
1398 @code{\time} sets the property @code{timeSignatureFraction},
1399 @code{beatLength} and @code{measureLength} in the @code{Timing}
1400 context, which is normally aliased to @internalsref{Score}.  The
1401 property @code{measureLength} determines where bar lines should be
1402 inserted, and how automatic beams should be generated.  Changing the
1403 value of @code{timeSignatureFraction} also causes the symbol to be
1404 printed.
1405
1406 More options are available through the Scheme function
1407 @code{set-time-signature}.  In combination with the
1408 @internalsref{Measure_grouping_engraver}, it will create
1409 @internalsref{MeasureGrouping} signs.  Such signs ease reading
1410 rhythmically complex modern music.  In the following example, the 9/8
1411 measure is subdivided in 2, 2, 2 and 3.  This is passed to
1412 @code{set-time-signature} as the third argument @code{(2 2 2 3)}
1413
1414 @lilypond[quote,ragged-right,verbatim]
1415 \score {
1416   \relative c'' {
1417     #(set-time-signature 9 8 '(2 2 2 3))
1418     g8[ g] d[ d] g[ g] a8[( bes g]) |
1419     #(set-time-signature 5 8 '(3 2))
1420     a4. g4
1421   }
1422   \layout {
1423     \context {
1424       \Staff
1425       \consists "Measure_grouping_engraver"
1426     }
1427   }
1428 }
1429 @end lilypond
1430
1431
1432 @seealso
1433
1434 Program reference: @internalsref{TimeSignature}, and
1435 @internalsref{Timing_translator}.
1436
1437 Examples: @inputfileref{input/@/test,compound@/-time@/.ly}.
1438
1439
1440 @refbugs
1441
1442 Automatic beaming does not use the measure grouping specified with
1443 @code{set-time-signature}.
1444
1445
1446 @node Partial measures
1447 @subsection Partial measures
1448
1449 @cindex anacrusis
1450 @cindex upbeat
1451 @cindex partial measure
1452 @cindex measure, partial
1453 @cindex shorten measures
1454 @findex \partial
1455
1456 Partial measures, such as an anacrusis or upbeat, are entered using the
1457
1458 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
1459 \partial 16*5 c16 cis d dis e | a2. c,4 | b2
1460 @end lilypond
1461
1462 The syntax for this command is
1463
1464 @example
1465 \partial @var{duration}
1466 @end example
1467
1468 This is internally translated into
1469
1470 @example
1471 \set Timing.measurePosition = -@var{length of duration}
1472 @end example
1473
1474 The property @code{measurePosition} contains a rational number
1475 indicating how much of the measure has passed at this point.
1476
1477
1478 @refbugs
1479
1480 This command does not take into account grace notes at the start of
1481 the music.  When a piece starts with graces notes in the pickup, then
1482 the @code{\partial} should follow the grace notes
1483
1484 @lilypond[verbatim,quote,ragged-right,relative,fragment]
1485 \grace f16
1486 \partial 4
1487 g4
1488 a2 g2
1489 @end lilypond
1490
1491
1492 @node Bar lines
1493 @subsection Bar lines
1494
1495 @cindex Bar lines
1496 @findex \bar
1497 @cindex measure lines
1498 @cindex repeat bars
1499
1500 Bar lines delimit measures, but are also used to indicate
1501 repeats.  Normally they are inserted automatically.  Line
1502 breaks may only happen on bar lines.
1503
1504 Special types of bar lines can be forced with the @code{\bar} command
1505
1506 @lilypond[quote,ragged-right,relative=2,fragment,verbatim]
1507 c4 \bar "|:" c4
1508 @end lilypond
1509
1510 The following bar types are available
1511
1512 @lilypondfile[ragged-right,quote]{bar-lines.ly}
1513
1514 In addition, you can specify @code{"||:"}, which is equivalent to 
1515 @code{"|:"} except at line breaks, where it gives a double bar line at
1516 the end of the line and a start repeat at the beginning of the next
1517 line. 
1518
1519 To allow a line break where there is no visible bar line, use
1520
1521 @example
1522 \bar ""
1523 @end example
1524
1525 @noindent
1526 This will insert an invisible bar line and allow line breaks at this
1527 point.
1528
1529 In scores with many staves, a @code{\bar} command in one staff is
1530 automatically applied to all staves.  The resulting bar lines are
1531 connected between different staves of a StaffGroup
1532
1533 @lilypond[quote,ragged-right,fragment,verbatim]
1534 <<
1535   \new StaffGroup <<
1536     \new Staff {
1537       e'4 d'
1538       \bar "||"
1539       f' e'
1540     }
1541     \new Staff { \clef bass c4 g e g }
1542   >>
1543   \new Staff { \clef bass c2 c2 }
1544 >>
1545 @end lilypond
1546
1547
1548 @commonprop
1549
1550 @findex whichBar
1551 @findex repeatCommands
1552 @findex defaultBarType
1553
1554 The command @code{\bar }@var{bartype} is a short cut for doing
1555 @code{\set Timing.whichBar = }@var{bartype}.  Whenever @code{whichBar}
1556 is set to a string, a bar line of that type is created.
1557
1558 A bar line is created whenever the @code{whichBar} property is set.
1559 At the start of a measure it is set to the contents of
1560 @code{Timing.defaultBarType}.  The contents of @code{repeatCommands} are
1561 used
1562 to override default measure bars.
1563
1564 You are encouraged to use @code{\repeat} for repetitions.  See
1565 @ref{Repeats}.
1566
1567
1568 @seealso
1569
1570 In this manual: @ref{Repeats}, @ref{System start delimiters}.
1571
1572 Program reference: @internalsref{BarLine} (created at
1573 @internalsref{Staff} level), @internalsref{SpanBar} (across staves).
1574
1575 Examples: @inputfileref{input/@/test,bar@/-lines@/.ly},
1576
1577
1578 @node Unmetered music
1579 @subsection Unmetered music
1580
1581 @cindex cadenza
1582 @findex \cadenzaOn
1583 @findex \cadenzaOff
1584
1585 Bar lines and bar numbers are calculated automatically.  For unmetered
1586 music (cadenzas, for example), this is not desirable.  To turn off
1587 automatic bar lines and bar numbers, use the commands @code{\cadenzaOn}
1588 and @code{\cadenzaOff}.
1589
1590 @lilypond[verbatim,quote,ragged-right,relative=2,fragment]
1591 c4 d e d
1592 \cadenzaOn
1593 c4 c d8 d d f4 g4.
1594 \cadenzaOff
1595 \bar "|"
1596 d4 e d c
1597 @end lilypond
1598
1599
1600 @refbugs
1601
1602 LilyPond will only insert page breaks at a barline.  Unless the unmetered
1603 music ends before the end of the staff line, you will need to insert
1604 invisible bar lines
1605
1606 @example
1607 \bar ""
1608 @end example
1609
1610 @noindent
1611 to indicate where line breaks can occur.
1612
1613
1614 @node System start delimiters
1615 @subsection System start delimiters
1616
1617 @cindex start of system
1618 @cindex Staff, multiple
1619 @cindex bracket, vertical
1620 @cindex brace, vertical
1621 @cindex grand staff
1622 @cindex staff group
1623 @cindex staff, choir
1624
1625 Many scores consist of more than one staff.  These staves can be
1626 joined in four different ways
1627
1628 @itemize @bullet
1629 @item The group is started with a brace at the left, and bar lines are
1630 connected.  This is done with the @internalsref{GrandStaff} context.
1631
1632 @lilypond[verbatim,ragged-right,quote]
1633 \new GrandStaff
1634 \relative <<
1635   \new Staff { c1 c }
1636   \new Staff { c c }
1637 >>
1638 @end lilypond
1639
1640 @item The group is started with a bracket, and bar lines are connected.
1641 This is done with the
1642 @internalsref{StaffGroup} context
1643
1644 @lilypond[verbatim,ragged-right,quote]
1645 \new StaffGroup
1646 \relative <<
1647   \new Staff { c1 c }
1648   \new Staff { c c }
1649 >>
1650 @end lilypond
1651
1652 @item The group is started with a bracket, but bar lines are not
1653 connected.  This is done with the @internalsref{ChoirStaff} context.
1654
1655 @lilypond[verbatim,ragged-right,quote]
1656 \new ChoirStaff
1657 \relative <<
1658   \new Staff { c1 c }
1659   \new Staff { c c }
1660 >>
1661 @end lilypond
1662
1663 @item The group is started with a vertical line.  Bar lines are not
1664 connected.  This is the default for the score.
1665
1666 @lilypond[verbatim,ragged-right,quote]
1667 \relative <<
1668   \new Staff { c1 c }
1669   \new Staff { c c }
1670 >>
1671 @end lilypond
1672 @end itemize
1673
1674
1675 @seealso
1676
1677 The bar lines at the start of each system are
1678 @internalsref{SystemStartBar}, @internalsref{SystemStartBrace}, and
1679 @internalsref{SystemStartBracket}.  Only one of these types is created
1680 in every context, and that type is determined by the property
1681 @code{systemStartDelimiter}.
1682
1683
1684 @node Staff symbol
1685 @subsection Staff symbol
1686
1687 @cindex adjusting staff symbol
1688
1689 Notes, dynamic signs, etc., are grouped
1690 with a set of horizontal lines, called a staff (plural `staves').  In
1691 LilyPond, these lines are drawn using a separate layout object called
1692 staff symbol.
1693
1694 The staff symbol may be tuned in the number, thickness and distance
1695 of lines, using properties.  This is demonstrated in the example files
1696 @inputfileref{input/@/test,staff@/-lines@/.ly},
1697 @inputfileref{input/@/test,staff@/-size@/.ly}.
1698
1699 In addition, staves may be started and stopped at will. This is done
1700 with @code{\startStaff} and @code{\stopStaff}.
1701
1702 @lilypond[verbatim,relative=2,fragment]
1703 b4 b
1704 \override Staff.StaffSymbol #'line-count = 2
1705 \stopStaff \startStaff
1706 b b
1707 \revert Staff.StaffSymbol #'line-count
1708 \stopStaff \startStaff
1709 b b
1710 @end lilypond
1711
1712 In combination with Frenched staves, this may be used to typeset ossia
1713 sections. An example is in @inputfileref{input/@/test@/,ossia.ly},
1714 shown here
1715
1716 @cindex ossia
1717
1718 @lilypondfile{ossia.ly}
1719
1720 @cindex staff lines, setting number of
1721 @cindex staff lines, setting thickness of
1722 @cindex thickness of staff lines, setting
1723 @cindex number of staff lines, setting
1724
1725 @seealso
1726
1727 Program reference: @internalsref{StaffSymbol}.
1728
1729 Examples: @inputfileref{input/@/test,staff@/-lines@/.ly},
1730 @inputfileref{input/@/test@/,ossia.ly},
1731 @inputfileref{input/@/test,staff@/-size@/.ly},
1732 @inputfileref{input/@/regression,staff@/-line@/-positions@/.ly}.
1733
1734
1735 @node Writing music in parallel
1736 @subsection Writing music in parallel
1737
1738 @cindex Writing music in parallel
1739 @cindex Interleaved music
1740
1741 Music for multiple parts can be interleaved
1742
1743 @lilypond[quote,fragment,verbatim]
1744 \parallelMusic #'(voiceA voiceB) {
1745   r8     g'16[ c''] e''[ g' c'' e''] r8     g'16[ c''] e''[ g' c'' e''] |
1746   c'2                                c'2                                |
1747   r8     a'16[ d''] f''[ a' d'' f''] r8     a'16[ d''] f''[ a' d'' f''] |
1748   c'2                                c'2                                |
1749 }
1750 \new StaffGroup <<
1751   \new Staff \new Voice \voiceA
1752   \new Staff \new Voice \voiceB
1753 >>
1754 @end lilypond
1755
1756
1757
1758 @node Connecting notes
1759 @section Connecting notes
1760
1761 This section deals with notation that affects groups of notes.
1762
1763 @menu
1764 * Ties::                        
1765 * Slurs::                       
1766 * Phrasing slurs::              
1767 * Laissez vibrer ties::         
1768 * Automatic beams::             
1769 * Manual beams::                
1770 * Grace notes::                 
1771 @end menu
1772
1773
1774 @node Ties
1775 @subsection Ties
1776
1777 @cindex tie
1778 @findex ~
1779
1780 A tie connects two adjacent note heads of the same pitch.  The tie in
1781 effect extends the length of a note.  Ties should not be confused with
1782 slurs, which indicate articulation, or phrasing slurs, which indicate
1783 musical phrasing.  A tie is entered using the tilde symbol `@code{~}'
1784
1785 @lilypond[quote,ragged-right,fragment,verbatim]
1786 e' ~ e' <c' e' g'> ~ <c' e' g'>
1787 @end lilypond
1788
1789 When a tie is applied to a chord, all note heads whose pitches match
1790 are connected.  When no note heads match, no ties will be created.
1791
1792 A tie is just a way of extending a note duration, similar to the
1793 augmentation dot.  The following example shows two ways of notating
1794 exactly the same concept
1795
1796 @lilypond[quote,fragment,ragged-right]
1797 \time 3/4 c'2. c'2 ~ c'4
1798 @end lilypond
1799
1800 @noindent
1801 Ties are used either when the note crosses a bar line, or when dots
1802 cannot be used to denote the rhythm.  When using ties, larger note
1803 values should be aligned to subdivisions of the measure, such as
1804
1805 @lilypond[fragment,quote,ragged-right]
1806 \relative {
1807   r8 c8 ~ c2 r4 | r8^"not" c2 ~ c8 r4
1808 }
1809 @end lilypond
1810
1811 If you need to tie a lot of notes over bars, it may be easier to use
1812 automatic note splitting (see @ref{Automatic note splitting}).  This
1813 mechanism automatically splits long notes, and ties them across bar
1814 lines.
1815
1816 When a second alternative of a repeat starts with a tied note, you
1817 have to repeat the tie. This can be achieved with @code{\repeatTie},
1818
1819 @lilypond[fragment,quote,ragged-right,relative=2]
1820 r <c e g>\repeatTie
1821 @end lilypond
1822
1823 @cindex repeating ties
1824 @cindex volta brackets and ties
1825
1826 @commonprop
1827
1828 Ties are sometimes used to write out arpeggios.  In this case, two tied
1829 notes need not be consecutive.  This can be achieved by setting the
1830 @code{tieWaitForNote} property to true. The same feature is also useful,
1831 for example, to tie a tremolo to a chord. For example,
1832
1833 @lilypond[fragment,verbatim,relative=1,ragged-right]
1834 \set tieWaitForNote = ##t
1835 \grace { c16[~ e~ g]~ } <c, e g>2
1836 \repeat "tremolo" 8 { c32~ c'~ } <c c,>1
1837 @end lilypond
1838
1839
1840 @refcommands
1841
1842
1843 @findex \tieUp
1844 @code{\tieUp},
1845 @findex \tieDown
1846 @code{\tieDown},
1847 @findex \tieNeutral
1848 @code{\tieNeutral},
1849 @findex \tieDotted
1850 @code{\tieDotted},
1851 @findex \tieDashed
1852 @code{\tieDashed},
1853 @findex \tieSolid
1854 @code{\tieSolid}.
1855
1856
1857 @seealso
1858
1859 In this manual: @ref{Automatic note splitting}.
1860
1861 Program reference: @internalsref{Tie}.
1862
1863 Examples:
1864 @inputfileref{input/@/regression,tie-arpeggio.ly}
1865 @inputfileref{input/@/regression,tie-manual.ly}
1866
1867
1868
1869
1870 @refbugs
1871
1872 Switching staves when a tie is active will not produce a slanted tie.
1873
1874
1875 @node Slurs
1876 @subsection Slurs
1877
1878 @cindex Slurs
1879
1880 A slur indicates that notes are to be played bound or
1881 @emph{legato}.  They are entered using parentheses
1882
1883 @lilypond[quote,ragged-right,relative=2,fragment,verbatim]
1884 f( g a) a8 b( a4 g2 f4)
1885 <c e>2( <b d>2)
1886 @end lilypond
1887
1888 The direction of a slur can be specified with
1889 @code{\slur@emph{DIR}}, where @code{@emph{DIR}} is
1890 either @code{Up}, @code{Down}, or @code{Neutral} (automatically
1891 selected).
1892
1893 However, there is a convenient shorthand for forcing slur
1894 directions.  By adding @code{_} or @code{^} before the opening
1895 parentheses, the direction is also set.  For example,
1896
1897 @lilypond[relative=2,ragged-right,quote,verbatim,fragment]
1898 c4_( c) c^( c)
1899 @end lilypond
1900
1901 Only one slur can be printed at once.  If you need to print a long
1902 slur over a few small slurs, please see @ref{Phrasing slurs}.
1903
1904
1905 @commonprop
1906
1907 Some composers write two slurs when they want legato chords.  This can
1908 be achieved in LilyPond by setting @code{doubleSlurs},
1909
1910 @lilypond[verbatim,ragged-right,relative,fragment,quote]
1911 \set doubleSlurs = ##t
1912 <c e>4 ( <d f> <c e> <d f> )
1913 @end lilypond
1914
1915
1916 @refcommands
1917
1918 @findex \slurUp
1919 @code{\slurUp},
1920 @findex \slurDown
1921 @code{\slurDown},
1922 @findex \slurNeutral
1923 @code{\slurNeutral},
1924 @findex \slurDashed
1925 @code{\slurDashed},
1926 @findex \slurDotted
1927 @code{\slurDotted},
1928 @findex \slurSolid
1929 @code{\slurSolid}.
1930
1931 @seealso
1932
1933 Program reference: @seeinternals{Slur}.
1934
1935
1936 @node Phrasing slurs
1937 @subsection Phrasing slurs
1938
1939 @cindex phrasing slurs
1940 @cindex phrasing marks
1941
1942 A phrasing slur (or phrasing mark) connects notes and is used to
1943 indicate a musical sentence.  It is written using @code{\(} and @code{\)}
1944 respectively
1945
1946 @lilypond[quote,ragged-right,fragment,verbatim,relative=1]
1947 \time 6/4 c'\( d( e) f( e) d\)
1948 @end lilypond
1949
1950 Typographically, the phrasing slur behaves almost exactly like a
1951 normal slur.  However, they are treated as different objects.  A
1952 @code{\slurUp} will have no effect on a phrasing slur; instead, use
1953 @code{\phrasingSlurUp}, @code{\phrasingSlurDown}, and
1954 @code{\phrasingSlurNeutral}.
1955
1956 You cannot have simultaneous phrasing slurs.
1957
1958
1959 @refcommands
1960
1961 @findex \phrasingSlurUp
1962 @code{\phrasingSlurUp},
1963 @findex \phrasingSlurDown
1964 @code{\phrasingSlurDown},
1965 @findex \phrasingSlurNeutral
1966 @code{\phrasingSlurNeutral}.
1967
1968
1969 @seealso
1970
1971 Program reference: @internalsref{PhrasingSlur}.
1972
1973
1974 @node Laissez vibrer ties
1975 @subsection Laissez vibrer ties
1976 @cindex Laissez vibrer
1977 @cindex Ties, laissez vibrer
1978
1979 L.v. ties (laissez vibrer) indicate that notes must not be damped at the
1980 end. It is used in notation for piano, harp and other string and
1981 percussion instruments. They can be entered using @code{\laissezVibrer},
1982
1983 @lilypond[fragment,ragged-right,verbatim,relative=1]
1984 <c f g>\laissezVibrer
1985 @end lilypond
1986
1987 @seealso
1988
1989 Program reference:
1990 @internalsref{LaissezVibrerTie}
1991 @internalsref{LaissezVibrerTieColumn}
1992
1993 Example files:
1994 @inputfileref{input/regression,laissez-vibrer-tie.ly}
1995
1996
1997 @node Automatic beams
1998 @subsection Automatic beams
1999
2000 LilyPond inserts beams automatically
2001
2002 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
2003 \time 2/4 c8 c c c \time 6/8 c c c c8. c16 c8
2004 @end lilypond
2005
2006 When these automatic decisions are not good enough, beaming can be
2007 entered explicitly.  It is also possible to define beaming patterns
2008 that differ from the defaults.  See @ref{Setting automatic beam behavior}
2009 for details.
2010
2011 Individual notes may be marked with @code{\noBeam} to prevent them
2012 from being beamed
2013
2014 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
2015 \time 2/4 c8 c\noBeam c c
2016 @end lilypond
2017
2018
2019 @seealso
2020
2021 Program reference: @internalsref{Beam}.
2022
2023
2024 @node Manual beams
2025 @subsection Manual beams
2026
2027 @cindex beams, manual
2028 @findex ]
2029 @findex [
2030
2031 In some cases it may be necessary to override the automatic beaming
2032 algorithm.  For example, the autobeamer will not put beams over rests
2033 or bar lines.  Such beams are specified manually by marking the begin
2034 and end point with @code{[} and @code{]}
2035
2036 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
2037 {
2038   r4 r8[ g' a r8] r8 g[ | a] r8
2039 }
2040 @end lilypond
2041
2042
2043 @commonprop
2044
2045 @findex stemLeftBeamCount
2046 @findex stemRightBeamCount
2047
2048 Normally, beaming patterns within a beam are determined automatically.
2049 If necessary, the properties @code{stemLeftBeamCount} and
2050 @code{stemRightBeamCount} can be used to override the defaults.  If
2051 either property is set, its value will be used only once, and then it
2052 is erased
2053
2054 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
2055 {
2056    f8[ r16
2057       f g a]
2058    f8[ r16
2059    \set stemLeftBeamCount = #1
2060       f g a]
2061 }
2062 @end lilypond
2063
2064 The property @code{subdivideBeams} can be set in order to subdivide
2065 all 16th or shorter beams at beat positions, as defined by the
2066 @code{beatLength} property.
2067
2068 @lilypond[fragment,quote,relative=2,verbatim]
2069 c16[ c c c c c c c]
2070 \set subdivideBeams = ##t
2071 c16[ c c c c c c c]
2072 \set Score.beatLength = #(ly:make-moment 1 8)
2073 c16[ c c c c c c c]
2074 @end lilypond
2075 @findex subdivideBeams
2076
2077 @noindent
2078 For more information about @code{make-moment}, see
2079 @ref{Time administration}.
2080
2081 Line breaks are normally forbidden when beams cross bar lines.  This
2082 behavior can be changed by setting @code{allowBeamBreak}.
2083
2084 @findex allowBeamBreak
2085 @cindex beams and line breaks
2086 @cindex beams, kneed
2087 @cindex kneed beams
2088 @cindex auto-knee-gap
2089
2090
2091 @refbugs
2092
2093 Kneed beams are inserted automatically when a large gap is detected
2094 between the note heads.  This behavior can be tuned through the object.
2095
2096 Automatically kneed cross-staff beams cannot be used together with
2097 hidden staves.  See @ref{Hiding staves}.
2098
2099 Beams do not avoid collisions with symbols around the notes, such as
2100 texts and accidentals.
2101
2102
2103 @node Grace notes
2104 @subsection Grace notes
2105
2106 @findex \grace
2107 @cindex ornaments
2108 @cindex grace notes
2109 @cindex appoggiatura
2110 @cindex acciaccatura
2111
2112 Grace notes are ornaments that are written out.  The most common ones
2113 are acciaccatura, which should be played as very short.  It is denoted
2114 by a slurred small note with a slashed stem.  The appoggiatura is a
2115 grace note that takes a fixed fraction of the main note, and is
2116 denoted as a slurred note in small print without a slash.  They
2117 are entered with the commands @code{\acciaccatura} and
2118 @code{\appoggiatura}, as demonstrated in the following example
2119
2120 @lilypond[quote,ragged-right,relative=2,verbatim,fragment]
2121 b4 \acciaccatura d8 c4 \appoggiatura e8 d4
2122 \acciaccatura { g16[ f] } e4
2123 @end lilypond
2124
2125 Both are special forms of the @code{\grace} command.  By prefixing this
2126 keyword to a music expression, a new one is formed, which will be
2127 printed in a smaller font and takes up no logical time in a measure.
2128
2129 @lilypond[quote,ragged-right,relative=2,verbatim,fragment]
2130 c4 \grace c16 c4
2131 \grace { c16[ d16] } c2 c4
2132 @end lilypond
2133
2134 @noindent
2135 Unlike @code{\acciaccatura} and @code{\appoggiatura}, the
2136 @code{\grace} command does not start a slur.
2137
2138 Internally, timing for grace notes is done using a second, `grace'
2139 timing.  Every point in time consists of two rational numbers: one
2140 denotes the logical time, one denotes the grace timing.  The above
2141 example is shown here with timing tuples
2142
2143 @lilypond[quote,ragged-right]
2144 <<
2145   \relative c''{
2146     c4 \grace c16 c4 \grace {
2147     c16[ d16] } c2 c4
2148   }
2149   \new Lyrics \lyricmode {
2150     \override LyricText #'font-family = #'typewriter
2151
2152     \markup { (0,0) } 4
2153     \grace { \markup {
2154       ( \fraction 1 4 , \fraction -1 16 ) } 16 }
2155     \markup { (\fraction 1 4 , 0 ) } 4
2156     \grace {
2157       \markup { (\fraction 2 4 , \fraction "-1" 8 ) } 16
2158       \markup { (\fraction 2 4 , \fraction "-1" 16 ) } 16
2159     }
2160     \markup { ( \fraction 2 4 , 0 ) }
2161   }
2162 >>
2163 @end lilypond
2164
2165 The placement of grace notes is synchronized between different staves.
2166 In the following example, there are two sixteenth grace notes for
2167 every eighth grace note
2168
2169 @lilypond[quote,ragged-right,relative=2,verbatim,fragment]
2170 << \new Staff { e4 \grace { c16[ d e f] } e4 }
2171    \new Staff { c4 \grace { g8[ b] } c4 } >>
2172 @end lilypond
2173
2174 @findex \afterGrace
2175
2176 If you want to end a note with a grace, use the @code{\afterGrace}
2177 command.  It takes two arguments: the main note, and the grace notes
2178 following the main note.
2179
2180 @lilypond[ragged-right, verbatim,relative=2,fragment]
2181 c1 \afterGrace d1 { c16[ d] } c4
2182 @end lilypond
2183
2184 This will put the grace notes after a ``space'' lasting 3/4 of the
2185 length of the main note.  The fraction 3/4 can be changed by setting
2186 @code{afterGraceFraction}, ie.
2187
2188 @example
2189 afterGraceFraction = #(cons 7 8)
2190 @end example
2191
2192 @noindent
2193 will put the grace note at 7/8 of the main note.
2194
2195 The same effect can be achieved manually by doing
2196
2197 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
2198 \new Voice {
2199   << { d1^\trill_( }
2200      { s2 \grace { c16[ d] } } >>
2201   c4)
2202 }
2203 @end lilypond
2204
2205 @noindent
2206 By adjusting the duration of the skip note (here it is a half-note),
2207 the space between the main-note and the grace is adjusted.
2208
2209 A @code{\grace} section will introduce special typesetting settings,
2210 for example, to produce smaller type, and set directions.  Hence, when
2211 introducing layout tweaks, they should be inside the grace section,
2212 for example,
2213 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
2214 \new Voice {
2215   \acciaccatura {
2216     \stemDown
2217     f16->
2218     \stemNeutral
2219   }
2220   g4
2221 }
2222 @end lilypond
2223
2224 @noindent
2225 The overrides should also be reverted inside the grace section.
2226
2227 The layout of grace sections can be changed throughout the music using
2228 the function @code{add-grace-property}.  The following example
2229 undefines the Stem direction for this grace, so stems do not always
2230 point up.
2231
2232 @example
2233 \new Staff @{
2234   #(add-grace-property 'Voice 'Stem 'direction '())
2235   @dots{}
2236 @}
2237 @end example
2238
2239 @noindent
2240 Another option is to change the variables @code{startGraceMusic},
2241 @code{stopGraceMusic}, @code{startAcciaccaturaMusic},
2242 @code{stopAcciaccaturaMusic}, @code{startAppoggiaturaMusic},
2243 @code{stopAppoggiaturaMusic}.  More information is in the file
2244 @file{ly/@/grace@/-init@/.ly}.
2245
2246 @noindent
2247 The slash through the stem in acciaccaturas can be obtained
2248 in other situations by @code{\override Stem  #'stroke-style = #"grace"}.
2249
2250 @seealso
2251
2252 Program reference: @internalsref{GraceMusic}.
2253
2254
2255 @refbugs
2256
2257 A score that starts with a @code{\grace} section needs an explicit
2258 @code{\new Voice} declaration, otherwise the main note and the grace
2259 note end up on different staves.
2260
2261 Grace note synchronization can also lead to surprises.  Staff notation,
2262 such as key signatures, bar lines, etc., are also synchronized.  Take
2263 care when you mix staves with grace notes and staves without, for example,
2264
2265 @lilypond[quote,ragged-right,relative=2,verbatim,fragment]
2266 << \new Staff { e4 \bar "|:" \grace c16 d4 }
2267    \new Staff { c4 \bar "|:" d4 } >>
2268 @end lilypond
2269
2270 @noindent
2271 This can be remedied by inserting grace skips of the corresponding
2272 durations in the other staves. For the above example
2273
2274 @example
2275 \new Staff @{ c4 \bar "|:" \grace s16 d4 @}
2276 @end example
2277
2278 Grace sections should only be used within sequential music
2279 expressions.  Nesting or juxtaposing grace sections is not supported,
2280 and might produce crashes or other errors.
2281
2282
2283
2284 @node Expressive marks
2285 @section Expressive marks
2286
2287 Expressive marks help musicians to bring more to the music than simple
2288 notes and rhythms.
2289
2290 @menu
2291 * Articulations::               
2292 * Fingering instructions::      
2293 * Dynamics::                    
2294 * Breath marks::                
2295 * Trills::                      
2296 * Glissando::                   
2297 * Arpeggio::                    
2298 @end menu
2299
2300
2301 @node Articulations
2302 @subsection Articulations
2303
2304 @cindex Articulations
2305 @cindex scripts
2306 @cindex ornaments
2307
2308 A variety of symbols can appear above and below notes to indicate
2309 different characteristics of the performance.  They are added to a note
2310 by adding a dash and the character signifying the
2311 articulation.  They are demonstrated here
2312
2313 @lilypondfile[quote,ragged-right]{script-abbreviations.ly}
2314
2315 The meanings of these shorthands can be changed.  See
2316 @file{ly/@/script@/-init@/.ly} for examples.
2317
2318 The script is automatically placed, but the direction can be forced as
2319 well.  Like other pieces of LilyPond code, @code{_} will place them
2320 below the staff, and @code{^} will place them above.
2321
2322 @lilypond[quote,ragged-right,fragment,verbatim]
2323 c''4^^ c''4_^
2324 @end lilypond
2325
2326 Other symbols can be added using the syntax
2327 @var{note}@code{\}@var{name}.  Again, they
2328 can be forced up or down using @code{^} and @code{_},
2329 e.g.,
2330
2331 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
2332 c\fermata c^\fermata c_\fermata
2333 @end lilypond
2334
2335 @cindex accent
2336 @cindex marcato
2337 @cindex staccatissimo
2338 @cindex espressivo
2339 @cindex fermata
2340 @cindex stopped
2341 @cindex staccato
2342 @cindex portato
2343 @cindex tenuto
2344 @cindex upbow
2345 @cindex downbow
2346 @cindex foot marks
2347 @cindex organ pedal marks
2348 @cindex turn
2349 @cindex open
2350 @cindex flageolet
2351 @cindex reverseturn
2352 @cindex trill
2353 @cindex prall
2354 @cindex mordent
2355 @cindex prallprall
2356 @cindex prallmordent
2357 @cindex prall, up
2358 @cindex prall, down
2359 @cindex mordent
2360 @cindex thumb marking
2361 @cindex segno
2362 @cindex coda
2363 @cindex varcoda
2364
2365 Here is a chart showing all scripts available,
2366
2367 @lilypondfile[ragged-right,quote]{script-chart.ly}
2368
2369
2370 @commonprop
2371
2372 The vertical ordering of scripts is controlled with the
2373 @code{script-priority} property.  The lower this number, the closer it
2374 will be put to the note.  In this example, the
2375 @internalsref{TextScript} (the sharp symbol) first has the lowest
2376 priority, so it is put lowest in the first example.  In the second, the
2377 prall trill (the @internalsref{Script}) has the lowest, so it is on the
2378 inside.  When two objects have the same priority, the order in which
2379 they are entered decides which one comes first.
2380
2381 @lilypond[verbatim,relative=3,ragged-right,fragment,quote]
2382 \once \override TextScript #'script-priority = #-100
2383 a4^\prall^\markup { \sharp }
2384
2385 \once \override Script #'script-priority = #-100
2386 a4^\prall^\markup { \sharp }
2387 @end lilypond
2388
2389
2390 @seealso
2391
2392 Program reference: @internalsref{Script}.
2393
2394
2395 @refbugs
2396
2397 These signs appear in the printed output but have no effect on the
2398 MIDI rendering of the music.
2399
2400
2401 @node Fingering instructions
2402 @subsection Fingering instructions
2403
2404 @cindex fingering
2405 @cindex finger change
2406
2407 Fingering instructions can be entered using
2408 @example
2409 @var{note}-@var{digit}
2410 @end example
2411 For finger changes, use markup texts
2412
2413 @lilypond[quote,verbatim,ragged-right,fragment,relative=1]
2414 c4-1 c-2 c-3 c-4
2415 c^\markup { \finger "2 - 3" }
2416 @end lilypond
2417
2418 You can use the thumb-script to indicate that a note should be
2419 played with the thumb (e.g., in cello music)
2420 @lilypond[quote,verbatim,ragged-right,fragment,relative=2]
2421 <a_\thumb a'-3>8 <b_\thumb b'-3>
2422 @end lilypond
2423
2424 Fingerings for chords can also be added to individual notes
2425 of the chord by adding them after the pitches
2426 @lilypond[quote,verbatim,ragged-right,fragment,relative=2]
2427 < c-1 e-2 g-3 b-5 >4
2428 @end lilypond
2429
2430
2431 @commonprop
2432
2433 You may exercise greater control over fingering chords by
2434 setting @code{fingeringOrientations}
2435
2436 @lilypond[quote,verbatim,ragged-right,fragment,relative=1]
2437 \set fingeringOrientations = #'(left down)
2438 <c-1 es-2 g-4 bes-5 > 4
2439 \set fingeringOrientations = #'(up right down)
2440 <c-1 es-2 g-4 bes-5 > 4
2441 @end lilypond
2442
2443 Using this feature, it is also possible to put fingering instructions
2444 very close to note heads in monophonic music,
2445
2446 @lilypond[verbatim,ragged-right,quote,fragment]
2447 \set fingeringOrientations = #'(right)
2448 <es'-2>4
2449 @end lilypond
2450
2451
2452 @seealso
2453
2454 Program reference: @internalsref{Fingering}.
2455
2456 Examples: @inputfileref{input/@/regression,finger@/-chords@/.ly}.
2457
2458
2459 @node Dynamics
2460 @subsection Dynamics
2461
2462 @cindex Dynamics
2463 @findex \pppp
2464 @findex \ppp
2465 @findex \pp
2466 @findex \p
2467 @findex \mp
2468 @findex \mf
2469 @findex \f
2470 @findex \ff
2471 @findex \fff
2472 @findex \ffff
2473 @findex \fp
2474 @findex \sf
2475 @findex \sff
2476 @findex \sp
2477 @findex \spp
2478 @findex \sfz
2479 @findex \rfz
2480
2481 Absolute dynamic marks are specified using a command after a note
2482 @code{c4\ff}.  The available dynamic marks are @code{\ppppp},
2483 @code{\pppp}, @code{\ppp},
2484 @code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff},
2485 @code{\fff}, @code{\ffff}, @code{\fp}, @code{\sf}, @code{\sff},
2486 @code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}.
2487
2488 @lilypond[quote,verbatim,ragged-right,fragment,relative=2]
2489 c\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff
2490 c2\fp c\sf c\sff c\sp c\spp c\sfz c\rfz
2491 @end lilypond
2492
2493 @findex \<
2494 @findex \>
2495 @findex \!
2496
2497 A crescendo mark is started with @code{\<} and terminated with
2498 @code{\!} or an absolute dynamic.  A decrescendo is started with
2499 @code{\>} and is also terminated with @code{\!} or an absolute
2500 dynamic.  @code{\cr} and @code{\decr} may be used instead of
2501 @code{\<} and @code{\>}.  Because these marks are bound to notes, you must
2502 use spacer notes if multiple marks are needed during one note
2503
2504 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
2505 c\< c\! d\> e\!
2506 << f1 { s4 s4\< s4\! \> s4\! } >>
2507 @end lilypond
2508
2509 @noindent
2510 A hairpin starts at the left edge of the beginning note and ends on the
2511 right edge of the ending note.
2512
2513 In some situations the @code{\espressivo} articulation mark may
2514 be suitable to indicate a crescendo and decrescendo on the one note,
2515
2516 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
2517 c2 b4 a g1\espressivo
2518 @end lilypond
2519
2520 This may give rise to very short hairpins.  Use @code{minimum-length}
2521 in @internalsref{Voice}.@internalsref{Hairpin} to lengthen them, for
2522 example
2523
2524 @example
2525 \override Staff.Hairpin #'minimum-length = #5
2526 @end example
2527
2528 @cindex crescendo
2529 @cindex decrescendo
2530 @cindex diminuendo
2531
2532 You can also use a text saying @emph{cresc.} instead of hairpins
2533
2534 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
2535 \setTextCresc
2536 c\< d e f\!
2537 \setHairpinCresc
2538 e\> d c b\!
2539 \setTextDecresc
2540 c\> d e f\!
2541 \setTextDim
2542 e\> d c b\!
2543 @end lilypond
2544
2545 You can also supply your own texts
2546 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
2547 \set crescendoText = \markup { \italic "cresc. poco" }
2548 \set crescendoSpanner = #'dashed-line
2549 a'2\< a a a\!\mf
2550 @end lilypond
2551
2552 To create new dynamic marks or text that should be aligned
2553 with dynamics, see @ref{New dynamic marks}.
2554
2555
2556 @commonprop
2557
2558 Dynamics that occur at, begin on, or end on, the same note
2559 will be vertically aligned.  If you want to ensure that dynamics
2560 are aligned when they do not occur on the same note, you can
2561 increase the @code{staff-padding} property.
2562
2563 @example
2564 \override DynamicLineSpanner #'staff-padding = #4
2565 @end example
2566
2567 You may also use this property if the dynamics are colliding
2568 with other notation.
2569
2570 Crescendi and decrescendi that end on the first note of a
2571 new line are not printed.  To change this behavior, use
2572
2573 @example
2574 \override Score.Hairpin #'after-line-breaking = ##t
2575 @end example
2576
2577 Text style dynamic changes (such as cresc. and dim.) are printed with a
2578 dashed line showing their extent.  To surpress printing this line, use
2579
2580 @example
2581 \override DynamicTextSpanner #'dash-period = #-1.0
2582 @end example
2583
2584
2585 @refcommands
2586
2587 @findex \dynamicUp
2588 @code{\dynamicUp},
2589 @findex \dynamicDown
2590 @code{\dynamicDown},
2591 @findex \dynamicNeutral
2592 @code{\dynamicNeutral}.
2593
2594
2595 @seealso
2596
2597 Program reference: @internalsref{DynamicText}, @internalsref{Hairpin}.
2598 Vertical positioning of these symbols is handled by
2599 @internalsref{DynamicLineSpanner}.
2600
2601
2602 @node Breath marks
2603 @subsection Breath marks
2604
2605 Breath marks are entered using @code{\breathe}
2606
2607 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
2608 c'4 \breathe d4
2609 @end lilypond
2610
2611
2612 @commonprop
2613
2614 The glyph of the breath mark can be tuned by overriding the
2615 @code{text} property of the @code{BreathingSign} layout object with
2616 any markup text.  For example,
2617 @lilypond[quote,ragged-right,fragment,verbatim,relative=1]
2618 c'4
2619 \override BreathingSign #'text
2620   = #(make-musicglyph-markup "scripts.rvarcomma")
2621 \breathe
2622 d4
2623 @end lilypond
2624
2625 @seealso
2626
2627 Program reference: @internalsref{BreathingSign}.
2628
2629 Examples: @inputfileref{input/@/regression,breathing@/-sign@/.ly}.
2630
2631
2632 @node Trills
2633 @subsection Trills
2634
2635 Short trills are printed like normal articulation; see @ref{Articulations}.
2636
2637 Long running trills are made with @code{\startTrillSpan} and
2638 @code{\stopTrillSpan},
2639
2640 @lilypond[verbatim,ragged-right,relative=2,quote,fragment]
2641 \new Voice {
2642   << { c1 \startTrillSpan }
2643      { s2. \grace { d16[\stopTrillSpan e] } } >>
2644   c4 }
2645 @end lilypond
2646
2647 @cindex Pitched trills
2648
2649 Trills that should be executed on an explicitly specified pitch can be
2650 typeset with the command @code{pitchedTrill},
2651
2652 @lilypond[ragged-right,verbatim,fragment,relative=1]
2653 \pitchedTrill c4\startTrillSpan fis
2654 f\stopTrillSpan
2655 @end lilypond
2656
2657 The first argument is the main note.  The pitch of the second
2658 is printed as a stemless note head in parentheses.
2659
2660
2661 @refcommands
2662
2663 @code{\startTrillSpan},
2664 @findex \startTrillSpan
2665 @code{\stopTrillSpan}.
2666 @findex \stopTrillSpan
2667
2668
2669 @seealso
2670
2671 Program reference: @internalsref{TrillSpanner}.
2672
2673
2674 @node Glissando
2675 @subsection Glissando
2676
2677 @cindex Glissando
2678 @findex \glissando
2679
2680 A glissando is a smooth change in pitch.  It is denoted by a line or a
2681 wavy line between two notes.  It is requested by attaching
2682 @code{\glissando} to a note
2683
2684 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
2685 c2\glissando c'
2686 \override Glissando #'style = #'zigzag
2687 c2\glissando c,
2688 @end lilypond
2689
2690
2691 @seealso
2692
2693 Program reference: @internalsref{Glissando}.
2694
2695 Example files: @file{input/@/regression/@/glissando@/.ly}.
2696
2697
2698 @refbugs
2699
2700 Printing text over the line (such as @emph{gliss.}) is not supported.
2701
2702
2703 @node Arpeggio
2704 @subsection Arpeggio
2705
2706 @cindex Arpeggio
2707 @cindex broken chord
2708 @findex \arpeggio
2709
2710 You can specify an arpeggio sign (also known as broken chord) on a
2711 chord by attaching an @code{\arpeggio} to a chord
2712
2713 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
2714 <c e g c>\arpeggio
2715 @end lilypond
2716
2717 A square bracket on the left indicates that the player should not
2718 arpeggiate the chord
2719
2720 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
2721 \arpeggioBracket
2722 <c' e g c>\arpeggio
2723 @end lilypond
2724
2725 The direction of the arpeggio is sometimes denoted by adding an
2726 arrowhead to the wiggly line
2727
2728 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
2729 \new Voice {
2730   \arpeggioUp
2731   <c e g c>\arpeggio
2732   \arpeggioDown
2733   <c e g c>\arpeggio
2734 }
2735 @end lilypond
2736
2737
2738 @commonprop
2739
2740 When an arpeggio crosses staves, you may attach an arpeggio to the chords
2741 in both staves and set
2742 @internalsref{PianoStaff}.@code{connectArpeggios}
2743
2744 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
2745 \new PianoStaff <<
2746   \set PianoStaff.connectArpeggios = ##t
2747   \new Staff { <c' e g c>\arpeggio }
2748   \new Staff { \clef bass <c,, e g>\arpeggio }
2749 >>
2750 @end lilypond
2751
2752
2753 @refcommands
2754
2755 @code{\arpeggio},
2756 @findex \arpeggioUp
2757 @code{\arpeggioUp},
2758 @findex \arpeggioDown
2759 @code{\arpeggioDown},
2760 @findex \arpeggioNeutral
2761 @code{\arpeggioNeutral},
2762 @findex \arpeggioBracket
2763 @code{\arpeggioBracket}.
2764
2765
2766 @seealso
2767
2768 Notation manual: @ref{Ties}, for writing out arpeggios.
2769
2770 Program reference: @internalsref{Arpeggio}.
2771
2772
2773 @refbugs
2774
2775 It is not possible to mix connected arpeggios and unconnected
2776 arpeggios in one @internalsref{PianoStaff} at the same point in time.
2777
2778
2779
2780
2781
2782 @node Repeats
2783 @section Repeats
2784
2785 Repetition is a central concept in music, and multiple notations exist
2786 for repetitions.
2787
2788 @menu
2789 * Repeat types::                
2790 * Repeat syntax::               
2791 * Repeats and MIDI::            
2792 * Manual repeat commands::      
2793 * Tremolo repeats::             
2794 * Tremolo subdivisions::        
2795 * Measure repeats::             
2796 @end menu
2797
2798
2799 @node Repeat types
2800 @subsection Repeat types
2801
2802 @cindex repeats
2803 @findex \repeat
2804
2805 The following types of repetition are supported
2806
2807 @table @code
2808 @item unfold
2809 Repeated music is fully written (played) out.  This is useful when
2810 entering repetitious music.  This is the only kind of repeat that
2811 is included in MIDI output.
2812
2813 @item volta
2814 Repeats are not written out, but alternative endings (volte) are
2815 printed, left to right with brackets.  This is the standard notation
2816 for repeats with alternatives.  These are not played in MIDI output by
2817 default.
2818
2819 @ignore
2820 @item fold
2821 Alternative endings are written stacked.  This has limited use but may be
2822 used to typeset two lines of lyrics in songs with repeats, see
2823 @inputfileref{input,star-spangled-banner@/.ly}.
2824 @end ignore
2825
2826 @item tremolo
2827 Make tremolo beams.  These are not played in MIDI output by default.
2828
2829 @item percent
2830 Make beat or measure repeats.  These look like percent signs.  These
2831 are not played in MIDI output by default.  Percent repeats must be
2832 declared within a Voice context.
2833
2834 @end table
2835
2836
2837 @node Repeat syntax
2838 @subsection Repeat syntax
2839
2840 LilyPond has one syntactic construct for specifying different types of
2841 repeats.  The syntax is
2842
2843 @example
2844 \repeat @var{variant} @var{repeatcount} @var{repeatbody}
2845 @end example
2846
2847 If you have alternative endings, you may add
2848 @findex \alternative
2849 @example
2850 \alternative @{
2851   @var{alternative1}
2852   @var{alternative2}
2853   @var{alternative3}
2854   @dots{}
2855 @}
2856 @end example
2857
2858 @noindent
2859 where each @var{alternative} is a music expression.  If you do not
2860 give enough alternatives for all of the repeats, the first alternative
2861 is assumed to be played more than once.
2862
2863 Standard repeats are used like this
2864 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
2865 c1
2866 \repeat volta 2 { c4 d e f }
2867 \repeat volta 2 { f e d c }
2868 @end lilypond
2869
2870 With alternative endings
2871 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
2872 c1
2873 \repeat volta 2 {c4 d e f}
2874 \alternative { {d2 d} {f f,} }
2875 @end lilypond
2876
2877 In this example, the first ending is not a complete bar (it
2878 only had 3 beats).  The beginning of the second ending
2879 contains the 4th beat from the first ending.  This ``extra''
2880 beat in the second ending is due to the first time ending,
2881 and has nothing to do with the @code{\partial} at the
2882 beginning of the example.
2883
2884 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
2885 \new Staff {
2886   \partial 4
2887   \repeat volta 4 { e | c2 d2 | e2 f2 | }
2888   \alternative { { g4 g g } { a | a a a a | b2. } }
2889 }
2890 @end lilypond
2891
2892 It is possible to shorten volta brackets
2893 by setting @code{voltaSpannerDuration}.  In the next example, the
2894 bracket only lasts one measure, which is a duration of 3/4.
2895
2896 @lilypond[verbatim,ragged-right,quote]
2897 \relative c''{
2898   \time 3/4
2899   c c c
2900   \set Staff.voltaSpannerDuration = #(ly:make-moment 3 4)
2901   \repeat "volta" 5 { d d d }
2902   \alternative { { e e e f f f }
2903   { g g g } }
2904 }
2905 @end lilypond
2906
2907
2908 @seealso
2909
2910 Examples:
2911
2912 Brackets for the repeat are normally only printed over the topmost
2913 staff.  This can be adjusted by setting the @code{voltaOnThisStaff}
2914 property; see @inputfileref{input/@/regression,volta@/-multi@/-staff@/.ly}.
2915
2916
2917 @refbugs
2918
2919 @cindex repeat, ambiguous
2920
2921 A nested repeat like
2922
2923 @example
2924 \repeat @dots{}
2925 \repeat @dots{}
2926 \alternative
2927 @end example
2928
2929 @noindent
2930 is ambiguous, since it is is not clear to which @code{\repeat} the
2931 @code{\alternative} belongs.  This ambiguity is resolved by always
2932 having the @code{\alternative} belong to the inner @code{\repeat}.
2933 For clarity, it is advisable to use braces in such situations.
2934
2935 Timing information is not remembered at the start of an alternative,
2936 so after a repeat timing information must be reset by hand, for
2937 example by setting @code{Score.measurePosition} or entering
2938 @code{\partial}.  Similarly, slurs or ties are also not repeated.
2939
2940
2941 @node Repeats and MIDI
2942 @subsection Repeats and MIDI
2943
2944 @cindex expanding repeats
2945 @findex \unfoldRepeats
2946
2947 With a little bit of tweaking, all types of repeats can be present
2948 in the MIDI output.  This is achieved by applying the
2949 @code{\unfoldRepeats} music function.  This functions changes all
2950 repeats to unfold repeats.
2951
2952 @lilypond[quote,verbatim,fragment,line-width=8.0\cm]
2953 \unfoldRepeats {
2954   \repeat tremolo 8 {c'32 e' }
2955   \repeat percent 2 { c''8 d'' }
2956   \repeat volta 2 {c'4 d' e' f'}
2957   \alternative {
2958     { g' a' a' g' }
2959     {f' e' d' c' }
2960   }
2961 }
2962 \bar "|."
2963 @end lilypond
2964
2965 When creating a score file using @code{\unfoldRepeats} for midi, then
2966 it is necessary to make two @code{\score} blocks.  One for MIDI (with
2967 unfolded repeats) and one for notation (with volta, tremolo, and
2968 percent repeats).  For example,
2969
2970 @example
2971 \score @{
2972   @var{..music..}
2973   \layout @{ .. @}
2974 @}
2975 \score @{
2976   \unfoldRepeats @var{..music..}
2977   \midi @{ .. @}
2978 @}
2979 @end example
2980
2981
2982 @node Manual repeat commands
2983 @subsection Manual repeat commands
2984
2985 @findex repeatCommands
2986
2987 The property @code{repeatCommands} can be used to control the layout of
2988 repeats.  Its value is a Scheme list of repeat commands.
2989
2990 @table @asis
2991 @item @code{start-repeat}
2992 Print a @code{|:} bar line.
2993
2994 @item @code{end-repeat}
2995 Print a @code{:|} bar line.
2996
2997 @item @code{(volta @var{text})}
2998 Print a volta bracket saying @var{text}: The text can be specified as
2999 a text string or as a markup text, see @ref{Text markup}.  Do not
3000 forget to change the font, as the default number font does not contain
3001 alphabetic characters;
3002
3003 @item @code{(volta #f)}
3004 Stop a running volta bracket.
3005 @end table
3006
3007 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
3008 c4
3009   \set Score.repeatCommands = #'((volta "93") end-repeat)
3010 c4 c4
3011   \set Score.repeatCommands = #'((volta #f))
3012 c4 c4
3013 @end lilypond
3014
3015
3016 @seealso
3017
3018 Program reference: @internalsref{VoltaBracket},
3019 @internalsref{RepeatedMusic},
3020 @internalsref{VoltaRepeatedMusic},
3021 @internalsref{UnfoldedRepeatedMusic}, and
3022 @internalsref{FoldedRepeatedMusic}.
3023
3024
3025 @node Tremolo repeats
3026 @subsection Tremolo repeats
3027
3028 @cindex tremolo beams
3029
3030 To place tremolo marks between notes, use @code{\repeat} with tremolo
3031 style
3032 @lilypond[quote,verbatim,ragged-right]
3033 \new Voice \relative c' {
3034   \repeat "tremolo" 8 { c16 d16 }
3035   \repeat "tremolo" 4 { c16 d16 }
3036   \repeat "tremolo" 2 { c16 d16 }
3037 }
3038 @end lilypond
3039
3040 Tremolo marks can also be put on a single note.  In this case, the
3041 note should not be surrounded by braces.
3042 @lilypond[quote,verbatim,ragged-right]
3043 \repeat "tremolo" 4 c'16
3044 @end lilypond
3045
3046 Similar output is obtained using the tremolo subdivision, described in
3047 @ref{Tremolo subdivisions}.
3048
3049
3050 @seealso
3051
3052 In this manual: @ref{Tremolo subdivisions}, @ref{Repeats}.
3053
3054 Program reference: @internalsref{Beam}, @internalsref{StemTremolo}.
3055
3056 Example files: @inputfileref{input/@/regression,chord@/-tremolo@/.ly},
3057 @inputfileref{input/@/regression,stem@/-tremolo@/.ly}.
3058
3059
3060 @node Tremolo subdivisions
3061 @subsection Tremolo subdivisions
3062
3063 @cindex tremolo marks
3064 @findex tremoloFlags
3065
3066 Tremolo marks can be printed on a single note by adding
3067 `@code{:}[@var{number}]' after the note.  The number indicates the
3068 duration of the subdivision, and it must be at least 8.  A
3069 @var{length} value of 8 gives one line across the note stem.  If the
3070 length is omitted, the last value (stored in @code{tremoloFlags}) is
3071 used
3072
3073 @lilypond[quote,ragged-right,verbatim,fragment]
3074 c'2:8 c':32 | c': c': |
3075 @end lilypond
3076
3077
3078 @refbugs
3079
3080 Tremolos entered in this way do not carry over into the MIDI output.
3081
3082
3083 @seealso
3084
3085 In this manual: @ref{Tremolo repeats}.
3086
3087 Elsewhere: @internalsref{StemTremolo}.
3088
3089
3090 @node Measure repeats
3091 @subsection Measure repeats
3092
3093 @cindex percent repeats
3094 @cindex measure repeats
3095
3096 In the @code{percent} style, a note pattern can be repeated.  It is
3097 printed once, and then the pattern is replaced with a special sign.
3098 Patterns of one and two measures are replaced by percent-like signs,
3099 patterns that divide the measure length are replaced by slashes.
3100 Percent repeats must be declared within a @code{Voice} context.
3101
3102 @lilypond[quote,verbatim,ragged-right]
3103 \new Voice \relative c' {
3104   \repeat "percent" 4 { c4 }
3105   \repeat "percent" 2 { c2 es2 f4 fis4 g4 c4 }
3106 }
3107 @end lilypond
3108
3109 Measure repeats of more than 2 measures get a counter, if you switch
3110 on the @code{countPercentRepeats} property,
3111
3112 @lilypond[relative=2,fragment,quote,verbatim,ragged-right]
3113 \new Voice {
3114 \set countPercentRepeats = ##t
3115   \repeat "percent" 4 { c1 }
3116 }
3117 @end lilypond
3118
3119
3120
3121 Isolated percents can also be printed. This is done by putting a multi
3122 measure rest with a different print function,
3123
3124 @lilypond[fragment,verbatim]
3125 \override MultiMeasureRest #'stencil
3126   = #ly:multi-measure-rest::percent
3127 R1
3128 @end lilypond
3129
3130
3131
3132
3133 @seealso
3134
3135 Program reference: @internalsref{RepeatSlash},
3136 @internalsref{PercentRepeat}, @internalsref{DoublePercentRepeat},
3137 @internalsref{DoublePercentRepeatCounter},
3138 @internalsref{PercentRepeatCounter},
3139 @internalsref{PercentRepeatedMusic}.
3140
3141
3142