X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fbasic-notation.itely;h=aeeb5ed9d4cb5d9ca4f2deaa58eb6596e9dad886;hb=ba3045ce76cd37a4e11fd775fa04ce4b7586ad77;hp=d58ba1157d326cf51871faf52ac9d6a9f092e4c9;hpb=20af64b688c9232a99c47facfd1cf56fe680f6e5;p=lilypond.git diff --git a/Documentation/user/basic-notation.itely b/Documentation/user/basic-notation.itely index d58ba1157d..aeeb5ed9d4 100644 --- a/Documentation/user/basic-notation.itely +++ b/Documentation/user/basic-notation.itely @@ -5,137 +5,136 @@ @c M-x texinfo-all-menus-update @c to automatically fill in these menus before saving changes - @node Basic notation @chapter Basic notation -This chapter explains how to use all basic notation features. +This chapter explains how to use basic notation features. @menu -* Note entry:: -* Alternate music entry:: +* Pitches:: +* Rhythms:: +* Multiple notes at once:: * Staff notation:: * Connecting notes:: * Expressive marks:: -* Polyphony:: * Repeats:: @end menu -@node Note entry -@section Note entry -@cindex Note entry +@node Pitches +@section Pitches -This section is about basic notation elements like notes, rests, and -related constructs, such as stems, tuplets and ties. +This section discusses how to specify the pitch of notes. @menu -* Notes:: -* Pitches:: +* Normal pitches:: +* Accidentals:: * Cautionary accidentals:: * Micro tones:: -* Chords:: +* Notes names in other languages:: +* Relative octaves:: +* Octave check:: +* Transpose:: * Rests:: * Skips:: -* Durations:: -* Augmentation dots:: -* Tuplets:: -* Scaling durations:: -* Stems:: @end menu -@node Notes -@subsection Notes +@node Normal pitches +@subsection Normal pitches -@cindex Note specification -@cindex entering notes +@cindex Pitch names +@cindex pitches -A note is printed by specifying its pitch and then its duration, +A pitch name is specified using lowercase letters @code{a} through @code{g}. +An ascending C-major scale is engraved with -@lilypond[quote,verbatim,ragged-right,fragment] -cis'4 d'8 e'16 c'16 +@lilypond[quote,fragment,verbatim,ragged-right] +\clef bass +c d e f g a b c' @end lilypond -@seealso - -This manual: @ref{Pitches}, @ref{Durations} - - -@node Pitches -@subsection Pitches - -@cindex Pitch names -@cindex pitches - -The most common syntax for pitch entry is used for standard notes and -@code{\chordmode} modes. In these modes, pitches may be designated by -names. The notes are specified by the letters @code{a} through -@code{g}. The octave is formed with notes ranging from @code{c} -to @code{b}. The pitch @code{c} is an octave below middle C and the -letters span the octave above that C +The note name @code{c} is engraved one octave below middle C. @lilypond[quote,fragment,verbatim,ragged-right] +\clef treble +c1 \clef bass -a,4 b, c d e f g a b c' d' e' \clef treble f' g' a' b' c'' +c1 @end lilypond -@cindex @code{'} -@cindex @code{,} +@funindex ' +@funindex , The optional octave specification takes the form of a series of single quote (`@code{'}') characters or a series of comma (`@code{,}') characters. Each @code{'} raises the pitch by one -octave; each @code{,} lowers the pitch by an octave +octave; each @code{,} lowers the pitch by an octave. @lilypond[quote,ragged-right,fragment,verbatim] -c' c'' e' g d'' d' +\clef treble +c' c'' e' g d'' d' d c +\clef bass +c, c,, e, g d,, d, d c @end lilypond +An alternate method may be used to declare which octave to +engrave a pitch; this method does not require as many +octave specifications (@code{'} and @code{,}). See +@ref{Relative octaves}. + + +@node Accidentals +@subsection Accidentals + @cindex note names, Dutch +@cindex note names, default A sharp is formed by adding @code{-is} to the end of a pitch name and a flat is formed by adding @code{-es}. Double sharps and double flats -are obtained by adding @code{-isis} or @code{-eses}. These -names are the Dutch note names. In Dutch, @code{aes} is contracted to +are obtained by adding @code{-isis} or @code{-eses} to a note name. + +@lilypond[quote,ragged-right,fragment,verbatim,relative=2] +a2 ais a aes +a2 aisis a aeses +@end lilypond + +@noindent +These are the Dutch note names. In Dutch, @code{aes} is contracted to @code{as}, but both forms are accepted. Similarly, both @code{es} and @code{ees} are accepted @lilypond[fragment,quote,ragged-right,verbatim,relative=2] -ceses4 -ces -c -cis -cisis +a2 as e es @end lilypond -There are predefined sets of note names for various other languages. -To use them, include the language specific init file. For -example: @code{\include "english.ly"}. The available language files -and the note names they define are +A natural will cancel the effect of an accidental or key signature. +However, naturals are not encoded into the note name syntax with a +suffix; a natural pitch is shown as a simple note name -@anchor{note name} -@anchor{note names} -@example - Note Names sharp flat -nederlands.ly c d e f g a bes b -is -es -english.ly c d e f g a bf b -s/-sharp -f/-flat - -x (double) -deutsch.ly c d e f g a b h -is -es -norsk.ly c d e f g a b h -iss/-is -ess/-es -svenska.ly c d e f g a b h -iss -ess -italiano.ly do re mi fa sol la sib si -d -b -catalan.ly do re mi fa sol la sib si -d/-s -b -espanol.ly do re mi fa sol la sib si -s -b -@end example +@lilypond[quote,ragged-right,fragment,verbatim,relative=2] +a4 aes a2 +@end lilypond + +The input @code{d e f} is interpreted as ``print a D-natural, +E-natural, and an F-natural,'' regardless of the key +signature. For more information about the distinction between +musical content and the presentation of that content, see +@ref{More about pitches}. + +@lilypond[fragment,quote,ragged-right,verbatim,relative] +\key d \major +d e f g +d e fis g +@end lilypond @commonprop -In accordance with standard typsetting rules, a natural sign is printed +In accordance with standard typesetting rules, a natural sign is printed before a sharp or flat if a previous accidental needs to be -cancelled. To change this behaviour, use +cancelled. To change this behavior, use @code{\set Staff.extraNatural = ##f} @lilypond[fragment,quote,ragged-right,verbatim,relative=2] @@ -144,30 +143,24 @@ ceses4 ces cis c ceses4 ces cis c @end lilypond -@cindex Musica ficta - -Suggested accidentals (used in notating musica ficta) may -be written with @code{suggestAccidentals} - -@lilypond[fragment,quote,ragged-right,verbatim,relative=2] -\set suggestAccidentals = ##t -ais4 bis -@end lilypond - @seealso -Program reference: @internalsref{LedgerLineSpanner}, @internalsref{NoteHead}. +Program reference: @internalsref{LedgerLineSpanner}, +@internalsref{NoteHead}. @node Cautionary accidentals -@subsection Cautionary accidentals +@subsection Cautionary accidentals +@cindex accidental, reminder +@cindex accidental, cautionary +@cindex accidental, parenthesized @cindex reminder accidental -@cindex @code{?} +@funindex ? @cindex cautionary accidental @cindex parenthesized accidental -@cindex @code{!} +@funindex ! Normally accidentals are printed automatically, but you may also print them manually. A reminder accidental @@ -185,8 +178,7 @@ cis cis cis! cis? c c? c! c @seealso The automatic production of accidentals can be tuned in many -ways. For more information, refer to @ref{Automatic accidentals}. - +ways. For more information, see @ref{Automatic accidentals}. @node Micro tones @@ -208,140 +200,397 @@ Micro tones are also exported to the MIDI file. @refbugs -There are no generally accepted standards for denoting three quarter -flats, so LilyPond's symbol does not conform to any standard. +There are no generally accepted standards for denoting +three-quarter flats, so LilyPond's symbol does not conform to any +standard. -@node Chords -@subsection Chords +@node Notes names in other languages +@subsection Notes names in other languages -@cindex Chords +There are predefined sets of note names for various other languages. +To use them, include the language specific init file. For +example, add @code{\include "english.ly"} to the top of the input +file. The available language files +and the note names they define are -A chord is formed by a enclosing a set of pitches in @code{<} and -@code{>}. A chord may be followed by a duration, and a set of -articulations, just like simple notes +@c what about micro-tunes, double-sharps, and double-flats? add +@c more columns to the table? +@c Oh, and should this be made into a multitable? +@cindex note names, other languages +@example + Note Names sharp flat +nederlands.ly c d e f g a bes b -is -es +english.ly c d e f g a bf b -s/-sharp -f/-flat + -x (double) +deutsch.ly c d e f g a b h -is -es +norsk.ly c d e f g a b h -iss/-is -ess/-es +svenska.ly c d e f g a b h -iss -ess +italiano.ly do re mi fa sol la sib si -d -b +catalan.ly do re mi fa sol la sib si -d/-s -b +espanol.ly do re mi fa sol la sib si -s -b +@end example -@lilypond[verbatim,ragged-right,fragment,quote,relative=1] -4 8 -@end lilypond -For more information about chords, see @ref{Chord names}. +@node Relative octaves +@subsection Relative octaves +@cindex Relative +@cindex Relative octave specification +@funindex \relative -@node Rests -@subsection Rests -@cindex Rests +Octaves are specified by adding @code{'} and @code{,} to pitch names. +When you copy existing music, it is easy to accidentally put a pitch +in the wrong octave and hard to find such an error. The relative +octave mode prevents these errors by making the mistakes much +larger: a single error puts the rest of the piece off by one octave + +@example +\relative @var{startpitch} @var{musicexpr} +@end example +@noindent +or -@cindex @code{\rest} -@cindex @code{r} +@example +\relative @var{musicexpr} +@end example -Rests are entered like notes with the note name @code{r} +@noindent +@code{c'} is used as the default if no starting pitch is defined. -@lilypond[fragment,quote,ragged-right,verbatim] -r1 r2 r4 r8 +The octave of notes that appear in @var{musicexpr} are calculated as +follows: if no octave changing marks are used, the basic interval +between this and the last note is always taken to be a fourth or +less. This distance is determined without regarding alterations; a +@code{fisis} following a @code{ceses} will be put above the +@code{ceses}. In other words, a doubly-augmented fourth is considered +a smaller interval than a diminished fifth, even though the +doubly-augmented fourth spans seven semitones while the diminished +fifth only spans six semitones. + +The octave changing marks @code{'} and @code{,} can be added to raise +or lower the pitch by an extra octave. Upon entering relative mode, +an absolute starting pitch can be specified that will act as the +predecessor of the first note of @var{musicexpr}. If no starting pitch +is specified, then middle C is used as a start. + +Here is the relative mode shown in action +@lilypond[quote,fragment,ragged-right,verbatim] +\relative c'' { + b c d c b c bes a +} @end lilypond -Whole bar rests, centered in middle of the bar, -must be done with multi-measure rests. They can be used for a -single bar as well as many bars, and are discussed in -@ref{Multi measure rests}. +Octave changing marks are used for intervals greater than a fourth +@lilypond[quote,ragged-right,fragment,verbatim] +\relative c'' { + c g c f, c' a, e'' +} +@end lilypond -A rest's vertical position may be explicitly specified by entering a -note with the @code{\rest} keyword appended, the rest will be placed at -the note's place. This makes manual formatting in polyphonic music -easier. Automatic rest collision formatting will leave these rests -alone +If the preceding item is a chord, the first note of the chord is used +to determine the first note of the next chord -@lilypond[fragment,quote,ragged-right,verbatim] -a'4\rest d'4\rest +@lilypond[quote,ragged-right,fragment,verbatim] +\relative c' { + c + + +} @end lilypond -@seealso +The pitch after @code{\relative} contains a note name. -Program reference: @internalsref{Rest}. +The relative conversion will not affect @code{\transpose}, +@code{\chordmode} or @code{\relative} sections in its argument. To use +relative within transposed music, an additional @code{\relative} must +be placed inside @code{\transpose}. -@node Skips -@subsection Skips +@node Octave check +@subsection Octave check -@cindex Skip -@cindex Invisible rest -@cindex Space note -@cindex @code{\skip} -@cindex @code{s} +@cindex Octave check -An invisible rest (also called a `skip') can be entered like a note -with note name `@code{s}' or with @code{\skip @var{duration}} +Octave checks make octave errors easier to correct: a note may be +followed by @code{=}@var{quotes} which indicates what its absolute +octave should be. In the following example, -@lilypond[fragment,quote,ragged-right,verbatim,relative=2] -a4 a4 s4 a4 \skip 1 a4 -@end lilypond +@example +\relative c'' @{ c='' b=' d,='' @} +@end example -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 +@noindent +the @code{d} will generate a warning, because a @code{d''} is expected +(because @code{b'} to @code{d''} is only a third), but a @code{d'} is +found. In the output, the octave is corrected to be a @code{d''} and +the next note is calculated relative to @code{d''} instead of @code{d'}. -@lilypond[quote,ragged-right,verbatim] -<< - \relative { a'2 a2 } - \new Lyrics \lyricmode { \skip 2 bla2 } ->> -@end lilypond +There is also an octave check that produces no visible output. The syntax -The skip command is merely an empty musical placeholder. It does not -produce any output, not even transparent output. +@example +\octave @var{pitch} +@end example -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. +This checks that @var{pitch} (without quotes) yields @var{pitch} (with +quotes) in @code{\relative} mode compared to the note given in the +@code{\relative} command. If not, a warning is printed, and the +octave is corrected. The @var{pitch} is not printed as a note. -@lilypond[quote,ragged-right,verbatim] -{ s4 } -@end lilypond +In the example below, the first check passes without incident, since +the @code{e} (in @code{relative} mode) is within a fifth of +@code{a'}. However, +the second check produces a warning, since the @code{e} is not within +a fifth of @code{b'}. The warning message is printed, and the octave +is adjusted so that the following notes are in the correct octave +once again. -The fragment @code{@{ \skip 4 @} } would produce an empty page. +@example +\relative c' @{ + e + \octave a' + \octave b' +@} +@end example -@seealso -Program reference: @internalsref{SkipMusic}. +The octave of a note following an octave check is determined with +respect to the note preceding it. In the next fragment, the last note +is an @code{a'}, above middle C. That means that the @code{\octave} +check passes successfully, so the check could be deleted without changing +the output of the piece. +@lilypond[quote,ragged-right,verbatim,fragment] +\relative c' { + e + \octave b + a +} +@end lilypond -@node Durations -@subsection Durations -@cindex duration -@cindex @code{\longa} -@cindex @code{\breve} -@cindex @code{\maxima} +@node Transpose +@subsection Transpose -In Note, Chord, and Lyrics mode, 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 variables @code{\longa} and -@code{\breve} +@cindex Transpose +@cindex Transposition of pitches +@funindex \transpose +A music expression can be transposed with @code{\transpose}. The +syntax is @example -c'\breve -c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64 -r\longa r\breve -r1 r2 r4 r8 r16 r32 r64 r64 +\transpose @var{from} @var{to} @var{musicexpr} @end example -@lilypond[quote] -\score { - \relative c'' { - a\breve*1/2 \autoBeamOff - a1 a2 a4 a8 a16 a32 a64 a64 - \bar "empty" - \break - r\longa*1/4 r\breve *1/2 - r1 r2 r4 r8 r16 r32 r64 r64 +This means that @var{musicexpr} is transposed by the interval between +the pitches @var{from} and @var{to}: any note with pitch @code{from} +is changed to @code{to}. + +For example, consider a piece written in the key of D-major. If +this piece is a little too low for its performer, it can be +transposed up to E-major with +@example +\transpose d e @dots{} +@end example + +Consider a part written for violin (a C instrument). If +this part is to be played on the A clarinet (for which an +A is notated as a C, and which sounds a minor third lower +than notated), the following +transposition will produce the appropriate part + +@example +\transpose a c @dots{} +@end example + +@code{\transpose} distinguishes between enharmonic pitches: both +@code{\transpose c cis} or @code{\transpose c des} will transpose up +half a tone. The first version will print sharps and the second +version will print flats + +@lilypond[quote,ragged-right,verbatim] +mus = { \key d \major cis d fis g } +\new Staff { + \clef "F" \mus + \clef "G" + \transpose c g' \mus + \transpose c f' \mus +} +@end lilypond + +@code{\transpose} may also be used to input written notes for a +transposing instrument. Pitches are normally entered into LilyPond +in C (or ``concert pitch''), but they may be entered in another +key. For example, when entering music for a B-flat trumpet which +begins on concert D, one would write + +@example +\transpose c bes @{ e4 @dots{} @} +@end example + +To print this music in B-flat again (i.e., producing a trumpet part, +instead of a concert pitch conductor's score) you would wrap the +existing music with another @code{transpose} + +@example +\transpose bes c @{ \transpose c bes @{ e4 @dots{} @} @} +@end example + + +@seealso + +Program reference: @internalsref{TransposedMusic}. + +Example: @inputfileref{input/@/test,smart@/-transpose@/.ly}. + + +@refbugs + +If you want to use both @code{\transpose} and @code{\relative}, +you must put @code{\transpose} outside of @code{\relative}, since +@code{\relative} will have no effect on music that appears inside a +@code{\transpose}. + + +@node Rests +@subsection Rests +@cindex Rests + +@funindex \rest +@funindex r + +Rests are entered like notes with the note name @code{r} + +@lilypond[fragment,quote,ragged-right,verbatim] +r1 r2 r4 r8 +@end lilypond + +Whole bar rests, centered in middle of the bar, +must be done with multi-measure rests. They can be used for a +single bar as well as many bars, and are discussed in +@ref{Multi 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, + +@lilypond[fragment,quote,ragged-right,verbatim] +a'4\rest d'4\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}. + + +@node Skips +@subsection Skips + +@cindex Skip +@cindex Invisible rest +@cindex Space note +@funindex \skip +@funindex s + +An invisible rest (also called a `skip') can be entered like a 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 + +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 + +@lilypond[quote,ragged-right,verbatim] +<< + \relative { a'2 a2 } + \new Lyrics \lyricmode { \skip 2 bla2 } +>> +@end lilypond + +The skip command is merely an empty musical placeholder. It does not +produce any output, not even transparent output. + +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] +{ s4 } +@end lilypond + +The fragment @code{@{ \skip 4 @} } would produce an empty page. + +@seealso + +Program reference: @internalsref{SkipMusic}. + + + +@node Rhythms +@section Rhythms + +This section discusses rhythms, durations, and bars. + +@menu +* Durations:: +* Augmentation dots:: +* Tuplets:: +* Scaling durations:: +* Bar check:: +* Barnumber check:: +* Automatic note splitting:: +@end menu + + +@node Durations +@subsection Durations + +@cindex duration +@funindex \longa +@funindex \breve +@funindex \maxima + +In Note, Chord, and Lyrics mode, 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 + +@example +c'\breve +c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64 +r\longa r\breve +r1 r2 r4 r8 r16 r32 r64 r64 +@end example + +@lilypond[quote] +\score { +\relative c'' { + a\breve*1/2 \autoBeamOff + a1 a2 a4 a8 a16 a32 a64 a64 + \bar "empty" + \break + r\longa*1/4 r\breve *1/2 + r1 r2 r4 r8 r16 r32 r64 r64 } \layout { ragged-right = ##t + indent=0\mm + \context { + \Score + \remove "Bar_number_engraver" + } \context { \Staff \remove "Clef_engraver" @@ -365,9 +614,9 @@ duration. The default for the first note is a quarter note. @node Augmentation dots @subsection Augmentation dots -@cindex @code{.} +@funindex . -To obtain dotted note lenghts, simply add a dot (`@code{.}') to +To obtain dotted note lengths, simply add a dot (`@code{.}') to the number. Double-dotted notes are produced in a similar way. @lilypond[quote,ragged-right,fragment,verbatim] @@ -380,11 +629,11 @@ 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 -@cindex @code{\dotsUp} +@funindex \dotsUp @code{\dotsUp}, -@cindex @code{\dotsDown} +@funindex \dotsDown @code{\dotsDown}, -@cindex @code{\dotsNeutral} +@funindex \dotsNeutral @code{\dotsNeutral}. @seealso @@ -397,7 +646,7 @@ Program reference: @internalsref{Dots}, and @internalsref{DotColumn}. @cindex tuplets @cindex triplets -@cindex @code{\times} +@funindex \times Tuplets are made out of a music expression by multiplying all durations with a fraction @@ -420,26 +669,26 @@ g'4 \times 2/3 {c'4 c' c'} d'4 d'4 Tuplets may be nested, for example, @lilypond[fragment,ragged-right,verbatim,relative=2] -\set tupletNumberFormatFunction = #fraction-tuplet-formatter +\override TupletNumber #'text = #tuplet-number::calc-fraction-text \times 4/6 { - a4 a + a4 a \times 3/5 { a a a a a } } @end lilypond @refcommands -@cindex @code{\tupletUp} +@funindex \tupletUp @code{\tupletUp}, -@cindex @code{\tupletDown} +@funindex \tupletDown @code{\tupletDown}, -@cindex @code{\tupletNeutral} +@funindex \tupletNeutral @code{\tupletNeutral}. @commonprop -@cindex @code{tupletNumberFormatFunction} +@funindex tupletNumberFormatFunction @cindex tuplet formatting The property @code{tupletSpannerDuration} specifies how long each @@ -457,11 +706,10 @@ used once For more information about @code{make-moment}, see @ref{Time administration}. -The format of the number is determined by the property -@code{tupletNumberFormatFunction}. The default prints only the -denominator, but if it is set to the Scheme function -@code{fraction-tuplet-formatter}, @var{num}:@var{den} will be printed -instead. +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. To avoid printing tuplet numbers, use @@ -471,6 +719,26 @@ To avoid printing tuplet numbers, use \times 2/3 { c8 c c } \times 2/3 { c8 c c } @end lilypond +Tuplet brackets can be made to run to prefatory matter or +the next note + +@lilypond[ragged-right] +\new RhythmicStaff { + \set tupletFullLength = ##t + \time 4/4 + \times 4/5 { + c4 c1 + } + \set tupletFullLengthNote = ##t + \time 2/4 + \times 2/3 { + c4 c c + } + \time 3/4 + c4 +} +@end lilypond + @seealso @@ -503,436 +771,454 @@ b16*4 c4 This manual: @ref{Tuplets} -@node Stems -@subsection Stems +@node Bar check +@subsection Bar check -Whenever a note is found, a @internalsref{Stem} object is created -automatically. For whole notes and rests, they are also created but -made invisible. +@cindex Bar check +@funindex barCheckSynchronize +@funindex | -@refcommands +Bar checks help detect errors in the durations. A bar check is +entered using the bar symbol, `@code{|}'. Whenever it is encountered +during interpretation, it should fall on a measure boundary. If it +does not, a warning is printed. In the next example, the second bar +check will signal an error +@example +\time 3/4 c2 e4 | g2 | +@end example -@cindex @code{\stemUp} -@code{\stemUp}, -@cindex @code{\stemDown} -@code{\stemDown}, -@cindex @code{\stemNeutral} -@code{\stemNeutral}. +Bar checks can also be used in lyrics, for example +@example +\lyricmode @{ + \time 2/4 + Twin -- kle | Twin -- kle +@} +@end example -@commonprop +Failed bar checks are caused by entering incorrect +durations. Incorrect durations often completely garble up the score, +especially if the score is polyphonic, so a good place to start correcting +input is by scanning for failed bar checks and incorrect durations. -To change the direction of stems in the middle of the staff, use +@funindex | +@funindex pipeSymbol -@lilypond[quote,ragged-right,fragment,relative=2,verbatim] -a4 b c b -\override Stem #'neutral-direction = #up -a4 b c b -\override Stem #'neutral-direction = #down -a4 b c b +It is also possible to redefine the meaning of @code{|}. This is done +by assigning a music expression to @code{pipeSymbol}, + +@lilypond[quote,ragged-right,verbatim] +pipeSymbol = \bar "||" + +{ c'2 c' | c'2 c' } @end lilypond -@node Alternate music entry -@section Alternate music entry -@cindex Music entry +@node Barnumber check +@subsection Barnumber check -This section deals with tricks and features of the input language that -were added solely to help entering music and finding and correcting -mistakes. There are also external tools that make debugging easier. -See @ref{Point and click} for more information. +When copying large pieces of music, it can be helpful to check that +the LilyPond bar number corresponds to the original that you are +entering from. This can be checked with @code{\barNumberCheck}, for +example, -It is also possible to enter and edit music using other programs, such as -GUI interfaces or MIDI sequencers. Refer to the LilyPond -website for more information. +@verbatim +\barNumberCheck #123 +@end verbatim -@menu -* Relative octaves:: -* Octave check:: -* Transpose:: -* Bar check:: -* Barnumber check:: -* Skipping corrected music:: -* Automatic note splitting:: -* Writing music in parallel:: -@end menu +@noindent +will print a warning if the @code{currentBarNumber} is not 123 when it +is processed. -@node Relative octaves -@subsection Relative octaves - -@cindex Relative -@cindex Relative octave specification -@cindex @code{\relative} - -Octaves are specified by adding @code{'} and @code{,} to pitch names. -When you copy existing music, it is easy to accidentally put a pitch -in the wrong octave and hard to find such an error. The relative -octave mode prevents these errors by making the mistakes much -larger: a single error puts the rest of the piece off by one octave - -@example -\relative @var{startpitch} @var{musicexpr} -@end example - -@noindent -or - -@example -\relative @var{musicexpr} -@end example - -The octave of notes that appear in @var{musicexpr} are calculated as -follows: if no octave changing marks are used, the basic interval -between this and the last note is always taken to be a fourth or -less. This distance is determined without regarding alterations; a -@code{fisis} following a @code{ceses} will be put above the -@code{ceses}. In other words, a doubly-augmented fourth is considered -a smaller interval than a diminished fifth, even though the -doubly-augmented fourth spans seven semitones while the diminished -fifth only spans six semitones. - -The octave changing marks @code{'} and @code{,} can be added to raise -or lower the pitch by an extra octave. Upon entering relative mode, -an absolute starting pitch can be specified that will act as the -predecessor of the first note of @var{musicexpr}. If no starting pitch -is specified, then middle C is used as a start. +@node Automatic note splitting +@subsection Automatic note splitting -Here is the relative mode shown in action -@lilypond[quote,fragment,ragged-right,verbatim] -\relative c'' { - b c d c b c bes a -} -@end lilypond +Long notes 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. -Octave changing marks are used for intervals greater than a fourth -@lilypond[quote,ragged-right,fragment,verbatim] -\relative c'' { - c g c f, c' a, e'' +@lilypond[quote,fragment,verbatim,relative=1,line-width=12\cm] +\new Voice \with { + \remove "Note_heads_engraver" + \consists "Completion_heads_engraver" +} { + c2. c8 d4 e f g a b c8 c2 b4 a g16 f4 e d c8. c2 } @end lilypond -If the preceding item is a chord, the first note of the chord is used -to determine the first note of the next chord +This engraver splits all running notes at the bar line, and inserts +ties. One of its uses is to debug complex scores: if the measures are +not entirely filled, then the ties exactly show how much each measure +is off. -@lilypond[quote,ragged-right,fragment,verbatim] -\relative c' { - c - - -} -@end lilypond +If you want to allow line breaking on the bar lines where +@internalsref{Completion_heads_engraver} splits notes, you must +also remove @internalsref{Forbid_line_breaks_engraver}. -The pitch after the @code{\relative} contains a note name. -The relative conversion will not affect @code{\transpose}, -@code{\chordmode} or @code{\relative} sections in its argument. To use -relative within transposed music, an additional @code{\relative} must -be placed inside @code{\transpose}. +@refbugs +Not all durations (especially those containing tuplets) can be +represented exactly with normal notes and dots, but the engraver will +not insert tuplets. -@node Octave check -@subsection Octave check +@code{Completion_heads_engraver} only affects notes; it does not split +rests. -@cindex Octave check -Octave checks make octave errors easier to correct: a note may be -followed by @code{=}@var{quotes} which indicates what its absolute -octave should be. In the following example, +@seealso -@example -\relative c'' @{ c='' b=' d,='' @} -@end example +Examples: @inputfileref{input/@/regression,completion@/-heads@/.ly}. @noindent -the @code{d} will generate a warning, because a @code{d''} is expected -(because @code{b'} to @code{d''} is only a third), but a @code{d'} is -found. In the output, the octave is corrected to be a @code{d''} and -the next note is calculated relative to @code{d''} instead of @code{d'}. -There is also a syntax that is separate from the notes. The syntax +Program reference: @internalsref{Completion_heads_engraver}. -@example -\octave @var{pitch} -@end example -This checks that @var{pitch} (without quotes) yields @var{pitch} (with -quotes) in \relative mode. If not, a warning is printed, and the -octave is corrected. +@node Multiple notes at once +@section Multiple notes at once -In the example below, the first check passes without incident, since -the @code{e} (in relative mode) is within a fifth of @code{a'}. However, -the second check produces a warning, since the @code{e} is not within -a fifth of @code{b'}. The warning message is printed, and the octave -is adjusted so that the following notes are in the correct octave -once again. +Polyphony in music refers to having more than one voice occurring in +a piece of music. Polyphony in LilyPond refers to having more than +one voice on the same staff. -@example -\relative c' @{ - e - \octave a' - \octave b' -@} -@end example +@menu +* Chords:: +* Stems:: +* Basic polyphony:: +* Explicitly instantiating voices:: +* Collision Resolution:: +@end menu -The octave of a note following an octave check is determined with -respect to the note preceding it. In the next fragment, the last note -is an @code{a'}, above middle C. That means that the @code{\octave} -check passes successfully, so the check could be deleted without changing -the output of the piece. +@node Chords +@subsection Chords -@lilypond[quote,ragged-right,verbatim,fragment] -\relative c' { - e - \octave b - a -} +@cindex Chords + +A chord is formed by a enclosing a set of pitches between @code{<} +and @code{>}. A chord may be followed by a duration, and a set of +articulations, just like simple notes + +@lilypond[verbatim,ragged-right,fragment,quote,relative=1] +4 8 @end lilypond +For more information about chords, see @ref{Chord names}. -@node Transpose -@subsection Transpose -@cindex Transpose -@cindex transposition of pitches -@cindex @code{\transpose} +@node Stems +@subsection Stems -A music expression can be transposed with @code{\transpose}. The -syntax is -@example -\transpose @var{from} @var{to} @var{musicexpr} -@end example +Whenever a note is found, a @internalsref{Stem} object is created +automatically. For whole notes and rests, they are also created but +made invisible. -This means that @var{musicexpr} is transposed by the interval between -the pitches @var{from} and @var{to}: any note with pitch @code{from} -is changed to @code{to}. +@refcommands -For example, consider a piece written in the key of D-major. If -this piece is a little too low for its performer, it can be -transposed up to E-major with -@example -\transpose d e @dots{} -@end example +@funindex \stemUp +@code{\stemUp}, +@funindex \stemDown +@code{\stemDown}, +@funindex \stemNeutral +@code{\stemNeutral}. -Consider a part written for violin (a C instrument). If -this part is to be played on the A clarinet (for which an -A is notated as a C, and which sounds a minor third lower -than notated), the following -transposition will produce the appropriate part -@example -\transpose a c @dots{} -@end example +@commonprop -@code{\transpose} distinguishes between enharmonic pitches: both -@code{\transpose c cis} or @code{\transpose c des} will transpose up -half a tone. The first version will print sharps and the second -version will print flats +To change the direction of stems in the middle of the staff, use -@lilypond[quote,ragged-right,verbatim] -mus = { \key d \major cis d fis g } -\new Staff { - \clef "F" \mus - \clef "G" - \transpose c g' \mus - \transpose c f' \mus -} +@lilypond[quote,ragged-right,fragment,relative=2,verbatim] +a4 b c b +\override Stem #'neutral-direction = #up +a4 b c b +\override Stem #'neutral-direction = #down +a4 b c b @end lilypond -@code{\transpose} may also be used to input written notes for a -transposing instrument. Pitches are normally entered into LilyPond -in C (or ``concert pitch''), but they may be entered in another -key. For example, when entering music for a B-flat trumpet which -begins on concert D, one would write -@example -\transpose c bes @{ e4 @dots{} @} -@end example +@node Basic polyphony +@subsection Basic polyphony -To print this music in B-flat again (ie producing a trumpet part, -instead of a concert pitch conductor's score) you would wrap the -existing music with another @code{transpose} +@cindex polyphony -@example -\transpose bes c @{ \transpose c bes @{ e4 @dots{} @} @} -@end example +The easiest way to enter fragments with more than one voice on a staff +is to enter each voice as a sequence (with @code{@{...@}}), and combine +them simultaneously, separating the voices with @code{\\} +@funindex \\ -@seealso +@lilypond[quote,verbatim,fragment] +\new Staff \relative c' { + c16 d e f + << + { g4 f e | d2 e2 } \\ + { r8 e4 d c8 ~ | c b16 a b8 g ~ g2 } \\ + { s2. | s4 b4 c2 } + >> +} +@end lilypond -Program reference: @internalsref{TransposedMusic}. +The separator causes @internalsref{Voice} contexts@footnote{Polyphonic +voices are sometimes called ``layers'' in other notation packages} +@cindex layers +to be instantiated. They bear the names @code{"1"}, @code{"2"}, etc. In +each of these contexts, vertical direction of slurs, stems, etc., is set +appropriately. +These voices are all separate from the voice that contains the notes just +outside the @code{<< \\ >>} construct. This should be noted when making +changes at the voice level. This also means that slurs and ties cannot go +into or out of a @code{<< \\ >>} construct. Conversely, parallel voices +from separate @code{<< \\ >>} constructs on the same staff are the the +same voice. Here is the same example, with different noteheads for each +voice. Note that the change to the note-head style in the main voice does +not affect +the inside of the @code{<< \\ >>} constructs. Also, the change to the +second +voice in the first @code{<< \\ >>} construct is effective in the second +@code{<< \\ >>}, and the voice is tied across the two constructs. -@refbugs +@cindex note heads, styles -If you want to use both @code{\transpose} and @code{\relative}, -you must put @code{\transpose} outside of @code{\relative}, since -@code{\relative} will have no effect music that appears inside a -@code{\transpose}. +@lilypond[quote,verbatim,fragment] +\new Staff \relative c' { + \override NoteHead #'style = #'cross + c16 d e f + << + { g4 f e } \\ + { \override NoteHead #'style = #'triangle + r8 e4 d c8 ~ } + >> | + << + { d2 e2 } \\ + { c8 b16 a b8 g ~ g2 } \\ + { \override NoteHead #'style = #'slash s4 b4 c2 } + >> +} +@end lilypond +Polyphony does not change the relationship of notes within a +@code{\relative @{ @}} block. Each note is calculated relative +to the note immediately preceding it. -@node Bar check -@subsection Bar check +@example +\relative @{ noteA << noteB \\ noteC >> noteD @} +@end example -@cindex Bar check -@cindex @code{barCheckSynchronize} -@cindex @code{|} +@code{noteC} is relative to @code{noteB}, not @code{noteA}; +@code{noteD} is relative to @code{noteC}, not @code{noteB} or +@code{noteA}. -Bar checks help detect errors in the durations. A bar check is -entered using the bar symbol, `@code{|}'. Whenever it is encountered -during interpretation, it should fall on a measure boundary. If it -does not, a warning is printed. In the next example, the second bar -check will signal an error +@node Explicitly instantiating voices +@subsection Explicitly instantiating voices + +@internalsref{Voice} contexts can also be instantiated manually +inside a @code{<< >>} block to create polyphonic music, using +@code{\voiceOne}, up to @code{\voiceFour} to assign stem directions +and a horizontal shift for each part. + +Specifically, @example -\time 3/4 c2 e4 | g2 | +<< \upper \\ \lower >> @end example -Bar checks can also be used in lyrics, for example +@noindent +is equivalent to @example -\lyricmode @{ - \time 2/4 - Twin -- kle | Twin -- kle -@} +<< + \new Voice = "1" @{ \voiceOne \upper @} + \new Voice = "2" @{ \voiceTwo \lower @} +>> @end example -Failed bar checks are caused by entering incorrect -durations. Incorrect durations often completely garble up the score, -especially if the score is polyphonic, so a good place to start correcting -input is by scanning for failed bar checks and incorrect durations. +The @code{\voiceXXX} commands set the direction of stems, slurs, ties, +articulations, text annotations, augmentation dots of dotted +notes, and fingerings. @code{\voiceOne} and @code{\voiceThree} make +these objects point upwards, while @code{\voiceTwo} and @code{\voiceFour} +make them point downwards. +The command @code{\oneVoice} will revert back to the normal setting. -@cindex @code{|} -@cindex @code{pipeSymbol} +An expression that appears directly inside a @code{<< >>} belongs to +the main voice. This is useful when extra voices appear while the main +voice is playing. Here is a more correct rendition of the example from +the previous section. The crossed noteheads demonstrate that the main +melody is now in a single voice context. + +@lilypond[quote,ragged-right,verbatim] +\new Staff \relative c' { + \override NoteHead #'style = #'cross + c16 d e f + \voiceOne + << + { g4 f e | d2 e2 } + \new Voice="1" { \voiceTwo + r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 + \oneVoice + } + \new Voice { \voiceThree + s2. | s4 b4 c2 + \oneVoice + } + >> + \oneVoice +} +@end lilypond + +The correct definition of the voices allows the melody to be slurred. +@lilypond[quote,ragged-right,verbatim] +\new Staff \relative c' { + c16^( d e f + \voiceOne + << + { g4 f e | d2 e2) } + \context Voice="1" { \voiceTwo + r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 + \oneVoice + } + \new Voice { \voiceThree + s2. s4 b4 c2 + \oneVoice + } + >> + \oneVoice +} +@end lilypond -It is also possible to redefine the meaning of @code{|}. This is done -by assigning a music expression to @code{pipeSymbol}, +Avoiding the @code{\\} separator also allows nesting polyphony +constructs, which in some case might be a more natural way to typeset +the music. @lilypond[quote,ragged-right,verbatim] -pipeSymbol = \bar "||" - -{ c'2 c' | c'2 c' } +\new Staff \relative c' { + c16^( d e f + \voiceOne + << + { g4 f e | d2 e2) } + \context Voice="1" { \voiceTwo + r8 e4 d c8 ~ | + << + {c8 b16 a b8 g ~ g2} + \new Voice { \voiceThree + s4 b4 c2 + \oneVoice + } + >> + \oneVoice + } + >> + \oneVoice +} @end lilypond -@node Barnumber check -@subsection Barnumber check - -When copying large pieces of music, it can be helpful to check that -the LilyPond bar number corresponds to the original that you are -entering from. This can be checked with @code{\barNumberCheck}, for -example, - -@verbatim -\barNumberCheck #123 -@end verbatim - -@noindent -will print a warning if the @code{currentBarNumber} is not 123 when it -is processed. - - -@node Skipping corrected music -@subsection Skipping corrected music - - -@cindex @code{skipTypesetting} -@cindex @code{showLastLength} +@node Collision Resolution +@subsection Collision Resolution -When entering or copying music, usually only the music near the end (where you -are adding notes) is interesting to view and correct. To speed up -this correction process, it is possible to skip typesetting of all but -the last few measures. This is achieved by putting +Normally, note heads with a different number of dots are not merged, but +when the object property @code{merge-differently-dotted} is set in +the @internalsref{NoteCollision} object, they are merged +@lilypond[quote,verbatim,fragment,ragged-right,relative=2] +\new Voice << { + g8 g8 + \override Staff.NoteCollision + #'merge-differently-dotted = ##t + g8 g8 +} \\ { g8.[ f16] g8.[ f16] } >> +@end lilypond -@verbatim -showLastLength = R1*5 -\score { ... } -@end verbatim +Similarly, you can merge half note heads with eighth notes, by setting +@code{merge-differently-headed} +@lilypond[quote,ragged-right,fragment,relative=2,verbatim] +\new Voice << { + c8 c4. + \override Staff.NoteCollision + #'merge-differently-headed = ##t +c8 c4. } \\ { c2 c2 } >> +@end lilypond @noindent -in your source file. This will render only the last 5 measures -(assuming 4/4 time signature) of every @code{\score} in the input -file. For longer pieces, rendering only a small part is often an order -of magnitude quicker than rendering it completely +@code{merge-differently-headed} and @code{merge-differently-dotted} +only apply to opposing stem directions (ie. Voice 1 & 2). -Skipping parts of a score can be controlled in a more fine-grained -fashing with the property @code{Score.skipTypesetting}. When it is -set, no typesetting is performed at all. +LilyPond also vertically shifts rests that are opposite of a stem, +for example -@lilypond[quote,fragment,ragged-right,verbatim] -\relative c'' { - c8 d - \set Score.skipTypesetting = ##t - e e e e e e e e - \set Score.skipTypesetting = ##f - c d b bes a g c2 } +@lilypond[quote,ragged-right,fragment,verbatim] +\new Voice << c''4 \\ r4 >> @end lilypond -In polyphonic music, @code{Score.skipTypesetting} will affect all -voices and staves, saving even more time. - - -@node Automatic note splitting -@subsection Automatic note splitting - -Long notes 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. - -@lilypond[quote,fragment,verbatim,relative=1,line-width=12\cm] -\new Voice \with { - \remove "Note_heads_engraver" - \consists "Completion_heads_engraver" -} { - c2. c8 d4 e f g a b c8 c2 b4 a g16 f4 e d c8. c2 -} -@end lilypond -This engraver splits all running notes at the bar line, and inserts -ties. One of its uses is to debug complex scores: if the measures are -not entirely filled, then the ties exactly show how much each measure -is off. +@refcommands +@funindex \oneVoice +@code{\oneVoice}, +@funindex \voiceOne +@code{\voiceOne}, +@funindex \voiceTwo +@code{\voiceTwo}, +@funindex \voiceThree +@code{\voiceThree}, +@funindex \voiceFour +@code{\voiceFour}. -@refbugs +@funindex \shiftOn +@code{\shiftOn}, +@funindex \shiftOnn +@code{\shiftOnn}, +@funindex \shiftOnnn +@code{\shiftOnnn}, +@funindex \shiftOff +@code{\shiftOff}: these commands specify in what chords of the current +voice should be shifted. The outer voices (normally: voice one and +two) have @code{\shiftOff}, while the inner voices (three and four) +have @code{\shiftOn}. @code{\shiftOnn} and @code{\shiftOnnn} define +further shift levels. -Not all durations (especially those containing tuplets) can be -represented exactly with normal notes and dots, but the engraver will -not insert tuplets. +When LilyPond cannot cope, the @code{force-hshift} +property of the @internalsref{NoteColumn} object and pitched rests can +be used to override typesetting decisions. -@code{Completion_heads_engraver} only affects notes; it does not split -rests. +@lilypond[quote,verbatim,ragged-right] +\relative << +{ + + +} \\ { + + \once \override NoteColumn #'force-hshift = #1.7 + +} >> +@end lilypond @seealso -Examples: @inputfileref{input/@/regression,completion@/-heads@/.ly}. +Program reference: the objects responsible for resolving collisions are +@internalsref{NoteCollision} and @internalsref{RestCollision}. -@noindent +Examples: +@inputfileref{input/@/regression,collision@/-dots@/.ly}, +@inputfileref{input/@/regression,collision@/-head-chords@/.ly}, +@inputfileref{input/@/regression,collision@/-heads@/.ly}, +@inputfileref{input/@/regression,collision@/-mesh@/.ly}, and +@inputfileref{input/@/regression,collisions@/.ly}. -Program reference: @internalsref{Completion_heads_engraver}. +@refbugs -@node Writing music in parallel -@subsection Writing music in parallel -@cindex Writing music in parallel -@cindex Interleaved music +When using @code{merge-differently-headed} with an upstem eighth or a +shorter note, and a downstem half note, the eighth note gets the wrong +offset. -Music for multiple parts can be interleaved +There is no support for clusters where the same note occurs with +different accidentals in the same chord. In this case, it is +recommended to use enharmonic transcription, or to use special cluster +notation (see @ref{Clusters}). -@lilypond[quote,fragment,verbatim,relative=1] -\parallelMusic #'(voiceA voiceB) { - r8 g'16[ c''] e''[ g' c'' e''] r8 g'16[ c''] e''[ g' c'' e''] | - c'2 c'2 | - r8 a'16[ d''] f''[ a' d'' f''] r8 a'16[ d''] f''[ a' d'' f''] | - c'2 c'2 | -} -\new StaffGroup << - \new Staff \new Voice \voiceA - \new Staff \new Voice \voiceB ->> -@end lilypond @node Staff notation @@ -952,13 +1238,14 @@ such as key signatures, clefs and time signatures. * Unmetered music:: * System start delimiters:: * Staff symbol:: +* Writing music in parallel:: @end menu @node Clef @subsection Clef -@cindex @code{\clef} +@funindex \clef The clef indicates which lines of the staff correspond to which pitches. The clef is set with the @code{\clef} command @@ -979,33 +1266,35 @@ pitches. The clef is set with the @code{\clef} command @cindex varbaritone clef @cindex subbass clef -Supported clefs finclude -@table @code -@item treble, violin, G, G2 - G clef on 2nd line -@item alto, C - C clef on 3rd line -@item tenor - C clef on 4th line. -@item bass, F - F clef on 4th line -@item french - G clef on 1st line, so-called French violin clef -@item soprano - C clef on 1st line -@item mezzosoprano - C clef on 2nd line -@item baritone - C clef on 5th line -@item varbaritone - F clef on 3rd line -@item subbass - F clef on 5th line -@item percussion - percussion clef -@item tab - tablature clef -@end table +Supported clefs include + +@multitable @columnfractions .33 .66 +@headitem Clef @tab Position +@item @code{treble}, violin, G, G2 @tab +G clef on 2nd line +@item @code{alto, C} @tab +C clef on 3rd line +@item @code{tenor} @tab +C clef on 4th line. +@item @code{bass, F} @tab +F clef on 4th line +@item @code{french} @tab +G clef on 1st line, so-called French violin clef +@item @code{soprano} @tab +C clef on 1st line +@item @code{mezzosoprano} @tab +C clef on 2nd line +@item @code{baritone} @tab +C clef on 5th line +@item @code{varbaritone} @tab +F clef on 3rd line +@item @code{subbass} @tab +F clef on 5th line +@item @code{percussion} @tab +percussion clef +@item @code{tab} @tab +tablature clef +@end multitable By adding @code{_8} or @code{^8} to the clef name, the clef is transposed one octave down or up, respectively, and @code{_15} and @@ -1021,7 +1310,8 @@ example, @commonprop -The command @code{\clef "treble_8"} is equivalent to setting @code{clefGlyph}, +The command @code{\clef "treble_8"} is equivalent to setting +@code{clefGlyph}, @code{clefPosition} (which controls the Y position of the clef), @code{middleCPosition} and @code{clefOctavation}. A clef is printed when any of these properties are changed. The following example shows @@ -1051,6 +1341,8 @@ possibilities when setting properties manually. @seealso +Manual: @ref{Grace notes}. + Program reference: @internalsref{Clef}. @@ -1058,7 +1350,7 @@ Program reference: @internalsref{Clef}. @subsection Key signature @cindex Key signature -@cindex @code{\key} +@funindex \key The key signature indicates the tonality in which a piece is played. It is denoted by a set of alterations (flats or sharps) at the start of the @@ -1071,16 +1363,16 @@ command @code{\key} @var{pitch} @var{type} @end example -@cindex @code{\minor} -@cindex @code{\major} -@cindex @code{\minor} -@cindex @code{\ionian} -@cindex @code{\locrian} -@cindex @code{\aeolian} -@cindex @code{\mixolydian} -@cindex @code{\lydian} -@cindex @code{\phrygian} -@cindex @code{\dorian} +@funindex \minor +@funindex \major +@funindex \minor +@funindex \ionian +@funindex \locrian +@funindex \aeolian +@funindex \mixolydian +@funindex \lydian +@funindex \phrygian +@funindex \dorian @cindex church modes Here, @var{type} should be @code{\major} or @code{\minor} to get @@ -1095,7 +1387,13 @@ can be specified by setting this property directly. Accidentals and key signatures often confuse new users, because unaltered notes get natural signs depending on the key signature. For -more information, see @ref{More about pitches}. +more information, see @ref{Accidentals} or @ref{More about pitches}. + +@lilypond[quote,ragged-right,verbatim,relative=2,fragment] +\key g \major +f1 +fis +@end lilypond @commonprop @@ -1119,7 +1417,8 @@ a bes c d @seealso -Program reference: @internalsref{KeyCancellation}, @internalsref{KeySignature}. +Program reference: @internalsref{KeyCancellation}, +@internalsref{KeySignature}. @node Time signature @@ -1127,7 +1426,7 @@ Program reference: @internalsref{KeyCancellation}, @internalsref{KeySignature}. @cindex Time signature @cindex meter -@cindex @code{\time} +@funindex \time 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 @@ -1189,9 +1488,13 @@ measure is subdivided in 2, 2, 2 and 3. This is passed to } @end lilypond + @seealso -Program reference: @internalsref{TimeSignature}, and @internalsref{Timing_translator}. +Program reference: @internalsref{TimeSignature}, and +@internalsref{Timing_translator}. + +Examples: @inputfileref{input/@/test,compound@/-time@/.ly}. @refbugs @@ -1208,7 +1511,7 @@ Automatic beaming does not use the measure grouping specified with @cindex partial measure @cindex measure, partial @cindex shorten measures -@cindex @code{\partial} +@funindex \partial Partial measures, such as an anacrusis or upbeat, are entered using the @@ -1222,6 +1525,9 @@ The syntax for this command is \partial @var{duration} @end example +where @code{duration} is the rhythmic length to be added before +the next bar. + This is internally translated into @example @@ -1229,7 +1535,9 @@ This is internally translated into @end example The property @code{measurePosition} contains a rational number -indicating how much of the measure has passed at this point. +indicating how much of the measure has passed at this point. Note +that this is a negative number; @code{\partial 4} is internally +translated to mean ``there is a quarter note left in the bar''. @refbugs @@ -1245,12 +1553,16 @@ g4 a2 g2 @end lilypond +@code{\partial} is only intended to be used at the beginning of a +piece. If you use it after the beginning, some odd warnings may +occur. + @node Bar lines @subsection Bar lines @cindex Bar lines -@cindex @code{\bar} +@funindex \bar @cindex measure lines @cindex repeat bars @@ -1268,6 +1580,11 @@ The following bar types are available @lilypondfile[ragged-right,quote]{bar-lines.ly} +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 the next +line. + To allow a line break where there is no visible bar line, use @example @@ -1276,11 +1593,12 @@ To allow a line break where there is no visible bar line, use @noindent This will insert an invisible bar line and allow line breaks at this -point. +point (without increasing the bar number counter). 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 StaffGroup +connected between different staves of a @code{StaffGroup}, +@code{PianoStaff}, or @code{ChoirStaff}. @lilypond[quote,ragged-right,fragment,verbatim] << @@ -1299,9 +1617,9 @@ connected between different staves of a StaffGroup @commonprop -@cindex @code{whichBar} -@cindex @code{repeatCommands} -@cindex @code{defaultBarType} +@funindex whichBar +@funindex repeatCommands +@funindex defaultBarType The command @code{\bar }@var{bartype} is a short cut for doing @code{\set Timing.whichBar = }@var{bartype}. Whenever @code{whichBar} @@ -1309,7 +1627,8 @@ is set to a string, a bar line of that type is created. A bar line is created whenever the @code{whichBar} property is set. At the start of a measure it is set to the contents of -@code{Timing.defaultBarType}. The contents of @code{repeatCommands} are used +@code{Timing.defaultBarType}. The contents of @code{repeatCommands} are +used to override default measure bars. You are encouraged to use @code{\repeat} for repetitions. See @@ -1323,15 +1642,13 @@ In this manual: @ref{Repeats}, @ref{System start delimiters}. Program reference: @internalsref{BarLine} (created at @internalsref{Staff} level), @internalsref{SpanBar} (across staves). -Examples: @inputfileref{input/@/test,bar@/-lines@/.ly}, - @node Unmetered music @subsection Unmetered music @cindex cadenza -@cindex @code{\cadenzaOn} -@cindex @code{\cadenzaOff} +@funindex \cadenzaOn +@funindex \cadenzaOff Bar lines and bar numbers are calculated automatically. For unmetered music (cadenzas, for example), this is not desirable. To turn off @@ -1350,8 +1667,9 @@ d4 e d c @refbugs -LilyPond will only insert page breaks at a barline. Unless the unmetered -music ends before the end of the staff line, you will need to insert +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 @example @@ -1359,7 +1677,7 @@ invisible bar lines @end example @noindent -to indicate where line breaks can occur. +to indicate where breaks can occur. @node System start delimiters @@ -1429,7 +1747,25 @@ The bar lines at the start of each system are @internalsref{SystemStartBar}, @internalsref{SystemStartBrace}, and @internalsref{SystemStartBracket}. Only one of these types is created in every context, and that type is determined by the property -@code{systemStartDelimiter}. +@internalsref{systemStartDelimiter}. + + +@commonprop + +System start delimiters may be deeply nested, + +@lilypond[quote,ragged-right,verbatim] +\new StaffGroup +\relative << + \set StaffGroup.systemStartDelimiterHierarchy + = #'(SystemStartSquare (SystemStartBracket a (SystemStartSquare b)) d) + \new Staff { c1 } + \new Staff { c1 } + \new Staff { c1 } + \new Staff { c1 } + \new Staff { c1 } +>> +@end lilypond @node Staff symbol @@ -1440,7 +1776,7 @@ in every context, and that type is determined by the property Notes, dynamic signs, etc., are grouped with a set of horizontal lines, called a staff (plural `staves'). In LilyPond, these lines are drawn using a separate layout object called -staff symbol. +@code{staff symbol}. The staff symbol may be tuned in the number, thickness and distance of lines, using properties. This is demonstrated in the example files @@ -1457,12 +1793,11 @@ b4 b b b \revert Staff.StaffSymbol #'line-count \stopStaff \startStaff -b b +b b @end lilypond In combination with Frenched staves, this may be used to typeset ossia -sections. An example is in @inputfileref{input/@/test@/,ossia.ly}, -shown here +sections. An example is shown here @cindex ossia @@ -1479,8 +1814,72 @@ Program reference: @internalsref{StaffSymbol}. Examples: @inputfileref{input/@/test,staff@/-lines@/.ly}, @inputfileref{input/@/test@/,ossia.ly}, -@inputfileref{input/@/test,staff@/-size@/.ly}. +@inputfileref{input/@/test,staff@/-size@/.ly}, +@inputfileref{input/@/regression,staff@/-line@/-positions@/.ly}. + + +@node Writing music in parallel +@subsection Writing music in parallel + +@cindex Writing music in parallel +@cindex Interleaved music + +Music for multiple parts can be interleaved + +@lilypond[quote,fragment,verbatim] +\parallelMusic #'(voiceA voiceB) { + r8 g'16[ c''] e''[ g' c'' e''] r8 g'16[ c''] e''[ g' c'' e''] | + c'2 c'2 | + r8 a'16[ d''] f''[ a' d'' f''] r8 a'16[ d''] f''[ a' d'' f''] | + c'2 c'2 | +} +\new StaffGroup << + \new Staff \new Voice \voiceA + \new Staff \new Voice \voiceB +>> +@end lilypond + +This works quite well for piano music + +@lilypond[quote,verbatim] +music = { + \key c \major + \time 4/4 + \parallelMusic #'(voiceA voiceB voiceC voiceD) { + % Bar 1 + r8 g'16[ c''] e''[ g' c'' e''] r8 g'16[ c''] e''[ g' c'' +e''] | + c'2 c'2 | + r8 a16[ d'] f'[ a d' f'] r8 a16[ d'] f'[ a d' f'] | + c2 c2 | + + % Bar 2 + a'8 b' c'' d'' e'' f'' g'' a'' | + d'4 d' d' d' | + c16 d e f d e f g e f g a f g a b | + a,4 a,4 a,4 a,4 | + + % Bar 3 ... + } +} +\score { + \new PianoStaff << + \music + \new Staff << + \voiceA \\ + \voiceB + >> + \new Staff { + \clef bass + << + \voiceC \\ + \voiceD + >> + } + >> +} +@end lilypond @node Connecting notes @@ -1503,7 +1902,7 @@ This section deals with notation that affects groups of notes. @subsection Ties @cindex tie -@cindex @code{~} +@funindex ~ A tie connects two adjacent note heads of the same pitch. The tie in effect extends the length of a note. Ties should not be confused with @@ -1515,7 +1914,12 @@ e' ~ e' ~ @end lilypond 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. +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 A tie is just a way of extending a note duration, similar to the augmentation dot. The following example shows two ways of notating @@ -1528,7 +1932,7 @@ exactly the same concept @noindent Ties are used either when the note crosses a bar line, or when dots cannot be used to denote the rhythm. When using ties, larger note -values should be aligned to subdivisions of the measure, eg. +values should be aligned to subdivisions of the measure, such as @lilypond[fragment,quote,ragged-right] \relative { @@ -1541,9 +1945,10 @@ automatic note splitting (see @ref{Automatic note splitting}). This mechanism automatically splits long notes, and ties them across bar lines. +@funindex \repeatTie + 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}, -eg. @lilypond[fragment,quote,ragged-right,relative=2] r \repeatTie @@ -1559,27 +1964,40 @@ 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. For example, -@lilypond[fragment,verbatim,relative=1,ragged-right] +@lilypond[fragment,verbatim,relative=1,ragged-right,quote] \set tieWaitForNote = ##t -\grace { c16[~ e~ g]~ } 2 +\grace { c16[~ e~ g]~ } 2 \repeat "tremolo" 8 { c32~ c'~ } 1 +e8~ c~ a~ f~ 2 +@end lilypond + +Ties may be engraved manually by changing the @code{tie-configuration} +property. 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 @refcommands -@cindex @code{\tieUp} +@funindex \tieUp @code{\tieUp}, -@cindex @code{\tieDown} +@funindex \tieDown @code{\tieDown}, -@cindex @code{\tieNeutral} +@funindex \tieNeutral @code{\tieNeutral}, -@cindex @code{\tieDotted} +@funindex \tieDotted @code{\tieDotted}, -@cindex @code{\tieDashed} +@funindex \tieDashed @code{\tieDashed}, -@cindex @code{\tieSolid} +@funindex \tieSolid @code{\tieSolid}. @@ -1600,6 +2018,9 @@ Examples: 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. + @node Slurs @subsection Slurs @@ -1644,17 +2065,17 @@ be achieved in LilyPond by setting @code{doubleSlurs}, @refcommands -@cindex @code{\slurUp} +@funindex \slurUp @code{\slurUp}, -@cindex @code{\slurDown} +@funindex \slurDown @code{\slurDown}, -@cindex @code{\slurNeutral} +@funindex \slurNeutral @code{\slurNeutral}, -@cindex @code{\slurDashed} +@funindex \slurDashed @code{\slurDashed}, -@cindex @code{\slurDotted} +@funindex \slurDotted @code{\slurDotted}, -@cindex @code{\slurSolid} +@funindex \slurSolid @code{\slurSolid}. @seealso @@ -1687,11 +2108,11 @@ You cannot have simultaneous phrasing slurs. @refcommands -@cindex @code{\phrasingSlurUp} +@funindex \phrasingSlurUp @code{\phrasingSlurUp}, -@cindex @code{\phrasingSlurDown} +@funindex \phrasingSlurDown @code{\phrasingSlurDown}, -@cindex @code{\phrasingSlurNeutral} +@funindex \phrasingSlurNeutral @code{\phrasingSlurNeutral}. @@ -1710,12 +2131,12 @@ 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 +\laissezVibrer @end lilypond @seealso -Program reference: +Program reference: @internalsref{LaissezVibrerTie} @internalsref{LaissezVibrerTieColumn} @@ -1754,8 +2175,8 @@ Program reference: @internalsref{Beam}. @subsection Manual beams @cindex beams, manual -@cindex @code{]} -@cindex @code{[} +@funindex ] +@funindex [ In some cases it may be necessary to override the automatic beaming algorithm. For example, the autobeamer will not put beams over rests @@ -1771,8 +2192,8 @@ and end point with @code{[} and @code{]} @commonprop -@cindex @code{stemLeftBeamCount} -@cindex @code{stemRightBeamCount} +@funindex stemLeftBeamCount +@funindex stemRightBeamCount Normally, beaming patterns within a beam are determined automatically. If necessary, the properties @code{stemLeftBeamCount} and @@ -1801,7 +2222,7 @@ 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 -@cindex @code{subdivideBeams} +@funindex subdivideBeams @noindent For more information about @code{make-moment}, see @@ -1810,7 +2231,7 @@ For more information about @code{make-moment}, see Line breaks are normally forbidden when beams cross bar lines. This behavior can be changed by setting @code{allowBeamBreak}. -@cindex @code{allowBeamBreak} +@funindex allowBeamBreak @cindex beams and line breaks @cindex beams, kneed @cindex kneed beams @@ -1832,7 +2253,7 @@ texts and accidentals. @node Grace notes @subsection Grace notes -@cindex @code{\grace} +@funindex \grace @cindex ornaments @cindex grace notes @cindex appoggiatura @@ -1900,14 +2321,14 @@ every eighth grace note \new Staff { c4 \grace { g8[ b] } c4 } >> @end lilypond -@cindex @code{\afterGrace} +@funindex \afterGrace 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. +following the main note. @lilypond[ragged-right, verbatim,relative=2,fragment] -c1 \afterGrace d1 { c16[ d] } c4 +c1 \afterGrace d1 { c16[ d] } c4 @end lilypond This will put the grace notes after a ``space'' lasting 3/4 of the @@ -1915,11 +2336,11 @@ length of the main note. The fraction 3/4 can be changed by setting @code{afterGraceFraction}, ie. @example -afterGraceFraction = #(cons 7 8) +afterGraceFraction = #(cons 7 8) @end example @noindent -will put the grace note at 7/8 of the main note. +will put the grace note at 7/8 of the main note. The same effect can be achieved manually by doing @@ -1939,6 +2360,7 @@ A @code{\grace} section will introduce special typesetting settings, for example, to produce smaller type, and set directions. Hence, when introducing layout tweaks, they should be inside the grace section, for example, + @lilypond[quote,ragged-right,fragment,verbatim,relative=2] \new Voice { \acciaccatura { @@ -1955,8 +2377,8 @@ The overrides should also be reverted inside the grace section. The layout of grace sections can be changed throughout the music using the function @code{add-grace-property}. The following example -undefines the Stem direction for this grace, so stems do not always -point up. +undefines the @code{Stem} direction for this grace, so +that stems do not always point up. @example \new Staff @{ @@ -1976,6 +2398,30 @@ Another option is to change the variables @code{startGraceMusic}, The slash through the stem in acciaccaturas can be obtained in other situations by @code{\override Stem #'stroke-style = #"grace"}. + +@commonprop + +Grace notes may be forced to use floating spacing, + +@lilypond[relative=2,ragged-right] +<< + \override Score.SpacingSpanner #'strict-grace-spacing = ##t + \new Staff { + c'4 + \afterGrace + c'4 + { c'16[ c'8 c'16] } + c'4 + } + \new Staff { + c'16[ c'16 c'16 c'16] + c'16[ c'16 c'16 c'16] + c'4 + } +>> +@end lilypond + + @seealso Program reference: @internalsref{GraceMusic}. @@ -2024,6 +2470,7 @@ notes and rhythms. * Trills:: * Glissando:: * Arpeggio:: +* Falls and doits:: @end menu @@ -2189,27 +2636,29 @@ Examples: @inputfileref{input/@/regression,finger@/-chords@/.ly}. @subsection Dynamics @cindex Dynamics -@cindex @code{\ppp} -@cindex @code{\pp} -@cindex @code{\p} -@cindex @code{\mp} -@cindex @code{\mf} -@cindex @code{\f} -@cindex @code{\ff} -@cindex @code{\fff} -@cindex @code{\ffff} -@cindex @code{\fp} -@cindex @code{\sf} -@cindex @code{\sff} -@cindex @code{\sp} -@cindex @code{\spp} -@cindex @code{\sfz} -@cindex @code{\rfz} +@funindex \pppp +@funindex \ppp +@funindex \pp +@funindex \p +@funindex \mp +@funindex \mf +@funindex \f +@funindex \ff +@funindex \fff +@funindex \ffff +@funindex \fp +@funindex \sf +@funindex \sff +@funindex \sp +@funindex \spp +@funindex \sfz +@funindex \rfz Absolute dynamic marks are specified using a command after a note -@code{c4\ff}. The available dynamic marks are @code{\ppp}, +@code{c4\ff}. The available dynamic marks are @code{\ppppp}, +@code{\pppp}, @code{\ppp}, @code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff}, -@code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, @code{\sff}, +@code{\fff}, @code{\ffff}, @code{\fp}, @code{\sf}, @code{\sff}, @code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}. @lilypond[quote,verbatim,ragged-right,fragment,relative=2] @@ -2217,14 +2666,15 @@ c\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff c2\fp c\sf c\sff c\sp c\spp c\sfz c\rfz @end lilypond -@cindex @code{\<} -@cindex @code{\>} -@cindex @code{\!} +@funindex \< +@funindex \> +@funindex \! A crescendo mark is started with @code{\<} and terminated with @code{\!} or an absolute dynamic. A decrescendo is started with @code{\>} and is also terminated with @code{\!} or an absolute -dynamic. Because these marks are bound to notes, you must +dynamic. @code{\cr} and @code{\decr} may be used instead of +@code{\<} and @code{\>}. Because these marks are bound to notes, you must use spacer notes if multiple marks are needed during one note @lilypond[quote,ragged-right,fragment,verbatim,relative=2] @@ -2233,22 +2683,50 @@ c\< c\! d\> e\! @end lilypond @noindent -A hairpin starts at the left edge of the beginning note and ends on the -right edge of the ending note. +A hairpin normally starts at the left edge of the beginning note +and ends on the right edge of the ending note. If the ending +note falls on the downbeat, the hairpin ends on the immediately +preceding barline. This may be modified by setting the +@code{hairpinToBarline} property, + +@lilypond[quote,ragged-right,fragment,verbatim,relative=2] +\set hairpinToBarline = ##f +c4\< c2. c4\! +@end lilypond + +In some situations the @code{\espressivo} articulation mark may +be suitable to indicate a crescendo and decrescendo on the one note, + +@lilypond[quote,ragged-right,fragment,verbatim,relative=2] +c2 b4 a g1\espressivo +@end lilypond This may give rise to very short hairpins. Use @code{minimum-length} in @internalsref{Voice}.@internalsref{Hairpin} to lengthen them, for example @example -\override Staff.Hairpin #'minimum-length = #5 +\override Voice.Hairpin #'minimum-length = #5 @end example +@cindex al niente +@cindex niente, al + +Hairpins may be printed with a circled tip (al niente notation) by +setting the @code{circled-tip} property, + +@lilypond[quote,ragged-right,fragment,relative=2,verbatim] +\override Hairpin #'circled-tip = ##t +c2\< c\! +c4\> c\< c2\! +@end lilypond + + @cindex crescendo @cindex decrescendo @cindex diminuendo -You can also use a text saying @emph{cresc.} instead of hairpins +You can also use text saying @emph{cresc.} instead of hairpins @lilypond[quote,ragged-right,fragment,relative=2,verbatim] \setTextCresc @@ -2293,14 +2771,22 @@ new line are not printed. To change this behavior, use \override Score.Hairpin #'after-line-breaking = ##t @end example +Text style dynamic changes (such as @emph{cresc.} and @emph{dim.}) +are printed with a +dashed line showing their extent. To surpress printing this line, use + +@example +\override DynamicTextSpanner #'dash-period = #-1.0 +@end example + @refcommands -@cindex @code{\dynamicUp} +@funindex \dynamicUp @code{\dynamicUp}, -@cindex @code{\dynamicDown} +@funindex \dynamicDown @code{\dynamicDown}, -@cindex @code{\dynamicNeutral} +@funindex \dynamicNeutral @code{\dynamicNeutral}. @@ -2359,12 +2845,11 @@ Long running trills are made with @code{\startTrillSpan} and @cindex Pitched trills Trills that should be executed on an explicitly specified pitch can be -typeset with the command @code{pitchedTrill}, +typeset with the command @code{pitchedTrill}, -@c if bug fixed, remove ! in f1 --gp -@lilypond[ragged-right,verbatim,fragment,relative=1] +@lilypond[ragged-right,verbatim,fragment,relative=1,quote] \pitchedTrill c4\startTrillSpan fis -f!\stopTrillSpan +f\stopTrillSpan @end lilypond The first argument is the main note. The pitch of the second @@ -2374,9 +2859,9 @@ is printed as a stemless note head in parentheses. @refcommands @code{\startTrillSpan}, -@cindex @code{\startTrillSpan} +@funindex \startTrillSpan @code{\stopTrillSpan}. -@cindex @code{\stopTrillSpan} +@funindex \stopTrillSpan @seealso @@ -2388,7 +2873,7 @@ Program reference: @internalsref{TrillSpanner}. @subsection Glissando @cindex Glissando -@cindex @code{\glissando} +@funindex \glissando A glissando is a smooth change in pitch. It is denoted by a line or a wavy line between two notes. It is requested by attaching @@ -2418,7 +2903,7 @@ Printing text over the line (such as @emph{gliss.}) is not supported. @cindex Arpeggio @cindex broken chord -@cindex @code{\arpeggio} +@funindex \arpeggio You can specify an arpeggio sign (also known as broken chord) on a chord by attaching an @code{\arpeggio} to a chord @@ -2466,13 +2951,13 @@ in both staves and set @refcommands @code{\arpeggio}, -@cindex @code{\arpeggioUp} +@funindex \arpeggioUp @code{\arpeggioUp}, -@cindex @code{\arpeggioDown} +@funindex \arpeggioDown @code{\arpeggioDown}, -@cindex @code{\arpeggioNeutral} +@funindex \arpeggioNeutral @code{\arpeggioNeutral}, -@cindex @code{\arpeggioBracket} +@funindex \arpeggioBracket @code{\arpeggioBracket}. @@ -2489,295 +2974,19 @@ It is not possible to mix connected arpeggios and unconnected arpeggios in one @internalsref{PianoStaff} at the same point in time. +@node Falls and doits +@subsection Falls and doits -@node Polyphony -@section Polyphony - -Polyphony in music refers to having more than one voice occuring in -a piece of music. Polyphony in LilyPond refers to having more than -one voice on the same staff. - -@menu -* Basic polyphony:: -* Explicitly instantiating voices:: -* Collision Resolution:: -@end menu - - -@node Basic polyphony -@subsection Basic polyphony - -@cindex polyphony - -The easiest way to enter fragments with more than one voice on a staff -is to enter each voice as a sequence (with @code{@{...@}}), and combine -them simultaneously, separating the voices with @code{\\} - -@cindex @code{\\} - -@lilypond[quote,verbatim,fragment] -\new Staff \relative c' { - c16 d e f - << - { g4 f e | d2 e2 } \\ - { r8 e4 d c8 ~ | c b16 a b8 g ~ g2 } \\ - { s2. | s4 b4 c2 } - >> -} -@end lilypond - -The separator causes @internalsref{Voice} contexts@footnote{Polyphonic -voices are sometimes called ``layers'' in other notation packages} -@cindex layers -to be instantiated. They bear the names @code{"1"}, @code{"2"}, etc. In -each of these contexts, vertical direction of slurs, stems, etc., is set -appropriately. - -These voices are all seperate from the voice that contains the notes just -outside the @code{<< \\ >>} construct. This should be noted when making -changes at the voice level. This also means that slurs and ties cannot go -into or out of a @code{<< \\ >>} construct. Conversely, parallel voices -from separate @code{<< \\ >>} constructs on the same staff are the the -same voice. Here is the same example, with different noteheads for each -voice. Note that the change to the note-head style in the main voice does not affect -the inside of the @code{<< \\ >>} constructs. Also, the change to the second -voice in the first @code{<< \\ >>} construct is effective in the second -@code{<< \\ >>}, and the voice is tied accross the two constructs. - -@lilypond[quote,verbatim,fragment] -\new Staff \relative c' { - \override NoteHead #'style = #'cross - c16 d e f - << - { g4 f e } \\ - { \override NoteHead #'style = #'triangle - r8 e4 d c8 ~ } - >> | - << - { d2 e2 } \\ - { c8 b16 a b8 g ~ g2 } \\ - { \override NoteHead #'style = #'slash s4 b4 c2 } - >> -} -@end lilypond - -Polyphony does not change the relationship of notes within a -@code{\relative @{ @}} block. Each note is calculated relative -to the note immediately preceding it. - -@example -\relative @{ noteA << noteB \\ noteC >> noteD @} -@end example - -@code{noteC} is relative to @code{noteB}, not @code{noteA}; -@code{noteD} is relative to @code{noteC}, not @code{noteB} or -@code{noteA}. - -@node Explicitly instantiating voices -@subsection Explicitly instantiating voices - -@internalsref{Voice} contexts can also be instantiated manually -inside a @code{<< >>} block to create polyphonic music, using -@code{\voiceOne}, up to @code{\voiceFour} to assign stem directions -and a horizontal shift for each part. - -Specifically, -@example -<< \upper \\ \lower >> -@end example - -@noindent -is equivalent to - -@example -<< - \new Voice = "1" @{ \voiceOne \upper @} - \new Voice = "2" @{ \voiceTwo \lower @} ->> -@end example - -The @code{\voiceXXX} commands set the direction of stems, slurs, ties, -articulations, text annotations, augmentation dots of dotted -notes, and fingerings. @code{\voiceOne} and @code{\voiceThree} make -these objects point upwards, while @code{\voiceTwo} and @code{\voiceFour} -make them point downwards. -The command @code{\oneVoice} will revert back to the normal setting. - -An expression that appears directly inside a @code{<< >>} belongs to -the main voice. This is useful when extra voices appear while the main -voice is playing. Here is a more correct rendition of the example from -the previous section. The crossed noteheads demonstrate that the main -melody is now in a single voice context. - -@lilypond[quote,ragged-right,verbatim] -\new Staff \relative c' { - \override NoteHead #'style = #'cross - c16 d e f - \voiceOne - << - { g4 f e | d2 e2 } - \new Voice="1" { \voiceTwo - r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 - \oneVoice - } - \new Voice { \voiceThree - s2. | s4 b4 c2 - \oneVoice - } - >> - \oneVoice -} -@end lilypond - -The correct definition of the voices allows the melody to be slurred. -@lilypond[quote,ragged-right,verbatim] -\new Staff \relative c' { - c16^( d e f - \voiceOne - << - { g4 f e | d2 e2) } - \context Voice="1" { \voiceTwo - r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 - \oneVoice - } - \new Voice { \voiceThree - s2. s4 b4 c2 - \oneVoice - } - >> - \oneVoice -} -@end lilypond - -Avoiding the @code{\\} seperator also allows nesting polyphony -constructs, which in some case might be a more natural way to typeset -the music. - -@lilypond[quote,ragged-right,verbatim] -\new Staff \relative c' { - c16^( d e f - \voiceOne - << - { g4 f e | d2 e2) } - \context Voice="1" { \voiceTwo - r8 e4 d c8 ~ | - << - {c8 b16 a b8 g ~ g2} - \new Voice { \voiceThree - s4 b4 c2 - \oneVoice - } - >> - \oneVoice - } - >> - \oneVoice -} -@end lilypond - - -@node Collision Resolution -@subsection Collision Resolution - -Normally, note heads with a different number of dots are not merged, but -when the object property @code{merge-differently-dotted} is set in -the @internalsref{NoteCollision} object, they are merged -@lilypond[quote,verbatim,fragment,ragged-right,relative=2] -\new Voice << { - g8 g8 - \override Staff.NoteCollision - #'merge-differently-dotted = ##t - g8 g8 -} \\ { g8.[ f16] g8.[ f16] } >> -@end lilypond - -Similarly, you can merge half note heads with eighth notes, by setting -@code{merge-differently-headed} -@lilypond[quote,ragged-right,fragment,relative=2,verbatim] -\new Voice << { - c8 c4. - \override Staff.NoteCollision - #'merge-differently-headed = ##t -c8 c4. } \\ { c2 c2 } >> -@end lilypond - -LilyPond also vertically shifts rests that are opposite of a stem, -for example - -@lilypond[quote,ragged-right,fragment,verbatim] -\new Voice << c''4 \\ r4 >> -@end lilypond - - -@refcommands - -@cindex @code{\oneVoice} -@code{\oneVoice}, -@cindex @code{\voiceOne} -@code{\voiceOne}, -@cindex @code{\voiceTwo} -@code{\voiceTwo}, -@cindex @code{\voiceThree} -@code{\voiceThree}, -@cindex @code{\voiceFour} -@code{\voiceFour}. - -@cindex @code{\shiftOn} -@code{\shiftOn}, -@cindex @code{\shiftOnn} -@code{\shiftOnn}, -@cindex @code{\shiftOnnn} -@code{\shiftOnnn}, -@cindex @code{\shiftOff} -@code{\shiftOff}: these commands specify in what chords of the current -voice should be shifted. The outer voices (normally: voice one and -two) have @code{\shiftOff}, while the inner voices (three and four) -have @code{\shiftOn}. @code{\shiftOnn} and @code{\shiftOnnn} define -further shift levels. - -When LilyPond cannot cope, the @code{force-hshift} -property of the @internalsref{NoteColumn} object and pitched rests can -be used to override typesetting decisions. +Falls and doits can be added to notes using the @code{\bendAfter} +command, -@lilypond[quote,verbatim,ragged-right] -\relative << -{ - - -} \\ { - - \once \override NoteColumn #'force-hshift = #1.7 - -} >> +@lilypond[fragment,ragged-right,relative=2] +\override Score.SpacingSpanner #'shortest-duration-space = #3.0 +c4-\bendAfter #+5 +c4-\bendAfter #-3 @end lilypond -@seealso - -Program reference: the objects responsible for resolving collisions are -@internalsref{NoteCollision} and @internalsref{RestCollision}. - -Examples: -@inputfileref{input/@/regression,collision@/-dots@/.ly}, -@inputfileref{input/@/regression,collision@/-head-chords@/.ly}, -@inputfileref{input/@/regression,collision@/-heads@/.ly}, -@inputfileref{input/@/regression,collision@/-mesh@/.ly}, and -@inputfileref{input/@/regression,collisions@/.ly}. - - -@refbugs - -When using @code{merge-differently-headed} with an upstem eighth or a -shorter note, and a downstem half note, the eighth note gets the wrong -offset. - -There is no support for clusters where the same note occurs with -different accidentals in the same chord. In this case, it is -recommended to use enharmonic transcription, or to use special cluster -notation (see @ref{Clusters}). - - - @node Repeats @section Repeats @@ -2799,7 +3008,7 @@ for repetitions. @subsection Repeat types @cindex repeats -@cindex @code{\repeat} +@funindex \repeat The following types of repetition are supported @@ -2812,14 +3021,9 @@ is included in MIDI output. @item volta Repeats are not written out, but alternative endings (volte) are printed, left to right with brackets. This is the standard notation -for repeats with alternatives. These are not played in MIDI output by default. +for repeats with alternatives. These are not played in MIDI output by +default. -@ignore -@item fold -Alternative endings are written stacked. This has limited use but may be -used to typeset two lines of lyrics in songs with repeats, see -@inputfileref{input,star-spangled-banner@/.ly}. -@end ignore @item tremolo Make tremolo beams. These are not played in MIDI output by default. @@ -2827,7 +3031,7 @@ Make tremolo beams. These are not played in MIDI output by default. @item percent Make beat or measure repeats. These look like percent signs. These are not played in MIDI output by default. Percent repeats must be -declared within a Voice context. +declared within a @code{Voice} context. @end table @@ -2843,7 +3047,7 @@ repeats. The syntax is @end example If you have alternative endings, you may add -@cindex @code{\alternative} +@funindex \alternative @example \alternative @{ @var{alternative1} @@ -2859,6 +3063,7 @@ give enough alternatives for all of the repeats, the first alternative is assumed to be played more than once. Standard repeats are used like this + @lilypond[quote,ragged-right,fragment,verbatim,relative=2] c1 \repeat volta 2 { c4 d e f } @@ -2866,12 +3071,20 @@ c1 @end lilypond With alternative endings + @lilypond[quote,ragged-right,fragment,verbatim,relative=2] c1 \repeat volta 2 {c4 d e f} \alternative { {d2 d} {f f,} } @end lilypond +In the following example, the first ending is not a complete +bar (it only had 3 beats). The beginning of the second ending +contains the 4th beat from the first ending. This ``extra'' +beat in the second ending is due to the first time ending, +and has nothing to do with the @code{\partial} at the +beginning of the example. + @lilypond[quote,ragged-right,fragment,verbatim,relative=2] \new Staff { \partial 4 @@ -2880,6 +3093,16 @@ c1 } @end lilypond +@funindex \repeatTie + +Ties may be added to a second ending, + +@lilypond[quote,ragged-right,fragment,verbatim,relative=2] +c1 +\repeat volta 2 {c4 d e f ~ } +\alternative { {f2 d} {f\repeatTie f,} } +@end lilypond + It is possible to shorten volta brackets by setting @code{voltaSpannerDuration}. In the next example, the bracket only lasts one measure, which is a duration of 3/4. @@ -2924,20 +3147,22 @@ having the @code{\alternative} belong to the inner @code{\repeat}. For clarity, it is advisable to use braces in such situations. Timing information is not remembered at the start of an alternative, -so after a repeat timing information must be reset by hand, for -example by setting @code{Score.measurePosition} or entering +so after a repeat timing information must be reset by hand; for +example, by setting @code{Score.measurePosition} or entering @code{\partial}. Similarly, slurs or ties are also not repeated. +Volta brackets are not vertically aligned. + @node Repeats and MIDI @subsection Repeats and MIDI @cindex expanding repeats -@cindex @code{\unfoldRepeats} +@funindex \unfoldRepeats With a little bit of tweaking, all types of repeats can be present in the MIDI output. This is achieved by applying the -@code{\unfoldRepeats} music function. This functions changes all +@code{\unfoldRepeats} music function. This function changes all repeats to unfold repeats. @lilypond[quote,verbatim,fragment,line-width=8.0\cm] @@ -2953,8 +3178,8 @@ repeats to unfold repeats. \bar "|." @end lilypond -When creating a score file using @code{\unfoldRepeats} for midi, then -it is necessary to make two @code{\score} blocks. One for MIDI (with +When creating a score file using @code{\unfoldRepeats} for MIDI, +it is necessary to make two @code{\score} blocks: one for MIDI (with unfolded repeats) and one for notation (with volta, tremolo, and percent repeats). For example, @@ -2973,7 +3198,7 @@ percent repeats). For example, @node Manual repeat commands @subsection Manual repeat commands -@cindex @code{repeatCommands} +@funindex repeatCommands The property @code{repeatCommands} can be used to control the layout of repeats. Its value is a Scheme list of repeat commands. @@ -3006,7 +3231,8 @@ c4 c4 @seealso -Program reference: @internalsref{VoltaBracket}, @internalsref{RepeatedMusic}, +Program reference: @internalsref{VoltaBracket}, +@internalsref{RepeatedMusic}, @internalsref{VoltaRepeatedMusic}, @internalsref{UnfoldedRepeatedMusic}, and @internalsref{FoldedRepeatedMusic}. @@ -3051,7 +3277,7 @@ Example files: @inputfileref{input/@/regression,chord@/-tremolo@/.ly}, @subsection Tremolo subdivisions @cindex tremolo marks -@cindex @code{tremoloFlags} +@funindex tremoloFlags Tremolo marks can be printed on a single note by adding `@code{:}[@var{number}]' after the note. The number indicates the @@ -3100,17 +3326,18 @@ Measure repeats of more than 2 measures get a counter, if you switch on the @code{countPercentRepeats} property, @lilypond[relative=2,fragment,quote,verbatim,ragged-right] +\new Voice { \set countPercentRepeats = ##t -\new Voice \repeat "percent" 4 { c1 } +} @end lilypond -Isolated percents can also be printed. This is done by putting a multi -measure rest with a different print function, +Isolated percents can also be printed. This is done by putting a +multi-measure rest with a different print function, -@lilypond[fragment,verbatim] +@lilypond[fragment,verbatim,quote] \override MultiMeasureRest #'stencil = #ly:multi-measure-rest::percent R1 @@ -3125,5 +3352,7 @@ Program reference: @internalsref{RepeatSlash}, @internalsref{PercentRepeat}, @internalsref{DoublePercentRepeat}, @internalsref{DoublePercentRepeatCounter}, @internalsref{PercentRepeatCounter}, -@internalsref{PercentRepeatedMusic}, and +@internalsref{PercentRepeatedMusic}. + +