]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/notation/rhythms.itely
Merge branch 'master' into lilypond/translation
[lilypond.git] / Documentation / notation / rhythms.itely
1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @ignore
3     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
4
5     When revising a translation, copy the HEAD committish of the
6     version that you are working on.  For details, see the Contributors'
7     Guide, node Updating translation committishes..
8 @end ignore
9
10 @c \version "2.12.0"
11
12 @node Rhythms
13 @section Rhythms
14
15 @lilypondfile[quote]{rhythms-headword.ly}
16
17 This section discusses rhythms, rests, durations, beaming and bars.
18
19 @menu
20 * Writing rhythms::
21 * Writing rests::
22 * Displaying rhythms::
23 * Beams::
24 * Bars::
25 * Special rhythmic concerns::
26 @end menu
27
28
29 @node Writing rhythms
30 @subsection Writing rhythms
31
32 @menu
33 * Durations::
34 * Tuplets::
35 * Scaling durations::
36 * Ties::
37 @end menu
38
39 @node Durations
40 @unnumberedsubsubsec Durations
41
42 @cindex durations, of notes
43 @cindex note durations
44 @cindex length of notes
45 @cindex note lengths
46
47 @funindex \longa
48 @funindex longa
49 @funindex \breve
50 @funindex breve
51 @funindex \maxima
52 @funindex maxima
53
54 Durations are designated by numbers and dots.  Durations are entered
55 as their reciprocal values.  For example, a quarter note is entered
56 using a @code{4} (since it is a 1/4 note), and a half note is entered
57 using a @code{2} (since it is a 1/2 note).  For notes longer than a
58 whole you must use the @code{\longa} (a double breve) and
59 @code{\breve} commands.  Durations as short as 128th notes may be
60 specified.  Shorter values are possible, but only as beamed notes.
61
62 @c Two 64th notes are needed to obtain beams
63 @lilypond[quote,verbatim,relative=2]
64 \time 8/1
65 c\longa c\breve c1 c2
66 c4 c8 c16 c32 c64 c128 c128
67 @end lilypond
68
69 Here are the same durations with automatic beaming turned off.
70
71 @c not strictly "writing rhythms"; more of a "displaying" thing,
72 @c but it's ok here.  -gp
73 @lilypond[quote,verbatim,relative=2]
74 \time 8/1
75 \autoBeamOff
76 c\longa c\breve c1 c2
77 c4 c8 c16 c32 c64 c128 c128
78 @end lilypond
79
80 A note with the duration of a quadruple breve may be entered with
81 @code{\maxima}, but this is supported only within ancient music
82 notation.  For details, see @ref{Ancient notation}.
83
84 @cindex duration, default
85 @cindex default note duration
86 @cindex note duration, default
87
88 If the duration is omitted, it is set to the previously
89 entered duration.  The default for the first note is a quarter
90 note.
91
92 @lilypond[quote,verbatim,relative=2]
93 a a a2 a a4 a a1 a
94 @end lilypond
95
96 @cindex notes, dotted
97 @cindex dotted notes
98 @cindex notes, double-dotted
99 @cindex double-dotted notes
100
101 @funindex .
102
103 To obtain dotted note lengths, place a dot (@code{.}) after the
104 duration.  Double-dotted notes are specified by appending two
105 dots, and so on.
106
107 @lilypond[quote,verbatim,relative=2]
108 a4 b c4. b8 a4. b4.. c8.
109 @end lilypond
110
111 Some durations cannot be represented with just binary durations
112 and dots; they can be represented only by tying two or more
113 notes together.  For details, see @ref{Ties}.
114
115 For ways of specifying durations for the syllables of lyrics and
116 ways of aligning lyrics to notes, see @ref{Vocal music}.
117
118 Optionally, notes can be spaced strictly proportionately to their
119 duration.  For details of this and other settings which control
120 proportional notation, see @ref{Proportional notation}.
121
122 @funindex \dotsUp
123 @funindex dotsUp
124 @funindex \dotsDown
125 @funindex dotsDown
126 @funindex \dotsNeutral
127 @funindex dotsNeutral
128
129 Dots are normally moved up to avoid staff lines, except in
130 polyphonic situations.  Dots may be manually placed above or below
131 the staff; see @ref{Direction and placement}.
132
133
134 @predefined
135 @code{\autoBeamOn},
136 @code{\autoBeamOff},
137 @code{\dotsUp},
138 @code{\dotsDown},
139 @code{\dotsNeutral}.
140 @endpredefined
141
142
143 @seealso
144 Music Glossary:
145 @rglos{breve},
146 @rglos{longa},
147 @rglos{maxima},
148 @rglos{note value},
149 @rglos{Duration names notes and rests}.
150
151 Notation Reference:
152 @ref{Automatic beams},
153 @ref{Ties},
154 @ref{Stems},
155 @ref{Writing rhythms},
156 @ref{Writing rests},
157 @ref{Vocal music},
158 @ref{Ancient notation},
159 @ref{Proportional notation}.
160
161 Snippets:
162 @rlsr{Rhythms}.
163
164 Internals Reference:
165 @rinternals{Dots},
166 @rinternals{DotColumn}.
167
168
169 @knownissues
170
171 @c Deliberately duplicated in Durations and Rests.  -gp
172 There is no fundamental limit to rest durations (both in terms of
173 longest and shortest), but the number of glyphs is limited:
174 rests from 128th to maxima (8 x whole) may be printed.
175
176
177 @node Tuplets
178 @unnumberedsubsubsec Tuplets
179
180 @cindex tuplets
181 @cindex triplets
182
183 @funindex \times
184 @funindex times
185
186 Tuplets are made from a music expression by multiplying all the
187 durations with a fraction:
188
189 @example
190 \times @var{fraction} @{ @var{music} @}
191 @end example
192
193 @noindent
194 The duration of @var{music} will be multiplied by the
195 fraction.  The fraction's denominator will be printed over or
196 under the notes, optionally with a bracket.  The most common
197 tuplet is the triplet in which 3 notes have the duration of 2, so
198 the notes are 2/3 of their written length.
199
200 @lilypond[quote,verbatim,relative=2]
201 a2 \times 2/3 { b4 b b }
202 c4 c \times 2/3 { b4 a g }
203 @end lilypond
204
205 @cindex tuplet bracket placement
206
207 @funindex \tupletUp
208 @funindex tupletUp
209 @funindex \tupletDown
210 @funindex tupletDown
211 @funindex \tupletNeutral
212 @funindex tupletNeutral
213
214 Tuplet brackets may be manually placed above or below the staff;
215 see @ref{Direction and placement}.
216
217 Tuplets may be nested:
218
219 @lilypond[quote,verbatim,relative=2]
220 \autoBeamOff
221 c4 \times 4/5 { f8 e f \times 2/3 { e[ f g] } } f4 |
222 @end lilypond
223
224 Modifying nested tuplets which begin at the same musical moment
225 must be done with @code{\tweak}.
226
227 To modify the duration of notes without printing a tuplet bracket,
228 see @ref{Scaling durations}.
229
230
231 @predefined
232 @code{\tupletUp},
233 @code{\tupletDown},
234 @code{\tupletNeutral}.
235 @endpredefined
236
237
238 @snippets
239
240 @cindex tuplet formatting
241 @cindex triplet formatting
242
243 @funindex tupletNumberFormatFunction
244 @funindex tupletSpannerDuration
245
246 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
247 {entering-several-tuplets-using-only-one--times-command.ly}
248
249 @cindex Tuplet number changes
250
251 @funindex TupletNumber
252
253 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
254 {changing-the-tuplet-number.ly}
255
256 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
257 {non-default-tuplet-numbers.ly}
258
259 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
260 {permitting-line-breaks-within-beamed-tuplets.ly}
261
262
263 @seealso
264 Music Glossary:
265 @rglos{triplet},
266 @rglos{tuplet},
267 @rglos{polymetric}.
268
269 Learning Manual:
270 @rlearning{Tweaking methods}.
271
272 Notation Reference:
273 @ref{Time administration},
274 @ref{Scaling durations},
275 @ref{The tweak command},
276 @ref{Polymetric notation}.
277
278 Snippets:
279 @rlsr{Rhythms}.
280
281 Internals Reference:
282 @rinternals{TupletBracket},
283 @rinternals{TupletNumber},
284 @rinternals{TimeScaledMusic}.
285
286
287 @cindex grace notes within tuplet brackets
288
289 @knownissues
290 When the first note on a staff is a grace note followed by a
291 tuplet the grace note must be placed before the @code{\times}
292 command to avoid errors.  Anywhere else, grace notes may be
293 placed within tuplet brackets.
294
295
296 @node Scaling durations
297 @unnumberedsubsubsec Scaling durations
298
299 @cindex scaling durations
300 @cindex durations, scaling
301
302 You can alter the duration of single notes, rests or chords by a
303 fraction @code{N/M} by appending @code{*N/M} (or @code{*N} if @code{M}
304 is 1) to the duration.  This will not affect the appearance of the
305 notes or rests produced, but the altered duration will be used in
306 calculating the position within the measure and setting the duration
307 in the MIDI output.  Multiplying factors may be combined such as
308 @code{*L*M/N}.
309
310 In the following example, the first three notes take up exactly
311 two beats, but no triplet bracket is printed.
312
313 @lilypond[quote,relative=2,verbatim]
314 \time 2/4
315 % Alter durations to triplets
316 a4*2/3 gis4*2/3 a4*2/3
317 % Normal durations
318 a4 a4
319 % Double the duration of chord
320 <a d>4*2
321 % Duration of quarter, appears like sixteenth
322 b16*4 c4
323 @end lilypond
324
325 The duration of spacing notes may also be modified by
326 a multiplier.  This is useful for skipping many measures, e.g.,
327 @code{s1*23}.
328
329 @cindex compressing music
330 @cindex expanding music
331
332 @funindex \scaleDurations
333 @funindex scaleDurations
334
335 Longer stretches of music may be compressed by a fraction in the
336 same way, as if every note, chord or rest had the fraction as a
337 multiplier.  This leaves the appearance of the music unchanged but
338 the internal duration of the notes will be multiplied by the
339 fraction @emph{num}/@emph{den}.  The spaces around the dot are
340 required.  Here is an example showing how music can be compressed
341 and expanded:
342
343 @lilypond[quote,relative=2,verbatim]
344 \time 2/4
345 % Normal durations
346 <c a>4 c8 a
347 % Scale music by *2/3
348 \scaleDurations #'(2 . 3) {
349   <c a f>4. c8 a f
350 }
351 % Scale music by *2
352 \scaleDurations #'(2 . 1) {
353   <c' a>4 c8 b
354 }
355 @end lilypond
356
357 One application of this command is in polymetric
358 notation, see @ref{Polymetric notation}.
359
360
361 @seealso
362 Notation Reference:
363 @ref{Tuplets},
364 @ref{Invisible rests},
365 @ref{Polymetric notation}.
366
367 Snippets:
368 @rlsr{Rhythms}.
369
370
371 @node Ties
372 @unnumberedsubsubsec Ties
373
374 @cindex tie
375
376 @funindex ~
377
378 A tie connects two adjacent note heads of the same pitch.  The tie
379 in effect extends the duration of a note.
380
381 @warning{Ties should not be confused with @emph{slurs}, which
382 indicate articulation, or @emph{phrasing slurs}, which indicate
383 musical phrasing.  A tie is just a way of extending a note
384 duration, similar to the augmentation dot.}
385
386 A tie is entered using the tilde symbol (@code{~}).
387
388 @lilypond[quote,verbatim,relative=2]
389 a2 ~ a
390 @end lilypond
391
392 Ties are used either when the note crosses a bar line, or when
393 dots cannot be used to denote the rhythm.  Ties should also be
394 used when note values cross larger subdivisions of the measure:
395
396 @lilypond[verbatim,quote]
397 \relative c' {
398   r8 c8 ~ c2 r4 |
399   r8^"not" c2 ~ c8 r4
400 }
401 @end lilypond
402
403 If you need to tie many notes across bar lines, it may be
404 easier to use automatic note splitting, see @ref{Automatic note
405 splitting}.  This mechanism automatically splits long notes, and
406 ties them across bar lines.
407
408 @cindex ties and chords
409 @cindex chords and ties
410
411 When a tie is applied to a chord, all note heads whose pitches
412 match are connected.  When no note heads match, no ties will be
413 created.  Chords may be partially tied by placing the tie inside
414 the chord.
415
416 @lilypond[quote,verbatim,relative=1]
417 <c e g> ~ <c e g>
418 <c~ e g~ b> <c e g b>
419 @end lilypond
420
421 @cindex repeating ties
422 @cindex ties, repeating
423 @cindex volta brackets and ties
424 @cindex ties and volta brackets
425
426 @funindex \repeatTie
427 @funindex repeatTie
428
429 When a second alternative of a repeat starts with a tied note, you
430 have to specify the repeated tie as follows:
431
432 @lilypond[quote,relative=2,verbatim]
433 \repeat volta 2 { c g <c e>2 ~ }
434 \alternative {
435   % First alternative: following note is tied normally
436   { <c e>2. r4 }
437   % Second alternative: following note has a repeated tie
438   { <c e>2\repeatTie d4 c } }
439 @end lilypond
440
441 @cindex laissez vibrer
442 @cindex ties, laissez vibrer
443
444 @funindex \laissezVibrer
445 @funindex laissezVibrer
446
447 @notation{L.v.}@: ties (@notation{laissez vibrer}) indicate that
448 notes must not be damped at the end.  It is used in notation for
449 piano, harp and other string and percussion instruments.  They can
450 be entered as follows:
451
452 @lilypond[quote,verbatim,relative=1]
453 <c f g>1\laissezVibrer
454 @end lilypond
455
456 @cindex ties, placement
457
458 @funindex \tieUp
459 @funindex tieUp
460 @funindex \tieDown
461 @funindex tieDown
462 @funindex \tieNeutral
463 @funindex tieNeutral
464
465 Ties may be manually placed above or below the staff; see
466 @ref{Direction and placement}.
467
468 @cindex ties, appearance
469 @cindex ties, dotted
470 @cindex ties, dashed
471 @cindex dashed ties
472 @cindex dotted ties
473
474 @funindex \tieDotted
475 @funindex tieDotted
476 @funindex \tieDashed
477 @funindex tieDashed
478 @funindex \tieSolid
479 @funindex tieSolid
480
481 Ties may be made dashed, dotted, or a combination of solid and
482 dashed.
483
484 @lilypond[quote, verbatim, relative=1]
485 \tieDotted
486 c2 ~ c
487 \tieDashed
488 c2 ~ c
489 \tieHalfDashed
490 c2 ~ c
491 \tieHalfSolid
492 c2 ~ c
493 \tieSolid
494 c2 ~ c
495 @end lilypond
496
497 Custom dash patterns can be specified:
498
499 @lilypond[quote, verbatim, relative=1]
500 \tieDashPattern #0.3 #0.75
501 c2 ~ c
502 \tieDashPattern #0.7 #1.5
503 c2 ~ c
504 \tieSolid
505 c2 ~ c
506 @end lilypond
507
508 Dash pattern definitions for ties have the same structure as
509 dash pattern definitions for slurs.
510 For more information about complex dash patterns,
511 see the snippets under @ref{Slurs}.
512
513 @predefined
514 @code{\tieUp},
515 @code{\tieDown},
516 @code{\tieNeutral},
517 @code{\tieDotted},
518 @code{\tieDashed},
519 @code{\tieDashPattern},
520 @code{\tieHalfDashed},
521 @code{\tieHalfSolid},
522 @code{\tieSolid}.
523 @endpredefined
524
525
526 @snippets
527
528 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
529 {using-ties-with-arpeggios.ly}
530
531 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
532 {engraving-ties-manually.ly}
533
534
535 @seealso
536 Music Glossary:
537 @rglos{tie},
538 @rglos{laissez vibrer}.
539
540 Notation Reference:
541 @ref{Slurs},
542 @ref{Automatic note splitting}.
543
544 Snippets:
545 @rlsr{Rhythms}.
546
547 Internals Reference:
548 @rinternals{LaissezVibrerTie},
549 @rinternals{LaissezVibrerTieColumn},
550 @rinternals{TieColumn},
551 @rinternals{Tie}.
552
553
554 @knownissues
555
556 Switching staves when a tie is active will not produce a slanted
557 tie.
558
559 Changing clefs or octavations during a tie is not really
560 well-defined.  In these cases, a slur may be preferable.
561
562
563
564 @node Writing rests
565 @subsection Writing rests
566
567 Rests are entered as part of the music in music expressions.
568
569 @menu
570 * Rests::
571 * Invisible rests::
572 * Full measure rests::
573 @end menu
574
575 @node Rests
576 @unnumberedsubsubsec Rests
577
578 @cindex rest
579 @cindex rest, entering durations
580 @cindex maxima rest
581 @cindex longa rest
582 @cindex breve rest
583
584 @funindex \rest
585 @funindex rest
586 @funindex r
587 @funindex \maxima
588 @funindex maxima
589 @funindex \longa
590 @funindex longa
591 @funindex \breve
592 @funindex breve
593
594 Rests are entered like notes with the note name @code{r}.
595 Durations longer than a whole rest use the predefined
596 commands shown:
597
598 @c \time 16/1 is used to avoid spurious bar lines
599 @c and long tracts of empty measures
600 @lilypond[fragment,quote,verbatim]
601 \new Staff {
602   % These two lines are just to prettify this example
603   \time 16/1
604   \override Staff.TimeSignature #'stencil = ##f
605   % Print a maxima rest, equal to four breves
606   r\maxima
607   % Print a longa rest, equal to two breves
608   r\longa
609   % Print a breve rest
610   r\breve
611   r1 r2 r4 r8 r16 r32 r64 r128
612 }
613 @end lilypond
614
615 @cindex rest, multi-measure
616 @cindex rest, whole-measure
617
618 Whole measure rests, centered in the middle of the measure, must be
619 entered as multi-measure rests.  They can be used for a single
620 measure as well as many measures and are discussed in @ref{Full
621 measure rests}.
622
623 @cindex rest, specifying vertical position
624
625 To explicitly specify a rest's vertical position, write a note
626 followed by @code{\rest}.  A rest of the duration of the note will
627 be placed at the staff position where the note would appear.  This
628 allows for precise manual formatting of polyphonic music, since the
629 automatic rest collision formatter will not move these rests.
630
631 @lilypond[quote,verbatim,relative=2]
632 a4\rest d4\rest
633 @end lilypond
634
635 @snippets
636
637 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
638 {rest-styles.ly}
639
640
641 @seealso
642 Music Glossary:
643 @rglos{breve},
644 @rglos{longa},
645 @rglos{maxima}.
646
647 Notation Reference:
648 @ref{Full measure rests}.
649
650 Snippets:
651 @rlsr{Rhythms}.
652
653 Internals Reference:
654 @rinternals{Rest}.
655
656
657 @knownissues
658
659 @c Deliberately duplicated in Durations and Rests.  -gp
660 There is no fundamental limit to rest durations (both in terms of
661 longest and shortest), but the number of glyphs is limited: there
662 are rests from 128th to maxima (8 x whole).
663
664
665 @node Invisible rests
666 @unnumberedsubsubsec Invisible rests
667
668 @cindex skip
669 @cindex invisible rest
670 @cindex rest, invisible
671 @cindex spacer note
672 @cindex spacer rest
673
674 @funindex s
675 @funindex \skip
676 @funindex skip
677
678 An invisible rest (also called a @q{spacer rest}) can be entered
679 like a note with the note name@tie{}@code{s}:
680
681 @lilypond[verbatim,quote,relative=2]
682 c4 c s c
683 s2 c
684 @end lilypond
685
686 @cindex lyrics, skip
687
688 Spacer rests are available only in note mode and chord mode.  In
689 other situations, for example, when entering lyrics, the
690 command @code{\skip} is used to skip a musical moment.
691 @code{\skip} requires an explicit duration.
692
693 @lilypond[quote,verbatim,relative=2]
694 <<
695   {
696     a2 \skip2 a2 a2
697   }
698   \new Lyrics {
699     \lyricmode {
700       foo2 \skip 1 bla2
701     }
702   }
703 >>
704 @end lilypond
705
706 Because @code{\skip} is a command, it does not affect the default
707 durations of following notes, unlike@tie{}@code{s}.
708
709 @lilypond[quote,verbatim,relative=2]
710 <<
711   {
712     \repeat unfold 8 {a4}
713   }
714   {
715     a4 \skip 2 a |
716     s2 a
717   }
718 >>
719 @end lilypond
720
721
722 A spacer rest implicitly causes @code{Staff} and @code{Voice}
723 contexts to be created if none exist, just like notes and rests
724 do:
725
726 @lilypond[quote,verbatim,fragment]
727 s1 s s
728 @end lilypond
729
730 @code{\skip} simply skips musical time; it creates no output of
731 any kind.
732
733 @lilypond[quote,verbatim,fragment]
734 % This is valid input, but does nothing
735 \skip 1 \skip1 \skip 1
736 @end lilypond
737
738
739 @seealso
740 Learning Manual:
741 @rlearning{Visibility and color of objects}.
742
743 Notation Reference:
744 @ref{Hidden notes},
745 @ref{Visibility of objects}.
746
747 Snippets:
748 @rlsr{Rhythms}.
749
750 Internals Reference:
751 @rinternals{SkipMusic}.
752
753
754 @node Full measure rests
755 @unnumberedsubsubsec Full measure rests
756
757 @cindex multi-measure rests
758 @cindex full-measure rests
759 @cindex rest, multi-measure
760 @cindex rest, full-measure
761 @cindex whole rest for a full measure
762 @cindex rest, whole for a full measure
763
764 @funindex R
765
766 Rests for one or more full measures are entered like notes with
767 the note name uppercase @code{R}:
768
769 @lilypond[quote,verbatim,relative=2]
770 % Rest measures contracted to single measure
771 \compressFullBarRests
772 R1*4
773 R1*24
774 R1*4
775 b2^"Tutti" b4 a4
776 @end lilypond
777
778 The duration of full-measure rests is identical to the duration
779 notation used for notes.  The duration in a multi-measure rest must
780 always be an integral number of measure-lengths, so augmentation dots
781 or fractions must often be used:
782
783 @lilypond[quote,fragment,verbatim]
784 \compressFullBarRests
785 \time 2/4
786 R1 | R2 |
787 \time 3/4
788 R2. | R2.*2 |
789 \time 13/8
790 R1*13/8 | R1*13/8*12 |
791 \time 10/8
792 R4*5*4 |
793 @end lilypond
794
795 A full-measure rest is printed as either a whole or breve rest,
796 centered in the measure, depending on the time signature.
797
798 @lilypond[quote,verbatim,fragment]
799 \time 4/4
800 R1 |
801 \time 6/4
802 R1*3/2 |
803 \time 8/4
804 R1*2 |
805 @end lilypond
806
807 @cindex multi-measure rest, expanding
808 @cindex multi-measure rest, contracting
809
810 @funindex \expandFullBarRests
811 @funindex expandFullBarRests
812 @funindex \compressFullBarRests
813 @funindex compressFullBarRests
814
815 By default a multi-measure rest is expanded in the printed score to
816 show all the rest measures explicitly.  Alternatively, a multi-measure
817 rest can be shown as a single measure containing a multi-measure rest
818 symbol, with the number of measures of rest printed above the measure:
819
820 @lilypond[quote,fragment,verbatim]
821 % Default behavior
822 \time 3/4 r2. | R2.*2 |
823 \time 2/4 R2 |
824 \time 4/4
825 % Rest measures contracted to single measure
826 \compressFullBarRests
827 r1 | R1*17 | R1*4 |
828 % Rest measures expanded
829 \expandFullBarRests
830 \time 3/4
831 R2.*2 |
832 @end lilypond
833
834
835 @cindex text on multi-measure rest
836 @cindex multi-measure rest, attaching text
837 @cindex script on multi-measure rest
838 @cindex multi-measure rest, script
839 @cindex fermata on multi-measure rest
840 @cindex multi-measure rest, attaching fermata
841 @cindex markup on multi-measure rest
842 @cindex multi-measure rest with markup
843
844 @funindex \fermataMarkup
845 @funindex fermataMarkup
846 @funindex MultiMeasureRestText
847
848 Markups can be added to multi-measure rests.
849 The predefined command @code{\fermataMarkup}
850 is provided for adding fermatas.
851
852 @lilypond[quote,verbatim,fragment]
853 \compressFullBarRests
854 \time 3/4
855 R2.*10^\markup { \italic "ad lib." }
856 R2.^\fermataMarkup
857 @end lilypond
858
859 @warning{
860 Markups attached to a multi-measure rest are
861 objects of type @code{MultiMeasureRestText}, not
862 @code{TextScript}.  Overrides must be directed to the correct
863 object, or they will be ignored.  See the following example.
864 }
865
866 @lilypond[quote,verbatim,fragment]
867 % This fails, as the wrong object name is specified
868 \override TextScript #'padding = #5
869 R1^"wrong"
870 % This is correct and works
871 \override MultiMeasureRestText #'padding = #5
872 R1^"right"
873 @end lilypond
874
875 When a multi-measure rest immediately follows a @code{\partial}
876 setting, resulting bar-check warnings may not be displayed.
877
878
879 @funindex \textLengthOn
880 @funindex textLengthOn
881 @funindex \textLengthOff
882 @funindex textLenthOff
883 @funindex \fermataMarkup
884 @funindex fermataMarkup
885 @funindex \compressFullBarRests
886 @funindex compressFullBarRests
887 @funindex \expandFullBarRests
888 @funindex expandFullBarRests
889
890 @predefined
891 @code{\textLengthOn},
892 @code{\textLengthOff},
893 @code{\fermataMarkup},
894 @code{\compressFullBarRests},
895 @code{\expandFullBarRests}.
896 @endpredefined
897
898
899 @snippets
900
901 @cindex church rest
902 @cindex rest, church
903 @cindex kirchenpausen
904
905 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
906 {changing-form-of-multi-measure-rests.ly}
907
908 @cindex multi-measure rests, positioning
909 @cindex positioning multi-measure rests
910
911 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
912 {positioning-multi-measure-rests.ly}
913
914 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
915 {multi-measure-rest-markup.ly}
916
917
918 @seealso
919 Music Glossary:
920 @rglos{multi-measure rest}.
921
922 Notation Reference:
923 @ref{Durations},
924 @ref{Text},
925 @ref{Formatting text},
926 @ref{Text scripts}.
927
928 Snippets:
929 @rlsr{Rhythms}.
930
931 Internals Reference:
932 @rinternals{MultiMeasureRest},
933 @rinternals{MultiMeasureRestNumber},
934 @rinternals{MultiMeasureRestText}.
935
936
937 @cindex fingerings and multi-measure rests
938 @cindex multi-measure rests and fingerings
939
940 @knownissues
941
942 If an attempt is made to use fingerings (e.g.,
943 @code{R1*10-4}) to put numbers over multi-measure rests, the
944 fingering numeral (4) may collide with the bar counter
945 numeral (10).
946
947 @cindex condensing rests
948 @cindex rest, condensing ordinary
949
950 There is no way to automatically condense multiple ordinary rests
951 into a single multi-measure rest.
952
953 @cindex rest, collisions of
954
955 Multi-measure rests do not take part in rest collisions.
956
957 @node Displaying rhythms
958 @subsection Displaying rhythms
959
960 @menu
961 * Time signature::
962 * Upbeats::
963 * Unmetered music::
964 * Polymetric notation::
965 * Automatic note splitting::
966 * Showing melody rhythms::
967 @end menu
968
969 @node Time signature
970 @unnumberedsubsubsec Time signature
971
972 @cindex time signature
973 @cindex meter
974
975 @funindex \time
976 @funindex time
977
978 The time signature is set as follows:
979
980 @lilypond[quote,verbatim,relative=2]
981 \time 2/4 c2
982 \time 3/4 c2.
983 @end lilypond
984
985 @cindex time signature, visibility of
986
987 Time signatures are printed at the beginning of a piece
988 and whenever the time signature changes.  If a change takes place
989 at the end of a line a warning time signature sign is printed
990 there.  This default behavior may be changed, see
991 @ref{Visibility of objects}.
992
993 @lilypond[quote,verbatim,relative=2]
994 \time 2/4
995 c2 c
996 \break
997 c c
998 \break
999 \time 4/4
1000 c c c c
1001 @end lilypond
1002
1003 @cindex time signature style
1004 @cindex meter style
1005
1006 @funindex \numericTimeSignature
1007 @funindex numericTimeSignature
1008 @funindex \defaultTimeSignature
1009 @funindex defaultTimeSignature
1010
1011 The time signature symbol that is used in 2/2 and 4/4 time can be
1012 changed to a numeric style:
1013
1014 @lilypond[quote,verbatim,relative=2]
1015 % Default style
1016 \time 4/4 c1
1017 \time 2/2 c1
1018 % Change to numeric style
1019 \numericTimeSignature
1020 \time 4/4 c1
1021 \time 2/2 c1
1022 % Revert to default style
1023 \defaultTimeSignature
1024 \time 4/4 c1
1025 \time 2/2 c1
1026 @end lilypond
1027
1028
1029 Mensural time signatures are covered in
1030 @ref{Mensural time signatures}.
1031
1032
1033 @predefined
1034 @code{\numericTimeSignature},
1035 @code{\defaultTimeSignature}.
1036 @endpredefined
1037
1038
1039 @snippets
1040
1041 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
1042 {changing-the-time-signature-without-affecting-the-beaming.ly}
1043
1044 @cindex compound time signatures
1045 @cindex time signature, compound
1046
1047 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
1048 {compound-time-signatures.ly}
1049
1050 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
1051 {time-signature-printing-only-the-numerator-as-a-number-instead-of-the-fraction.ly}
1052
1053
1054 @seealso
1055 Music Glossary:
1056 @rglos{time signature}
1057
1058 Notation Reference:
1059 @ref{Mensural time signatures},
1060 @ref{Time administration}.
1061
1062 Snippets:
1063 @rlsr{Rhythms}.
1064
1065 Internals Reference:
1066 @rinternals{TimeSignature},
1067 @rinternals{Timing_translator}.
1068
1069
1070 @node Upbeats
1071 @unnumberedsubsubsec Upbeats
1072
1073 @cindex anacrusis
1074 @cindex upbeat
1075 @cindex partial measure
1076 @cindex measure, partial
1077 @cindex pickup measure
1078 @cindex measure, change length
1079
1080 @funindex measurePosition
1081 @funindex \partial
1082 @funindex partial
1083
1084 Partial or pick-up measures, such as an anacrusis or upbeat, are
1085 entered using the @code{\partial} command, with the syntax
1086
1087 @example
1088 \partial @var{duration}
1089 @end example
1090
1091 @noindent
1092 where @code{duration} is the rhythmic length of the interval
1093 before the start of the first complete measure:
1094
1095 @lilypond[quote,verbatim,relative=2]
1096 \partial 4 e4 |
1097 a2. c,4 |
1098 @end lilypond
1099
1100 The partial measure can be any duration less than a full measure:
1101
1102 @lilypond[quote,verbatim,relative=2]
1103 \partial 8*3 c8 d e |
1104 a2. c,4 |
1105 @end lilypond
1106
1107 Internally, @code{\partial} is translated into
1108
1109 @example
1110 \set Timing.measurePosition = -@var{duration}
1111 @end example
1112
1113 @noindent
1114 The property @code{measurePosition} contains a rational number
1115 indicating how much of the measure has passed at this point.  Note
1116 that this is set to a negative number by the @code{\partial}
1117 command: i.e., @code{\partial 4} is internally translated to
1118 @code{-4}, meaning @qq{there is a quarter note left in the measure.}
1119
1120
1121 @seealso
1122 Music Glossary:
1123 @rglos{anacrusis}.
1124
1125 Notation Reference:
1126 @ref{Grace notes}.
1127
1128 Snippets:
1129 @rlsr{Rhythms}.
1130
1131 Internal Reference:
1132 @rinternals{Timing_translator}.
1133
1134
1135 @knownissues
1136
1137 The @code{\partial} command is intended to be used only at the
1138 beginning of a piece.  If you use it after the beginning, some
1139 odd warnings may occur.
1140
1141 @node Unmetered music
1142 @unnumberedsubsubsec Unmetered music
1143
1144 @cindex bar lines, turning off
1145 @cindex bar numbering, turning off
1146 @cindex cadenza
1147 @cindex unmetered music
1148
1149 @funindex \cadenzaOn
1150 @funindex cadenzaOn
1151 @funindex \cadenzaOff
1152 @funindex cadenzaOff
1153
1154 Bar lines and bar numbers are calculated automatically.  For
1155 unmetered music (some cadenzas, for example), this is not desirable.
1156 To turn off automatic calculation of bar lines and bar numbers,
1157 use the command @code{\cadenzaOn}, and use @code{\cadenzaOff}
1158 to turn them on again.
1159
1160 @lilypond[verbatim,relative=2,fragment]
1161 c4 d e d
1162 \cadenzaOn
1163 c4 c d8 d d f4 g4.
1164 \cadenzaOff
1165 \bar "|"
1166 d4 e d c
1167 @end lilypond
1168
1169 Bar numbering is resumed at the end of the cadenza as if the
1170 cadenza were not there:
1171
1172 @lilypond[verbatim,relative=2,fragment]
1173 % Show all bar numbers
1174 \override Score.BarNumber #'break-visibility = #all-visible
1175 c4 d e d
1176 \cadenzaOn
1177 c4 c d8 d d f4 g4.
1178 \cadenzaOff
1179 \bar "|"
1180 d4 e d c
1181 @end lilypond
1182
1183 Note that these predefined commands affect all staves in the
1184 score, even when they are placed in just one @code{Voice}
1185 context.  To change this, move the @code{Timing_translator}
1186 from the @code{Score} context to the @code{Staff} context, as
1187 shown in @ref{Polymetric notation}.
1188
1189 @predefined
1190 @code{\cadenzaOn},
1191 @code{\cadenzaOff}.
1192 @endpredefined
1193
1194
1195 @seealso
1196 Music Glossary:
1197 @rglos{cadenza}.
1198
1199 Notation Reference:
1200 @ref{Visibility of objects},
1201 @ref{Polymetric notation}.
1202
1203 Snippets:
1204 @rlsr{Rhythms}.
1205
1206
1207 @cindex cadenza line breaks
1208 @cindex cadenza page breaks
1209 @cindex unmetered music, line breaks
1210 @cindex unmetered music, page breaks
1211 @cindex breaks in unmetered music
1212 @cindex line breaks in cadenzas
1213 @cindex page breaks in cadenzas
1214 @cindex line breaks in unmetered music
1215 @cindex page breaks in unmetered music
1216
1217 @knownissues
1218
1219 LilyPond will insert line breaks and page breaks only at a
1220 bar line.  Unless the unmetered music ends before the end of the
1221 staff line, you will need to insert invisible bar lines with
1222
1223 @example
1224 \bar ""
1225 @end example
1226
1227 @noindent
1228 to indicate where breaks can occur.
1229
1230 You must explicitly create a @code{Voice} context when starting a
1231 piece with @code{\cadenzaOn}, otherwise strange errors may occur.
1232
1233 @lilypond[verbatim,relative=2,fragment]
1234 \new Voice \relative c'{
1235   \cadenzaOn
1236   c16^"Solo Free Time" d e f g2. \bar "||"
1237   \cadenzaOff
1238 }
1239 @end lilypond
1240
1241
1242 @node Polymetric notation
1243 @unnumberedsubsubsec Polymetric notation
1244
1245 @c This section necessarily uses \set
1246 @c This is acceptable  -td
1247
1248 @cindex double time signatures
1249 @cindex signatures, polymetric
1250 @cindex time signatures, polymetric
1251 @cindex time signatures, double
1252 @cindex polymetric signatures
1253 @cindex meter, polymetric
1254
1255 @funindex timeSignatureFraction
1256 @funindex \scaleDurations
1257 @funindex scaleDurations
1258 @funindex \times
1259 @funindex times
1260
1261 Polymetric notation is supported, either explicitly or by modifying
1262 the visible time signature symbol and scaling the note durations.
1263
1264 @strong{@i{Staves with different time signatures, equal measure lengths}}
1265
1266 This notation can be created by setting a common time signature
1267 for each staff but replacing the symbol manually by setting
1268 @code{timeSignatureFraction} to the desired fraction and scaling
1269 the printed durations in each staff to the common time
1270 signature; see @ref{Time signature}.  The scaling is done with
1271 @code{\scaleDurations}, which is used in a similar way to
1272 @code{\times}, but does not create a tuplet bracket; see
1273 @ref{Scaling durations}.
1274
1275 @cindex beaming in polymetric music
1276 @cindex beaming in polymetric meter
1277
1278 In this example, music with the time signatures of 3/4, 9/8, and
1279 10/8 are used in parallel.  In the second staff, shown durations
1280 are multiplied by 2/3, as 2/3 * 9/8 = 3/4, and in the third
1281 staff, shown durations are multiplied by 3/5, as 3/5 * 10/8 = 3/4.
1282 It will often be necessary to insert beams manually, as the
1283 duration scaling affects the autobeaming rules.
1284
1285 @lilypond[quote,verbatim,fragment]
1286 \relative c' <<
1287   \new Staff {
1288     \time 3/4
1289     c4 c c |
1290     c c c |
1291   }
1292   \new Staff {
1293     \time 3/4
1294     \set Staff.timeSignatureFraction = #'(9 . 8)
1295     \scaleDurations #'(2 . 3)
1296     \repeat unfold 6 { c8[ c c] }
1297   }
1298   \new Staff {
1299     \time 3/4
1300     \set Staff.timeSignatureFraction = #'(10 . 8)
1301     \scaleDurations #'(3 . 5) {
1302       \repeat unfold 2 { c8[ c c] }
1303       \repeat unfold 2 { c8[ c] } |
1304       c4. c4. \times 2/3 { c8[ c c] } c4
1305     }
1306   }
1307 >>
1308 @end lilypond
1309
1310 @strong{@i{Staves with different time signatures, unequal bar lengths}}
1311
1312 Each staff can be given its own independent time signature by
1313 moving the @code{Timing_translator} and the
1314 @code{Default_bar_line_engraver} to the @code{Staff} context.
1315
1316 @lilypond[quote,verbatim]
1317 \layout {
1318   \context {
1319     \Score
1320     \remove "Timing_translator"
1321     \remove "Default_bar_line_engraver"
1322   }
1323   \context {
1324     \Staff
1325     \consists "Timing_translator"
1326     \consists "Default_bar_line_engraver"
1327   }
1328 }
1329
1330 % Now each staff has its own time signature.
1331
1332 \relative c' <<
1333   \new Staff {
1334     \time 3/4
1335     c4 c c |
1336     c4 c c |
1337   }
1338   \new Staff {
1339     \time 2/4
1340     c4 c |
1341     c4 c |
1342     c4 c |
1343   }
1344   \new Staff {
1345     \time 3/8
1346     c4. |
1347     c8 c c |
1348     c4. |
1349     c8 c c |
1350   }
1351 >>
1352 @end lilypond
1353
1354 @snippets
1355
1356 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
1357 {compound-time-signatures.ly}
1358
1359
1360 @seealso
1361 Music Glossary:
1362 @rglos{polymetric},
1363 @rglos{polymetric time signature},
1364 @rglos{meter}.
1365
1366 Notation Reference:
1367 @ref{Time signature},
1368 @ref{Scaling durations}.
1369
1370 Snippets:
1371 @rlsr{Rhythms}.
1372
1373 Internals Reference:
1374 @rinternals{TimeSignature},
1375 @rinternals{Timing_translator},
1376 @rinternals{Default_bar_line_engraver},
1377 @rinternals{Staff}.
1378
1379
1380 @knownissues
1381
1382 When using different time signatures in parallel, notes
1383 at the same moment will be placed at the same horizontal
1384 location.  However, the bar lines in the different staves
1385 will cause the note spacing to be less regular in each of the
1386 individual staves than would be normal without the different
1387 time signatures.
1388
1389 @node Automatic note splitting
1390 @unnumberedsubsubsec Automatic note splitting
1391
1392 @cindex notes, splitting
1393 @cindex splitting notes
1394
1395 @funindex Note_heads_engraver
1396 @funindex Completion_heads_engraver
1397
1398 Long notes which overrun bar lines can be converted automatically
1399 to tied notes.  This is done by replacing the
1400 @code{Note_heads_engraver} with the
1401 @code{Completion_heads_engraver}.  In the following
1402 example, notes crossing the bar lines are split and tied.
1403
1404 @lilypond[quote,verbatim,relative=1]
1405 \new Voice \with {
1406   \remove "Note_heads_engraver"
1407   \consists "Completion_heads_engraver"
1408 }
1409
1410 { c2. c8 d4 e f g a b c8 c2 b4 a g16 f4 e d c8. c2 }
1411 @end lilypond
1412
1413 This engraver splits all running notes at the bar line, and
1414 inserts ties.  One of its uses is to debug complex scores: if the
1415 measures are not entirely filled, then the ties show exactly how
1416 much each measure is off.
1417
1418
1419 @seealso
1420 Music Glossary:
1421 @rglos{tie}
1422
1423 Learning Manual:
1424 @rlearning{Engravers explained},
1425 @rlearning{Adding and removing engravers}.
1426
1427 Snippets:
1428 @rlsr{Rhythms}.
1429
1430 Internals Reference:
1431 @rinternals{Note_heads_engraver},
1432 @rinternals{Completion_heads_engraver},
1433 @rinternals{Forbid_line_break_engraver}.
1434
1435
1436 @knownissues
1437
1438 Not all durations (especially those containing tuplets) can be
1439 represented exactly with normal notes and dots, but the
1440 @code{Completion_heads_engraver} will not insert tuplets.
1441
1442 The @code{Completion_heads_engraver} only affects notes; it does not
1443 split rests.
1444
1445
1446 @node Showing melody rhythms
1447 @unnumberedsubsubsec Showing melody rhythms
1448
1449 @cindex melody rhythms, showing
1450 @cindex rhythms, showing melody
1451
1452 Sometimes you might want to show only the rhythm of a melody.  This
1453 can be done with the rhythmic staff.  All pitches of notes on such a
1454 staff are squashed, and the staff itself has a single line
1455
1456 @lilypond[quote,relative=1,verbatim]
1457 <<
1458   \new RhythmicStaff {
1459     \new Voice = "myRhythm" {
1460       \time 4/4
1461       c4 e8 f g2
1462       r4 g g f
1463       g1
1464     }
1465   }
1466   \new Lyrics {
1467     \lyricsto "myRhythm" {
1468       This is my song
1469       I like to sing
1470     }
1471   }
1472 >>
1473 @end lilypond
1474
1475 @cindex guitar chord charts
1476 @cindex strumming rhythms, showing
1477 @cindex guitar strumming rhythms, showing
1478
1479 @funindex Pitch_squash_engraver
1480 @funindex \improvisationOn
1481 @funindex improvisationOn
1482 @funindex \improvisationOff
1483 @funindex improvisationOff
1484
1485 Guitar chord charts often show the strumming rhythms.  This can
1486 be done with the @code{Pitch_squash_engraver} and
1487 @code{\improvisationOn}.
1488
1489
1490 @lilypond[quote,verbatim]
1491 <<
1492   \new ChordNames {
1493     \chordmode {
1494       c1 f g c
1495     }
1496   }
1497
1498   \new Voice \with {
1499     \consists Pitch_squash_engraver
1500   } \relative c'' {
1501     \improvisationOn
1502     c4 c8 c c4 c8 c
1503     f4 f8 f f4 f8 f
1504     g4 g8 g g4 g8 g
1505     c4 c8 c c4 c8 c
1506   }
1507 >>
1508 @end lilypond
1509
1510
1511 @predefined
1512 @code{\improvisationOn},
1513 @code{\improvisationOff}.
1514 @endpredefined
1515
1516
1517 @snippets
1518
1519 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
1520 {guitar-strum-rhythms.ly}
1521
1522
1523 @seealso
1524 Snippets:
1525 @rlsr{Rhythms}.
1526
1527 Internals Reference:
1528 @rinternals{RhythmicStaff},
1529 @rinternals{Pitch_squash_engraver}.
1530
1531
1532 @node Beams
1533 @subsection Beams
1534
1535 @menu
1536 * Automatic beams::
1537 * Setting automatic beam behavior::
1538 * Manual beams::
1539 * Feathered beams::
1540 @end menu
1541
1542 @node Automatic beams
1543 @unnumberedsubsubsec Automatic beams
1544
1545 By default, beams are inserted automatically:
1546
1547 @cindex beams, manual
1548 @cindex manual beams
1549 @cindex beams, setting rules for
1550 @cindex beams, custom rules for
1551
1552 @funindex \autoBeamOn
1553 @funindex autoBeamOn
1554 @funindex \autoBeamOff
1555 @funindex autoBeamOff
1556
1557 @lilypond[quote,verbatim,relative=2]
1558 \time 2/4 c8 c c c
1559 \time 6/8 c c c c8. c16 c8
1560 @end lilypond
1561
1562 If these automatic decisions are not satisfactory, beaming can be
1563 entered explicitly; see @ref{Manual beams}.  Beams @emph{must} be
1564 entered manually if beams are to be extended over rests.
1565
1566 If automatic beaming is not required, it may be turned off with
1567 @code{\autoBeamOff} and on with @code{\autoBeamOn}:
1568
1569 @lilypond[quote,relative=1,verbatim]
1570 c4 c8 c8. c16 c8. c16 c8
1571 \autoBeamOff
1572 c4 c8 c8. c16 c8.
1573 \autoBeamOn
1574 c16 c8
1575 @end lilypond
1576
1577 @cindex melismata, beams
1578 @cindex beams and melismata
1579
1580 @warning{If beams are used to indicate melismata in songs, then
1581 automatic beaming should be switched off with @code{\autoBeamOff}
1582 and the beams indicated manually.}
1583
1584 Beaming patterns that differ from the automatic defaults can be
1585 created; see @ref{Setting automatic beam behavior}.
1586
1587
1588 @predefined
1589 @code{\autoBeamOff},
1590 @code{\autoBeamOn}.
1591 @endpredefined
1592
1593
1594 @snippets
1595
1596 @cindex line breaks and beams
1597 @cindex beams and line breaks
1598
1599 @funindex breakable
1600
1601 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
1602 {beams-across-line-breaks.ly}
1603
1604 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
1605 {changing-beam-knee-gap.ly}
1606
1607
1608 @seealso
1609 Notation Reference:
1610 @ref{Manual beams},
1611 @ref{Setting automatic beam behavior}.
1612
1613 Installed Files:
1614 @file{scm/@/auto@/-beam@/.scm}.
1615
1616 Snippets:
1617 @rlsr{Rhythms}.
1618
1619 Internals Reference:
1620 @rinternals{Auto_beam_engraver},
1621 @rinternals{Beam_engraver},
1622 @rinternals{Beam},
1623 @rinternals{BeamEvent},
1624 @rinternals{BeamForbidEvent},
1625 @rinternals{beam-interface},
1626 @rinternals{unbreakable-spanner-interface}.
1627
1628
1629 @knownissues
1630
1631 Beams can collide with note heads and accidentals in other voices.
1632
1633
1634 @node Setting automatic beam behavior
1635 @unnumberedsubsubsec Setting automatic beam behavior
1636
1637
1638 @cindex automatic beams, tuning
1639 @cindex tuning automatic beaming
1640 @cindex automatic beam generation
1641 @cindex autobeam
1642 @cindex lyrics and beaming
1643
1644 @funindex autoBeaming
1645 @funindex beamSettings
1646 @funindex measureLength
1647 @funindex beatLength
1648 @funindex \time
1649 @funindex time
1650 @funindex \set
1651 @funindex set
1652
1653 The placement of automatic beams is determined by the time signature.
1654 Three types of rules are used for determining the end of automatic
1655 beams: @emph{default} rules
1656 for the time signature, @emph{explicit} rules for the beam in the time
1657 signature, and the @emph{beatLength} for the time signature.
1658
1659 The following rules, in order of priority, apply when determining
1660 the appearance of beams:
1661
1662 @itemize
1663 @item
1664 If a manual beam is specified with @code{[..]} set the beam
1665 as specified, otherwise
1666
1667 @item
1668 if @code{\autoBeamOff} is in force do not beam, otherwise
1669
1670 @item
1671 if an explicit beam-ending rule is defined for the beam type
1672 in the time signature, use it to determine the valid
1673 places where beams may end, otherwise
1674
1675 @item
1676 if a default beam-ending rule is defined in the time signature,
1677 use it to group notes with beams, otherwise
1678
1679 @item
1680 use the value of @code{beatLength} to group notes with beams
1681
1682 @end itemize
1683
1684 @i{@strong{Modifying the grouping of beats}}
1685
1686 By default @code{beatLength} is
1687 derived from the time signature set by the @code{\time} command.
1688 The @code{beatLength} is set to be one over the denominator
1689 of the time signature.
1690
1691 @code{beatLength} is a @i{moment},
1692 a unit of musical duration.  A quantity of type @i{moment} is
1693 created by the scheme function @code{ly:make-moment}.  For more
1694 information about this function, see @ref{Time administration}.
1695
1696 Autobeam settings are stored in the
1697 @code{beamSettings} property.  Default values of @code{beamSettings}
1698 are determined in @file{scm/@/beam@/-settings@/.scm}.  Entries in
1699 @code{beamSettings} are indexed by time signature and
1700 rule type.
1701
1702 Time signature should be a scheme pair , e.g. @code{#'(4 . 4)}.
1703
1704 Rule type should be @code{#'end} for beam ending.
1705
1706 The ending rules consist of a scheme alist
1707 (or list of pairs) that
1708 indicates the beam type and the grouping to be applied to
1709 beams containing notes with a shortest duration of that
1710 beam type.
1711
1712 @example
1713 #'((beam-type1 . grouping-1)
1714    (beam-type2 . grouping-2)
1715    (beam-type3 . grouping-3))
1716 @end example
1717
1718 Beam type is either a scheme pair indicating the duration
1719 of the beam, e.g. @code{(1 . 16)}, or @code{*} to indicate a
1720 default rule, which applies to all beams if no explicit rule is
1721 defined.
1722
1723 Grouping is a scheme list indicating the grouping to be applied to
1724 the beam.  For default rules (where beam type is
1725 @code{*}, the grouping is in units of @code{beatLength}.
1726 For explicit rules, the grouping is in units of the beam type.
1727
1728 For reference, the default beaming rules are found in
1729 @file{scm/beam-settings.scm}.
1730
1731 Beam settings are changed with
1732 @code{\overrideBeamSettings} and @code{\revertBeamSettings}.
1733
1734 @warning{
1735 The ending settings must be
1736 @emph{complete} rules.  That is, every rule that should apply to
1737 the current time signature must be included in the setting.
1738 It is not possible to change the grouping of only one beam type
1739 for a given time signature.  While this may seem cumbersome,
1740 it means that the current beaming settings need not be known
1741 in order to specify a new beaming pattern.}
1742
1743 @lilypond[quote,relative=2,verbatim]
1744 \time 5/16
1745 c8^"beats" c16 c8 |
1746 \overrideBeamSettings #'Score #'(5 . 16) #'end #'((* . (2 3)))
1747 c8^"(2+3)" c16 c8
1748 \overrideBeamSettings #'Score #'(5 . 16) #'end #'((* . (3 2)))
1749 c8^"(3+2)" c16 c8
1750 @end lilypond
1751
1752 Beam setting changes can be limited to specific contexts.  If no
1753 setting is included in a lower-level context, the setting of the
1754 enclosing context will apply.
1755
1756 @lilypond[quote, verbatim,relative=1]
1757 \new Staff <<
1758   \time 7/8
1759   \new Voice = one {
1760     \relative c'' {
1761       \overrideBeamSettings #'Staff #'(7 . 8) #'end #'((* . (2 3 2)))
1762         a8 a a a a a a
1763     }
1764   }
1765   \new Voice  = two {
1766     \relative c' {
1767       \voiceTwo
1768       \overrideBeamSettings #'Voice #'(7 . 8) #'end #'((* . (1 3 3)))
1769       f8 f f f f f f
1770     }
1771   }
1772 >>
1773 @end lilypond
1774
1775 When multiple voices are used the @code{Staff} context must be
1776 specified if the beaming is to be applied to all voices in the
1777 staff:
1778
1779 @lilypond[quote,verbatim,relative=2]
1780 \time 7/8
1781 % rhythm 3-1-1-2
1782 % Context Voice specified --  does not work correctly
1783 % Because of autogenerated voices, all beating will
1784 % be at beatLength (1 . 8)
1785 \overrideBeamSettings #'Voice #'(7 . 8) #'end #'((* . (3 1 1 2)))
1786 << {a8 a a a16 a a a a8 a} \\ {f4. f8 f f f} >>
1787
1788 % Works correctly with context Staff specified
1789 \overrideBeamSettings #'Staff #'(7 . 8) #'end #'((* . (3 1 1 2)))
1790 << {a8 a a a16 a a a a8 a} \\ {f4. f8 f f f} >>
1791 @end lilypond
1792
1793 @funindex revertBeamSettings
1794
1795 Beam settings can be reverted to get back to default behavior.  This
1796 is accomplished by using @code{\revertBeamSettings}.  The arguments
1797 are the same as for @code{\overrideBeamSettings}, except no value
1798 for @var{grouping} is given:
1799
1800 @example
1801 \revertBeamSettings context time-signature rule-type
1802 @end example
1803
1804
1805 @lilypond[quote,verbatim,relative=2]
1806 \time 4/4
1807 \repeat unfold 8 {a8}
1808 % set default rule for (1 1 1 1) grouping
1809 \overrideBeamSettings #'Score #'(4 . 4) #'end #'((* . (1 1 1 1)))
1810 \repeat unfold 8 {a8}
1811 % revert the new rule
1812 \revertBeamSettings #'Score #'(4 . 4) #'end
1813 \repeat unfold 8 {a8}
1814 @end lilypond
1815
1816
1817 @predefined
1818 @code{\overrideBeamSettings},
1819 @code{\revertBeamSettings}.
1820 @endpredefined
1821
1822
1823 @snippets
1824
1825 @cindex beams, subdividing
1826
1827 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
1828 {sub-dividing-beams.ly}
1829
1830 @cindex measure groupings
1831 @cindex beats, grouping
1832 @cindex grouping beats
1833 @cindex measure sub-grouping
1834
1835 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
1836 {conducting-signs,-measure-grouping-signs.ly}
1837
1838 @cindex beam, last in score
1839 @cindex beam, last in polyphonic voice
1840
1841 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
1842 {beam-endings-in-score-context.ly}
1843
1844
1845 @seealso
1846 Installed files:
1847 @file{scm/beam-settings.scm}.
1848
1849 Snippets:
1850 @rlsr{Rhythms}.
1851
1852 Internals Reference:
1853 @rinternals{Auto_beam_engraver},
1854 @rinternals{Beam},
1855 @rinternals{BeamForbidEvent},
1856 @rinternals{beam-interface}.
1857
1858
1859 @knownissues
1860
1861 If a score ends while an automatic beam has not been ended and is
1862 still accepting notes, this last beam will not be typeset at all.
1863 The same holds for polyphonic voices, entered with @code{<<
1864 @dots{} \\ @dots{} >>}.  If a polyphonic voice ends while an
1865 automatic beam is still accepting notes, it is not typeset.
1866 The workaround for these problems is to manually beam the last
1867 beam in the voice or score.
1868
1869 @node Manual beams
1870 @unnumberedsubsubsec Manual beams
1871
1872 @cindex beams, manual
1873 @cindex manual beams
1874
1875 @funindex ]
1876 @funindex [
1877
1878 In some cases it may be necessary to override the automatic
1879 beaming algorithm.  For example, the autobeamer will not put beams
1880 over rests or bar lines, and in choral scores the beaming is
1881 often set to follow the meter of the lyrics rather than the
1882 notes.  Such beams can be specified manually by
1883 marking the begin and end point with @code{[} and @code{]}.
1884
1885 @lilypond[quote,relative=1,verbatim]
1886 r4 r8[ g' a r8] r8 g[ | a] r8
1887 @end lilypond
1888
1889 @cindex manual beams, direction shorthand for
1890
1891 Beaming direction can be set manually using direction indicators:
1892
1893 @lilypond[quote,relative=2,verbatim]
1894 c8^[ d e] c,_[ d e f g]
1895 @end lilypond
1896
1897 @funindex \noBeam
1898 @funindex noBeam
1899
1900 Individual notes may be marked with @code{\noBeam} to prevent them
1901 from being beamed:
1902
1903 @lilypond[quote,verbatim,relative=2]
1904 \time 2/4
1905 c8 c\noBeam c c
1906 @end lilypond
1907
1908 @funindex stemLeftBeamCount
1909 @funindex stemRightBeamCount
1910
1911 Even more strict manual control with the beams can be achieved by
1912 setting the properties @code{stemLeftBeamCount} and
1913 @code{stemRightBeamCount}.  They specify the number of beams to
1914 draw on the left and right side, respectively, of the next note.
1915 If either property is set, its value will be used only once, and
1916 then it is erased.  In this example, the last @code{f} is printed
1917 with only one beam on the left side, i.e., the eighth-note beam of
1918 the group as a whole.
1919
1920 @lilypond[quote,relative=2,verbatim]
1921 a8[ r16 f g a]
1922 a8[ r16
1923 \set stemLeftBeamCount = #2
1924 \set stemRightBeamCount = #1
1925 f16
1926 \set stemLeftBeamCount = #1
1927 g16 a]
1928 @end lilypond
1929
1930
1931 @predefined
1932 @code{\noBeam}.
1933 @endpredefined
1934
1935
1936 @snippets
1937
1938 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
1939 {flat-flags-and-beam-nibs.ly}
1940
1941
1942 @seealso
1943 Notation Reference:
1944 @ref{Direction and placement}.
1945
1946 Snippets:
1947 @rlsr{Rhythms}.
1948
1949 Internals Reference:
1950 @rinternals{Beam},
1951 @rinternals{BeamEvent},
1952 @rinternals{Beam_engraver},
1953 @rinternals{beam-interface},
1954 @rinternals{Stem_engraver}.
1955
1956
1957 @node Feathered beams
1958 @unnumberedsubsubsec Feathered beams
1959
1960 @cindex beams, feathered
1961 @cindex feathered beams
1962
1963 @funindex \featherDurations
1964 @funindex featherDurations
1965 @funindex grow-direction
1966
1967 Feathered beams are used to indicate that a small group of notes
1968 should be played at an increasing (or decreasing) tempo, without
1969 changing the overall tempo of the piece.  The extent of the
1970 feathered beam must be indicated manually using @code{[} and
1971 @code{]}, and the beam feathering is turned on by specifying a
1972 direction to the @code{Beam} property @code{grow-direction}.
1973
1974 If the placement of the notes and the sound in the MIDI output is to
1975 reflect the ritardando or accelerando indicated by the feathered beam
1976 the notes must be grouped as a music expression delimited by braces
1977 and preceded by a @code{featherDurations} command which specifies
1978 the ratio between the durations of the first and last notes in the
1979 group.
1980
1981 The square brackets show the extent of the beam and the braces show
1982 which notes are to have their durations modified.  Normally these
1983 would delimit the same group of notes, but this is not required: the
1984 two commands are independent.
1985
1986 In the following example the eight 16th notes occupy exactly the
1987 same time as a half note, but the first note is one half as long
1988 as the last one, with the intermediate notes gradually
1989 lengthening.  The first four 32nd notes gradually speed up, while
1990 the last four 32nd notes are at a constant tempo.
1991
1992 @lilypond[relative=1,verbatim,quote]
1993 \override Beam #'grow-direction = #LEFT
1994 \featherDurations #(ly:make-moment 2 1)
1995 { c16[ c c c c c c c] }
1996 \override Beam #'grow-direction = #RIGHT
1997 \featherDurations #(ly:make-moment 2 3)
1998 { c32[ d e f] }
1999 % revert to non-feathered beams
2000 \override Beam #'grow-direction = #'()
2001 { g32[ a b c] }
2002 @end lilypond
2003
2004 @noindent
2005 The spacing in the printed output represents the
2006 note durations only approximately, but the MIDI output is exact.
2007
2008
2009 @predefined
2010 @code{\featherDurations}.
2011 @endpredefined
2012
2013 @seealso
2014 Snippets:
2015 @rlsr{Rhythms}.
2016
2017
2018 @knownissues
2019
2020 The @code{\featherDurations} command only works with very short
2021 music snippets, and when numbers in the fraction are small.
2022
2023
2024 @node Bars
2025 @subsection Bars
2026
2027
2028 @menu
2029 * Bar lines::
2030 * Bar numbers::
2031 * Bar and bar number checks::
2032 * Rehearsal marks::
2033 @end menu
2034
2035 @node Bar lines
2036 @unnumberedsubsubsec Bar lines
2037
2038 @cindex bar lines
2039 @cindex measure lines
2040 @cindex closing bar lines
2041 @cindex bar lines, closing
2042 @cindex double bar lines
2043 @cindex bar lines, double
2044 @cindex repeat bars
2045
2046 @funindex \bar
2047 @funindex bar
2048
2049 Bar lines delimit measures, and are also used to indicate
2050 repeats.  Normally, simple bar lines are automatically inserted
2051 into the printed output at places based on the current time
2052 signature.
2053
2054 The simple bar lines inserted automatically can be changed to
2055 other types with the @code{\bar} command.  For example, a closing
2056 double bar line is usually placed at the end of a piece:
2057
2058 @lilypond[quote,relative=1,verbatim]
2059 e4 d c2 \bar "|."
2060 @end lilypond
2061
2062 It is not invalid if the final note in a measure does not
2063 end on the automatically entered bar line: the note is assumed
2064 to carry over into the next measure.  But if a long sequence
2065 of such carry-over measures appears the music can appear compressed
2066 or even flowing off the page.  This is because automatic line
2067 breaks happen only at the end of complete measures, i.e., where
2068 all notes end before the end of a measure.
2069
2070 @warning{An incorrect duration can cause line breaks to be
2071 inhibited, leading to a line of highly compressed music or
2072 music which flows off the page.}
2073
2074 @cindex line breaks
2075 @cindex bar lines, invisible
2076 @cindex measure lines, invisible
2077
2078 Line breaks are also permitted at manually inserted bar lines
2079 even within incomplete measures.  To allow a line break without
2080 printing a bar line, use the following:
2081
2082 @example
2083 \bar ""
2084 @end example
2085
2086 @noindent
2087 This will insert an invisible bar line and allow (but not
2088 force) a line break to occur at this point.  The bar number
2089 counter is not increased.  To force a line break see
2090 @ref{Line breaking}.
2091
2092 @cindex manual bar lines
2093 @cindex manual measure lines
2094 @cindex bar lines, manual
2095 @cindex measure lines, manual
2096
2097 This and other special bar lines may be inserted manually at any
2098 point.  When they coincide with the end of a measure they replace
2099 the simple bar line which would have been inserted there
2100 automatically.  When they do not coincide with the end of a measure
2101 the specified bar line is inserted at that point in the printed
2102 output.
2103
2104 Note that manual bar lines are purely visual.  They do not affect
2105 any of the properties that a normal bar line would affect, such as
2106 measure numbers, accidentals, line breaks, etc.  They do not affect
2107 the calculation and placement of subsequent automatic bar lines.
2108 When a manual bar line is placed where a normal bar line already
2109 exists, the effects of the original bar line are not altered.
2110
2111 Two types of simple bar lines and five types of double bar lines are
2112 available for manual insertion:
2113
2114 @lilypond[quote,relative=1,verbatim]
2115 f1 \bar "|"
2116 f1 \bar "."
2117 g1 \bar "||"
2118 a1 \bar ".|"
2119 b1 \bar ".|."
2120 c1 \bar "|.|"
2121 d1 \bar "|."
2122 e1
2123 @end lilypond
2124
2125 @noindent
2126 together with dotted and dashed bar lines:
2127
2128 @lilypond[quote,relative=1,verbatim]
2129 f1 \bar ":"
2130 g1 \bar "dashed"
2131 a1
2132 @end lilypond
2133
2134 @noindent
2135 and five types of repeat bar line:
2136
2137 @lilypond[quote,relative=1,verbatim]
2138 f1 \bar "|:"
2139 g1 \bar ":|:"
2140 a1 \bar ":|.|:"
2141 b1 \bar ":|.:"
2142 c1 \bar ":|"
2143 d1
2144 @end lilypond
2145
2146 Additionally, a bar line can be printed as a simple tick:
2147 @lilypond[quote,relative=1,verbatim]
2148 f1 \bar "'"
2149 @end lilypond
2150 However, as such ticks are typically used in Gregorian chant, it is
2151 preferable to use @code{\divisioMinima} there instead, described in
2152 the section @ref{Divisiones} in Gregorian chant.
2153
2154
2155 @cindex repeats
2156
2157 Although the bar line types signifying repeats may be inserted
2158 manually they do not in themselves cause LilyPond to recognize
2159 a repeated section.  Such repeated sections are better entered
2160 using the various repeat commands (see @ref{Repeats}), which
2161 automatically print the appropriate bar lines.
2162
2163 In addition, you can specify @code{"||:"}, which is equivalent to
2164 @code{"|:"} except at line breaks, where it gives a double bar
2165 line at the end of the line and a start repeat at the beginning of
2166 the next line.
2167
2168 @lilypond[quote,relative=2,verbatim]
2169 c4 c c c
2170 \bar "||:"
2171 c4 c c c \break
2172 \bar "||:"
2173 c4 c c c
2174 @end lilypond
2175
2176 In scores with many staves, a @code{\bar} command in one staff is
2177 automatically applied to all staves.  The resulting bar lines are
2178 connected between different staves of a @code{StaffGroup},
2179 @code{PianoStaff}, or @code{GrandStaff}.
2180
2181 @lilypond[quote,relative=1,verbatim]
2182 <<
2183   \new StaffGroup <<
2184     \new Staff {
2185       e4 d
2186       \bar "||"
2187       f4 e
2188     }
2189     \new Staff { \clef bass c4 g e g }
2190   >>
2191   \new Staff { \clef bass c2 c2 }
2192 >>
2193 @end lilypond
2194
2195
2196 @cindex default bar lines, changing
2197 @cindex bar lines, default, changing
2198
2199 @snippets
2200
2201 @funindex whichBar
2202 @funindex defaultBarType
2203 @funindex \bar
2204 @funindex bar
2205 @funindex bartype
2206
2207 The command @code{\bar }@var{bartype} is a shortcut for
2208 @code{\set Timing.whichBar = }@var{bartype}.  A bar line is
2209 created whenever the @code{whichBar} property is set.
2210
2211 The default bar type used for automatically inserted bar lines is
2212 @code{"|"}.  This may be changed at any time
2213 with @code{\set Timing.defaultBarType = }@var{bartype}.
2214
2215
2216 @seealso
2217 Notation Reference:
2218 @ref{Line breaking},
2219 @ref{Repeats},
2220 @ref{Grouping staves}.
2221
2222 Snippets:
2223 @rlsr{Rhythms}.
2224
2225 Internals Reference:
2226 @rinternals{BarLine} (created at @code{Staff} level),
2227 @rinternals{SpanBar} (across staves),
2228 @rinternals{Timing_translator} (for Timing properties).
2229
2230
2231 @node Bar numbers
2232 @unnumberedsubsubsec Bar numbers
2233
2234 @cindex bar numbers
2235 @cindex measure numbers
2236 @cindex numbers, bar
2237 @cindex numbers, measure
2238
2239 @funindex currentBarNumber
2240
2241 Bar numbers are typeset by default at the start of every line except
2242 the first line.  The number itself is stored in the
2243 @code{currentBarNumber} property, which is normally updated
2244 automatically for every measure.  It may also be set manually:
2245
2246 @lilypond[verbatim,quote,relative=1]
2247 c1 c c c
2248 \break
2249 \set Score.currentBarNumber = #50
2250 c1 c c c
2251 @end lilypond
2252
2253 @cindex bar numbers, regular spacing
2254
2255 @funindex barNumberVisibility
2256 @funindex BarNumber
2257
2258 Bar numbers can be typeset at regular intervals instead of just at
2259 the beginning of every line.  To do this the default behavior
2260 must be overridden to permit bar numbers to be printed at places
2261 other than the start of a line.  This is controlled by the
2262 @code{break-visibility} property of @code{BarNumber}.  This takes
2263 three values which may be set to @code{#t} or @code{#f} to specify
2264 whether the corresponding bar number is visible or not.  The order
2265 of the three values is @code{end of line visible}, @code{middle of
2266 line visible}, @code{beginning of line visible}.  In the following
2267 example bar numbers are printed at all possible places:
2268
2269 @lilypond[verbatim,quote,relative=1]
2270 \override Score.BarNumber #'break-visibility = #'#(#t #t #t)
2271 \set Score.currentBarNumber = #11
2272 % Permit first bar number to be printed
2273 \bar ""
2274 c1 | c | c | c
2275 \break
2276 c1 | c | c | c
2277 @end lilypond
2278
2279
2280 @snippets
2281
2282 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
2283 {printing-the-bar-number-for-the-first-measure.ly}
2284
2285 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
2286 {printing-bar-numbers-at-regular-intervals.ly}
2287
2288 @cindex measure number, format
2289 @cindex bar number, format
2290
2291 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
2292 {printing-bar-numbers-inside-boxes-or-circles.ly}
2293
2294 @cindex bar number alignment
2295
2296 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
2297 {aligning-bar-numbers.ly}
2298
2299 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
2300 {removing-bar-numbers-from-a-score.ly}
2301
2302
2303 @seealso
2304 Snippets:
2305 @rlsr{Rhythms}.
2306
2307 Internals Reference:
2308 @rinternals{BarNumber},
2309 @rinternals{Bar_number_engraver}.
2310
2311
2312 @cindex bar number collision
2313 @cindex collision, bar number
2314
2315 @knownissues
2316
2317 Bar numbers may collide with the top of the @code{StaffGroup} bracket,
2318 if there is one.  To solve this, the @code{padding} property of
2319 @code{BarNumber} can be used to position the number correctly.  See
2320 @rinternals{StaffGroup} and @rinternals{BarNumber} for more.
2321
2322
2323 @node Bar and bar number checks
2324 @unnumberedsubsubsec Bar and bar number checks
2325
2326 @cindex bar check
2327 @cindex bar number check
2328 @cindex measure check
2329 @cindex measure number check
2330
2331 @funindex barCheckSynchronize
2332 @funindex |
2333
2334 Bar checks help detect errors in the entered durations.  A bar check
2335 may be entered using the bar symbol, @code{|}, at any place where a
2336 bar line is expected to fall.  If bar check lines are encountered at
2337 other places, a list of warnings is printed in the log file, showing
2338 the line numbers and lines in which the bar checks failed.  In the
2339 next example, the second bar check will signal an error.
2340
2341 @example
2342 \time 3/4 c2 e4 | g2 |
2343 @end example
2344
2345 Bar checks can also be used in lyrics:
2346
2347 @example
2348 \lyricmode @{
2349   \time 2/4
2350   Twin -- kle | Twin -- kle |
2351 @}
2352 @end example
2353
2354 An incorrect duration can result in a completely garbled score,
2355 especially if the score is polyphonic, so a good place to start
2356 correcting input is by scanning for failed bar checks and
2357 incorrect durations.
2358
2359 If successive bar checks are off by the same musical interval,
2360 only the first warning message is displayed.  This allows the
2361 warning to focus on the source of the timing error.
2362
2363
2364 @funindex |
2365 @funindex pipeSymbol
2366
2367 It is also possible to redefine the action taken when a bar check
2368 or pipe symbol, @code{|}, is encountered in the input, so that
2369 it does something other than a bar check.  This is done by
2370 assigning a music expression to @code{pipeSymbol}.
2371 In the following example @code{|} is set to insert a double bar
2372 line wherever it appears in the input, rather than checking
2373 for end of bar.
2374
2375 @lilypond[quote,verbatim]
2376 pipeSymbol = \bar "||"
2377 {
2378   c'2 c'2 |
2379   c'2 c'2
2380   c'2 | c'2
2381   c'2 c'2
2382 }
2383 @end lilypond
2384
2385 @funindex \barNumberCheck
2386 @funindex barNumberCheck
2387
2388 When copying large pieces of music, it can be helpful to check that
2389 the LilyPond bar number corresponds to the original that you are
2390 entering from.  This can be checked with @code{\barNumberCheck}, for
2391 example,
2392
2393 @verbatim
2394 \barNumberCheck #123
2395 @end verbatim
2396
2397 @noindent
2398 will print a warning if the @code{currentBarNumber} is not 123
2399 when it is processed.
2400
2401
2402 @seealso
2403 Snippets:
2404 @rlsr{Rhythms}.
2405
2406
2407 @node Rehearsal marks
2408 @unnumberedsubsubsec Rehearsal marks
2409
2410 @cindex rehearsal marks
2411 @cindex mark, rehearsal
2412
2413 @funindex \mark
2414 @funindex mark
2415
2416 To print a rehearsal mark, use the @code{\mark} command.
2417
2418 @lilypond[quote,verbatim,relative=2]
2419 c1 \mark \default
2420 c1 \mark \default
2421 c1 \mark \default
2422 c1 \mark \default
2423 @end lilypond
2424
2425 @noindent
2426 The mark is incremented automatically if you use @code{\mark
2427 \default}, but you can also use an integer argument to set the
2428 mark manually.  The value to use is stored in the property
2429 @code{rehearsalMark}.
2430
2431 @lilypond[quote,verbatim,relative=2]
2432 c1 \mark \default
2433 c1 \mark \default
2434 c1 \mark #8
2435 c1 \mark \default
2436 c1 \mark \default
2437 @end lilypond
2438
2439 @noindent
2440 The letter@tie{}@q{I} is skipped in accordance with engraving
2441 traditions.  If you wish to include the letter @q{I}, then use one
2442 of the following commands, depending on which style of rehearsal mark
2443 you want (letters only, letters in a hollow box, or letters in a
2444 hollow circle).
2445
2446 @example
2447 \set Score.markFormatter = #format-mark-alphabet
2448 \set Score.markFormatter = #format-mark-box-alphabet
2449 \set Score.markFormatter = #format-mark-circle-alphabet
2450 @end example
2451
2452 @lilypond[quote,verbatim,relative=2]
2453 \set Score.markFormatter = #format-mark-box-alphabet
2454 c1 \mark \default
2455 c1 \mark \default
2456 c1 \mark #8
2457 c1 \mark \default
2458 c1 \mark \default
2459 @end lilypond
2460
2461 @cindex rehearsal mark format
2462 @cindex rehearsal mark style
2463 @cindex style, rehearsal mark
2464 @cindex format, rehearsal mark
2465 @cindex mark, rehearsal, style
2466 @cindex mark, rehearsal, format
2467 @cindex rehearsal mark, manual
2468 @cindex mark, rehearsal, manual
2469 @cindex custom rehearsal mark
2470 @cindex manual rehearsal mark
2471
2472 The style is defined by the property @code{markFormatter}.  It is
2473 a function taking the current mark (an integer) and the current
2474 context as argument.  It should return a markup object.  In the
2475 following example, @code{markFormatter} is set to a pre-defined
2476 procedure.  After a few measures, it is set to a procedure that
2477 produces a boxed number.
2478
2479 @lilypond[quote,verbatim,relative=2]
2480 \set Score.markFormatter = #format-mark-numbers
2481 c1 \mark \default
2482 c1 \mark \default
2483 \set Score.markFormatter = #format-mark-box-numbers
2484 c1 \mark \default
2485 \set Score.markFormatter = #format-mark-circle-numbers
2486 c1 \mark \default
2487 \set Score.markFormatter = #format-mark-circle-letters
2488 c1
2489 @end lilypond
2490
2491 The file @file{scm/@/translation@/-functions@/.scm} contains the
2492 definitions of @code{format-mark-numbers} (the default format),
2493 @code{format-mark-box-numbers}, @code{format-mark-letters} and
2494 @code{format-mark-box-letters}.  These can be used as inspiration
2495 for other formatting functions.
2496
2497 You may use @code{format-mark-barnumbers},
2498 @code{format-mark-box-barnumbers}, and
2499 @code{format-mark-circle-barnumbers} to get bar numbers instead of
2500 incremented numbers or letters.
2501
2502 Other styles of rehearsal mark can be specified manually:
2503
2504 @example
2505 \mark "A1"
2506 @end example
2507
2508 @noindent
2509 Note that @code{Score.markFormatter} does not affect marks specified
2510 in this manner.  However, it is possible to apply a @code{\markup} to the
2511 string.
2512
2513 @example
2514 \mark \markup@{ \box A1 @}
2515 @end example
2516
2517 @cindex segno
2518 @cindex coda
2519 @cindex D.S. al Fine
2520 @cindex fermata
2521 @cindex music glyphs
2522 @cindex glyphs, music
2523
2524 @funindex \musicglyph
2525 @funindex musicglyph
2526
2527 Music glyphs (such as the segno sign) may be printed inside a
2528 @code{\mark}
2529
2530 @lilypond[quote,verbatim,relative=1]
2531 c1 \mark \markup { \musicglyph #"scripts.segno" }
2532 c1 \mark \markup { \musicglyph #"scripts.coda" }
2533 c1 \mark \markup { \musicglyph #"scripts.ufermata" }
2534 c1
2535 @end lilypond
2536
2537 @noindent
2538 See @ref{The Feta font}, for a list of symbols which may be
2539 printed with @code{\musicglyph}.
2540
2541 For common tweaks to the positioning of rehearsal marks, see
2542 @ref{Formatting text}.  For more precise control, see
2543 @code{break-alignable-interface} in @ref{Aligning objects}.
2544
2545
2546 @seealso
2547 Notation Reference:
2548 @ref{The Feta font},
2549 @ref{Formatting text},
2550 @ref{Aligning objects}.
2551
2552 Installed Files:
2553 @file{scm/@/translation@/-functions@/.scm} contains
2554 the definitions of @code{format-mark-numbers} and
2555 @code{format-mark-letters}.  They can be used as inspiration for
2556 other formatting functions.
2557
2558 Snippets:
2559 @rlsr{Rhythms}.
2560
2561 Internals Reference:
2562 @rinternals{MarkEvent},
2563 @rinternals{Mark_engraver},
2564 @rinternals{RehearsalMark}.
2565
2566
2567 @node Special rhythmic concerns
2568 @subsection Special rhythmic concerns
2569
2570
2571 @menu
2572 * Grace notes::
2573 * Aligning to cadenzas::
2574 * Time administration::
2575 @end menu
2576
2577 @node Grace notes
2578 @unnumberedsubsubsec Grace notes
2579
2580 @cindex ornaments
2581 @cindex grace notes
2582 @cindex appoggiatura
2583 @cindex acciaccatura
2584
2585 @funindex \grace
2586 @funindex grace
2587
2588 Grace notes are ornaments that are written out. Grace notes
2589 are printed in a smaller font and take up no logical time
2590 in a measure.
2591
2592 @lilypond[quote,relative=2,verbatim]
2593 c4 \grace c16 c4
2594 \grace { c16[ d16] } c2
2595 @end lilypond
2596
2597 LilyPond also supports two special types of grace notes, the
2598 @emph{acciaccatura} -- an unmeasured grace note indicated by a slurred
2599 small note with a slashed stem -- and the @emph{appoggiatura}, which
2600 takes a fixed fraction of the main note and appears in small print
2601 without a slash.
2602
2603 @lilypond[quote,relative=2,verbatim]
2604 \grace c8 b4
2605 \acciaccatura d8 c4
2606 \appoggiatura e8 d4
2607 \acciaccatura { g16[ f] } e4
2608 @end lilypond
2609
2610 The placement of grace notes is synchronized between different
2611 staves.  In the following example, there are two sixteenth grace
2612 notes for every eighth grace note
2613
2614 @lilypond[quote,relative=2,verbatim]
2615 <<
2616   \new Staff { e2 \grace { c16[ d e f] } e2 }
2617   \new Staff { c2 \grace { g8[ b] } c2 }
2618 >>
2619 @end lilypond
2620
2621 @cindex grace notes, following
2622
2623 @funindex \afterGrace
2624 @funindex afterGrace
2625
2626 If you want to end a note with a grace, use the @code{\afterGrace}
2627 command.  It takes two arguments: the main note, and the grace
2628 notes following the main note.
2629
2630 @lilypond[quote,verbatim,relative=2]
2631 c1 \afterGrace d1 { c16[ d] } c1
2632 @end lilypond
2633
2634 This will put the grace notes after a space lasting 3/4 of the
2635 length of the main note.  The default fraction 3/4 can be changed by
2636 setting @code{afterGraceFraction}.  The following example shows
2637 the results from setting the space at the default,  at 15/16, and
2638 finally at 1/2 of the main note.
2639
2640 @lilypond[quote,verbatim,relative=2]
2641 <<
2642   \new Staff {
2643     c1 \afterGrace d1 { c16[ d] } c1
2644   }
2645   \new Staff {
2646     #(define afterGraceFraction (cons 15 16))
2647     c1 \afterGrace d1 { c16[ d] } c1
2648   }
2649   \new Staff {
2650     #(define afterGraceFraction (cons 1 2))
2651     c1 \afterGrace d1 { c16[ d] } c1
2652   }
2653 >>
2654 @end lilypond
2655
2656 The space between the main note and the grace note may also be
2657 specified using spacers. The following example places the grace
2658 note after a space lasting 7/8 of the main note.
2659
2660 @lilypond[quote,verbatim,relative=2]
2661 \new Voice {
2662   <<
2663     { d1^\trill_( }
2664     { s2 s4. \grace { c16[ d] } }
2665   >>
2666   c1)
2667 }
2668 @end lilypond
2669
2670 @cindex tweaking grace notes
2671 @cindex grace notes, tweaking
2672 @cindex grace notes, changing layout settings
2673
2674 A @code{\grace} music expression will introduce special
2675 typesetting settings, for example, to produce smaller type, and
2676 set directions.  Hence, when introducing layout tweaks to
2677 override the special settings, they should be placed inside
2678 the grace expression.  The overrides should also be reverted
2679 inside the grace expression.  Here, the grace note's default stem
2680 direction is overridden and then reverted.
2681
2682 @lilypond[quote,verbatim,relative=2]
2683 \new Voice {
2684   \acciaccatura {
2685     \stemDown
2686     f16->
2687     \stemNeutral
2688   }
2689   g4 e c2
2690 }
2691 @end lilypond
2692
2693
2694 @cindex stem, with slash
2695
2696
2697 @snippets
2698
2699 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
2700 {using-grace-note-slashes-with-normal-heads.ly}
2701
2702 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
2703 {tweaking-grace-layout-within-music.ly}
2704
2705 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
2706 {redefining-grace-note-global-defaults.ly}
2707
2708 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
2709 {positioning-grace-notes-with-floating-space.ly}
2710
2711
2712 @seealso
2713 Music Glossary:
2714 @rglos{grace notes},
2715 @rglos{acciaccatura},
2716 @rglos{appoggiatura}.
2717
2718 Installed Files:
2719 @file{ly/@/grace@/-init@/.ly}.
2720
2721 Snippets:
2722 @rlsr{Rhythms}.
2723
2724 Internals Reference:
2725 @rinternals{GraceMusic},
2726 @rinternals{Grace_beam_engraver},
2727 @rinternals{Grace_engraver},
2728 @rinternals{Grace_spacing_engraver}.
2729
2730
2731 @knownissues
2732
2733 @cindex acciaccatura, multi-note
2734 @cindex multi-note acciaccatura
2735 @cindex grace-note synchronization
2736
2737 A multi-note beamed @i{acciaccatura} is printed without a slash,
2738 and looks exactly the same as a multi-note beamed
2739 @i{appoggiatura}.
2740
2741 @c TODO Add link to LSR snippet to add slash when available
2742
2743 Grace note synchronization can also lead to surprises.  Staff
2744 notation, such as key signatures, bar lines, etc., are also
2745 synchronized.  Take care when you mix staves with grace notes and
2746 staves without, for example,
2747
2748 @lilypond[quote,relative=2,verbatim]
2749 <<
2750   \new Staff { e4 \bar "|:" \grace c16 d2. }
2751   \new Staff { c4 \bar "|:" d2. }
2752 >>
2753 @end lilypond
2754
2755 @noindent
2756 This can be remedied by inserting grace skips of the corresponding
2757 durations in the other staves.  For the above example
2758
2759 @lilypond[quote,relative=2,verbatim]
2760 <<
2761   \new Staff { e4 \bar "|:" \grace c16 d2. }
2762   \new Staff { c4 \bar "|:" \grace s16 d2. }
2763 >>
2764 @end lilypond
2765
2766 Grace sections should only be used within sequential music
2767 expressions.  Nesting or juxtaposing grace sections is not
2768 supported, and might produce crashes or other errors.
2769
2770 @node Aligning to cadenzas
2771 @unnumberedsubsubsec Aligning to cadenzas
2772
2773 @cindex cadenza
2774 @cindex cadenza, aligning to
2775 @cindex aligning to cadenza
2776
2777 In an orchestral context, cadenzas present a special problem: when
2778 constructing a score that includes a measured cadenza or other solo
2779 passage, all other instruments should skip just as many notes as the
2780 length of the cadenza, otherwise they will start too soon or too late.
2781
2782 One solution to this problem is to use the functions
2783 @code{mmrest-of-length} and @code{skip-of-length}.  These Scheme
2784 functions take a defined piece of music as an argument and generate a
2785 multi-measure rest or @code{\skip} exactly as long as the piece.
2786
2787 @lilypond[verbatim,quote]
2788 MyCadenza = \relative c' {
2789   c4 d8 e f g g4
2790   f2 g4 g
2791 }
2792
2793 \new GrandStaff <<
2794   \new Staff {
2795     \MyCadenza c'1
2796     \MyCadenza c'1
2797   }
2798   \new Staff {
2799     #(ly:export (mmrest-of-length MyCadenza))
2800     c'1
2801     #(ly:export (skip-of-length MyCadenza))
2802     c'1
2803   }
2804 >>
2805 @end lilypond
2806
2807
2808 @seealso
2809 Music Glossary:
2810 @rglos{cadenza}.
2811
2812 Snippets:
2813 @rlsr{Rhythms}.
2814
2815
2816 @node Time administration
2817 @unnumberedsubsubsec Time administration
2818
2819 @cindex time administration
2820 @cindex timing (within the score)
2821 @cindex music, unmetered
2822 @cindex unmetered music
2823
2824 @funindex currentBarNumber
2825 @funindex measurePosition
2826 @funindex measureLength
2827
2828 Time is administered by the @code{Timing_translator}, which by
2829 default is to be found in the @code{Score} context.  An alias,
2830 @code{Timing}, is added to the context in which the
2831 @code{Timing_translator} is placed.
2832
2833 The following properties of @code{Timing} are used
2834 to keep track of timing within the score.
2835
2836 @cindex bar number
2837 @cindex measure number
2838
2839 @table @code
2840 @item currentBarNumber
2841 The current measure number.  For an example showing the
2842 use of this property see @ref{Bar numbers}.
2843
2844 @item measureLength
2845 The length of the measures in the current time signature.  For a
2846 4/4 time this is@tie{}1, and for 6/8 it is 3/4.  Its value
2847 determines when bar lines are inserted and how automatic beams
2848 should be generated.
2849
2850 @item measurePosition
2851 The point within the measure where we currently are.  This
2852 quantity is reset by subtracting @code{measureLength} whenever
2853 @code{measureLength} is reached or exceeded.  When that happens,
2854 @code{currentBarNumber} is incremented.
2855
2856 @item timing
2857 If set to true, the above variables are updated for every time
2858 step.  When set to false, the engraver stays in the current
2859 measure indefinitely.
2860
2861 @end table
2862
2863 Timing can be changed by setting any of these variables
2864 explicitly.  In the next example, the default 4/4 time
2865 signature is printed, but @code{measureLength} is set to 5/4.
2866 At 4/8 through the third measure, the @code{measurePosition} is
2867 advanced by 1/8 to 5/8, shortening that bar by 1/8.
2868 The next bar line then falls at 9/8 rather than 5/4.
2869
2870 @lilypond[quote,verbatim,relative=1]
2871 \set Score.measureLength = #(ly:make-moment 5 4)
2872 c1 c4
2873 c1 c4
2874 c4 c4
2875 \set Score.measurePosition = #(ly:make-moment 5 8)
2876 b4 b4 b8
2877 c4 c1
2878 @end lilypond
2879
2880 @noindent
2881 As the example illustrates, @code{ly:make-moment n m} constructs a
2882 duration of n/m of a whole note.  For example,
2883 @code{ly:make-moment 1 8} is an eighth note duration and
2884 @code{ly:make-moment 7 16} is the duration of seven sixteenths
2885 notes.
2886
2887
2888 @seealso
2889 Notation Reference:
2890 @ref{Bar numbers},
2891 @ref{Unmetered music}.
2892
2893 Snippets:
2894 @rlsr{Rhythms}.
2895
2896 Internals Reference:
2897 @rinternals{Timing_translator},
2898 @rinternals{Score}.
2899