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