X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Frhythms.itely;h=2da0f2c048527dabcd9b12641123acfb7ce5697a;hb=9a14a394dfa23b38ab78c3eb09a2d7b5f504fa35;hp=d01848fdd558950ca581e30f72388a3793392012;hpb=1df1d03d3572d72ef18cdfe34e9d719f8ae48003;p=lilypond.git diff --git a/Documentation/user/rhythms.itely b/Documentation/user/rhythms.itely index d01848fdd5..2da0f2c048 100644 --- a/Documentation/user/rhythms.itely +++ b/Documentation/user/rhythms.itely @@ -9,10 +9,10 @@ @node Rhythms @section Rhythms -@lilypondfile[ragged-right,line-width=16\cm,staffsize=16,quote] +@lilypondfile[ragged-right,line-width=16\cm,staffsize=14,quote] {rhythms-headword.ly} -This section discusses rhythms, durations, and bars. +This section discusses rhythms, rests, durations, beaming and bars. @menu * Writing rhythms:: @@ -31,101 +31,89 @@ This section discusses rhythms, durations, and bars. * Durations:: * Tuplets:: * Scaling durations:: +* Ties:: @end menu @node Durations -@unnumberedsubsubsec Durations +@subsubsection Durations + +@cindex durations, of notes +@cindex note durations -@cindex duration @funindex \longa @funindex \breve @funindex \maxima -When entering notes or rests, durations are designated by -numbers and dots: durations are entered as their reciprocal -values. For example, a quarter note is entered using a @code{4} -(since it is a 1/4 note), while a half note is entered using a -@code{2} (since it is a 1/2 note). For notes longer than a whole -you must use the @code{\longa} and @code{\breve} commands. - -@ignore ----- Example to be removed if following is thought better ---- -@example -c'\longa c'\breve c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64 -@end example +Durations are designated by numbers and dots. +Durations are entered as their reciprocal values. For example, a +quarter note is entered using a @code{4} (since it is a 1/4 note), +and a half note is entered using a @code{2} (since it is a 1/2 +note). For notes longer than a whole you must use the +@code{\longa} (a double breve) and @code{\breve} commands. +Durations as short as 64th notes may be specified. Shorter values +are possible, but only as beamed notes. -@lilypond[quote] -\score { -\relative c'' { - a\longa*1/4 a\breve*1/2 \autoBeamOff - a1 a2 a4 a8 a16 a32 a64 a64 - } - \layout { - ragged-right = ##t - indent=0\mm - \context { - \Score - \remove "Bar_number_engraver" - } - \context { - \Staff - \remove "Clef_engraver" - \override StaffSymbol #'transparent = ##t - \override TimeSignature #'transparent = ##t - \override BarLine #'transparent = ##t - \consists "Pitch_squash_engraver" - } - } -} +@c Two 64th notes are needed to obtain beams +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +\time 8/1 +c\longa c\breve c1 c2 +c4 c8 c16 c32 c64 c64 @end lilypond -@end ignore -@c TODO Consider whether the beams should be -@c removed in the following. If they, -@c the c'128 notes are not displayed -@c properly. See Note below. \autoBeamOff ? +@noindent +Here are the same durations with automatic beaming turned off. -@lilypond[quote,ragged-right,verbatim,fragment] -<< - \new Staff { - \time 8/1 - c'\longa c'\breve c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'128 c'128 - } - \new Staff { - r\longa r\breve r1 r2 r4 r8 r16 r32 r64 r128 r128 - } ->> +@c not strictly "writing rhythms"; more of a "displaying" thing, +@c but it's ok here. -gp +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +\time 8/1 +\autoBeamOff +c\longa c\breve c1 c2 +c4 c8 c16 c32 c64 c64 @end lilypond -Note: Up to four flags and up to five beams can be attached -to note stems, so durations as small as 128 may be specified -with beaming, but without beaming durations shorter than -64 should not be entered - a warning will be produced. -Durations up to 128 may be specified for rests. +A note with the duration of a quadruple breve may be entered with +@code{\maxima}, but this is supported only within ancient music +notation. For details, see @ref{Ancient notation}. -If the duration is omitted then it is set to the previously +If the duration is omitted, it is set to the previously entered duration. The default for the first note is a quarter note. -@lilypond[quote,ragged-right,verbatim,fragment] -{ a a a2 a a4 a a1 a } +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +a a a2 a a4 a a1 a @end lilypond +@cindex notes, dotted +@cindex dotted notes @funindex . -To obtain dotted note lengths, simply add a dot (@samp{.}) to the -number. Double-dotted notes are produced in a similar way. +To obtain dotted note lengths, place a dot (@code{.}) after the +duration. Double-dotted notes are specified by appending two +dots, and so on. -@lilypond[quote,ragged-right,fragment,verbatim] -a'4 b' c''4. b'8 a'4. b'4.. c''8. +@lilypond[quote,ragged-right,fragment,verbatim,relative=2] +a4 b c4. b8 a4. b4.. c8. @end lilypond -@refcommands +Some durations cannot be represented with just binary durations +and dots; they can be represented only by tying two or more +notes together. For details, see @ref{Ties}. + +For ways of specifying durations for the syllables of lyrics and +ways of aligning lyrics to notes, see @ref{Vocal music}. + +Optionally, notes can be spaced strictly proportionately to their +duration. For details of this and other settings which control +proportional notation, see @ref{Proportional notation}. + +@predefined Dots are normally moved up to avoid staff lines, except in polyphonic situations. The following commands may be used to -force a particular direction manually +force a particular direction manually, and to return to the +default behaviour: @funindex \dotsUp @code{\dotsUp}, @@ -134,59 +122,71 @@ force a particular direction manually @funindex \dotsNeutral @code{\dotsNeutral}. -@c TODO: after deciding the link question, fix these. -gp -Durations are entered in the same way in @code{drummode}, -@code{chordmode}, @code{figuremode} and (optionally) -in @code{lyricmode}. @seealso -For alternative ways of aligning lyrics to notes see -This manual: @ref{Vocal music} +Music Glossary: @rglos{breve}, @rglos{longa}, @rglos{note value} +@rglos{Duration names notes and rests}. -For a complete description of how to enter rests see -This manual: @ref{Writing rests} +Notation Reference: @ref{Automatic beams}, @ref{Ties}, +@ref{Writing rhythms}, @ref{Writing rests}, @ref{Vocal music}, +@ref{Ancient notation}, @ref{Proportional notation}. -Program reference: @internalsref{Dots}, and +Snippets: @lsrdir{Rhythms,Rhythms} + +Internals Reference: @internalsref{Dots}, @internalsref{DotColumn}. +@knownissues + +@c Deliberately duplicated in Durations and Rests. -gp +There is no fundamental limit to rest durations (both in terms of +longest and shortest), but the number of glyphs is limited: +rests from 128th to maxima (8 x whole) may be printed. + + @node Tuplets -@unnumberedsubsubsec Tuplets +@subsubsection Tuplets @cindex tuplets @cindex triplets @funindex \times Tuplets are made out of a music expression by multiplying all -durations with a fraction +durations with a fraction: @example \times @var{fraction} @var{musicexpr} @end example @noindent -The duration of @var{musicexpr} will be multiplied by the -fraction. The fraction's denominator will be printed over the -notes, optionally with a bracket. The most common tuplet is the -triplet in which 3 notes have the length of 2, so the notes are -2/3 of their written length +The duration of @var{musicexpr} will be multiplied by the +fraction. The fraction's denominator will be printed over or +under the notes, optionally with a bracket. The most common +tuplet is the triplet in which 3 notes have the length of 2, so +the notes are 2/3 of their written length. + +@lilypond[quote,ragged-right,fragment,verbatim,relative=2] +a2 \times 2/3 {b4 b b} +c4 c \times 2/3 {b4 a g} -@lilypond[quote,ragged-right,fragment,verbatim] -g'4 \times 2/3 {c'4 c' c'} d'4 d'4 @end lilypond -Tuplets may be nested, for example, +Tuplets may be nested: @lilypond[fragment,ragged-right,verbatim,relative=2] -\override TupletNumber #'text = #tuplet-number::calc-fraction-text -\times 4/6 { - a4 a - \times 3/5 { a a a a a } +\relative c'' { + \autoBeamOff + c4 \times 4/5 { f8 e f \times 2/3 {e[ f g] } } f4 | } @end lilypond -@refcommands +Modifying nested tuplets which begin at the same musical moment +must be done with @code{\tweak}. +@c TODO Add link to LM section which deals with this. + +@predefined @funindex \tupletUp @code{\tupletUp}, @@ -196,118 +196,227 @@ Tuplets may be nested, for example, @code{\tupletNeutral}. -@commonprop +@snippets -@funindex tupletNumberFormatFunction @cindex tuplet formatting +@cindex triplet formatting + +@funindex tupletNumberFormatFunction +@funindex tupletSpannerDuration + +@lilypondfile [verbatim,lilyquote,ragged-right,texidoc] +{entering-several-tuplets-using-only-one--times-command.ly} +@ignore +@c TODO Remove when snippet works ok +@c Sent to Snippet 5 Feb 08 The property @code{tupletSpannerDuration} specifies how long each bracket should last. With this, you can make lots of tuplets while typing @code{\times} only once, thus saving lots of typing. In the next example, there are two triplets shown, while -@code{\times} was only used once +@code{\times} was only used once. @lilypond[quote,fragment,relative=2,ragged-right,verbatim] \set tupletSpannerDuration = #(ly:make-moment 1 4) \times 2/3 { c8 c c c c c } @end lilypond +@end ignore @noindent For more information about @code{make-moment}, see @ref{Time administration}. -The format of the number is determined by the property @code{text} -in @code{TupletNumber}. The default prints only the denominator, -but if it is set to the function -@code{tuplet-number::calc-fraction-text}, @var{num}:@var{den} will -be printed instead. +@funindex TupletNumber + +By default, only the numerator of the tuplet number +is printed over the tuplet bracket, i.e. the denominator +of the argument to the @code{\times} command. Alternatively, +@var{num}:@var{den} of the tuplet number may be printed, or +the tuplet number may be suppressed altogether. -To avoid printing tuplet numbers, use @lilypond[quote,fragment,relative=2,ragged-right,verbatim] \times 2/3 { c8 c c } \times 2/3 { c8 c c } +\override TupletNumber #'text = #tuplet-number::calc-fraction-text +\times 2/3 { c8 c c } \override TupletNumber #'transparent = ##t -\times 2/3 { c8 c c } \times 2/3 { c8 c c } +\times 2/3 { c8 c c } @end lilypond -Use the @code{\tweak} function to override nested tuplets -beginning at the same music moment. In this example, -@code{\tweak} specifies fraction text for the outer -@code{TupletNumber} and denominator text for the -@code{TupletNumber} of the first of the three inner tuplets. +@c TODO Add snippet to show this +Tuplets may extend over bar lines, but they will inhibit a +line break unless the @code{Forbid_line_break_engraver} is +removed from the @code{Voice context}. -@lilypond[quote,ragged-right,verbatim] -\new Staff { - \tweak #'text #tuplet-number::calc-fraction-text - \times 4/3 { - \tweak #'text #tuplet-number::calc-denominator-text - \times 2/3 { c'8[ c'8 c'8] } - \times 2/3 { c'8[ c'8 c'8] } - \times 2/3 { c'8[ c'8 c'8] } - } +@c TODO Move to LM 4 +@ignore +@subheading Modifying nested tuplets + +@cindex tuplets, nested +@cindex triplets, nested +@cindex bracket, tuplet +@cindex tuplet bracket +@cindex triplet bracket +@funindex TupletBracket + +If nested tuplets do not begin at the same moment their +appearance may be modified in the usual way with +@code{\override} commands: + +@c NOTE Tuplet brackets collide if notes are high on staff +@c See issue 509 +@lilypond[quote,ragged-right,verbatim,fragment,relative=1] +\times 2/3 { c8[ c c]} +\once \override TupletNumber #'text = #tuplet-number::calc-fraction-text +\times 2/3 { + c[ c] + c[ c] + \once \override TupletNumber #'transparent = ##t + \times 2/3 { c8[ c c] } +\times 2/3 { c8[ c c]} } @end lilypond -Here @code{\tweak} and @code{\override} work together to specify -@code{TupletBracket} direction. The first @code{\tweak} positions -the @code{TupletBracket} of the outer tuplet above the staff. The -second @code{\tweak} positions the @code{TupletBracket} of the -first of the three inner tuplets below the staff. Note that this -pair of @code{\tweak} functions affects only the outer tuplet and -the first of the three inner tuplets because only those two -tuplets begin at the same music moment. We use @code{\override} -in the usual way to position the @code{TupletBrackets} of the -second and third of the inner tuplets below the staff. +However, if the nested tuplets begin at the same musical moment, +@code{\override} commands cannot be applied to just one of them +-- they apply to both. So to change the appearance of nested +tuplets beginning at the same musical moment individually, the +@code{\tweak} function must be used (see @ref{Objects connected +to the input}). The @code{\tweak} function is applied to the +following @code{\times} command as it appears in the input stream, +and so can distinguish between separate @code{\times} commands +even if their tuplets begin at the same musical moment. + +In this example, the @code{\tweak} command is used to specify +fraction text for the outer @code{TupletNumber} and denominator +text for the @code{TupletNumber} of the first of the three +inner tuplets. + +@c NOTE Tuplet brackets collide if notes are high on staff +@c so use relative=1 until this is fixed +@c See issue 509 +@lilypond[quote,ragged-right,verbatim,fragment,relative=1] +\tweak #'text #tuplet-number::calc-fraction-text +\times 4/3 { + \tweak #'text #tuplet-number::calc-denominator-text + \times 2/3 { c8[ c8 c8] } + \times 2/3 { c8[ c8 c8] } + \times 2/3 { c8[ c8 c8] } +} +@end lilypond -@lilypond[quote,ragged-right,verbatim] -\new Staff { - \tweak #'text #tuplet-number::calc-fraction-text - \tweak #'direction #up - \times 4/3 { - \tweak #'direction #down - \times 2/3 { c'8[ c'8 c'8] } - \override TupletBracket #'direction = #down - \times 2/3 { c'8[ c'8 c'8] } - \times 2/3 { c'8[ c'8 c'8] } - } +In the next example, @code{\tweak} and @code{\override} work +together to specify @code{TupletBracket} direction. The first +@code{\tweak} positions the @code{TupletBracket} of the outer +tuplet above the staff. The second @code{\tweak} positions the +@code{TupletBracket} of the first of the three inner tuplets below +the staff. Note that the @code{\tweak} command needs to be used +only for events that begin at the same music moment: the outer +tuplet and the first of the three inner tuplets. To position the +@code{TupletBracket}s of the second and third of the inner tuplets +below the staff, we can use @code{\override} in the usual way. + +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +\tweak #'text #tuplet-number::calc-fraction-text +\tweak #'direction #up +\times 4/3 { + \tweak #'direction #down + \times 2/3 { c8[ c8 c8] } + \override TupletBracket #'direction = #down + \times 2/3 { c8[ c8 c8] } + \times 2/3 { c8[ c8 c8] } } @end lilypond +@end ignore -Tuplet brackets can be made to run to prefatory matter or the next -note +@c TODO - tidy up +@c Sent to Valentin for LSR (general list of Rhythm snippets) 22 Feb +@c Maybe try referencing with: +@c For example of modifying bracket length see @lsr{..} +@c Index entries could then be added above this. +@c Delete ignore block when available in LSR -@lilypond[ragged-right] +@ignore +@subheading Modifying tuplet bracket length + +@cindex tuplet bracket length +@cindex triplet bracket length +@cindex bracket length, tuplets +@funindex tupletFullLength +@funindex tupletFullLengthNote + +Tuplet brackets can be made to run to prefatory matter or the +next note. +Default tuplet brackets end at the right edge of the final note +of the tuplet; full-length tuplet brackets extend farther to the +right, either to cover all the non-rhythmic notation up to the +following note, or to cover only the whitespace before the next +item of notation, be that a clef, time signature, key signature, +or another note. The example shows how to switch tuplets to +full length mode and how to modify what material they cover. + + +@lilypond[ragged-right,verbatim,quote] \new RhythmicStaff { + % Set tuplets to be extendable .. \set tupletFullLength = ##t - \time 4/4 - \times 4/5 { - c4 c1 - } + % .. to cover all items up to the next note \set tupletFullLengthNote = ##t \time 2/4 - \times 2/3 { - c4 c c - } + \times 2/3 { c4 c c } + % .. or to cover just whitespace + \set tupletFullLengthNote = ##f + \time 4/4 + \times 4/5 { c4 c1 } \time 3/4 - c4 + c4 } @end lilypond +@end ignore + +@c Compressing music + +@cindex compressing music +@funindex \compressMusic + +@code{\compressMusic} works similarly to \times, but does not +create a tuplet bracket. One application is in polymetric +notation, as shown in the following example. See +@ref{Polymetric notation}. + +@lilypondfile [verbatim,lilyquote,ragged-right,texidoc] +{printing-music-with-different-time-signatures.ly} @seealso -Program reference: @internalsref{TupletBracket}, -@internalsref{TupletNumber}, and @internalsref{TimeScaledMusic}. +Music Glossary: @rglos{triplet}, @rglos{tuplet}, +@rglos{polymetric}. + +Notation Reference: @ref{Time administration}, +@ref{Objects connected to the input}, @ref{Polymetric notation}. +Snippets: @lsrdir{Rhythms,Rhythms}. + +Internals Reference: @internalsref{TupletBracket}, +@internalsref{TupletNumber}, @internalsref{TimeScaledMusic}. + +@knownissues + +Lines may be broken within a tuplet with @code{\bar "" \break}, +but the tuplet bracket does not correctly carry over. @node Scaling durations -@unnumberedsubsubsec Scaling durations +@subsubsection Scaling durations -You can alter the length of duration by a fraction @var{N/M} -appending @samp{*@var{N/M}} (or @samp{*@var{N}} if @var{M=1}). +You can alter the length of a duration by a fraction @var{N/M} +by appending @code{*@var{N/M}} (or @code{*@var{N}} if @var{M=1}). This will not affect the appearance of the notes or rests -produced. These may be combined such as @samp{*M*N}. +produced, but the altered duration will be used in calculating the +position within the measure and setting the duration in the MIDI +output. Multiplying factors may be combined +such as @code{*M*N}. In the following example, the first three notes take up exactly two beats, but no triplet bracket is printed. @@ -319,10 +428,189 @@ a4 a4 a4*2 b16*4 c4 @end lilypond +The duration of skip or spacing notes may also be modified by +a multiplier. This is useful for skipping many measures, e.g., +@code{s1*23}. + +@seealso + +Notation Reference: @ref{Tuplets}, @ref{Skips}, @ref{Polymetric notation}. + +Snippets: @lsrdir{Rhythms,Rhythms} + +@node Ties +@subsubsection Ties + +@cindex tie +@funindex ~ + +A tie connects two adjacent note heads of the same pitch. The tie +in effect extends the length of a note. + +@warning{Ties should not be confused with @emph{slurs}, which +indicate articulation, or @emph{phrasing slurs}, which indicate +musical phrasing. A tie is just a way of extending a note +duration, similar to the augmentation dot.} + +A tie is entered using the tilde symbol @code{~} + +@lilypond[quote,ragged-right,fragment,verbatim] +e' ~ e' +@end lilypond + + +@noindent +Ties are used either when the note crosses a bar line, or when +dots cannot be used to denote the rhythm. Ties should also be +used when note values cross larger subdivisions of the measure: + +@lilypond[fragment,quote,ragged-right] +\relative { + r8 c8 ~ c2 r4 | r8^"not" c2 ~ c8 r4 +} +@end lilypond + +If you need to tie a lot of notes across bar lines, it may be +easier to use automatic note splitting (see @ref{Automatic note +splitting}). This mechanism automatically splits long notes, and +ties them across bar lines. + +@funindex \repeatTie +@cindex repeating ties +@cindex volta brackets and ties + +When a tie is applied to a chord, all note heads whose pitches +match are connected. When no note heads match, no ties will be +created. Chords may be partially tied by placing the tie inside +the chord. + +@lilypond[quote,ragged-right,fragment,verbatim,relative=1] + ~ + +@end lilypond + +When a second alternative of a repeat starts with a tied note, you +have to repeat the tie. This can be achieved with +@code{\repeatTie}, + +@lilypond[fragment,quote,ragged-right,relative=2,verbatim] +\repeat volta 2 { c g 2 ~ } +\alternative {{ 2. r4 } {2\repeatTie d4 c }} +@end lilypond + +@cindex laissez vibrer +@cindex ties, laissez vibrer +@funindex \laissezVibrer +@funindex \tieUp +@funindex \tieDown +@funindex \tieNeutral + +@notation{L.v.} ties (@notation{laissez vibrer}) indicate that +notes must not be damped at the end. It is used in notation for +piano, harp and other string and percussion instruments. They can +be entered using @code{\laissezVibrer}: + +@lilypond[fragment,ragged-right,verbatim,relative=1] +\laissezVibrer +@end lilypond + +The vertical placement of ties may be controlled; see +@ref{Controlling direction}. + +@quotation +DELETE THIS ? +@code{\tieDown} (see example below). @code{\tieNeutral} reverts +to the default behaviour again. + +However, as with other music elements of this kind, there is a +convenient shorthand for forcing tie directions. By adding +@code{_} or @code{^} before the tilde, the direction is also set: + +@lilypond[relative=2,ragged-right,quote,verbatim,fragment] +c4_~ c c^~ c) +@end lilypond +@end quotation + +@predefined + +@funindex \tieUp +@code{\tieUp}, +@funindex \tieDown +@code{\tieDown}, +@funindex \tieNeutral +@code{\tieNeutral}, +@funindex \tieDotted +@code{\tieDotted}, +@funindex \tieDashed +@code{\tieDashed}, +@funindex \tieSolid +@code{\tieSolid}. + + +@snippets + +Ties are sometimes used to write out arpeggios. In this case, two +tied notes need not be consecutive. This can be achieved by +setting the @code{tieWaitForNote} property to true. The same +feature is also useful, for example, to tie a tremolo to a chord, +but in principle, it can also be used for ordinary, consecutive +notes: + +@lilypond[fragment,verbatim,relative=1,ragged-right,quote] +\set tieWaitForNote = ##t +\grace { c16[~ e~ g]~ } 2 +\repeat tremolo 8 { c32~ c'~ } 1 +e8~ c~ a~ f~ 2 +\tieUp c8~ a \tieDown \tieDotted g~ c g2 +@end lilypond + +Ties may be engraved manually by changing the +@code{tie-configuration} property of the @code{TieColumn} object. +The first number indicates the distance from the center of the +staff in staff-spaces, and the second number indicates the +direction (1=up, -1=down). + +@lilypond[fragment,verbatim,relative=1,ragged-right,quote] +2~ | +\override TieColumn #'tie-configuration = + #'((0.0 . 1) (-2.0 . 1) (-4.0 . 1)) +~ | +@end lilypond + + @seealso -This manual: @ref{Tuplets}. +Music Glossary: @rglos{tie}, +@c [TODO]add @rglos{laissez vibrer}. when there is a glossary entry. + +Snippets: @lsrdir{Rhythms,Rhythms} + +Internals Reference: +@internalsref{LaissezVibrerTie} +@internalsref{LaissezVibrerTieColumn} + +Example files: +@c @lsr{connecting,laissez-vibrer-ties.ly} + + + + +Notation Reference: @ref{Automatic note splitting}. + +Snippets: @lsrdir{Rhythms,Rhythms} + +Internals Reference: @internalsref{Tie}. + + +@knownissues + +Switching staves when a tie is active will not produce a slanted +tie. + +Changing clefs or octavations during a tie is not really +well-defined. In these cases, a slur may be preferable. + @@ -331,69 +619,94 @@ This manual: @ref{Tuplets}. @subsection Writing rests @menu -* Rests:: -* Skips:: -* Multi measure rests:: +* Rests:: +* Skips:: +* Full measure rests:: @end menu @node Rests -@unnumberedsubsubsec Rests -@cindex Rests +@subsubsection Rests +@cindex rest +@cindex maxima +@cindex longa +@cindex breve @funindex \rest @funindex r +@funindex \maxima +@funindex \longa +@funindex \breve -Rests are entered like notes with the note name @code{r} +Rests are entered like notes with the note name @code{r}: +@c \time 16/1 is used to avoid spurious bar lines +@c and long tracts of empty measures @lilypond[fragment,quote,ragged-right,verbatim] -r1 r2 r4 r8 +\new Staff { + \time 16/1 + \override Staff.TimeSignature #'stencil = ##f + r\maxima + r\longa r\breve r1 r2 + r4 r8 r16 r32 r64 +} @end lilypond -Whole bar rests, centered in middle of the bar, must be entered as -multi-measure rests. They can be used for a single bar as well as -many bars, and are discussed in @ref{Multi measure rests}. +Whole measure rests, centered in middle of the measure, must be entered as +multi-measure rests. They can be used for a single measure as well as +many measures and are discussed in @ref{Full measure rests}. To explicitly specify a rest's vertical position, write a note followed by @code{\rest}. A rest will be placed in the position -where the note would appear, +where the note would appear. This allows for precise manual +formatting of polyphonic music, since the automatic rest collision +formatter will leave these rests alone. -@lilypond[fragment,quote,ragged-right,verbatim] -a'4\rest d'4\rest +@lilypond[fragment,quote,ragged-right,verbatim,relative=2] +a4\rest d4\rest @end lilypond -@noindent -This makes manual formatting of polyphonic music much easier, -since the automatic rest collision formatter will leave these -rests alone. @seealso -Program reference: @internalsref{Rest}. +Notation Reference: @ref{Full measure rests}. +Snippets: @lsrdir{Rhythms,Rhythms}. + +Internals Reference: @internalsref{Rest}. + + +@knownissues + +@c Deliberately duplicated in Durations and Rests. -gp +There is no fundamental limit to rest durations (both in terms of +longest and shortest), but the number of glyphs is limited: there +are rests from 128th to maxima (8 x whole). @node Skips -@unnumberedsubsubsec Skips +@subsubsection Skips -@cindex Skip -@cindex Invisible rest -@cindex Space note +@cindex skip +@cindex invisible rest +@cindex space note @funindex \skip @funindex s An invisible rest (also called a @q{skip}) can be entered like a -note with note name @samp{s} or with @code{\skip @var{duration}} +note with note name @code{s} or with @code{\skip @var{duration}} @lilypond[fragment,quote,ragged-right,verbatim,relative=2] a4 a4 s4 a4 \skip 1 a4 @end lilypond +@cindex lyrics, skip + The @code{s} syntax is only available in note mode and chord mode. -In other situations, for example, when entering lyrics, you should -use the @code{\skip} command +In other situations, for example, when entering lyrics, one must +use the @code{\skip} command: -@lilypond[quote,ragged-right,verbatim] +@lilypond[quote,ragged-right,verbatim,relative=2] << - \relative { a'2 a2 } + { a2 a2 } \new Lyrics \lyricmode { \skip 2 bla2 } >> @end lilypond @@ -405,48 +718,56 @@ The @code{s} skip command does create @internalsref{Staff} and @internalsref{Voice} when necessary, similar to note and rest commands. For example, the following results in an empty staff. -@lilypond[quote,ragged-right,verbatim] +@lilypond[quote,verbatim] { s4 } @end lilypond +@c with ragged-right, the staff lines are cut BEFORE the time +@c signature, which makes for a VERY empty staff -The fragment @code{@{ \skip 4 @} } would produce an empty page. +@c The fragment @code{@{ \skip 4 @} } would produce an empty page. +@c Misleading -- it doesn't produce anything, not even an empty page. +@c Ppl who want to make empty sheets will see this and wonder what's +@c happening. -eo @seealso -Program reference: @internalsref{SkipMusic}. +Snippets: @lsrdir{Rhythms,Rhythms} + +Internals Reference: @internalsref{SkipMusic}. -@node Multi measure rests -@unnumberedsubsubsec Multi measure rests +@node Full measure rests +@subsubsection Full measure rests @cindex multi measure rests @cindex full measure rests -@cindex Rests, multi measure -@cindex Rests, full measure -@cindex whole rests for a full measure +@cindex rest, multi measure +@cindex rest, full measure +@cindex whole rest for a full measure @funindex R -Rests for one or more full measures are entered using -@code{R} followed by a duration (see @ref{Durations}). -The duration should correspond to an integral number -of bars, otherwise a barcheck warning is printed. -Multi-measure rests are principally used to indicate -that a part in a multi-part score should be silent: +Rests for one or more full measures are entered using @code{R} +followed by a duration (see @ref{Durations}). The duration should +correspond to an integral number of measures, otherwise a barcheck +warning is printed. A @rglos{multi-measure rest} is used +principally to indicate that a part in a multi-part score should +be silent: -@lilypond[quote,ragged-right,fragment,verbatim] -{ - \set Score.skipBars = ##t - R1*4^"Piano" R1*24^"Solo" R1*4^"Piano" b'2 b'4 a'4 -} +@lilypond[quote,fragment,verbatim,relative=2] +\set Score.skipBars = ##t +R1*4 +R1*24 +R1*4 +b2^"Tutti" b4 a4 @end lilypond A multi-measure rest can be expanded in the printed score -to show all the rest bars explicitly, or, as above, it can be -condensed to a single bar +to show all the rest measures explicitly, or, as above, it can be +condensed to a single measure containing a multi-measure rest symbol, with the number of -bars of rest printed above the bar. This expansion +measures of rest printed above the measure. This expansion is controlled by the property @code{Score.skipBars}. If this is -set to true, empty measures will condensed to a single bar. +set to true, empty measures will be condensed to a single measure. @lilypond[quote,ragged-right,fragment,verbatim] \time 4/4 r1 | R1 | R1*2 | @@ -457,10 +778,10 @@ R1*17 | R1*4 | @end lilypond The @code{1} in @code{R1} is similar to the duration notation -used for notes and is the length of a bar in 2/2 or 4/4 time. +used for notes and is the length of a measure in 2/2 or 4/4 time. The duration in a multi-measure rest must always be an integral -number of bar-lengths, so in other time signatures you must -use augmentation dots or fractions: +number of measure-lengths, so in other time signatures augmentation +dots or fractions must be used: @lilypond[quote,ragged-right,fragment,verbatim] \set Score.skipBars = ##t @@ -476,13 +797,14 @@ An @code{R} spanning a single measure is printed as either a whole or breve rest, centered in the measure, regardless of the time signature. -@c TODO Is "church rests" an accepted musical term? I can't -@c find it anywhere. Is there a better term? If it is -@c retained it should be added to glossary. +@cindex church rest +@cindex rest, church +@cindex kirchenpausen If there are 10 or fewer measures of rest, LilyPond prints -@q{church rests} (a series of rectangles) in the staff and -prints a simple line otherwise. This default number +a series of longa and breve rests (called in German +Kirchenpausen - @q{church rests}) within the staff and +prints a simple line otherwise. This default number of 10 may be changed by overriding @code{MultiMeasureRest.expand-limit}. @@ -493,13 +815,18 @@ R1*2 | R1*5 | R1*9 R1*2 | R1*5 | R1*9 @end lilypond +Note that unlike ordinary rests, the vertical position on the +staff of the multi-measure rest symbol of either form cannot be +changed. + @cindex text on multi-measure rest @cindex script on multi-measure rest @cindex fermata on multi-measure rest Text can be added to multi-measure rests by using the -@var{note}-@code{markup} syntax @ref{Text markup}. A variable -(@code{\fermataMarkup}) is provided for adding fermatas +@var{note}-@code{markup} syntax described in @ref{Text markup}. +The variable @code{\fermataMarkup} is provided for adding +fermatas. @lilypond[quote,ragged-right,verbatim,fragment] \set Score.skipBars = ##t @@ -508,8 +835,10 @@ R2.*10^\markup { \italic "ad lib." } R2.^\fermataMarkup @end lilypond -Warning! This text is created by @code{MultiMeasureRestText}, not -@code{TextScript}. +@warning{Text attached to a multi-measure rest is created +by @code{MultiMeasureRestText}, not +@code{TextScript}. Overrides must be directed to the correct +object, or they will be ignored. See the following example.} @lilypond[quote,ragged-right,verbatim,fragment] \override TextScript #'padding = #5 @@ -518,40 +847,58 @@ R1^"low" R1^"high" @end lilypond -Text attached to a multi-measure rest will be centered above -(or below) it. Long text attached in this way will not cause -the bar to expand, and may collide with text in adjacent bars. +Text attached to a multi-measure rest will be centered above or +below it. Long text attached in this way does not cause the +measure to expand, and may collide with text in adjacent measures. Long text is better attached to a zero-length skip note preceding -the rest, since this will cause the bar to expand to accommodate -the length of the text. However, text attached above the bar -in this way will collide with the rest number unless it is -raised, either by increasing the padding or using @code{\raise}: +the rest, preceded by @code{\textLengthOn} (turn off again with +@code{\textLengthOff}), since this will cause the measure to expand to +accommodate the length of the text: -@lilypond[quote,ragged-right,verbatim,fragment] +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] \set Score.skipBars = ##t -s1*0^\markup {\hspace #0 \raise #3 [FRED.]} -R1*4 -s1*0^\markup {\hspace #0 \raise #3 [MABEL] } -s1*0_\markup {\italic {Cue: ...so let it be}} -R1*6 +\textLengthOn +s1*0^\markup {[MAJOR GENERAL]} +R1*19 +s1*0^\markup {[MABEL] } +s1*0_\markup {\italic {Cue: ... it is yours}} +R1*30 +\textLengthOff +c4^\markup {CHORUS} d f c @end lilypond +@noindent +Text attached to a skip note in this way is left-aligned to the +position where the note would be placed in the bar, and placed +above the bar count numeral, but because the bar length is +determined by the length of the text, the text will appear to be +centered. If two (or more) texts are +attached to skip notes in a bar the bar length is determined by +the longer text, and the shorter text is then clearly +left-aligned, as shown in the second bar above. If the shorter +text of two marks is short enough to fit it will be placed +alongside and to the left of the bar count numeral. @seealso -Program reference: @internalsref{MultiMeasureRestMusicGroup}, -@internalsref{MultiMeasureRest}. +Notation Reference: @ref{Durations}, @ref{Text}, +@ref{Text markup}, @ref{Text scripts}. + +Snippets: @lsrdir{Rhythms,Rhythms} + +Internals Reference: @internalsref{MultiMeasureRest}. The layout object @internalsref{MultiMeasureRestNumber} is for the default number, and @internalsref{MultiMeasureRestText} for user specified texts. -@refbugs +@knownissues -It is not possible to use fingerings (e.g., @code{R1-4}) to put -numbers over multi-measure rests. And the pitch of multi-measure -rests (or staff-centered rests) can not be influenced. +If an attempt is made to use fingerings (e.g., +@code{R1*10-4}) to put numbers over multi-measure rests, the +fingering numeral (4) may collide with the bar counter +numeral (10). @cindex condensing rests @@ -561,16 +908,12 @@ in rest collisions. Be careful when entering multi-measure rests followed by whole notes. The following will enter two notes lasting four measures -each +each: @example R1*4 cis cis @end example -When @code{skipBars} is -set, the result will look OK, but the bar numbering will be off. - - @node Displaying rhythms @subsection Displaying rhythms @@ -584,58 +927,79 @@ set, the result will look OK, but the bar numbering will be off. @end menu @node Time signature -@unnumberedsubsubsec Time signature +@subsubsection Time signature -@cindex Time signature +@cindex time signature @cindex meter @funindex \time -@c TODO The word 'metrum' is latin for 'metre', I think -@c Should we not use 'metre' or 'meter' here? -Time signature indicates the metrum of a piece: a regular pattern -of strong and weak beats. It is denoted by a fraction at the -start of the staff. +The time signature is set with the @code{\time} command: -The time signature is set with the @code{\time} command - -@lilypond[quote,ragged-right,fragment,verbatim] -\time 2/4 c'2 \time 3/4 c'2. +@lilypond[quote,ragged-right,fragment,verbatim,relative=2] +\time 2/4 c2 \time 3/4 c2. @end lilypond -@commonprop +@snippets The symbol that is printed can be customized with the @code{style} property. Setting it to @code{#'()} uses fraction style for 4/4 and 2/2 time, -@lilypond[fragment,quote,ragged-right,verbatim] -\time 4/4 c'1 -\time 2/2 c'1 +@lilypond[fragment,quote,ragged-right,verbatim,relative=2] +\time 4/4 c1 +\time 2/2 c1 \override Staff.TimeSignature #'style = #'() -\time 4/4 c'1 -\time 2/2 c'1 +\time 4/4 c1 +\time 2/2 c1 +@end lilypond + +A time signature symbol is normally printed whenever the time +signature changes. If this takes place at the end of a line a +warning time signature sign is printed at the end of the line and +again at the start of a new line. This default behaviour can be +modified by setting the value of the @code{break-visibility} +property. This takes three values which may be set to @code{#t} +or @code{#f} to specify whether the corresponding time signature +is visible or not. The order of the three values is @code{end of +line visible}, @code{middle of line visible}, @code{beginning of +line visible}. + +@lilypond[fragment,quote,ragged-right,verbatim,relative=2] +% Do not print any time signatures at end of line +\override Staff.TimeSignature #'break-visibility = ##(#f #t #t) +\time 4/4 c1 +\time 3/4 c2. +% Do not print the following 9/8 time signature +\once \override Staff.TimeSignature #'break-visibility = ##(#t #f #t) +\time 9/8 c4. c c +\time 2/2 c1 +\break +\time 9/8 c4. c c +\time 12/8 c2. c2. @end lilypond There are many more options for its layout. See @ref{Ancient time signatures}, for more examples. -@code{\time} sets the property @code{timeSignatureFraction}, -@code{beatLength} and @code{measureLength} in the @code{Timing} +@code{\time} sets the properties @code{timeSignatureFraction}, +@code{beatLength}, and @code{measureLength} in the @code{Timing} context, which is normally aliased to @internalsref{Score}. The property @code{measureLength} determines where bar lines should be inserted, and how automatic beams should be generated. Changing the value of @code{timeSignatureFraction} also causes the symbol to be printed. -@cindex Measure groupings +@cindex measure groupings More options are available through the Scheme function -@code{set-time-signature}. In combination with the -@internalsref{Measure_grouping_engraver}, it will create +@code{set-time-signature}, which takes three arguments: the number +of beats, the beat length, and the internal grouping of beats in +the measure. If the @internalsref{Measure_grouping_engraver} is +included, the function will also create @internalsref{MeasureGrouping} signs. Such signs ease reading rhythmically complex modern music. In the following example, the 9/8 measure is subdivided in 2, 2, 2 and 3. This is passed to -@code{set-time-signature} as the third argument @code{(2 2 2 3)} +@code{set-time-signature} as the third argument @code{(2 2 2 3)}: @lilypond[quote,ragged-right,verbatim] \score { @@ -657,45 +1021,46 @@ rhythmically complex modern music. In the following example, the @seealso -Program reference: @internalsref{TimeSignature}, and +Snippets: @lsrdir{Rhythms,Rhythms} + +Internals Reference: @internalsref{TimeSignature}, and @internalsref{Timing_translator}. -Examples: @lsr{contemporary,compound-time-signature.ly}. +Examples: @c @lsr{contemporary,compound-time-signature.ly}. -@refbugs +@knownissues Automatic beaming does not use the measure grouping specified with @code{set-time-signature}. @node Upbeats -@unnumberedsubsubsec Upbeats +@subsubsection Upbeats @cindex anacrusis @cindex upbeat @cindex partial measure @cindex measure, partial +@cindex pickup measure @cindex shorten measures @funindex \partial -Partial measures, such as an anacrusis or upbeat, are entered -using the - -@lilypond[quote,ragged-right,fragment,verbatim,relative=2] -\partial 16*5 c16 cis d dis e | a2. c,4 | b2 -@end lilypond - -The syntax for this command is +Partial or pickup measures, such as an anacrusis or upbeat, are +entered using the @code{\partial} command, with the syntax @example \partial @var{duration} @end example where @code{duration} is the rhythmic length to be added before -the next bar. +the next measure: + +@lilypond[quote,ragged-right,fragment,verbatim,relative=2] +\partial 16*5 c16 cis d dis e | a2. c,4 | b2 +@end lilypond -This is internally translated into +Internally, this is translated into @example \set Timing.measurePosition = -@var{length of duration} @@ -707,11 +1072,11 @@ that this is a negative number; @code{\partial 4} is internally translated to mean @qq{there is a quarter note left in the bar.} -@refbugs +@knownissues This command does not take into account grace notes at the start -of the music. When a piece starts with graces notes in the -pickup, then the @code{\partial} should follow the grace notes +of the music. When a piece starts with grace notes in the +pickup, then the @code{\partial} should follow the grace notes: @lilypond[verbatim,quote,ragged-right,relative,fragment] \grace f16 @@ -724,9 +1089,12 @@ a2 g2 piece. If you use it after the beginning, some odd warnings may occur. +@seealso + +Snippets: @lsrdir{Rhythms,Rhythms} @node Unmetered music -@unnumberedsubsubsec Unmetered music +@subsubsection Unmetered music @cindex cadenza @funindex \cadenzaOn @@ -746,12 +1114,24 @@ c4 c d8 d d f4 g4. d4 e d c @end lilypond +Bar numbering is resumed at the end of the cadenza as if the +cadenza were not there: + +@lilypond[verbatim,quote,ragged-right,relative=2,fragment] +\override Score.BarNumber #'break-visibility = ##( #t #t #t ) +c4 d e d +\cadenzaOn +c4 c d8 d d f4 g4. +\cadenzaOff +\bar "|" +d4 e d c +@end lilypond -@refbugs +@knownissues LilyPond will only insert line breaks and page breaks at a -barline. Unless the unmetered music ends before the end of the -staff line, you will need to insert invisible bar lines +bar line. Unless the unmetered music ends before the end of the +staff line, you will need to insert invisible bar lines with @example \bar "" @@ -760,24 +1140,33 @@ staff line, you will need to insert invisible bar lines @noindent to indicate where breaks can occur. +@seealso + +Snippets: @lsrdir{Rhythms,Rhythms} + @node Polymetric notation -@unnumberedsubsubsec Polymetric notation +@subsubsection Polymetric notation @cindex double time signatures @cindex signatures, polymetric @cindex polymetric signatures @cindex meter, polymetric +Music Glossary: +@rglos{polymetric} +@rglos{polymetric time signature} +@rglos{meter} + Double time signatures are not supported explicitly, but they can be faked. In the next example, the markup for the time signature is created with a markup text. This markup text is inserted in the @internalsref{TimeSignature} grob. See also -@lsr{contemporary,compound-time-signature}. +@c @lsr{contemporary,compound-time-signature}. @lilypond[verbatim,ragged-right] % create 2/4 + 5/8 -tsMarkup =\markup { +tsMarkup = \markup { \override #'(baseline-skip . 2) \number { \column { "2" "4" } \vcenter "+" @@ -798,53 +1187,20 @@ Each staff can also have its own time signature. This is done by moving the @internalsref{Timing_translator} to the @internalsref{Staff} context. -@example -\layout @{ - \context @{ \Score - \remove "Timing_translator" - \remove "Default_bar_line_engraver" - @} - \context @{ +@lilypond[quote,verbatim,ragged-right] +\layout { + \context { + \Score + \remove "Timing_translator" + \remove "Default_bar_line_engraver" + } + \context { \Staff \consists "Timing_translator" \consists "Default_bar_line_engraver" - @} - -@} -@end example - - -Now, each staff has its own time signature. - -@example -<< - \new Staff @{ - \time 3/4 - c4 c c | c c c | - @} - \new Staff @{ - \time 2/4 - c4 c | c c | c c - @} - \new Staff @{ - \time 3/8 - c4. c8 c c c4. c8 c c - @} ->> -@end example - -@lilypond[quote,ragged-right] -\layout{ - \context{ - \Score - \remove "Timing_translator" - \remove "Default_bar_line_engraver" - } - \context{ \Staff - \consists "Timing_translator" - \consists "Default_bar_line_engraver" } } +%Now, each staff has its own time signature. \relative c' << \new Staff { @@ -864,16 +1220,23 @@ Now, each staff has its own time signature. A different form of polymetric notation is where note lengths have -different values across staves. +different values across staves, but the measures are all the same +length. This notation can be created by setting a common time signature for each staff but replacing it manually using @code{timeSignatureFraction} to the desired fraction. Then the printed durations in each staff are scaled to the common time signature. The latter is done with @code{\compressMusic}, which -is used similar to @code{\times}, but does not create a tuplet -bracket. The syntax is @example \compressMusic #'(@var{numerator} -. @var{denominator}) @var{musicexpr} @end example +is used in a similar way to @code{\times}, but does not create +a tuplet bracket. The syntax is + +@funindex \compressMusic + +@example +\compressMusic +#'(@var{numerator} . @var{denominator}) @var{musicexpr} +@end example @@ -908,17 +1271,24 @@ staff, shown durations are multiplied by 3/5, so that 3/5 * 10/8 = @end lilypond -@refbugs +@knownissues When using different time signatures in parallel, the spacing is aligned vertically, but bar lines distort the regular spacing. +@seealso + +Snippets: @lsrdir{Rhythms,Rhythms}, @c @lsr{contemporary,compound-time-signature}. + +Internals Reference: @internalsref{TimeSignature}, @internalsref{Timing-translator}, @internalsref{Staff}. + @node Automatic note splitting -@unnumberedsubsubsec Automatic note splitting +@subsubsection Automatic note splitting -Long notes can be converted automatically to tied notes. This is -done by replacing the @internalsref{Note_heads_engraver} by the +Long notes which overrun bar lines can be converted automatically +to tied notes. This is done by replacing the +@internalsref{Note_heads_engraver} by the @internalsref{Completion_heads_engraver}. In the following examples, notes crossing the bar line are split and tied. @@ -941,7 +1311,7 @@ If you want to allow line breaking on the bar lines where also remove @internalsref{Forbid_line_break_engraver}. -@refbugs +@knownissues Not all durations (especially those containing tuplets) can be represented exactly with normal notes and dots, but the engraver @@ -953,7 +1323,12 @@ split rests. @seealso -Program reference: @internalsref{Completion_heads_engraver}. +Snippets: @lsrdir{Rhythms,Rhythms} + +Internals Reference: @internalsref{Note_heads_engraver}, +@internalsref{Completion_heads_engraver}, +@internalsref{Forbid_line_break_engraver}. + @@ -963,80 +1338,328 @@ Program reference: @internalsref{Completion_heads_engraver}. @menu * Automatic beams:: +* Setting automatic beam behavior:: * Manual beams:: +* Feathered beams:: @end menu @node Automatic beams -@unnumberedsubsubsec Automatic beams +@subsubsection Automatic beams -By default beams are inserted automatically +By default, beams are inserted automatically: + +@cindex beams, manual +@cindex manual beams @lilypond[quote,ragged-right,fragment,verbatim,relative=2] \time 2/4 c8 c c c \time 6/8 c c c c8. c16 c8 @end lilypond -When these automatic decisions are not good enough, beaming -can be entered explicitly, see @ref{Manual beams} below. -It is also possible to define beaming -patterns that differ from the defaults. See @ref{Manual beams} -and @ref{Setting automatic beam behavior}. +If these automatic decisions are not satisfactory, beaming can be +entered explicitly; see @ref{Manual beams}. It is also possible +to define beaming patterns that differ from the defaults; see +@ref{Setting automatic beam behavior}. The default beaming rules +are defined in @file{scm/@/auto@/-beam@/.scm}. +@cindex autoBeamOn +@cindex autoBeamOff -@commonprop - -Feathered beams are printed by setting the @code{grow-direction} -property of a @code{Beam}. The @code{\featherDurations} function -can be used to adjust note durations. +@noindent +Automatic beaming may be turned off and on with +@code{\autoBeamOff} and @code{\autoBeamOn} commands: -@lilypond[ragged-right,relative=1,fragment,verbatim,quote] -\override Beam #'grow-direction = #LEFT -\featherDurations #(ly:make-moment 5 4) -{ - c16[ c c c c c c] -} +@lilypond[quote,ragged-right,fragment,relative=1,verbatim] +c4 c8 c8. c16 c8. c16 c8 +\autoBeamOff +c4 c8 c8. c16 c8. +\autoBeamOn +c16 c8 @end lilypond -@seealso +@snippets -Program reference: @internalsref{Beam}. +Beaming patterns may be altered with the @code{beatGrouping} property, +@lilypond[quote,verbatim,relative=2,fragment,ragged-right] +\time 5/16 +\set beatGrouping = #'(2 3) +c8[^"(2+3)" c16 c8] +\set beatGrouping = #'(3 2) +c8[^"(3+2)" c16 c8] +@end lilypond -@refbugs +The beams of consecutive 16th (or shorter) notes are, by default, +not sub-divided. That is, the three (or more) beams stretch +unbroken over entire groups of notes. This behaviour can +be modified to sub-divide the beams into sub-groups by setting +the property @code{subdivideBeams}. When set, multiple beams +will be sub-divided at intervals defined by the current value of +@code{beatLength} by reducing the multiple beams to just one beam +between the sub-groups. Note that @code{beatLength} lives in the +@code{Score} context and defaults to a quarter note. It must be +set to a fraction giving the duration of the beam sub-group +using the @code{make-moment} function, as shown here: -The @code{\featherDurations} command only works with very short -music snippets. +@lilypond[fragment,ragged-right,quote,relative=2,verbatim] +c32[ c c c c c c c] +\set subdivideBeams = ##t +c32[ c c c c c c c] +% Set beam sub-group length to an eighth note +\set Score.beatLength = #(ly:make-moment 1 8) +c32[ c c c c c c c] +% Set beam sub-group length to a sixteenth note +\set Score.beatLength = #(ly:make-moment 1 16) +c32[ c c c c c c c] +@end lilypond +@funindex subdivideBeams -@node Manual beams -@unnumberedsubsubsec Manual beams +@noindent +For more information about @code{make-moment}, see +@ref{Time administration}. -@cindex beams, manual +@funindex breakable +@cindex break, line +@cindex line breaks -Individual notes may be marked with @code{\noBeam} to prevent them -from being beamed +Line breaks are normally forbidden when beams cross bar lines. +This behavior can be changed by setting the @code{breakable} +property: @code{\override Beam #'breakable = ##t}. -@lilypond[quote,ragged-right,fragment,verbatim,relative=2] -\time 2/4 c8 c\noBeam c c +@lilypond[ragged-right,relative=2,fragment,verbatim,quote] +\override Beam #'breakable = ##t +c8 \repeat unfold 15 {c[ c] } c @end lilypond -@cindex autoBeamOn -@cindex autoBeamOff +@cindex beams and line breaks +@cindex beams, kneed +@cindex kneed beams +@cindex auto-knee-gap + +Kneed beams are inserted automatically when a large gap is +detected between the note heads. This behavior can be tuned +through the @code{auto-knee-gap} property. A kneed beam is +drawn if the gap is larger than the value of +@code{auto-knee-gap} plus the width of the beam object (which +depends on the duration of the notes and the slope of the beam). +By default @code{auto-knee-gap} is set to 5.5 staff spaces. + +@lilypond[fragment,ragged-right,quote,verbatim] +f8 f''8 f8 f''8 +\override Beam #'auto-knee-gap = #6 +f8 f''8 f8 f''8 +@end lilypond + + +@seealso + +Notation Reference: @ref{Manual beams}, @ref{Setting automatic beam behavior}. + +Snippets: @lsrdir{Rhythms,Rhythms} + +Internals Reference: @internalsref{Beam}. + + +@knownissues + +Automatically kneed cross-staff beams cannot be used together with +hidden staves. See @ref{Hiding staves}. + +Beams can collide with note heads and accidentals in other voices + + +@node Setting automatic beam behavior +@subsubsection Setting automatic beam behavior + +@funindex autoBeamSettings +@funindex (end * * * *) +@funindex (begin * * * *) +@cindex automatic beams, tuning +@cindex tuning automatic beaming + +@c [TODO: use \applyContext] + +In normal time signatures, automatic beams can start on any note +but can end in only a few positions within the measure: beams can +end on a beat, or at durations specified by the properties in +@code{autoBeamSettings}. The properties in +@code{autoBeamSettings} consist of a list of rules for where beams +can begin and end. The default @code{autoBeamSettings} rules are +defined in @file{scm/@/auto@/-beam@/.scm}. + +In order to add a rule to the list, use +@example +#(override-auto-beam-setting '(be p q n m) a b [context]) +@end example + +@itemize + +@item @code{be} is either @code{begin} or @code{end}. + +@item @code{p/q} is the duration of the note for which you want +to add a rule. A beam is considered to have the duration of its +shortest note. Set @code{p} and @code{q} to @code{'*'} to +have this apply to any beam. + +@item @code{n/m} is the time signature to which +this rule should apply. Set @code{n} and @code{m} to @code{'*'} +to have this apply in any time signature. + +@item @code{a/b} is the position in the bar at which the beam should +begin/end. + +@item @code{context} is optional, and it specifies the context at which +the change should be made. The default is @code{'Voice}. + +@code{#(score-override-auto-beam-setting '(A B C D) E F)} is equivalent to +@code{#(override-auto-beam-setting '(A B C D) E F 'Score)}. + +@end itemize + +For example, if automatic beams should always end on the first quarter +note, use + +@example +#(override-auto-beam-setting '(end * * * *) 1 4) +@end example + +You can force the beam settings to only take effect on beams whose shortest +note is a certain duration + +@lilypond[quote,fragment,ragged-right,verbatim,relative=2] +\time 2/4 +#(override-auto-beam-setting '(end 1 16 * *) 1 16) +a16 a a a a a a a | +a32 a a a a16 a a a a a | +#(override-auto-beam-setting '(end 1 32 * *) 1 16) +a32 a a a a16 a a a a a | +@end lilypond + +You can force the beam settings to only take effect in certain time +signatures + +@lilypond[quote,fragment,ragged-right,verbatim,relative=2] +\time 5/8 +#(override-auto-beam-setting '(end * * 5 8) 2 8) +c8 c d d d +\time 4/4 +e8 e f f e e d d +\time 5/8 +c8 c d d d +@end lilypond + +You can also remove a previously set beam-ending rule by using + +@example +#(revert-auto-beam-setting '(be p q n m) a b [context]) +@end example @noindent -and automatic beaming may be turned off and on with -@code{\autoBeamOff} and @code{\autoBeamOn} commands: +be, p, q, n, m, a, b and context are the same as above. Note that the +default rules are specified in @file{scm/@/auto@/-beam@/.scm}, +so you can revert rules that you did not explicitly create. -@lilypond[quote,ragged-right,fragment,relative=1,verbatim] -c4 c8 c8. c16 c8. c16 c8 -\autoBeamOff -c4 c8 c8. c16 c8. -\autoBeamOn -c16 c8 +@lilypond[quote,fragment,ragged-right,verbatim,relative=2] +\time 4/4 +a16 a a a a a a a a a a a a a a a +#(revert-auto-beam-setting '(end 1 16 4 4) 1 4) +a16 a a a a a a a a a a a a a a a @end lilypond -@funindex ] -@funindex [ +The rule in a revert-auto-beam-setting statement must exactly match the +original rule. That is, no wildcard expansion is taken into account. + +@lilypond[quote,fragment,ragged-right,verbatim,relative=2] +\time 1/4 +#(override-auto-beam-setting '(end 1 16 1 4) 1 8) +a16 a a a +#(revert-auto-beam-setting '(end 1 16 * *) 1 8) % this won't revert it! +a a a a +#(revert-auto-beam-setting '(end 1 16 1 4) 1 8) % this will +a a a a +@end lilypond + + + +@c TODO: old material -- not covered by above stuff, I think. +If automatic beams should end on every quarter in 5/4 time, specify +all endings +@example +#(override-auto-beam-setting '(end * * * *) 1 4 'Staff) +#(override-auto-beam-setting '(end * * * *) 1 2 'Staff) +#(override-auto-beam-setting '(end * * * *) 3 4 'Staff) +#(override-auto-beam-setting '(end * * * *) 5 4 'Staff) +@dots{} +@end example + +The same syntax can be used to specify beam starting points. In this +example, automatic beams can only end on a dotted quarter note +@example +#(override-auto-beam-setting '(end * * * *) 3 8) +#(override-auto-beam-setting '(end * * * *) 1 2) +#(override-auto-beam-setting '(end * * * *) 7 8) +@end example +In 4/4 time signature, this means that automatic beams could end only on +3/8 and on the fourth beat of the measure (after 3/4, that is 2 times +3/8, has passed within the measure). + +If any unexpected beam behaviour occurs, check the default automatic beam +settings in @file{scm/@/auto@/-beam@/.scm} +for possible interference, because the beam +endings defined there will still apply on top of your own overrides. Any +unwanted endings in the default vales must be reverted for your time +signature(s). + +For example, to typeset @code{(3 4 3 2)}-beam endings in 12/8, begin +with + +@example +%%% revert default values in scm/auto-beam.scm regarding 12/8 time +#(revert-auto-beam-setting '(end * * 12 8) 3 8) +#(revert-auto-beam-setting '(end * * 12 8) 3 4) +#(revert-auto-beam-setting '(end * * 12 8) 9 8) + +%%% your new values +#(override-auto-beam-setting '(end 1 8 12 8) 3 8) +#(override-auto-beam-setting '(end 1 8 12 8) 7 8) +#(override-auto-beam-setting '(end 1 8 12 8) 10 8) +@end example + +@cindex automatic beam generation +@cindex autobeam +@funindex autoBeaming +@cindex lyrics + +If beams are used to indicate melismata in songs, then automatic +beaming should be switched off with @code{\autoBeamOff}. + + +@predefined + +@funindex \autoBeamOff +@code{\autoBeamOff}, +@funindex \autoBeamOn +@code{\autoBeamOn}. + + +@knownissues + +If a score ends while an automatic beam has not been ended and is +still accepting notes, this last beam will not be typeset at all. +The same holds for polyphonic voices, entered with @code{<< +@dots{} \\ @dots{} >>}. If a polyphonic voice ends while an +automatic beam is still accepting notes, it is not typeset. + +@seealso + +Snippets: @lsrdir{Rhythms,Rhythms} + + +@node Manual beams +@subsubsection Manual beams + +@cindex beams, manual In some cases it may be necessary to override the automatic beaming algorithm. For example, the autobeamer will not put beams @@ -1052,81 +1675,96 @@ marking the begin and end point with @code{[} and @code{]} @end lilypond -@commonprop +Individual notes may be marked with @code{\noBeam} to prevent them +from being beamed: + +@lilypond[quote,ragged-right,fragment,verbatim,relative=2] +\time 2/4 c8 c\noBeam c c +@end lilypond + +@funindex ] +@funindex [ @funindex stemLeftBeamCount @funindex stemRightBeamCount - -LilyPond can automatically determine beaming patterns within a -beam, but this automatic behavior can sometimes produce odd -results; therefore the @code{stemLeftBeamCount} and -@code{stemRightBeamCount} properties can be used to override the -defaults. If either property is set, its value will be used only -once, and then it is erased. +Even more strict manual control with the beams can be achieved by +setting the properties @code{stemLeftBeamCount} and +@code{stemRightBeamCount}. They specify the number of beams to +draw on the left and right side, respectively, of the next note. +If either property is set, its value will be used only once, and +then it is erased. In this example, the last @code{f} is printed +with only one beam on the left side, i.e. the eigth-note beam of +the group as a whole. @lilypond[quote,ragged-right,fragment,relative=1,verbatim] { - f8[ r16 - f g a] - f8[ r16 - \set stemLeftBeamCount = #1 - f g a] + f8[ r16 f g a] + f8[ r16 + \set stemLeftBeamCount = #1 + f g a] } @end lilypond -The property @code{subdivideBeams} can be set in order to -subdivide all 16th or shorter beams. -When set, multiple beams will be sub-divided at beat -positions, defined by the current value of @code{beatLength}, -by drawing only one beam over the beat. -@lilypond[fragment,ragged-right,quote,relative=2,verbatim] -c16[ c c c c c c c] -\set subdivideBeams = ##t -c16[ c c c c c c c] -\set Score.beatLength = #(ly:make-moment 1 8) -c16[ c c c c c c c] -@end lilypond -@funindex subdivideBeams +@snippets -@noindent -For more information about @code{make-moment}, see -@ref{Time administration}. +@node Feathered beams +@subsubsection Feathered beams -Line breaks are normally forbidden when beams cross bar lines. -This behavior can be changed by setting the @code{breakable} -property: @code{\override Beam #'breakable = ##t}. +@cindex beams, feathered +@funindex \featherDurations -@funindex breakable +Feathered beams are used to indicate that a small group of notes +should be played at an increasing (or decreasing) tempo, without +changing the overall tempo of the piece. The extent of the +feathered beam must be indicated manually using @code{[} and +@code{]}, and the beam feathering is turned on by specifying a +direction to the Beam property @code{grow-direction}. -@cindex beams and line breaks -@cindex beams, kneed -@cindex kneed beams -@cindex auto-knee-gap +If the placement of the notes and the sound in the MIDI output +is to reflect the ritardando or accelerando indicated by the +feathered beam the notes must be grouped as a +music expression delimited by braces and preceded by a +@code{featheredDurations} command which specifies the ratio +between the durations of the first and last notes in the group. -Kneed beams are inserted automatically when a large gap is -detected between the note heads. This behavior can be tuned -through the @code{auto-knee-gap} property. A kneed beam is -drawn if the gap is larger than the value of -@code{auto-knee-gap} plus the width of the beam object (which -depends on the duration of the notes and the slope of the beam). -By default @code{auto-knee-gap} is set to 5.5 staff spaces. +The square brackets +show the extent of the beam and the braces show +which notes are to have their durations modified. Normally +these would delimit the same group of notes, but this is not +required: the two commands are independent. -@lilypond[fragment,ragged-right,quote,verbatim] -f8 f''8 f8 f''8 -\override Beam #'auto-knee-gap = #6 -f8 f''8 f8 f''8 +In the following example the eight 16th notes occupy exactly the +same time as a half note, but the first note is one half as long +as the last one, with the intermediate notes gradually +lengthening. The first four 32nd notes gradually speed up, while +the last four 32nd notes are at a constant tempo. + +@lilypond[ragged-right,relative=1,fragment,verbatim,quote] +\override Beam #'grow-direction = #LEFT +\featherDurations #(ly:make-moment 2 1) +{ c16[ c c c c c c c] } +\override Beam #'grow-direction = #RIGHT +\featherDurations #(ly:make-moment 2 3) +{ c32[ d e f] } +% revert to non-feathered beams +\override Beam #'grow-direction = #'() +{ g32[ a b c] } @end lilypond -@refbugs +@noindent +The spacing in the printed output represents the +note durations only approximately, but the midi output is exact. -Automatically kneed cross-staff beams cannot be used together with -hidden staves. See @ref{Hiding staves}. +@knownissues -@c Is this still true with skyline spacing stuff? -J.Mandereau -Beams do not avoid collisions with symbols around the notes, such -as texts and accidentals. +The @code{\featherDurations} command only works with very short +music snippets, and when numbers in the fraction are small. + +@seealso + +Snippets: @lsrdir{Rhythms,Rhythms} @@ -1142,61 +1780,92 @@ as texts and accidentals. @end menu @node Bar lines -@unnumberedsubsubsec Bar lines +@subsubsection Bar lines -@cindex Bar lines +@cindex bar lines @funindex \bar @cindex measure lines @cindex repeat bars Bar lines delimit measures, and are also used to indicate -repeats. Normally, simple barlines are automatically inserted -into the printed output at places -based on the current time signature. It is not invalid if the -final note in a bar does not end on the automatically entered -barline: the note is assumed to carry over into the next bar. +repeats. Normally, simple bar lines are automatically inserted +into the printed output at places based on the current time +signature. -The simple barlines inserted automatically can be changed to +The simple bar lines inserted automatically can be changed to other types with the @code{\bar} command. For example, a closing -double barline is usually placed at the end of a piece: +double bar line is usually placed at the end of a piece: @lilypond[quote,ragged-right,relative=1,fragment,verbatim] -e4 d c2 \bar "||" +e4 d c2 \bar "|." @end lilypond -This and other special barlines may be inserted manually at any +@warning{An incorrect duration can lead to poorly formatted +music.} + +It is not invalid if the final note in a bar does not +end on the automatically entered bar line: the note is assumed +to carry over into the next bar. But if a long sequence +of such carry-over bars appears the music can appear compressed +or even flowing off the page. This is because automatic line +breaks happen only at the end of complete bars, i.e. where +the end of a note coincides with the end of a bar. + +@cindex line breaks +@cindex bar lines, invisible +@cindex measure lines, invisible + +Line breaks are also permitted at manually inserted bar lines +even within incomplete bars. To allow a line break without +printing a bar line, use + +@example +\bar "" +@end example + +@noindent +This will insert an invisible bar line and allow (but not +force) a line break to occur at this point. The bar number +counter is not increased. To force a line break see +@ref{Line breaking}. + +This and other special bar lines may be inserted manually at any point. When they coincide with the end of a bar they replace -the simple barline which would have been inserted there +the simple bar line which would have been inserted there automatically. When they do not coincide -with the end of a bar the specified barline is inserted at that +with the end of a bar the specified bar line is inserted at that point in the printed output. Such insertions do not affect -the calculation and placement of subsequent automatic barlines. +the calculation and placement of subsequent automatic bar lines. -Although the barline types signifying repeats may be inserted -manually they do not in themselves cause LilyPond to recognise -a repeated section. Such repeated sections are better entered -using the various repeat commands (see @ref{Repeats}), which -automatically print the appropriate barlines. +The simple bar line and four types of double bar line are available +for manual insertion: -The following bar types are available for manual insertion: +@lilypond[quote,ragged-right,fragment,relative=1,verbatim] +f1 \bar "|" g \bar "||" a \bar ".|" b \bar ".|." c \bar "|." d +@end lilypond -@lilypond[quote,ragged-right,relative=2,fragment,verbatim] -\override Score.RehearsalMark #'padding = #3 -c4 \bar "|" \mark \markup {\simple #"|" } -c \bar "|:" \mark \markup {\simple #"|:" } -c \bar "||" \mark \markup {\simple #"||" } -c \bar ":|" \mark \markup {\simple #":|" } -c \bar ".|" \mark \markup {\simple #".|" } -c \bar ".|." \mark \markup {\simple #".|."} -c \bar ":|:" \mark \markup {\simple #":|:"} -c \bar "|." \mark \markup {\simple #"|." } -c \bar ":" \mark \markup {\simple #":" } -c c c -\break -c \bar "dashed" \mark \markup { \simple #"dashed" } -c c c +@noindent +together with dotted and dashed bar lines: + +@lilypond[quote,ragged-right,fragment,relative=1,verbatim] +f1 \bar ":" g \bar "dashed" a +@end lilypond + +@noindent +and three types of repeat bar line: + +@lilypond[quote,ragged-right,fragment,relative=1,verbatim] +f1 \bar "|:" g \bar ":|:" a \bar ":|" b @end lilypond +@cindex repeats + +Although the bar line types signifying repeats may be inserted +manually they do not in themselves cause LilyPond to recognise +a repeated section. Such repeated sections are better entered +using the various repeat commands (see @ref{Repeats}), which +automatically print the appropriate bar lines. + In addition, you can specify @code{"||:"}, which is equivalent to @code{"|:"} except at line breaks, where it gives a double bar line at the end of the line and a start repeat at the beginning of @@ -1205,35 +1874,12 @@ the next line. @lilypond[quote,ragged-right,relative=2,fragment,verbatim] \override Score.RehearsalMark #'padding = #3 c c c c -\bar "||:" \mark \markup { - \tiny \typewriter "unbroken" \simple #"||:" } +\bar "||:" c c c c \break -\bar "||:" \mark \markup { - \tiny \typewriter "broken" \simple #"||:" } +\bar "||:" c c c c @end lilypond -Entered music is -automatically broken into lines, but this happens only at -manually inserted barlines or at automatically inserted barlines -where these occur at the -end of complete bars, i.e. where the end of a note coincides -with the end of a bar. If this never happens, perhaps due to -an error in entering durations, the outputted music can appear -very compressed as no place can be found to make a line break. - -To allow a line break without printing a bar line, use - -@example -\bar "" -@end example - -@noindent -This will insert an invisible bar line and allow (but not -force) a line break to occur at this point. The bar number -counter is not increased. To force a line break see -@ref{Line breaking}. - In scores with many staves, a @code{\bar} command in one staff is automatically applied to all staves. The resulting bar lines are connected between different staves of a @code{StaffGroup}, @@ -1254,13 +1900,12 @@ connected between different staves of a @code{StaffGroup}, @end lilypond -@commonprop +@snippets @funindex whichBar -@c TODO remove? @funindex repeatCommands @funindex defaultBarType -The command @code{\bar }@var{bartype} is a short cut for +The command @code{\bar }@var{bartype} is a shortcut for @code{\set Timing.whichBar = }@var{bartype}. A bar line is created whenever the @code{whichBar} property is set. @@ -1269,80 +1914,103 @@ The default bar type used for automatically inserted bar lines is @code{"|"}. This may be changed at any time with @code{\set Timing.defaultBarType = }@var{bartype}. -@ignore -TODO Delete this section - repeats are mentioned earlier -The contents of -@code{repeatCommands} are used to override default measure bars. - -You are encouraged to use @code{\repeat} for repetitions. See -@ref{Repeats}. -@end ignore - @seealso -In this manual: @ref{Repeats}, @ref{System start delimiters}. +Notation Reference: @ref{Line breaking}, @ref{Repeats}, +@ref{System start delimiters}. -Program reference: @internalsref{BarLine} (created at +Snippets: @lsrdir{Rhythms,Rhythms} + +Internals Reference: @internalsref{BarLine} (created at @internalsref{Staff} level), @internalsref{SpanBar} (across staves), @internalsref{Timing_translator} (for Timing properties). @node Bar numbers -@unnumberedsubsubsec Bar numbers +@subsubsection Bar numbers -@cindex Bar numbers +@cindex bar numbers @cindex measure numbers @funindex currentBarNumber -Bar numbers are typeset by default at the start of every line -except the first line. The -number itself is stored in the @code{currentBarNumber} property, -which is normally updated automatically for every measure. It -may also be set manually: +Bar numbers are typeset by default at the start of every line except +the first line. The number itself is stored in the +@code{currentBarNumber} property, which is normally updated +automatically for every measure. It may also be set manually: @lilypond[verbatim,ragged-right,quote,fragment,relative] -\repeat unfold 4 {c4 c c c} \break +c1 c c c +\break \set Score.currentBarNumber = #50 -\repeat unfold 4 {c4 c c c} +c1 c c c @end lilypond -Bar numbers may only be printed at bar lines; to print a bar -number at the beginning of a piece, an empty bar line must be -inserted there: + +@snippets + +@funindex barNumberVisibility +@cindex bar numbers, regular spacing + +Bar numbers can be typeset at regular intervals instead of just at +the beginning of every line. To do this the default behaviour +must be overridden to permit bar numbers to be printed at places +other than the start of a line. This is controlled by the +@code{break-visibility} property of @code{BarNumber}. This takes +three values which may be set to @code{#t} or @code{#f} to specify +whether the corresponding bar number is visible or not. The order +of the three values is @code{end of line visible}, @code{middle of +line visible}, @code{beginning of line visible}. In the following +example bar numbers are printed at all possible places: @lilypond[verbatim,ragged-right,quote,fragment,relative] -\set Score.currentBarNumber = #50 -\bar "" -\repeat unfold 4 {c4 c c c} \break -\repeat unfold 4 {c4 c c c} +\override Score.BarNumber #'break-visibility = ##(#t #t #t) +\set Score.currentBarNumber = #11 +\bar "" % Permit first bar number to be printed +c1 c c c +\break +c c c c @end lilypond -Bar numbers can be typeset at regular intervals instead of at the -beginning of every line. This is illustrated in the following -example, which also shows how to enclose bar numbers in boxes and -circles. +@c All the rest of these examples will be added to LSR +@c and moved into the Snippets. -gp -@ignore - TODO Text to be deleted ? -whose source is available as -@lsr{staff,making-bar-numbers-appear-at-regular-intervals.ly}. -@end ignore +@noindent +and here the bar numbers are printed every two bars +except at the end of the line: @lilypond[verbatim,ragged-right,quote,fragment,relative] -% Avoid printing a bar number at the end of a line -\override Score.BarNumber #'break-visibility = #end-of-line-invisible +\override Score.BarNumber #'break-visibility = ##(#f #t #t) +\set Score.currentBarNumber = #11 +\bar "" % Permit first bar number to be printed +% Print a bar number every 2nd bar +\set Score.barNumberVisibility = #(every-nth-bar-number-visible 2) +c1 c c c c +\break +c c c c c +@end lilypond + +@cindex measure number, format +@cindex bar number, format -% Print a bar number every 3th bar -\set Score.barNumberVisibility = #(every-nth-bar-number-visible 3) +The size of the bar number may be changed. This is illustrated +in the following example, which also shows how to enclose bar +numbers in boxes and circles, and shows an alternative way +of specifying @code{#(#f #t #t)} for @code{break-visibility}. + +@lilypond[verbatim,ragged-right,quote,fragment,relative] +% Prevent bar numbers at the end of a line and permit them elsewhere +\override Score.BarNumber #'break-visibility + = #end-of-line-invisible % Increase the size of the bar number by 2 \override Score.BarNumber #'font-size = #2 +\repeat unfold 3 { c1 } \bar "|" % Draw a box round the following bar number(s) \override Score.BarNumber #'stencil - = #(make-stencil-boxer 0.1 0.25 ly:text-interface::print) -\repeat unfold 5 { c1 } \bar "|" + = #(make-stencil-boxer 0.1 0.25 ly:text-interface::print) +\repeat unfold 3 { c1 } \bar "|" % Draw a circle round the following bar number(s) \override Score.BarNumber #'stencil @@ -1350,6 +2018,30 @@ whose source is available as \repeat unfold 4 { c1 } \bar "|." @end lilypond +@cindex bar number alignment + +Bar numbers by default are left-aligned to their parent object. +This is usually the left edge of a line or, if numbers are printed +within a line, the left bar line of the bar. The numbers may also +be positioned directly on the bar line or right-aligned to the +bar line: + +@lilypond[verbatim,ragged-right,quote,fragment,relative] +\set Score.currentBarNumber = #111 +\override Score.BarNumber #'break-visibility = ##(#t #t #t) +% Increase the size of the bar number by 2 +\override Score.BarNumber #'font-size = #2 +% Print a bar number every 2nd bar +\set Score.barNumberVisibility = #(every-nth-bar-number-visible 2) +c1 c1 +% Centre-align bar numbers +\override Score.BarNumber #'self-alignment-X = #0 +c1 c1 +% Right-align bar numbers +\override Score.BarNumber #'self-alignment-X = #-1 +c1 c1 +@end lilypond + Bar numbers can be removed entirely by removing the Bar number engraver from the score context. @@ -1369,25 +2061,37 @@ engraver from the score context. @seealso -Program reference: @internalsref{BarNumber}. +Snippets: @lsrdir{Rhythms,Rhythms} + +Internals Reference: @internalsref{BarNumber}. + + +@knownissues -Examples: @lsrdir{staff} +Bar numbers may collide with the top of the +@internalsref{StaffGroup} bracket, if there is one. To solve +this, the @code{padding} property of @internalsref{BarNumber} can +be used to position the number correctly. +Bar numbers may only be printed at bar lines; to print a bar +number at the beginning of a piece, an empty bar line must be +inserted there, and a value other than @code{1} must be placed +in @code{currentBarNumber}: -@refbugs +@lilypond[verbatim,ragged-right,quote,fragment,relative] +\set Score.currentBarNumber = #50 +\bar "" +c1 c c c +c1 c c c +\break +@end lilypond -@c TODO is this still a bug in 11? -Bar numbers can collide with the top of the -@internalsref{StaffGroup} bracket, if there is one. -To solve this, the @code{padding} property of -@internalsref{BarNumber} can be used to -position the number correctly. @node Bar and bar number checks -@unnumberedsubsubsec Bar and bar number checks +@subsubsection Bar and bar number checks -@cindex Bar check +@cindex bar check @funindex barCheckSynchronize @funindex | @@ -1398,7 +2102,7 @@ If bar check lines are encountered at other places, a list of warnings is printed in the log file, showing the line numbers and lines in which the bar checks failed. In the next -example, the second bar check will signal an error +example, the second bar check will signal an error. @example \time 3/4 c2 e4 | g2 | @@ -1421,13 +2125,22 @@ incorrect durations. @funindex | @funindex pipeSymbol -It is also possible to redefine the meaning of @code{|}. This is -done by assigning a music expression to @code{pipeSymbol}, +It is also possible to redefine the action taken when a bar check +or pipe symbol, @code{|}, is encountered in the input, so that +it does something other than a bar check. This is done by +assigning a music expression to @code{pipeSymbol}. +In the following example @code{|} is set to insert a double bar +line wherever it appears in the input, rather than checking +for end of bar. @lilypond[quote,ragged-right,verbatim] pipeSymbol = \bar "||" - -{ c'2 c' | c'2 c' } +{ + c'2 c'2 | + c'2 c'2 + c'2 | c'2 + c'2 c'2 +} @end lilypond When copying large pieces of music, it can be helpful to check @@ -1443,11 +2156,16 @@ are entering from. This can be checked with will print a warning if the @code{currentBarNumber} is not 123 when it is processed. +@seealso + +Snippets: @lsrdir{Rhythms,Rhythms} + @node Rehearsal marks -@unnumberedsubsubsec Rehearsal marks +@subsubsection Rehearsal marks -@cindex Rehearsal marks +@cindex rehearsal marks +@cindex mark, rehearsal @funindex \mark To print a rehearsal mark, use the @code{\mark} command @@ -1473,11 +2191,18 @@ The mark is incremented automatically if you use @code{\mark mark manually. The value to use is stored in the property @code{rehearsalMark}. +@cindex rehearsal mark format +@cindex rehearsal mark style +@cindex style, rehearsal mark +@cindex format, rehearsal mark +@cindex mark, rehearsal, style +@cindex mark, rehearsal, format + The style is defined by the property @code{markFormatter}. It is a function taking the current mark (an integer) and the current context as argument. It should return a markup object. In the -following example, @code{markFormatter} is set to a canned -procedure. After a few measures, it is set to function that +following example, @code{markFormatter} is set to a pre-defined +procedure. After a few measures, it is set to a procedure that produces a boxed number. @lilypond[fragment,quote,ragged-right,verbatim,relative=2] @@ -1539,16 +2264,18 @@ For common tweaks to the positioning of rehearsal marks, see @seealso -This manual: @ref{Text marks}. +Snippets: @lsrdir{Rhythms,Rhythms} -Program reference: @internalsref{RehearsalMark}. +This manual: @ref{The Feta font}, @ref{Text marks}. + +Internals Reference: @internalsref{RehearsalMark}. Init files: @file{scm/@/translation@/-functions@/.scm} contains the definition of @code{format-mark-numbers} and @code{format-mark-letters}. They can be used as inspiration for other formatting functions. -Examples: @lsr{parts,rehearsal-mark-numbers.ly} +Examples: @c @lsr{parts,rehearsal-mark-numbers.ly} @node Special rhythmic concerns @@ -1559,11 +2286,10 @@ Examples: @lsr{parts,rehearsal-mark-numbers.ly} * Grace notes:: * Aligning to cadenzas:: * Time administration:: -* Proportional notation (introduction):: @end menu @node Grace notes -@unnumberedsubsubsec Grace notes +@subsubsection Grace notes @funindex \grace @cindex ornaments @@ -1571,61 +2297,34 @@ Examples: @lsr{parts,rehearsal-mark-numbers.ly} @cindex appoggiatura @cindex acciaccatura -Grace notes are ornaments that are written out. The most common -ones are acciaccatura, which should be played as very short. It -is denoted by a slurred small note with a slashed stem. The -appoggiatura is a grace note that takes a fixed fraction of the -main note, and is denoted as a slurred note in small print without -a slash. They are entered with the commands @code{\acciaccatura} -and @code{\appoggiatura}, as demonstrated in the following example +Grace notes are ornaments that are written out. They are made with +the @code{\grace} command. By prefixing this keyword to a music +expression, a new one is formed, which will be printed in a +smaller font and takes up no logical time in a measure. @lilypond[quote,ragged-right,relative=2,verbatim,fragment] -b4 \acciaccatura d8 c4 \appoggiatura e8 d4 -\acciaccatura { g16[ f] } e4 +c4 \grace c16 c4 +\grace { c16[ d16] } c2 c4 @end lilypond -Both are special forms of the @code{\grace} command. By prefixing -this keyword to a music expression, a new one is formed, which -will be printed in a smaller font and takes up no logical time in -a measure. +Two special forms of the @code{\grace} command exist. +An @emph{acciaccatura}, which should be played as very short, +is denoted by a slurred small note with a slashed stem. The +@emph{appoggiatura}, a grace note that takes a fixed fraction of the +main note, is denoted as a slurred note in small print without +a slash. They are entered with the commands @code{\acciaccatura} +and @code{\appoggiatura}, as demonstrated in the following +example: @lilypond[quote,ragged-right,relative=2,verbatim,fragment] -c4 \grace c16 c4 -\grace { c16[ d16] } c2 c4 +b4 \acciaccatura d8 c4 +\appoggiatura e8 d4 +\acciaccatura { g16[ f] } e4 @end lilypond @noindent -Unlike @code{\acciaccatura} and @code{\appoggiatura}, the -@code{\grace} command does not start a slur. - -@cindex timing, internal - -Internally, timing for grace notes is done using a second, -@q{grace} timing. Every point in time consists of two rational -numbers: one denotes the logical time, one denotes the grace -timing. The above example is shown here with timing tuples - -@lilypond[quote,ragged-right] -<< - \relative c''{ - c4 \grace c16 c4 \grace { - c16[ d16] } c2 c4 - } - \new Lyrics \lyricmode { - \override LyricText #'font-family = #'typewriter - - \markup { (0,0) } 4 - \grace { \markup { - ( \fraction 1 4 , \fraction -1 16 ) } 16 } - \markup { (\fraction 1 4 , 0 ) } 4 - \grace { - \markup { (\fraction 2 4 , \fraction "-1" 8 ) } 16 - \markup { (\fraction 2 4 , \fraction "-1" 16 ) } 16 - } - \markup { ( \fraction 2 4 , 0 ) } - } ->> -@end lilypond +@code{\acciaccatura} and @code{\appoggiatura} start a slur, +@code{\grace} does not. The placement of grace notes is synchronized between different staves. In the following example, there are two sixteenth grace @@ -1638,6 +2337,8 @@ notes for every eighth grace note @funindex \afterGrace +@cindex grace notes, following + If you want to end a note with a grace, use the @code{\afterGrace} command. It takes two arguments: the main note, and the grace notes following the main note. @@ -1669,8 +2370,8 @@ The same effect can be achieved manually by doing @noindent By adjusting the duration of the skip note (here it is a -half-note), the space between the main-note and the grace is -adjusted. +half-note), the space between the main-note and the grace +may be adjusted. A @code{\grace} music expression will introduce special typesetting settings, for example, to produce smaller type, and @@ -1707,18 +2408,23 @@ that stems do not always point up. Another option is to change the variables @code{startGraceMusic}, @code{stopGraceMusic}, @code{startAcciaccaturaMusic}, @code{stopAcciaccaturaMusic}, @code{startAppoggiaturaMusic}, -@code{stopAppoggiaturaMusic}. More information is in the file -@file{ly/@/grace@/-init@/.ly}. +@code{stopAppoggiaturaMusic}. The default values of these can be +seen in the file @file{ly/@/grace@/-init@/.ly}. By redefining +them other effects may be obtained. + +@cindex stem, with slash @noindent -The slash through the stem in acciaccaturas can be obtained in +The slash through the stem in @emph{acciaccatura}s can be obtained in other situations by @code{\override Stem #'stroke-style = #"grace"}. -@commonprop +@snippets -Grace notes may be forced to use floating spacing, +Grace notes may be forced to use align with regular notes +in other staves by setting @code{strict-grace-spacing} to +##t: @lilypond[relative=2,ragged-right] << @@ -1741,14 +2447,22 @@ Grace notes may be forced to use floating spacing, @seealso -Program reference: @internalsref{GraceMusic}. +Music Glossary: +@rglos{grace notes}, +@rglos{acciaccatura}, +@rglos{appoggiatura} + +Snippets: @lsrdir{Rhythms,Rhythms} +Internals Reference: @internalsref{GraceMusic}. -@refbugs -A score that starts with a @code{\grace} expression needs an -explicit @code{\new Voice} declaration, otherwise the main note -and the grace note end up on different staves. +@knownissues + +A multi-note beamed @emph{acciaccatura} is printed without a slash, +and looks exactly the same as a multi-note beamed +@emph{appoggiatura}. +@c TODO Add link to LSR snippet to add slash when available Grace note synchronization can also lead to surprises. Staff notation, such as key signatures, bar lines, etc., are also @@ -1774,19 +2488,22 @@ expressions. Nesting or juxtaposing grace sections is not supported, and might produce crashes or other errors. @node Aligning to cadenzas -@unnumberedsubsubsec Aligning to cadenzas +@subsubsection Aligning to cadenzas + +@cindex cadenza +@cindex cadenza, aligning to +@cindex aligning to cadenza In an orchestral context, cadenzas present a special problem: when constructing a score that includes a cadenza, all other instruments should skip just as many notes as the length of the cadenza, otherwise they will start too soon or too late. -A solution to this problem are the functions +A solution to this problem is to use the functions @code{mmrest-of-length} and @code{skip-of-length}. These Scheme -functions take a piece of music as argument, and generate a -@code{\skip} or multi-rest, exactly as long as the piece. The use -of @code{mmrest-of-length} is demonstrated in the following -example. +functions take a piece of music as argument, and generate a multi-rest +or @code{\skip}, exactly as long as the piece. The use of +@code{mmrest-of-length} is demonstrated in the following example. @lilypond[verbatim,ragged-right,quote] cadenza = \relative c' { @@ -1803,30 +2520,50 @@ cadenza = \relative c' { >> @end lilypond +@seealso + +Snippets: @lsrdir{Rhythms,Rhythms} + @node Time administration -@unnumberedsubsubsec Time administration +@subsubsection Time administration -@cindex Time administration +@cindex time administration +@cindex timing (within the score) +@cindex music, unmetered +@cindex unmetered music -Time is administered by the -@internalsref{Time_signature_engraver}, which by default is -to be found in the @internalsref{Score} context. -The bookkeeping deals with the following variables +@funindex currentBarNumber +@funindex measurePosition +@funindex measureLength + +Time is administered by the @code{Timing_translator}, which by +default is to be found in the @code{Score} context. An alias, +@code{Timing}, is added to the context in which the +@code{Timing_translator} is placed. + +The following properties of @code{Timing} are used +to keep track of timing within the score. + +@cindex bar number +@cindex measure number @table @code @item currentBarNumber -The measure number. +The current measure number. For an example showing the +use of this property see @ref{Bar numbers}. @item measureLength The length of the measures in the current time signature. For a -4/4 time this is@tie{}1, and for 6/8 it is 3/4. +4/4 time this is@tie{}1, and for 6/8 it is 3/4. Its value +determines when bar lines are inserted and how automatic beams +should be generated. @item measurePosition The point within the measure where we currently are. This -quantity is reset to@tie{}0 whenever it exceeds -@code{measureLength}. When that happens, @code{currentBarNumber} -is incremented. +quantity is reset by subtracting @code{measureLength} whenever +@code{measureLength} is reached or exceeded. When that happens, +@code{currentBarNumber} is incremented. @item timing If set to true, the above variables are updated for every time @@ -1836,21 +2573,19 @@ measure indefinitely. @end table Timing can be changed by setting any of these variables -explicitly. In the next example, the 4/4 time signature is -printed, but @code{measureLength} is set to 5/4. After a while, -the measure is shortened by 1/8, by setting @code{measurePosition} -to 7/8 at 2/4 in the measure, so the next bar line will fall at -2/4 + 3/8. The 3/8 arises because 5/4 normally has 10/8, but we -have manually set the measure position to be 7/8 and 10/8 - 7/8 = -3/8. +explicitly. In the next example, the default 4/4 time +signature is printed, but @code{measureLength} is set to 5/4. +At 4/8 through the third measure, the @code{measurePosition} is +advanced by 1/8 to 5/8, shortening that bar by 1/8. +The next bar line then falls at 9/8 rather than 5/4. @lilypond[quote,ragged-right,verbatim,relative,fragment] \set Score.measureLength = #(ly:make-moment 5 4) c1 c4 c1 c4 c4 c4 -\set Score.measurePosition = #(ly:make-moment 7 8) -b8 b b +\set Score.measurePosition = #(ly:make-moment 5 8) +b4 b4 b8 c4 c1 @end lilypond @@ -1862,54 +2597,22 @@ duration of n/m of a whole note. For example, notes. -@node Proportional notation (introduction) -@unnumberedsubsubsec Proportional notation (introduction) -@cindex Proportional notation - -See @ref{Proportional notation}. +@seealso +This manual: @ref{Bar numbers}, @ref{Unmetered music} -TODO: remove all this stuff? +Snippets: @lsrdir{Rhythms,Rhythms} -Notes can be spaced proportionally to their time-difference by -assigning a duration to @code{proportionalNotationDuration} +Internals Reference: @internalsref{Timing_translator}, +@internalsref{Score} -@lilypond[quote,ragged-right,verbatim,relative=2,fragment] -<< - \set Score.proportionalNotationDuration = #(ly:make-moment 1 16) - \new Staff { c8[ c c c c c] c4 c2 r2 } - \new Staff { c2 \times 2/3 { c8 c c } c4 c1 } ->> -@end lilypond -Setting this property only affects the ideal spacing between -consecutive notes. For true proportional notation, the following -settings are also required. -@itemize -@item True proportional notation requires that symbols are allowed -to overstrike each other. That is achieved by removing the -@internalsref{Separating_line_group_engraver} from -@internalsref{Staff} context. - -@item Spacing influence of prefatory matter (clefs, bar lines, -etc.) is removed by setting the @code{strict-note-spacing} -property to @code{#t} in @internalsref{SpacingSpanner} grob. -@item Optical spacing tweaks are switched by setting -@code{uniform-stretching} in @internalsref{SpacingSpanner} to -true. -@end itemize -@seealso -Examples: @lsr{spacing,proportional@/-spacing@/.ly}, -@lsr{spacing,proportional@/-strict@/-grace@/-notes@/.ly}, and -@lsr{spacing,proportional@/-strict@/-notespacing@/.ly} -An example of strict proportional notation is in the -example file @file{input/proportional.ly}.