@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{,}
+@findex '
+@findex ,
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
+a flat is formed by adding @code{-es}
+
+@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
+a2 ais a aes
+@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
@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
-bes dis, eeses' ais,
+a2 aisis a aeses
@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
@commonprop
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]
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{?}
+@findex ?
@cindex cautionary accidental
@cindex parenthesized accidental
-@cindex @code{!}
+@findex !
Normally accidentals are printed automatically, but you may also
print them manually. A reminder accidental
@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
@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 clumns 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]
-<c e g>4 <c>8
-@end lilypond
-For more information about chords, see @ref{Chord names}.
+@node Relative octaves
+@subsection Relative octaves
+@cindex Relative
+@cindex Relative octave specification
+@findex \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
-@end lilypond
+@noindent
+@code{c'} is used as the default if no starting pitch is defined.
-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}.
+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.
-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,
+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.
-@lilypond[fragment,quote,ragged-right,verbatim]
-a'4\rest d'4\rest
+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
-@noindent
-This makes manual formatting of
-polyphonic music much easier, since the automatic rest collision
-formatter will leave these rests alone.
+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
-@seealso
+If the preceding item is a chord, the first note of the chord is used
+to determine the first note of the next chord
-Program reference: @internalsref{Rest}.
+@lilypond[quote,ragged-right,fragment,verbatim]
+\relative c' {
+ c <c e g>
+ <c' e g>
+ <c, e' g>
+}
+@end lilypond
+The pitch after the @code{\relative} contains a note name.
-@node Skips
-@subsection Skips
+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}.
-@cindex Skip
-@cindex Invisible rest
-@cindex Space note
-@cindex @code{\skip}
-@cindex @code{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}}
+@node Octave check
+@subsection Octave check
-@lilypond[fragment,quote,ragged-right,verbatim,relative=2]
-a4 a4 s4 a4 \skip 1 a4
-@end lilypond
+@cindex Octave check
-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
+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[quote,ragged-right,verbatim]
-<<
- \relative { a'2 a2 }
- \new Lyrics \lyricmode { \skip 2 bla2 }
->>
-@end lilypond
+@example
+\relative c'' @{ c='' b=' d,='' @}
+@end example
-The skip command is merely an empty musical placeholder. It does not
-produce any output, not even transparent output.
+@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} 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.
+There is also an octave check that produces no visible output. The syntax
-@lilypond[quote,ragged-right,verbatim]
-{ s4 }
-@end lilypond
+@example
+\octave @var{pitch}
+@end example
-The fragment @code{@{ \skip 4 @} } would produce an empty page.
+This checks that @var{pitch} (without quotes) yields @var{pitch} (with
+quotes) in @code{\relative} mode. If not, a warning is printed, and the
+octave is corrected. The @var{pitch} is not printed as a note.
-@seealso
+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.
-Program reference: @internalsref{SkipMusic}.
+@example
+\relative c' @{
+ e
+ \octave a'
+ \octave b'
+@}
+@end example
-@node Durations
-@subsection Durations
+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.
-@cindex duration
-@cindex @code{\longa}
-@cindex @code{\breve}
-@cindex @code{\maxima}
+@lilypond[quote,ragged-right,verbatim,fragment]
+\relative c' {
+ e
+ \octave b
+ a
+}
+@end lilypond
-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}
-@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
+@node Transpose
+@subsection Transpose
+
+@cindex Transpose
+@cindex Transposition of pitches
+@findex \transpose
+
+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
+\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}.
+
+
+@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 music that appears inside a
+@code{\transpose}.
+
+
+@node Rests
+@subsection Rests
+@cindex Rests
+
+@findex \rest
+@findex 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
+@findex \skip
+@findex 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
+@findex \longa
+@findex \breve
+@findex \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 variables @code{\longa} and
+@code{\breve}
+
+@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'' {
+\relative c'' {
a\breve*1/2 \autoBeamOff
a1 a2 a4 a8 a16 a32 a64 a64
\bar "empty"
@node Augmentation dots
@subsection Augmentation dots
-@cindex @code{.}
+@findex .
To obtain dotted note lengths, simply add a dot (`@code{.}') to
the number. Double-dotted notes are produced in a similar way.
situations. The following commands may be used to force a particular
direction manually
-@cindex @code{\dotsUp}
+@findex \dotsUp
@code{\dotsUp},
-@cindex @code{\dotsDown}
+@findex \dotsDown
@code{\dotsDown},
-@cindex @code{\dotsNeutral}
+@findex \dotsNeutral
@code{\dotsNeutral}.
@seealso
@cindex tuplets
@cindex triplets
-@cindex @code{\times}
+@findex \times
Tuplets are made out of a music expression by multiplying all durations
with a fraction
@lilypond[fragment,ragged-right,verbatim,relative=2]
\set tupletNumberFormatFunction = #fraction-tuplet-formatter
\times 4/6 {
- a4 a
+ a4 a
\times 3/5 { a a a a a }
}
@end lilypond
@refcommands
-@cindex @code{\tupletUp}
+@findex \tupletUp
@code{\tupletUp},
-@cindex @code{\tupletDown}
+@findex \tupletDown
@code{\tupletDown},
-@cindex @code{\tupletNeutral}
+@findex \tupletNeutral
@code{\tupletNeutral}.
@commonprop
-@cindex @code{tupletNumberFormatFunction}
+@findex tupletNumberFormatFunction
@cindex tuplet formatting
The property @code{tupletSpannerDuration} specifies how long each
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
+@findex barCheckSynchronize
+@findex |
-@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
+@findex |
+@findex 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
+@node Automatic note splitting
+@subsection Automatic note splitting
-@cindex Relative
-@cindex Relative octave specification
-@cindex @code{\relative}
+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.
-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
+@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
-@example
-\relative @var{startpitch} @var{musicexpr}
-@end example
+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.
-@noindent
-or
-@example
-\relative @var{musicexpr}
-@end example
+@refbugs
-@noindent
-@code{c'} is used as the default if no starting pitch is defined.
+Not all durations (especially those containing tuplets) can be
+represented exactly with normal notes and dots, but the engraver will
+not insert tuplets.
-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.
+@code{Completion_heads_engraver} only affects notes; it does not split
+rests.
-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
+@seealso
-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
+Examples: @inputfileref{input/@/regression,completion@/-heads@/.ly}.
-If the preceding item is a chord, the first note of the chord is used
-to determine the first note of the next chord
+@noindent
-@lilypond[quote,ragged-right,fragment,verbatim]
-\relative c' {
- c <c e g>
- <c' e g>
- <c, e' g>
-}
-@end lilypond
+Program reference: @internalsref{Completion_heads_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}.
+@node Multiple notes at once
+@section Multiple notes at once
+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.
-@node Octave check
-@subsection Octave check
+@menu
+* Chords::
+* Stems::
+* Basic polyphony::
+* Explicitly instantiating voices::
+* Collision Resolution::
+@end menu
-@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,
+@node Chords
+@subsection Chords
-@example
-\relative c'' @{ c='' b=' d,='' @}
-@end example
+@cindex Chords
-@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'}.
+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
-There is also an octave check that produces no visible output. The syntax
+@lilypond[verbatim,ragged-right,fragment,quote,relative=1]
+<c e g>4 <c>8
+@end lilypond
-@example
-\octave @var{pitch}
-@end example
+For more information about chords, see @ref{Chord names}.
-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.
-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.
+@node Stems
+@subsection Stems
-@example
-\relative c' @{
- e
- \octave a'
- \octave b'
-@}
-@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.
+@refcommands
-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.
+@findex \stemUp
+@code{\stemUp},
+@findex \stemDown
+@code{\stemDown},
+@findex \stemNeutral
+@code{\stemNeutral}.
-@lilypond[quote,ragged-right,verbatim,fragment]
-\relative c' {
- e
- \octave b
- a
-}
-@end lilypond
+@commonprop
-@node Transpose
-@subsection Transpose
+To change the direction of stems in the middle of the staff, use
-@cindex Transpose
-@cindex transposition of pitches
-@cindex @code{\transpose}
+@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
-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}.
+@node Basic polyphony
+@subsection Basic polyphony
-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
+@cindex polyphony
-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
+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{\\}
-@example
-\transpose a c @dots{}
-@end example
+@findex \\
-@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,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
-@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
+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 }
+ >>
}
@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}
+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
-\transpose bes c @{ \transpose c bes @{ e4 @dots{} @} @}
+\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}.
-@seealso
-
-Program reference: @internalsref{TransposedMusic}.
-
-
-@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 music that appears inside a
-@code{\transpose}.
-
-
-@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.
-
-
-@node Skipping corrected music
-@subsection Skipping corrected music
-
-
-@cindex @code{skipTypesetting}
-@cindex @code{showLastLength}
-
-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
-
-@verbatim
-showLastLength = R1*5
-\score { ... }
-@end verbatim
+Avoiding the @code{\\} separator also allows nesting polyphony
+constructs, which in some case might be a more natural way to typeset
+the music.
-@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
+@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
-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.
+@node Collision Resolution
+@subsection Collision Resolution
-@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 }
+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
-In polyphonic music, @code{Score.skipTypesetting} will affect all
-voices and staves, saving even more time.
-
-
-@node Automatic note splitting
-@subsection Automatic note splitting
+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
-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 also vertically shifts rests that are opposite of a stem,
+for example
-@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
-}
+@lilypond[quote,ragged-right,fragment,verbatim]
+\new Voice << c''4 \\ r4 >>
@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
-@refbugs
+@findex \oneVoice
+@code{\oneVoice},
+@findex \voiceOne
+@code{\voiceOne},
+@findex \voiceTwo
+@code{\voiceTwo},
+@findex \voiceThree
+@code{\voiceThree},
+@findex \voiceFour
+@code{\voiceFour}.
-Not all durations (especially those containing tuplets) can be
-represented exactly with normal notes and dots, but the engraver will
-not insert tuplets.
+@findex \shiftOn
+@code{\shiftOn},
+@findex \shiftOnn
+@code{\shiftOnn},
+@findex \shiftOnnn
+@code{\shiftOnnn},
+@findex \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.
-@code{Completion_heads_engraver} only affects notes; it does not split
-rests.
+When LilyPond cannot cope, the @code{force-hshift}
+property of the @internalsref{NoteColumn} object and pitched rests can
+be used to override typesetting decisions.
+
+@lilypond[quote,verbatim,ragged-right]
+\relative <<
+{
+ <d g>
+ <d g>
+} \\ {
+ <b f'>
+ \once \override NoteColumn #'force-hshift = #1.7
+ <b f'>
+} >>
+@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
@node Clef
@subsection Clef
-@cindex @code{\clef}
+@findex \clef
The clef indicates which lines of the staff correspond to which
pitches. The clef is set with the @code{\clef} command
@cindex subbass clef
Supported clefs include
-@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
+
+@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
@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
@subsection Key signature
@cindex Key signature
-@cindex @code{\key}
+@findex \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
@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}
+@findex \minor
+@findex \major
+@findex \minor
+@findex \ionian
+@findex \locrian
+@findex \aeolian
+@findex \mixolydian
+@findex \lydian
+@findex \phrygian
+@findex \dorian
@cindex church modes
Here, @var{type} should be @code{\major} or @code{\minor} to get
@seealso
-Program reference: @internalsref{KeyCancellation}, @internalsref{KeySignature}.
+Program reference: @internalsref{KeyCancellation},
+@internalsref{KeySignature}.
@node Time signature
@cindex Time signature
@cindex meter
-@cindex @code{\time}
+@findex \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
}
@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
@cindex partial measure
@cindex measure, partial
@cindex shorten measures
-@cindex @code{\partial}
+@findex \partial
Partial measures, such as an anacrusis or upbeat, are entered using the
@subsection Bar lines
@cindex Bar lines
-@cindex @code{\bar}
+@findex \bar
@cindex measure lines
@cindex repeat bars
@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
@commonprop
-@cindex @code{whichBar}
-@cindex @code{repeatCommands}
-@cindex @code{defaultBarType}
+@findex whichBar
+@findex repeatCommands
+@findex defaultBarType
The command @code{\bar }@var{bartype} is a short cut for doing
@code{\set Timing.whichBar = }@var{bartype}. Whenever @code{whichBar}
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
@subsection Unmetered music
@cindex cadenza
-@cindex @code{\cadenzaOn}
-@cindex @code{\cadenzaOff}
+@findex \cadenzaOn
+@findex \cadenzaOff
Bar lines and bar numbers are calculated automatically. For unmetered
music (cadenzas, for example), this is not desirable. To turn off
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
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}.
@subsection Ties
@cindex tie
-@cindex @code{~}
+@findex ~
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
@lilypond[fragment,verbatim,relative=1,ragged-right]
\set tieWaitForNote = ##t
-\grace { c16[~ e~ g]~ } <c, e g>2
+\grace { c16[~ e~ g]~ } <c, e g>2
\repeat "tremolo" 8 { c32~ c'~ } <c c,>1
@end lilypond
@refcommands
-@cindex @code{\tieUp}
+@findex \tieUp
@code{\tieUp},
-@cindex @code{\tieDown}
+@findex \tieDown
@code{\tieDown},
-@cindex @code{\tieNeutral}
+@findex \tieNeutral
@code{\tieNeutral},
-@cindex @code{\tieDotted}
+@findex \tieDotted
@code{\tieDotted},
-@cindex @code{\tieDashed}
+@findex \tieDashed
@code{\tieDashed},
-@cindex @code{\tieSolid}
+@findex \tieSolid
@code{\tieSolid}.
@refcommands
-@cindex @code{\slurUp}
+@findex \slurUp
@code{\slurUp},
-@cindex @code{\slurDown}
+@findex \slurDown
@code{\slurDown},
-@cindex @code{\slurNeutral}
+@findex \slurNeutral
@code{\slurNeutral},
-@cindex @code{\slurDashed}
+@findex \slurDashed
@code{\slurDashed},
-@cindex @code{\slurDotted}
+@findex \slurDotted
@code{\slurDotted},
-@cindex @code{\slurSolid}
+@findex \slurSolid
@code{\slurSolid}.
@seealso
@refcommands
-@cindex @code{\phrasingSlurUp}
+@findex \phrasingSlurUp
@code{\phrasingSlurUp},
-@cindex @code{\phrasingSlurDown}
+@findex \phrasingSlurDown
@code{\phrasingSlurDown},
-@cindex @code{\phrasingSlurNeutral}
+@findex \phrasingSlurNeutral
@code{\phrasingSlurNeutral}.
percussion instruments. They can be entered using @code{\laissezVibrer},
@lilypond[fragment,ragged-right,verbatim,relative=1]
-<c f g>\laissezVibrer
+<c f g>\laissezVibrer
@end lilypond
@seealso
-Program reference:
+Program reference:
@internalsref{LaissezVibrerTie}
@internalsref{LaissezVibrerTieColumn}
@subsection Manual beams
@cindex beams, manual
-@cindex @code{]}
-@cindex @code{[}
+@findex ]
+@findex [
In some cases it may be necessary to override the automatic beaming
algorithm. For example, the autobeamer will not put beams over rests
@commonprop
-@cindex @code{stemLeftBeamCount}
-@cindex @code{stemRightBeamCount}
+@findex stemLeftBeamCount
+@findex stemRightBeamCount
Normally, beaming patterns within a beam are determined automatically.
If necessary, the properties @code{stemLeftBeamCount} and
\set Score.beatLength = #(ly:make-moment 1 8)
c16[ c c c c c c c]
@end lilypond
-@cindex @code{subdivideBeams}
+@findex subdivideBeams
@noindent
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}
+@findex allowBeamBreak
@cindex beams and line breaks
@cindex beams, kneed
@cindex kneed beams
@node Grace notes
@subsection Grace notes
-@cindex @code{\grace}
+@findex \grace
@cindex ornaments
@cindex grace notes
@cindex appoggiatura
\new Staff { c4 \grace { g8[ b] } c4 } >>
@end lilypond
-@cindex @code{\afterGrace}
+@findex \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
@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
@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}
+@findex \pppp
+@findex \ppp
+@findex \pp
+@findex \p
+@findex \mp
+@findex \mf
+@findex \f
+@findex \ff
+@findex \fff
+@findex \ffff
+@findex \fp
+@findex \sf
+@findex \sff
+@findex \sp
+@findex \spp
+@findex \sfz
+@findex \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]
c2\fp c\sf c\sff c\sp c\spp c\sfz c\rfz
@end lilypond
-@cindex @code{\<}
-@cindex @code{\>}
-@cindex @code{\!}
+@findex \<
+@findex \>
+@findex \!
A crescendo mark is started with @code{\<} and terminated with
@code{\!} or an absolute dynamic. A decrescendo is started with
A hairpin starts at the left edge of the beginning note and ends on the
right edge of the ending note.
+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
@refcommands
-@cindex @code{\dynamicUp}
+@findex \dynamicUp
@code{\dynamicUp},
-@cindex @code{\dynamicDown}
+@findex \dynamicDown
@code{\dynamicDown},
-@cindex @code{\dynamicNeutral}
+@findex \dynamicNeutral
@code{\dynamicNeutral}.
@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},
@lilypond[ragged-right,verbatim,fragment,relative=1]
\pitchedTrill c4\startTrillSpan fis
@refcommands
@code{\startTrillSpan},
-@cindex @code{\startTrillSpan}
+@findex \startTrillSpan
@code{\stopTrillSpan}.
-@cindex @code{\stopTrillSpan}
+@findex \stopTrillSpan
@seealso
@subsection Glissando
@cindex Glissando
-@cindex @code{\glissando}
+@findex \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
@cindex Arpeggio
@cindex broken chord
-@cindex @code{\arpeggio}
+@findex \arpeggio
You can specify an arpeggio sign (also known as broken chord) on a
chord by attaching an @code{\arpeggio} to a chord
@refcommands
@code{\arpeggio},
-@cindex @code{\arpeggioUp}
+@findex \arpeggioUp
@code{\arpeggioUp},
-@cindex @code{\arpeggioDown}
+@findex \arpeggioDown
@code{\arpeggioDown},
-@cindex @code{\arpeggioNeutral}
+@findex \arpeggioNeutral
@code{\arpeggioNeutral},
-@cindex @code{\arpeggioBracket}
+@findex \arpeggioBracket
@code{\arpeggioBracket}.
-@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 }
- >>
-}
-@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{\\} 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
-
-
-@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.
-
-@lilypond[quote,verbatim,ragged-right]
-\relative <<
-{
- <d g>
- <d g>
-} \\ {
- <b f'>
- \once \override NoteColumn #'force-hshift = #1.7
- <b f'>
-} >>
-@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
@subsection Repeat types
@cindex repeats
-@cindex @code{\repeat}
+@findex \repeat
The following types of repetition are supported
@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
@end example
If you have alternative endings, you may add
-@cindex @code{\alternative}
+@findex \alternative
@example
\alternative @{
@var{alternative1}
\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''
+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
@subsection Repeats and MIDI
@cindex expanding repeats
-@cindex @code{\unfoldRepeats}
+@findex \unfoldRepeats
With a little bit of tweaking, all types of repeats can be present
in the MIDI output. This is achieved by applying the
@node Manual repeat commands
@subsection Manual repeat commands
-@cindex @code{repeatCommands}
+@findex repeatCommands
The property @code{repeatCommands} can be used to control the layout of
repeats. Its value is a Scheme list of repeat commands.
@seealso
-Program reference: @internalsref{VoltaBracket}, @internalsref{RepeatedMusic},
+Program reference: @internalsref{VoltaBracket},
+@internalsref{RepeatedMusic},
@internalsref{VoltaRepeatedMusic},
@internalsref{UnfoldedRepeatedMusic}, and
@internalsref{FoldedRepeatedMusic}.
@subsection Tremolo subdivisions
@cindex tremolo marks
-@cindex @code{tremoloFlags}
+@findex tremoloFlags
Tremolo marks can be printed on a single note by adding
`@code{:}[@var{number}]' after the note. The number indicates the
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
@internalsref{PercentRepeat}, @internalsref{DoublePercentRepeat},
@internalsref{DoublePercentRepeatCounter},
@internalsref{PercentRepeatCounter},
-@internalsref{PercentRepeatedMusic}, and
+@internalsref{PercentRepeatedMusic}.
+
+