X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fbasic-notation.itely;h=b4e36e8655209fe1d54b68178c1e446dee4d4447;hb=87eedcd59f4082cb0841528ad5bc82cb1d1191e3;hp=2fc5089cf557a9d2e6154eeabb2734f68e332f1f;hpb=e41b8ecb778768769ab600a79a2163b9f2dc8e24;p=lilypond.git diff --git a/Documentation/user/basic-notation.itely b/Documentation/user/basic-notation.itely index 2fc5089cf5..b4e36e8655 100644 --- a/Documentation/user/basic-notation.itely +++ b/Documentation/user/basic-notation.itely @@ -1,5 +1,12 @@ @c -*- coding: utf-8; mode: texinfo; -*- @c This file is part of lilypond.tely +@ignore + Translation of GIT committish: FILL-IN-HEAD-COMMITTISH + + When revising a translation, copy the HEAD committish of the + version that you are working on. See TRANSLATION for details. +@end ignore + @c A menu is needed before every deeper *section nesting of @node's; run @c M-x texinfo-all-menus-update @@ -11,59 +18,38 @@ This chapter explains how to use basic notation features. @menu -* Note entry:: -* Alternate music entry:: -* Staff notation:: -* Connecting notes:: -* Expressive marks:: -* Polyphony:: -* Repeats:: +* Pitches:: +* Rhythms:: +* Multiple notes at once:: +* Staff notation:: +* Connecting notes:: +* Expressive marks:: +* 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:: -* Cautionary accidentals:: -* Micro tones:: -* Chords:: -* Rests:: -* Skips:: -* Durations:: -* Augmentation dots:: -* Tuplets:: -* Scaling durations:: -* Stems:: +* Normal pitches:: +* Accidentals:: +* Cautionary accidentals:: +* Micro tones:: +* Notes names in other languages:: +* Relative octaves:: +* Octave check:: +* Transpose:: +* Rests:: +* Skips:: @end menu -@node Notes -@subsection Notes - -@cindex Note specification -@cindex entering notes - -A note is printed by specifying its pitch and duration, - -@lilypond[quote,verbatim,ragged-right,fragment] -cis'4 d'8 e'16 c'16 -@end lilypond - -@seealso - -This manual: @ref{Pitches}, @ref{Durations} - - -@node Pitches -@subsection Pitches +@node Normal pitches +@subsection Normal pitches @cindex Pitch names @cindex pitches @@ -78,19 +64,20 @@ c d e f g a b c' The note name @code{c} is engraved one octave below middle C. -@c this should be scored with a treble clef and -@c four leger lines below the staff. @lilypond[quote,fragment,verbatim,ragged-right] +\clef treble +c1 +\clef bass 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. +single quote (@samp{'}) characters or a series of comma +(@samp{,}) characters. Each @samp{'} raises the pitch by one +octave; each @samp{,} lowers the pitch by an octave. @lilypond[quote,ragged-right,fragment,verbatim] \clef treble @@ -101,27 +88,32 @@ c, c,, e, g d,, d, d c 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 +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} +a flat is formed by adding @code{-es}. Double sharps and double flats +are obtained by adding @code{-isis} or @code{-eses} to a note name. -@c avoid engraving naturals by crossing bar lines; we're not ready for them @lilypond[quote,ragged-right,fragment,verbatim,relative=2] a2 ais a aes +a2 aisis a aeses @end lilypond -Double sharps and double flats -are obtained by adding @code{-isis} or @code{-eses} to a note name. These -are the Dutch note names. In Dutch, @code{aes} is contracted to +@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] -a2 aisis a aeses +a2 as e es @end lilypond A natural will cancel the effect of an accidental or key signature. @@ -132,28 +124,17 @@ suffix; a natural pitch is shown as a simple note name a4 aes a2 @end lilypond +The input @code{d e f} is interpreted as @q{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}. - -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 - -@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[fragment,quote,ragged-right,verbatim,relative] +\key d \major +d e f g +d e fis g +@end lilypond @commonprop @@ -169,20 +150,10 @@ 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}, +Program reference: @internalsref{LedgerLineSpanner}, @internalsref{NoteHead}. @@ -193,17 +164,17 @@ Program reference: @internalsref{LedgerLineSpanner}, @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 can be forced by adding an exclamation mark @code{!} after the pitch. A cautionary accidental (i.e., an accidental within parentheses) can be obtained by adding the -question mark `@code{?}' after the pitch. These extra accidentals +question mark @samp{?} after the pitch. These extra accidentals can be used to produce natural signs, too. @lilypond[quote,ragged-right,fragment,verbatim,relative=1] @@ -216,6 +187,7 @@ cis cis cis! cis? c c? c! c The automatic production of accidentals can be tuned in many ways. For more information, see @ref{Automatic accidentals}. + @node Micro tones @subsection Micro tones @@ -240,127 +212,376 @@ 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 -@cindex @code{\rest} -@cindex @code{r} +@noindent +or -Rests are entered like notes with the note name @code{r} +@example +\relative @var{musicexpr} +@end example -@lilypond[fragment,quote,ragged-right,verbatim] -r1 r2 r4 r8 +@noindent +@code{c'} is used as the default if no starting pitch is defined. + +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 -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[quote,ragged-right,fragment,verbatim] +\relative c'' { + c g c f, c' a, e'' +} +@end lilypond -@lilypond[fragment,quote,ragged-right,verbatim] -a'4\rest d'4\rest +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[quote,ragged-right,fragment,verbatim] +\relative c' { + c + + +} @end lilypond -@noindent -This makes manual formatting of -polyphonic music much easier, since the automatic rest collision -formatter will leave these rests alone. +The pitch after @code{\relative} contains a note name. -@seealso +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}. -Program reference: @internalsref{Rest}. +@node Octave check +@subsection Octave check -@node Skips -@subsection Skips +@cindex Octave check -@cindex Skip -@cindex Invisible rest -@cindex Space note -@cindex @code{\skip} -@cindex @code{s} +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, -An invisible rest (also called a `skip') can be entered like a note -with note name `@code{s}' or with @code{\skip @var{duration}} +@example +\relative c'' @{ c='' b=' d,='' @} +@end example -@lilypond[fragment,quote,ragged-right,verbatim,relative=2] -a4 a4 s4 a4 \skip 1 a4 -@end lilypond +@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'}. -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 +There is also an octave check that produces no visible output. The syntax -@lilypond[quote,ragged-right,verbatim] -<< - \relative { a'2 a2 } - \new Lyrics \lyricmode { \skip 2 bla2 } ->> -@end lilypond +@example +\octave @var{pitch} +@end example -The skip command is merely an empty musical placeholder. It does not -produce any output, not even transparent output. +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. -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. +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. -@lilypond[quote,ragged-right,verbatim] -{ s4 } -@end lilypond +@example +\relative c' @{ + e + \octave a' + \octave b' +@} +@end example -The fragment @code{@{ \skip 4 @} } would produce an empty page. -@seealso +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. -Program reference: @internalsref{SkipMusic}. +@lilypond[quote,ragged-right,verbatim,fragment] +\relative c' { + e + \octave b + a +} +@end lilypond -@node Durations -@subsection Durations +@node Transpose +@subsection Transpose -@cindex duration -@cindex @code{\longa} -@cindex @code{\breve} -@cindex @code{\maxima} +@cindex Transpose +@cindex Transposition of pitches +@funindex \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} +A music expression can be transposed with @code{\transpose}. The +syntax is +@example +\transpose @var{from} @var{to} @var{musicexpr} +@end example + +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 -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 d e @dots{} @end example -@lilypond[quote] +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 @q{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 @q{skip}) can be entered like a note +with note name @samp{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 @@ -372,6 +593,11 @@ 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" @@ -395,9 +621,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 lengths, simply add a dot (`@code{.}') to +To obtain dotted note lengths, simply add a dot (@samp{.}) to the number. Double-dotted notes are produced in a similar way. @lilypond[quote,ragged-right,fragment,verbatim] @@ -410,11 +636,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 @@ -427,7 +653,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 @@ -450,7 +676,7 @@ 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 \times 3/5 { a a a a a } @@ -459,17 +685,17 @@ Tuplets may be nested, for example, @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 @@ -487,11 +713,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 @@ -501,6 +726,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 @@ -515,7 +760,7 @@ Examples: @inputfileref{input/@/regression,tuplet@/-nest@/.ly}. @subsection Scaling durations You can alter the length of duration by a fraction @var{N/M} -appending `@code{*}@var{N/M}' (or `@code{*}@var{N}' if @var{M=1}). This +appending @samp{*@var{N/M}} (or @samp{*@var{N}} if @var{M=1}). This will not affect the appearance of the notes or rests produced. In the following example, the first three notes take up exactly two @@ -533,444 +778,454 @@ b16*4 c4 This manual: @ref{Tuplets} -@node Stems -@subsection Stems - -Whenever a note is found, a @internalsref{Stem} object is created -automatically. For whole notes and rests, they are also created but -made invisible. - -@refcommands - -@cindex @code{\stemUp} -@code{\stemUp}, -@cindex @code{\stemDown} -@code{\stemDown}, -@cindex @code{\stemNeutral} -@code{\stemNeutral}. - - -@commonprop - -To change the direction of stems in the middle of the staff, use +@node Bar check +@subsection Bar check -@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 +@cindex Bar check +@funindex barCheckSynchronize +@funindex | +Bar checks help detect errors in the durations. A bar check is +entered using the bar symbol, @samp{|}. 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 -@node Alternate music entry -@section Alternate music entry -@cindex Music entry +Bar checks can also be used in lyrics, for example -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. +@example +\lyricmode @{ + \time 2/4 + Twin -- kle | Twin -- kle +@} +@end 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. +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. -@menu -* Relative octaves:: -* Octave check:: -* Transpose:: -* Bar check:: -* Barnumber check:: -* Skipping corrected music:: -* Automatic note splitting:: -* Writing music in parallel:: -@end menu +@funindex | +@funindex pipeSymbol +It is also possible to redefine the meaning of @code{|}. This is done +by assigning a music expression to @code{pipeSymbol}, -@node Relative octaves -@subsection Relative octaves +@lilypond[quote,ragged-right,verbatim] +pipeSymbol = \bar "||" -@cindex Relative -@cindex Relative octave specification -@cindex @code{\relative} +{ c'2 c' | c'2 c' } +@end lilypond -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 +@node Barnumber check +@subsection Barnumber check -@noindent -or +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, -@example -\relative @var{musicexpr} -@end example +@verbatim +\barNumberCheck #123 +@end verbatim @noindent -@code{c'} is used as the default if no starting pitch is defined. +will print a warning if the @code{currentBarNumber} is not 123 when it +is processed. -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 an octave check that produces no visible output. 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. The @var{pitch} is not printed as a note. +@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 (i.e. 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 @q{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. + +@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 Bar check -@subsection Bar check +@node Explicitly instantiating voices +@subsection Explicitly instantiating voices -@cindex Bar check -@cindex @code{barCheckSynchronize} -@cindex @code{|} +@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. -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 +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. - -@cindex @code{|} -@cindex @code{pipeSymbol} +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. -It is also possible to redefine the meaning of @code{|}. This is done -by assigning a music expression to @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] -pipeSymbol = \bar "||" - -{ c'2 c' | c'2 c' } +\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 -@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. - +Avoiding the @code{\\} separator also allows nesting polyphony +constructs, which in some case might be a more natural way to typeset +the music. -@node Skipping corrected music -@subsection Skipping corrected 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 -@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 -fashion with the property @code{Score.skipTypesetting}. When it is -set, no typesetting is performed at all. - -This property is also used to control output to the MIDI file. Note that -it skips all events, including tempo and instrument changes. You have -been warned. +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] -\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 @@ -982,21 +1237,22 @@ This section describes music notation that occurs on staff level, such as key signatures, clefs and time signatures. @menu -* Clef:: -* Key signature:: -* Time signature:: -* Partial measures:: -* Bar lines:: -* Unmetered music:: -* System start delimiters:: -* Staff symbol:: +* Clef:: +* Key signature:: +* Time signature:: +* Partial measures:: +* Bar lines:: +* 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 @@ -1061,7 +1317,7 @@ example, @commonprop -The command @code{\clef "treble_8"} is equivalent to setting +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 @@ -1092,6 +1348,8 @@ possibilities when setting properties manually. @seealso +Manual: @ref{Grace notes}. + Program reference: @internalsref{Clef}. @@ -1099,7 +1357,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 @@ -1112,21 +1370,21 @@ 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 @var{pitch}-major or @var{pitch}-minor, respectively. You may also -use the standard mode names (also called ``church modes''): @code{\ionian}, +use the standard mode names (also called @q{church modes}): @code{\ionian}, @code{\locrian}, @code{\aeolian}, @code{\mixolydian}, @code{\lydian}, @code{\phrygian}, and @code{\dorian}. @@ -1136,7 +1394,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 @@ -1169,7 +1433,7 @@ Program reference: @internalsref{KeyCancellation}, @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 @@ -1254,7 +1518,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 @@ -1268,6 +1532,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 @@ -1275,7 +1542,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 @qq{there is a quarter note left in the bar.} @refbugs @@ -1291,12 +1560,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 @@ -1314,6 +1587,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 @@ -1322,11 +1600,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] << @@ -1345,9 +1624,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} @@ -1355,7 +1634,7 @@ 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 +@code{Timing.defaultBarType}. The contents of @code{repeatCommands} are used to override default measure bars. @@ -1370,15 +1649,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 @@ -1397,8 +1674,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 @@ -1406,7 +1684,7 @@ invisible bar lines @end example @noindent -to indicate where line breaks can occur. +to indicate where breaks can occur. @node System start delimiters @@ -1476,7 +1754,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 @@ -1485,9 +1781,9 @@ in every context, and that type is determined by the property @cindex adjusting staff symbol Notes, dynamic signs, etc., are grouped -with a set of horizontal lines, called a staff (plural `staves'). In +with a set of horizontal lines, called a staff (plural @q{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 @@ -1508,8 +1804,7 @@ 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 @@ -1530,6 +1825,69 @@ Examples: @inputfileref{input/@/test,staff@/-lines@/.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 @section Connecting notes @@ -1537,13 +1895,13 @@ Examples: @inputfileref{input/@/test,staff@/-lines@/.ly}, This section deals with notation that affects groups of notes. @menu -* Ties:: -* Slurs:: -* Phrasing slurs:: -* Laissez vibrer ties:: -* Automatic beams:: -* Manual beams:: -* Grace notes:: +* Ties:: +* Slurs:: +* Phrasing slurs:: +* Laissez vibrer ties:: +* Automatic beams:: +* Manual beams:: +* Grace notes:: @end menu @@ -1551,19 +1909,24 @@ 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 slurs, which indicate articulation, or phrasing slurs, which indicate -musical phrasing. A tie is entered using the tilde symbol `@code{~}' +musical phrasing. A tie is entered using the tilde symbol @samp{~} @lilypond[quote,ragged-right,fragment,verbatim] 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 @@ -1589,6 +1952,8 @@ 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}, @@ -1606,27 +1971,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 \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}. @@ -1647,6 +2025,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 @@ -1691,17 +2072,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 @@ -1734,11 +2115,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}. @@ -1801,8 +2182,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 @@ -1818,8 +2199,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 @@ -1848,7 +2229,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 @@ -1857,7 +2238,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 @@ -1879,7 +2260,7 @@ texts and accidentals. @node Grace notes @subsection Grace notes -@cindex @code{\grace} +@funindex \grace @cindex ornaments @cindex grace notes @cindex appoggiatura @@ -1911,7 +2292,7 @@ c4 \grace c16 c4 Unlike @code{\acciaccatura} and @code{\appoggiatura}, the @code{\grace} command does not start a slur. -Internally, timing for grace notes is done using a second, `grace' +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 @@ -1947,7 +2328,7 @@ 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 @@ -1957,7 +2338,7 @@ following the main note. c1 \afterGrace d1 { c16[ d] } c4 @end lilypond -This will put the grace notes after a ``space'' lasting 3/4 of the +This will put the grace notes after a @q{space} lasting 3/4 of the length of the main note. The fraction 3/4 can be changed by setting @code{afterGraceFraction}, ie. @@ -1986,6 +2367,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 { @@ -2002,8 +2384,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 @{ @@ -2023,6 +2405,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}. @@ -2064,13 +2470,14 @@ Expressive marks help musicians to bring more to the music than simple notes and rhythms. @menu -* Articulations:: -* Fingering instructions:: -* Dynamics:: -* Breath marks:: -* Trills:: -* Glissando:: -* Arpeggio:: +* Articulations:: +* Fingering instructions:: +* Dynamics:: +* Breath marks:: +* Trills:: +* Glissando:: +* Arpeggio:: +* Falls and doits:: @end menu @@ -2236,23 +2643,23 @@ Examples: @inputfileref{input/@/regression,finger@/-chords@/.ly}. @subsection Dynamics @cindex Dynamics -@cindex @code{\pppp} -@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{\ppppp}, @@ -2266,9 +2673,9 @@ 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 @@ -2283,8 +2690,16 @@ 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, @@ -2298,14 +2713,27 @@ 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 @@ -2350,7 +2778,8 @@ 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 cresc. and dim.) are printed with a +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 @@ -2360,11 +2789,11 @@ dashed line showing their extent. To surpress printing this line, use @refcommands -@cindex @code{\dynamicUp} +@funindex \dynamicUp @code{\dynamicUp}, -@cindex @code{\dynamicDown} +@funindex \dynamicDown @code{\dynamicDown}, -@cindex @code{\dynamicNeutral} +@funindex \dynamicNeutral @code{\dynamicNeutral}. @@ -2425,422 +2854,144 @@ Long running trills are made with @code{\startTrillSpan} and Trills that should be executed on an explicitly specified pitch can be typeset with the command @code{pitchedTrill}, -@lilypond[ragged-right,verbatim,fragment,relative=1] +@lilypond[ragged-right,verbatim,fragment,relative=1,quote] \pitchedTrill c4\startTrillSpan fis -f\stopTrillSpan -@end lilypond - -The first argument is the main note. The pitch of the second -is printed as a stemless note head in parentheses. - - -@refcommands - -@code{\startTrillSpan}, -@cindex @code{\startTrillSpan} -@code{\stopTrillSpan}. -@cindex @code{\stopTrillSpan} - - -@seealso - -Program reference: @internalsref{TrillSpanner}. - - -@node Glissando -@subsection Glissando - -@cindex Glissando -@cindex @code{\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 -@code{\glissando} to a note - -@lilypond[quote,ragged-right,fragment,relative=2,verbatim] -c2\glissando c' -\override Glissando #'style = #'zigzag -c2\glissando c, -@end lilypond - - -@seealso - -Program reference: @internalsref{Glissando}. - -Example files: @file{input/@/regression/@/glissando@/.ly}. - - -@refbugs - -Printing text over the line (such as @emph{gliss.}) is not supported. - - -@node Arpeggio -@subsection Arpeggio - -@cindex Arpeggio -@cindex broken chord -@cindex @code{\arpeggio} - -You can specify an arpeggio sign (also known as broken chord) on a -chord by attaching an @code{\arpeggio} to a chord - -@lilypond[quote,ragged-right,fragment,relative=1,verbatim] -\arpeggio -@end lilypond - -A square bracket on the left indicates that the player should not -arpeggiate the chord - -@lilypond[quote,ragged-right,fragment,relative=1,verbatim] -\arpeggioBracket -\arpeggio -@end lilypond - -The direction of the arpeggio is sometimes denoted by adding an -arrowhead to the wiggly line - -@lilypond[quote,ragged-right,fragment,relative=1,verbatim] -\new Voice { - \arpeggioUp - \arpeggio - \arpeggioDown - \arpeggio -} -@end lilypond - - -@commonprop - -When an arpeggio crosses staves, you may attach an arpeggio to the chords -in both staves and set -@internalsref{PianoStaff}.@code{connectArpeggios} - -@lilypond[quote,ragged-right,fragment,relative=1,verbatim] -\new PianoStaff << - \set PianoStaff.connectArpeggios = ##t - \new Staff { \arpeggio } - \new Staff { \clef bass \arpeggio } ->> -@end lilypond - - -@refcommands - -@code{\arpeggio}, -@cindex @code{\arpeggioUp} -@code{\arpeggioUp}, -@cindex @code{\arpeggioDown} -@code{\arpeggioDown}, -@cindex @code{\arpeggioNeutral} -@code{\arpeggioNeutral}, -@cindex @code{\arpeggioBracket} -@code{\arpeggioBracket}. - - -@seealso - -Notation manual: @ref{Ties}, for writing out arpeggios. - -Program reference: @internalsref{Arpeggio}. - - -@refbugs - -It is not possible to mix connected arpeggios and unconnected -arpeggios in one @internalsref{PianoStaff} at the same point in time. - - - -@node Polyphony -@section Polyphony - -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. - -@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 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. - -@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 } - >> -} +f\stopTrillSpan @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. +The first argument is the main note. The pitch of the second +is printed as a stemless note head in parentheses. -@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}. +@refcommands -@node Explicitly instantiating voices -@subsection Explicitly instantiating voices +@code{\startTrillSpan}, +@funindex \startTrillSpan +@code{\stopTrillSpan}. +@funindex \stopTrillSpan -@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 +@seealso -@noindent -is equivalent to +Program reference: @internalsref{TrillSpanner}. -@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. +@node Glissando +@subsection Glissando -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. +@cindex Glissando +@funindex \glissando -@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 +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 +@code{\glissando} to a note -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 -} +@lilypond[quote,ragged-right,fragment,relative=2,verbatim] +c2\glissando c' +\override Glissando #'style = #'zigzag +c2\glissando c, @end lilypond -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] -\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 +@seealso +Program reference: @internalsref{Glissando}. -@node Collision Resolution -@subsection Collision Resolution +Example files: @file{input/@/regression/@/glissando@/.ly}. -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 } >> +@refbugs + +Printing text over the line (such as @emph{gliss.}) is not supported. + + +@node Arpeggio +@subsection Arpeggio + +@cindex Arpeggio +@cindex broken chord +@funindex \arpeggio + +You can specify an arpeggio sign (also known as broken chord) on a +chord by attaching an @code{\arpeggio} to a chord + +@lilypond[quote,ragged-right,fragment,relative=1,verbatim] +\arpeggio @end lilypond -LilyPond also vertically shifts rests that are opposite of a stem, -for example +A square bracket on the left indicates that the player should not +arpeggiate the chord -@lilypond[quote,ragged-right,fragment,verbatim] -\new Voice << c''4 \\ r4 >> +@lilypond[quote,ragged-right,fragment,relative=1,verbatim] +\arpeggioBracket +\arpeggio @end lilypond +The direction of the arpeggio is sometimes denoted by adding an +arrowhead to the wiggly line -@refcommands +@lilypond[quote,ragged-right,fragment,relative=1,verbatim] +\new Voice { + \arpeggioUp + \arpeggio + \arpeggioDown + \arpeggio +} +@end lilypond -@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. +@commonprop -When LilyPond cannot cope, the @code{force-hshift} -property of the @internalsref{NoteColumn} object and pitched rests can -be used to override typesetting decisions. +When an arpeggio crosses staves, you may attach an arpeggio to the chords +in both staves and set +@internalsref{PianoStaff}.@code{connectArpeggios} -@lilypond[quote,verbatim,ragged-right] -\relative << -{ - - -} \\ { - - \once \override NoteColumn #'force-hshift = #1.7 - -} >> +@lilypond[quote,ragged-right,fragment,relative=1,verbatim] +\new PianoStaff << + \set PianoStaff.connectArpeggios = ##t + \new Staff { \arpeggio } + \new Staff { \clef bass \arpeggio } +>> @end lilypond +@refcommands + +@code{\arpeggio}, +@funindex \arpeggioUp +@code{\arpeggioUp}, +@funindex \arpeggioDown +@code{\arpeggioDown}, +@funindex \arpeggioNeutral +@code{\arpeggioNeutral}, +@funindex \arpeggioBracket +@code{\arpeggioBracket}. + + @seealso -Program reference: the objects responsible for resolving collisions are -@internalsref{NoteCollision} and @internalsref{RestCollision}. +Notation manual: @ref{Ties}, for writing out arpeggios. -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{Arpeggio}. @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. +It is not possible to mix connected arpeggios and unconnected +arpeggios in one @internalsref{PianoStaff} at the same point in time. -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 Falls and doits +@subsection Falls and doits + +Falls and doits can be added to notes using the @code{\bendAfter} +command, + +@lilypond[fragment,ragged-right,relative=2] +\override Score.SpacingSpanner #'shortest-duration-space = #3.0 +c4-\bendAfter #+5 +c4-\bendAfter #-3 +@end lilypond @node Repeats @@ -2850,13 +3001,13 @@ Repetition is a central concept in music, and multiple notations exist for repetitions. @menu -* Repeat types:: -* Repeat syntax:: -* Repeats and MIDI:: -* Manual repeat commands:: -* Tremolo repeats:: -* Tremolo subdivisions:: -* Measure repeats:: +* Repeat types:: +* Repeat syntax:: +* Repeats and MIDI:: +* Manual repeat commands:: +* Tremolo repeats:: +* Tremolo subdivisions:: +* Measure repeats:: @end menu @@ -2864,7 +3015,7 @@ for repetitions. @subsection Repeat types @cindex repeats -@cindex @code{\repeat} +@funindex \repeat The following types of repetition are supported @@ -2880,12 +3031,6 @@ printed, left to right with brackets. This is the standard notation 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. @@ -2893,7 +3038,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 @@ -2901,6 +3046,10 @@ declared within a Voice context. @node Repeat syntax @subsection Repeat syntax +@cindex volta +@cindex prima volta +@cindex seconda volta + LilyPond has one syntactic construct for specifying different types of repeats. The syntax is @@ -2909,7 +3058,7 @@ repeats. The syntax is @end example If you have alternative endings, you may add -@cindex @code{\alternative} +@funindex \alternative @example \alternative @{ @var{alternative1} @@ -2925,6 +3074,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 } @@ -2932,15 +3082,16 @@ 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 this 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'' +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 @q{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. @@ -2953,6 +3104,16 @@ beginning of the example. } @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. @@ -2997,20 +3158,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] @@ -3026,8 +3189,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, @@ -3046,7 +3209,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. @@ -3079,7 +3242,7 @@ c4 c4 @seealso -Program reference: @internalsref{VoltaBracket}, +Program reference: @internalsref{VoltaBracket}, @internalsref{RepeatedMusic}, @internalsref{VoltaRepeatedMusic}, @internalsref{UnfoldedRepeatedMusic}, and @@ -3125,10 +3288,10 @@ 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 +@q{@code{:}[@var{number}]} after the note. The number indicates the duration of the subdivision, and it must be at least 8. A @var{length} value of 8 gives one line across the note stem. If the length is omitted, the last value (stored in @code{tremoloFlags}) is @@ -3182,10 +3345,10 @@ on the @code{countPercentRepeats} property, -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 @@ -3200,7 +3363,7 @@ Program reference: @internalsref{RepeatSlash}, @internalsref{PercentRepeat}, @internalsref{DoublePercentRepeat}, @internalsref{DoublePercentRepeatCounter}, @internalsref{PercentRepeatCounter}, -@internalsref{PercentRepeatedMusic}, and +@internalsref{PercentRepeatedMusic}.