Doc-it: chapter 1 completed

[lilypond.git] / Documentation / notation / vocal.itely

@c -*- coding: utf-8; mode: texinfo; -*-
@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.  For details, see the Contributors'
    Guide, node Updating translation committishes..
@end ignore

@c \version "2.17.19"

@node Vocal music
@section Vocal music

@lilypondfile[quote]{vocal-headword.ly}

This section explains how to typeset vocal music, and make sure
that the lyrics will be aligned with the notes of their melody.

@menu
* Common notation for vocal music::
* Techniques specific to lyrics::
* Stanzas::
* Songs::
* Choral::
* Opera and stage musicals::
* Chants psalms and hymns::
* Ancient vocal music::

@end menu


@node Common notation for vocal music
@subsection Common notation for vocal music

This section discusses issues common to most types of vocal music.

@menu
* References for vocal music::
* Entering lyrics::
* Aligning lyrics to a melody::
* Automatic syllable durations::
* Manual syllable durations::
* Multiple syllables to one note::
* Multiple notes to one syllable::
* Extenders and hyphens::
@end menu


@node References for vocal music
@unnumberedsubsubsec References for vocal music

This section indicates where to find details of notation issues
that may arise in any type of vocal music.

@itemize

@item
Most styles of vocal music use written text as lyrics.  An
introduction to this notation is to be found in
@rlearning{Setting simple songs}.

@item
Vocal music is likely to require the use of @code{markup} mode,
either for lyrics or for other text elements (characters' names,
etc.)  This syntax is described in @ref{Text markup introduction}.

@item
@notation{Ambitus} may be added at the beginning of vocal staves,
as explained in @ref{Ambitus}.

@item
Dynamic markings by default are placed below the staff, but in
choral music they are usually placed above the staff in order to
avoid the lyrics, as explained in @ref{Score layouts for choral}.

@end itemize

@seealso
Music Glossary:
@rglos{ambitus}.

Learning Manual:
@rlearning{Setting simple songs}.

Notation Reference:
@ref{Text markup introduction},
@ref{Ambitus},
@ref{Score layouts for choral}.

Snippets:
@rlsr{Vocal music}.


@node Entering lyrics
@unnumberedsubsubsec Entering lyrics

@cindex lyrics, entering
@cindex entering lyrics
@cindex formatting in lyrics
@cindex lyrics, formatting
@cindex punctuation in lyrics
@cindex lyrics punctuation
@cindex spaces in lyrics
@cindex quotes in lyrics
@funindex \lyricmode

@c TODO should we explain hyphens here

Lyrics are entered in a special input mode, which can be introduced
by the keyword @code{\lyricmode}, or by using @code{\addlyrics} or
@code{\lyricsto}.  In this special input mode, the input @code{d}
is not parsed as the pitch @notation{D}, but rather as a one-letter
syllable of text.  In other words, syllables are entered like notes
but with pitches replaced by text.

For example:

@example
\lyricmode @{ Three4 blind mice,2 three4 blind mice2 @}
@end example

There are two main methods for specifying the horizontal placement
of the syllables, either by specifying the duration of each syllable
explicitly, as in the example above, or by leaving the lyrics to be
aligned automatically to a melody or other voice of music, using
@code{\addlyrics} or @code{\lyricsto}.  The former method is
described below in @ref{Manual syllable durations}.  The latter
method is described in @ref{Automatic syllable durations}.

A word or syllable of lyrics begins with an alphabetic character
(plus some other characters, see below) and is terminated by any
white space or a digit.  Later characters in the syllable can be any
character that is not a digit or white space.

Because any character that is not a digit or white space is regarded
as part of the syllable, a word is valid even if it ends with
@code{@}}, which often leads to the following mistake:

@example
\lyricmode @{ lah lah lah@}
@end example

In this example, the @code{@}} is included in the final syllable, so the
opening brace is not balanced and the input file will probably not
compile.  Instead, braces should always be surrounded with white space:

@example
\lyricmode @{ lah lah lah @}
@end example

Punctuation, lyrics with accented characters, characters from
non-English languages, or special characters (such as the heart
symbol or slanted quotes), may simply be inserted directly
into the input file, providing it is saved with UTF-8 encoding.
For more information, see @ref{Special characters}.

@lilypond[quote,verbatim]
\relative c'' { d8 c16 a bes8 f e' d c4 }
\addlyrics { „Schad’ um das schö -- ne grü -- ne Band, }
@end lilypond

Normal quotes may be used in lyrics, but they have to be preceded
with a backslash character and the whole syllable has to be
enclosed between additional quotes.  For example,

@lilypond[quote,verbatim]
\relative c' { \time 3/4 e4 e4. e8 d4 e d c2. }
\addlyrics { "\"I" am so lone -- "ly,\"" said she }
@end lilypond

The full definition of a word start in lyrics mode is somewhat more
complex.  A word in lyrics mode is one that begins with an
alphabetic character, @code{_}, @code{?}, @code{!}, @code{:},
@code{'}, the control characters @code{^A} through @code{^F},
@code{^Q} through @code{^W}, @code{^Y}, @code{^^}, any 8-bit
character with an ASCII code over 127, or a two-character
combination of a backslash followed by one of @code{`}, @code{'},
@code{"}, or @code{^}.

@c " to balance double quotes for not-so-bright context-sensitive editors

Great control over the appearance of lyrics comes from using
@code{\markup} inside the lyrics themselves. For explanation of many
options, see @ref{Formatting text}.

@snippets

@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
{formatting-lyrics-syllables.ly}


@seealso
Learning Manual:
@rlearning{Songs}.

Notation Reference:
@ref{Automatic syllable durations},
@ref{Fonts},
@ref{Formatting text},
@ref{Input modes},
@ref{Manual syllable durations},
@ref{Special characters}.

Internals Reference:
@rinternals{LyricText}.

Snippets:
@rlsr{Text}.


@node Aligning lyrics to a melody
@unnumberedsubsubsec Aligning lyrics to a melody

@cindex lyrics, aligning to a melody
@cindex @code{associatedVoice}
@funindex \lyricmode
@funindex \addlyrics
@funindex \lyricsto

Lyrics are printed by interpreting them in the context called
@code{Lyrics}, see @ref{Contexts explained}.

@example
\new Lyrics \lyricmode @{ @dots{} @}
@end example

Lyrics can be aligned with melodies in two main ways:

@itemize

@item
Lyrics can be aligned automatically, with the durations of the
syllables being taken from another voice of music or (in special
circumstances) an associated melody, using @code{\addlyrics},
@code{\lyricsto}, or by setting the @code{associatedVoice} property.
For more details, see @ref{Automatic syllable durations}.

@lilypond[quote,ragged-right,verbatim]
<<
  \new Staff <<
    \time 2/4
    \new Voice = "one" \relative c'' {
      \voiceOne
      c4 b8. a16 g4. r8 a4 ( b ) c2
    }
    \new Voice = "two" \relative c' {
      \voiceTwo
       s2 s4. f8 e4 d c2
    }
  >>

% takes durations and alignment from notes in "one"
  \new Lyrics \lyricsto "one" {
    Life is __ _ love, live __ life.
  }

% takes durations and alignment from notes in "one" initially
% then switches to "two"
  \new Lyrics \lyricsto "one" {
    No more let
    \set associatedVoice = "two"  % must be set one syllable early
    sins and sor -- rows grow.
  }
>>
@end lilypond

The first stanza shows the normal way of entering lyrics.

The second stanza shows how the voice from which the lyric
durations are taken can be changed.  This is useful if the words to
different stanzas fit the notes in different ways and all the
durations are available in Voice contexts.  For more details, see
@ref{Stanzas}.

@item
Lyrics can be aligned independently of the duration of any notes
if the durations of the syllables are specified explicitly,
and entered with @code{\lyricmode}.

@lilypond[quote,ragged-right,verbatim]
<<
  \new Voice = "one" \relative c'' {
    \time 2/4
    c4 b8. a16 g4. f8 e4 d c2
  }

% uses previous explicit duration of 2;
  \new Lyrics \lyricmode {
    Joy to the earth!
  }

% explicit durations, set to a different rhythm
  \new Lyrics \lyricmode {
    Life4 is love,2. live4 life.2
  }
>>
@end lilypond

The first stanza is not aligned with the notes because the durations
were not specified, and the previous value of 2 is used for each
word.

The second stanza shows how the words can be aligned quite
independently from the notes.  This is useful if the words to
different stanzas fit the notes in different ways and the required
durations are not available in a music context.  For more details
see @ref{Manual syllable durations}.  This technique is also useful
when setting dialogue over music; for examples showing this, see
@ref{Dialogue over music}.

When entered in this way the words are left-aligned to the notes
by default, but may be center-aligned to the notes of a melody by
specifying an associated voice, if one exists.  For details, see
@ref{Manual syllable durations}.

@end itemize

@seealso
Learning Manual:
@rlearning{Aligning lyrics to a melody}.

Notation Reference:
@ref{Contexts explained},
@ref{Automatic syllable durations},
@ref{Stanzas},
@ref{Manual syllable durations},
@ref{Dialogue over music},
@ref{Manual syllable durations}.

Internals Reference:
@rinternals{Lyrics}.


@node Automatic syllable durations
@unnumberedsubsubsec Automatic syllable durations

@cindex syllable durations, automatic
@cindex lyrics and melodies
@cindex associatedVoice
@funindex \addlyrics
@funindex \lyricsto

Lyrics can be automatically aligned to the notes of a melody in
three ways:

@itemize

@item
by specifying the named Voice context containing the melody with
@code{\lyricsto},

@item
by introducing the lyrics with @code{\addlyrics} and placing them
immediately after the Voice context containing the melody,

@item
by setting the @code{associatedVoice} property, the alignment of
the lyrics may be switched to a different named Voice context at
any musical moment.

@end itemize

In all three methods hyphens can be drawn between the syllables of
a word and extender lines can be drawn beyond the end of a word.  For
details, see @ref{Extenders and hyphens}.

The @code{Voice} context containing the melody to which the lyrics
are being aligned must not have @qq{died}, or the lyrics after that
point will be lost.  This can happen if there are periods when that
voice has nothing to do.  For methods of keeping contexts alive, see
@ref{Keeping contexts alive}.

@subheading Using @code{\lyricsto}

@cindex \lyricsto
@funindex \lyricsto

Lyrics can be aligned under a melody automatically by specifying
the named Voice context containing the melody with
@code{\lyricsto}:

@lilypond[quote,verbatim,relative=2]
<<
  \new Voice = "melody" {
    a1 a4. a8 a2
  }
  \new Lyrics \lyricsto "melody" {
    These are the words
  }
>>
@end lilypond

@noindent
This aligns the lyrics to the notes of the named @code{Voice}
context, which must already exist.  Therefore normally the
@code{Voice} context is specified first, followed by the
@code{Lyrics} context.  The lyrics themselves follow the
@code{\lyricsto} command.  The @code{\lyricsto} command
invokes lyric mode automatically, so the @code{\lyricmode} keyword
may be omitted.  By default, the lyrics are placed underneath the
notes.  For other placements, see @ref{Placing lyrics vertically}.

@subheading Using @code{\addlyrics}

@cindex \addlyrics
@funindex \addlyrics

The @code{\addlyrics} command is just a convenient shortcut that
can sometimes be used instead of having to set up the lyrics
through a more complicated LilyPond structure.

@example
@{ MUSIC @}
\addlyrics @{ LYRICS @}
@end example

@noindent
is the same as

@example
\new Voice = "blah" @{ MUSIC @}
\new Lyrics \lyricsto "blah" @{ LYRICS @}
@end example

Here is an example,

@lilypond[verbatim,quote]
{
  \time 3/4
  \relative c' { c2 e4 g2. }
  \addlyrics { play the game }
}
@end lilypond

More stanzas can be added by adding more
@code{\addlyrics} sections:


@lilypond[ragged-right,verbatim,quote]
{
  \time 3/4
  \relative c' { c2 e4 g2. }
  \addlyrics { play the game }
  \addlyrics { speel het spel }
  \addlyrics { joue le jeu }
}
@end lilypond

The command @code{\addlyrics} cannot handle polyphonic settings.
Also, it cannot be used to associate lyrics to a @code{TabVoice}.
For these cases one should use @code{\lyricsto}.

@subheading Using associatedVoice

The melody to which the lyrics are being aligned can be changed by
setting the @code{associatedVoice} property,

@example
\set associatedVoice = #"lala"
@end example

@noindent

The value of the property (here: @code{"lala"}) should be the name
of a @code{Voice} context.  For technical reasons, the @code{\set}
command must be placed one syllable before the one to which the
change in voice is to apply.

Here is an example demonstrating its use:

@lilypond[quote,ragged-right,verbatim]
<<
  \new Staff <<
    \time 2/4
    \new Voice = "one" \relative c'' {
      \voiceOne
      c4 b8. a16 g4. r8 a4 ( b ) c2
    }
    \new Voice = "two" \relative c' {
      \voiceTwo
       s2 s4. f8 e8 d4. c2
    }
  >>
% takes durations and alignment from notes in "one" initially
% then switches to "two"
  \new Lyrics \lyricsto "one" {
    No more let
    \set associatedVoice = "two"  % must be set one syllable early
    sins and sor -- rows grow.
  }
>>
@end lilypond

@seealso
Notation Reference:
@ref{Extenders and hyphens},
@ref{Keeping contexts alive},
@ref{Placing lyrics vertically}.


@node Manual syllable durations
@unnumberedsubsubsec Manual syllable durations

In some complex vocal music, it may be desirable to place lyrics
completely independently of notes.  In this case do not use
@code{\lyricsto} or @code{\addlyrics} and do not set
@code{associatedVoice}.  Syllables are entered like notes --
but with pitches replaced by text -- and the duration of each
syllable is entered explicitly after the syllable.

By default, syllables will be left-aligned to the corresponding
musical moment.  Hyphenated lines may be drawn between syllables
as usual, but extender lines cannot be drawn when there is no
associated voice.

Here are two examples:

@lilypond[relative=1,verbatim,quote]
<<
  \new Voice = "melody" {
    \time 3/4
    c2 e4 g2 f
  }
  \new Lyrics \lyricmode {
    play1 the4 game4
  }
>>
@end lilypond


@lilypond[quote,verbatim,ragged-right]
<<
  \new Staff {
    \relative c'' {
      c2 c2
      d1
    }
  }
  \new Lyrics {
    \lyricmode {
      I2 like4. my8 cat!1
    }
  }
  \new Staff {
    \relative c' {
      c8 c c c c c c c
      c8 c c c c c c c
    }
  }
>>
@end lilypond

This technique is useful when writing dialogue over music, see
@ref{Dialogue over music}.

To center-align syllables on the notes at the corresponding musical
moments, set @code{associatedVoice} to the name of the Voice context
containing those notes.  When @code{associatedVoice} is set, both
double hyphens and double underscores can be used to draw
hyphenated lines and extenders under melismata correctly.

@lilypond[relative=1,verbatim,quote]
<<
  \new Voice = "melody" {
    \time 3/4
    c2 e4 g f g
  }
  \new Lyrics \lyricmode {
    \set associatedVoice = #"melody"
    play2 the4 game2. __
  }
>>
@end lilypond

@c TODO see also feature request 707 - show how to do this with manual durations

@seealso
Notation Reference:
@ref{Dialogue over music}.

Internals Reference:
@rinternals{Lyrics},
@rinternals{Voice}.


@node Multiple syllables to one note
@unnumberedsubsubsec Multiple syllables to one note

@funindex _
@cindex spaces, in lyrics
@cindex quotes, in lyrics
@cindex ties, in lyrics

In order to assign more than one syllable to a single note with
spaces between the syllables, you can surround the phrase with
quotes or use a @code{_} character.  Alternatively, you can use
the tilde symbol (@code{~}) to get a lyric tie.

@lilypond[quote,ragged-right,verbatim,relative=2]
{
  { \autoBeamOff
    r8 b c fis, fis c' b e,
  }
  \addlyrics
  {
    \override LyricHyphen.minimum-distance = #1.0 % Ensure hyphens are visible
    Che_in ques -- ta_e_in quel -- l'al -- tr'on -- da
  }
  \addlyrics { "Che in" ques -- "ta e in" quel -- l'al -- tr'on -- da }
  \addlyrics { Che~in ques -- ta~e~in quel -- l'al -- tr'on -- da }
}
@end lilypond

@seealso
Internals Reference:
@rinternals{LyricCombineMusic}.


@node Multiple notes to one syllable
@unnumberedsubsubsec Multiple notes to one syllable

@cindex melisma
@cindex melismata
@cindex phrasing, in lyrics
@funindex \melisma
@funindex \melismaEnd

Sometimes, particularly in Medieval and baroque music, several notes are
sung on one syllable; this is called melisma, see
@rglos{melisma}.  The syllable to a melisma is usually
left-aligned with the first note of the melisma.

When a melisma occurs on a syllable other than the last one in a
word, that syllable is usually joined to the following one with a
hyphenated line.  This is indicated by placing a double hyphen,
@w{@code{--}}, immediately after the syllable.

Alternatively, when a melisma occurs on the last or only syllable in
a word an extender line is usually drawn from the end of the syllable
to the last note of the melisma.  This is indicated by placing a
double underscore, @code{__}, immediately after the word.

There are five ways in which melismata can be indicated:

@itemize

@item
Melismata are created automatically over notes which are tied
together:

@lilypond[quote,relative=2,verbatim]
<<
  \new Voice = "melody" {
    \time 3/4
    f4 g2 ~ |
    g4 e2 ~ |
    e8
  }
  \new Lyrics \lyricsto "melody" {
    Ky -- ri -- e __
  }
>>
@end lilypond

@item
Melismata can be created automatically from the music by placing
slurs over the notes of each melisma.  This is the usual way of
entering lyrics:

@lilypond[quote,relative=2,verbatim]
<<
  \new Voice = "melody" {
    \time 3/4
    f4 g8 ( f e f )
    e8 ( d e2 )
  }
  \new Lyrics \lyricsto "melody" {
    Ky -- ri -- e __
  }
>>
@end lilypond

Note that phrasing slurs do not affect the creation of melismata.

@item
Notes are considered a melisma if they are manually beamed,
providing automatic beaming is switched off.  See
@ref{Setting automatic beam behavior}.

@lilypond[quote,relative=2,verbatim]
<<
  \new Voice = "melody" {
    \time 3/4
    \autoBeamOff
    f4 g8[ f e f]
    e2.
  }
  \new Lyrics \lyricsto "melody" {
    Ky -- ri -- e
  }
>>
@end lilypond

Clearly this is not suited to melismata over notes which are longer
than eighth notes.

@item
An unslurred group of notes will be treated as a melisma if they
are bracketed between @code{\melisma} and @code{\melismaEnd}.

@lilypond[quote,relative=2,verbatim]
<<
  \new Voice = "melody" {
    \time 3/4
    f4 g8
    \melisma
    f e f
    \melismaEnd
    e2.
  }
  \new Lyrics \lyricsto "melody" {
    Ky -- ri -- e
  }
>>
@end lilypond

@item
A melisma can be defined entirely in the lyrics by entering a
single underscore character, @code{_}, for every extra note that has
to be added to the melisma.

@lilypond[verbatim, quote, relative=2]
<<
  \new Voice = "melody" {
    \time 3/4
    f4 g8 f e f
    e8 d e2
  }
  \new Lyrics \lyricsto "melody" {
    Ky -- ri -- _ _ _ e __ _ _
  }
>>
@end lilypond

@end itemize

It is possible to have ties, slurs and manual beams in the melody
without their indicating melismata.  To do this, set
@code{melismaBusyProperties}:

@lilypond[relative=1,verbatim,quote]
<<
  \new Voice = "melody" {
    \time 3/4
    \set melismaBusyProperties = #'()
    c4 d ( e )
    g8 [ f ] f4 ~ f
  }
  \new Lyrics \lyricsto "melody" {
    Ky -- ri -- e e -- le -- i -- son
  }
>>
@end lilypond

Other settings for @code{melismaBusyProperties} can be used to
selectively include or exclude ties, slurs, and beams from the
automatic detection of melismata; see @code{melismaBusyProperties}
in @rinternals{Tunable context properties}.

Alternatively, if all melismata indications are to be ignored,
@code{ignoreMelismata} may be set true;
see @ref{Stanzas with different rhythms}.

If a melisma is required during a passage in which
@code{melismaBusyProperties} is active, it may be indicated by
placing a single underscore in the lyrics for each note which
should be included in the melisma:

@lilypond[relative=1,verbatim,quote]
<<
  \new Voice = "melody" {
    \time 3/4
    \set melismaBusyProperties = #'()
    c4 d ( e )
    g8 [ f ] ~ f4 ~ f
  }
  \new Lyrics \lyricsto "melody" {
    Ky -- ri -- _ e __ _ _ _
  }
>>
@end lilypond


@predefined

@code{\autoBeamOff},
@code{\autoBeamOn},
@code{\melisma},
@code{\melismaEnd}.

@seealso
Musical Glossary:
@rglos{melisma}.

Learning Manual:
@rlearning{Aligning lyrics to a melody}.

Notation Reference:
@ref{Aligning lyrics to a melody},
@ref{Automatic syllable durations},
@ref{Setting automatic beam behavior},
@ref{Stanzas with different rhythms}.

Internals Reference:
@rinternals{Tunable context properties}.

@knownissues
Extender lines under melismata are not created automatically; they
must be inserted manually with a double underscore.


@node Extenders and hyphens
@unnumberedsubsubsec Extenders and hyphens

@cindex melisma
@cindex extender

@c TODO cf Multiple notes to one syllable; should this be merged in?

@c leave this as samp. -gp
In the last syllable of a word, melismata are sometimes indicated with
a long horizontal line starting in the melisma syllable, and ending in
the next one.  Such a line is called an extender line, and it is
entered as @samp{ __ } (note the spaces before and after the two
underscore characters).

@warning{Melismata are indicated in the score with extender lines,
which are entered as one double underscore; but short melismata can
also be entered by skipping individual notes, which are entered as
single underscore characters; these do not make an extender line to be
typeset by default.}

@cindex hyphens

@c leave this as samp. -gp
Centered hyphens are entered as @samp{ -- } between syllables of a
same word (note the spaces before and after the two hyphen
characters).  The hyphen will be centered between the syllables, and
its length will be adjusted depending on the space between the
syllables.

In tightly engraved music, hyphens can be removed.  Whether this
happens can be controlled with the @code{minimum-distance} (minimum
distance between two syllables) and the @code{minimum-length}
(threshold below which hyphens are removed) properties of
@code{LyricHyphen}.

@seealso
Internals Reference:
@rinternals{LyricExtender},
@rinternals{LyricHyphen}.


@node Techniques specific to lyrics
@subsection Techniques specific to lyrics

@c TODO this whole section is to be reorganised

@menu
* Working with lyrics and variables::
* Placing lyrics vertically::
* Placing syllables horizontally::
* Lyrics and repeats::
* Divisi lyrics::
* Polyphony with shared lyrics::
@end menu



@node Working with lyrics and variables
@unnumberedsubsubsec Working with lyrics and variables

@cindex lyrics, using variables

Variables containing lyrics can be created, but the lyrics must be
entered in lyric mode:

@lilypond[quote,verbatim]
musicOne = \relative c'' {
  c4 b8. a16 g4. f8 e4 d c2
}
verseOne = \lyricmode {
  Joy to the world, the Lord is come.
}
\score {
  <<
    \new Voice = "one" {
      \time 2/4
      \musicOne
    }
    \new Lyrics \lyricsto "one" {
      \verseOne
    }
  >>
}
@end lilypond

Durations do not need to be added if the variable is to be invoked
with @code{\addlyrics} or @code{\lyricsto}.

For different or more complex orderings, the best way is to define
the music and lyric variables first, then set up the hierarchy of
staves and lyrics, omitting the lyrics themselves, and then add the
lyrics using @code{\context} underneath.  This ensures that the
voices referenced by @code{\lyricsto} have always been defined
earlier.  For example:

@lilypond[quote,verbatim]
sopranoMusic = \relative c'' { c4 c c c }
contraltoMusic = \relative c'' { a4 a a a }
sopranoWords = \lyricmode { Sop -- ra -- no words }
contraltoWords = \lyricmode { Con -- tral -- to words }

\score {
  \new ChoirStaff <<
    \new Staff {
      \new Voice = "sopranos" {
        \sopranoMusic
      }
    }
    \new Lyrics = "sopranos"
    \new Lyrics = "contraltos"
    \new Staff {
      \new Voice = "contraltos" {
        \contraltoMusic
      }
    }
    \context Lyrics = "sopranos" {
      \lyricsto "sopranos" {
        \sopranoWords
      }
    }
    \context Lyrics = "contraltos" {
      \lyricsto "contraltos" {
        \contraltoWords
      }
    }
  >>
}
@end lilypond

@seealso
Notation Reference:
@ref{Placing lyrics vertically}.

Internals Reference:
@rinternals{LyricCombineMusic},
@rinternals{Lyrics}.


@node Placing lyrics vertically
@unnumberedsubsubsec Placing lyrics vertically

@cindex placement of lyrics
@cindex lyrics, positioning

Depending on the type of music, lyrics may be positioned
above the staff, below the staff, or between staves.  Placing
lyrics below the associated staff is the easiest, and can be
achieved by simply defining the Lyrics context below the Staff
context:

@lilypond[quote,verbatim]
\score {
  <<
    \new Staff {
      \new Voice = "melody" {
        \relative c'' { c4 c c c }
      }
    }
    \new Lyrics {
      \lyricsto "melody" {
        Here are the words
      }
    }
  >>
}
@end lilypond

Lyrics may be positioned above the staff using one of
two methods.  The simplest (and preferred) method
is to use the same syntax as above and explicitly
specify the position of the lyrics:

@lilypond[quote,verbatim]
\score {
  <<
    \new Staff = "staff" {
      \new Voice = "melody" {
        \relative c'' { c4 c c c }
      }
    }
    \new Lyrics \with { alignAboveContext = "staff" } {
      \lyricsto "melody" {
        Here are the words
      }
    }
  >>
}
@end lilypond

Alternatively, a two-step process may be used.  First the Lyrics
context is declared (without any content) before the Staff and
Voice contexts, then the @code{\lyricsto} command is placed after
the Voice declaration it references by using @code{\context}, as
follows:

@lilypond[quote,verbatim]
\score {
  <<
    \new Lyrics = "lyrics" \with {
      % lyrics above a staff should have this override
      \override VerticalAxisGroup.staff-affinity = #DOWN
    }
    \new Staff {
      \new Voice = "melody" {
        \relative c'' { c4 c c c }
      }
    }
    \context Lyrics = "lyrics" {
      \lyricsto "melody" {
        Here are the words
      }
    }
  >>
}
@end lilypond

When there are two voices on separate staves the lyrics may be
placed between the staves using either of these methods.  Here
is an example of the second method:

@lilypond[quote,verbatim]
\score {
  \new ChoirStaff <<
    \new Staff {
      \new Voice = "sopranos" {
        \relative c'' { c4 c c c }
      }
    }
    \new Lyrics = "sopranos"
    \new Lyrics = "contraltos" \with {
      % lyrics above a staff should have this override
      \override VerticalAxisGroup.staff-affinity = #DOWN
    }
    \new Staff {
      \new Voice = "contraltos" {
        \relative c'' { a4 a a a }
      }
    }
    \context Lyrics = "sopranos" {
      \lyricsto "sopranos" {
        Sop -- ra -- no words
      }
    }
    \context Lyrics = "contraltos" {
      \lyricsto "contraltos" {
        Con -- tral -- to words
      }
    }
  >>
}
@end lilypond

Other combinations of lyrics and staves may be generated by
elaborating these examples, or by examining the templates in the
Learning Manual, see @rlearning{Vocal ensembles templates}.

@snippets
@lilypondfile[verbatim,quote,texidoc,doctitle]
{obtaining-2.12-lyrics-spacing-in-newer-versions.ly}

@seealso
Learning Manual:
@rlearning{Vocal ensembles templates}.

Notation Reference:
@ref{Context layout order},
@ref{Creating and referencing contexts}.


@node Placing syllables horizontally
@unnumberedsubsubsec Placing syllables horizontally

@cindex Spacing lyrics
@cindex Lyrics, increasing space between

To increase the spacing between lyrics, set the
@code{minimum-distance} property of @code{LyricSpace}.

@lilypond[relative=1,verbatim,quote,ragged-right]
{
  c c c c
  \override Lyrics.LyricSpace.minimum-distance = #1.0
  c c c c
}
\addlyrics {
  longtext longtext longtext longtext
  longtext longtext longtext longtext
}
@end lilypond

@noindent
To make this change for all lyrics in the score, set the property in the
@code{\layout} block.

@lilypond[verbatim,quote,ragged-right]
\score {
  \relative c' {
  c c c c
  c c c c
  }
  \addlyrics {
  longtext longtext longtext longtext
  longtext longtext longtext longtext
  }
  \layout {
    \context {
      \Lyrics
      \override LyricSpace.minimum-distance = #1.0
    }
  }
}
@end lilypond

@snippets
@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
{lyrics-alignment.ly}

@c TODO: move to LSR -vv

Checking to make sure that text scripts and lyrics are within the margins
requires additional calculations.  To speed up processing slightly, this
feature can be disabled:

@example
\override Score.PaperColumn.keep-inside-line = ##f
@end example

To make lyrics avoid bar lines as well, use

@example
\layout @{
  \context @{
    \Lyrics
      \consists "Bar_engraver"
      \consists "Separating_line_group_engraver"
      \override BarLine.transparent = ##t
  @}
@}
@end example

@node Lyrics and repeats
@unnumberedsubsubsec Lyrics and repeats

@cindex repeats and lyrics
@cindex lyrics, repeating

@subheading Simple repeats

Repeats in @emph{music} are fully described elsewhere; see
@ref{Repeats}.  This section explains how to add lyrics to repeated
sections of music.

Lyrics to a section of music that is repeated should be surrounded
by exactly the same repeat construct as the music, if the words are
unchanged.

@lilypond[verbatim,quote]
\score {
  <<
    \new Staff {
      \new Voice = "melody" {
        \relative c'' {
          a4 a a a
          \repeat volta 2 { b4 b b b }
        }
      }
    }
    \new Lyrics {
      \lyricsto "melody" {
        Not re -- peat -- ed.
        \repeat volta 2 { Re -- peat -- ed twice. }
      }
    }
  >>
}
@end lilypond

The words will then be correctly expanded if the repeats are
unfolded.

@lilypond[verbatim,quote]
\score {
  \unfoldRepeats {
    <<
      \new Staff {
        \new Voice = "melody" {
          \relative c'' {
            a4 a a a
            \repeat volta 2 { b4 b b b }
          }
        }
      }
      \new Lyrics {
        \lyricsto "melody" {
          Not re -- peat -- ed.
          \repeat volta 2 { Re -- peat -- ed twice. }
        }
      }
    >>
  }
}
@end lilypond

If the repeated section is to be unfolded and has different words,
simply enter all the words:

@lilypond[verbatim,quote,ragged-right]
\score {
  <<
    \new Staff {
      \new Voice = "melody" {
        \relative c'' {
          a4 a a a
          \repeat unfold 2 { b4 b b b }
        }
      }
    }
    \new Lyrics {
      \lyricsto "melody" {
        Not re -- peat -- ed.
        The first time words.
        Sec -- ond time words.
      }
    }
  >>
}
@end lilypond

When the words to a repeated volta section are different, the words
to each repeat must be entered in separate @code{Lyrics} contexts,
correctly nested in parallel sections:

@lilypond[verbatim,quote]
\score {
  <<
    \new Staff {
      \new Voice = "melody" {
        \relative c'' {
          a4 a a a
          \repeat volta 2 { b4 b b b }
        }
      }
    }
    \new Lyrics \lyricsto "melody" {
      Not re -- peat -- ed.
      <<
        { The first time words. }
        \new Lyrics {
          \set associatedVoice = "melody"
          Sec -- ond time words.
        }
      >>
    }
  >>
}
@end lilypond

More verses may be added in a similar way:

@lilypond[verbatim,quote]
\score {
  <<
    \new Staff {
      \new Voice = "singleVoice" {
        \relative c'' {
          a4 a a a
          \repeat volta 3 { b4 b b b }
          c4 c c c
        }
      }
    }
    \new Lyrics \lyricsto "singleVoice" {
      Not re -- peat -- ed.
      <<
        { The first time words. }
        \new Lyrics {
          \set associatedVoice = "singleVoice"
          Sec -- ond time words.
        }
        \new Lyrics {
          \set associatedVoice = "singleVoice"
          The third time words.
        }
      >>
      The end sec -- tion.
    }
  >>
}
@end lilypond

@cindex alignBelowContext
@funindex alignBelowContext

However, if this construct is embedded within a multi-staved
context such as a @code{ChoirStaff} the lyrics of the second and
third verses will appear beneath the bottom staff.

To position them correctly use @code{alignBelowContext}:

@lilypond[verbatim,quote]
\score {
  <<
    \new Staff {
      \new Voice = "melody" {
        \relative c'' {
          a4 a a a
          \repeat volta 3 { b4 b b b }
          c4 c c c
        }
      }
    }
    \new Lyrics = "firstVerse" \lyricsto "melody" {
      Not re -- peat -- ed.
      <<
        { The first time words. }
        \new Lyrics = "secondVerse"
        \with { alignBelowContext = #"firstVerse" } {
          \set associatedVoice = "melody"
          Sec -- ond time words.
        }
        \new Lyrics = "thirdVerse"
        \with { alignBelowContext = #"secondVerse" } {
          \set associatedVoice = "melody"
          The third time words.
        }
      >>
      The end sec -- tion.
    }
    \new Voice = "harmony" {
      \relative c' {
        f4 f f f \repeat volta 2 { g8 g g4 g2 } a4 a8. a16 a2
      }
    }
  >>
}
@end lilypond



@c TODO positioning a common line of lyrics

@subheading Repeats with alternative endings

@cindex lyrics, repeats with alternative endings
@cindex repeating lyrics with alternative endings
@cindex alternative endings and lyrics

If the words of the repeated section are the same, exactly the
same structure can be used for both the lyrics and music.

@lilypond[quote,verbatim]
\score {
  <<
    \new Staff {
      \time 2/4
      \new Voice = "melody" {
        \relative c'' {
          a4 a a a
          \repeat volta 2 { b4 b }
          \alternative { { b b } { b c } }
        }
      }
    }
    \new Lyrics {
      \lyricsto "melody" {
        Not re -- peat -- ed.
        \repeat volta 2 { Re -- peat -- }
        \alternative { { ed twice. } { ed twice. } }
      }
    }
  >>
}
@end lilypond

@funindex \skip
@cindex skipping notes in lyrics
@cindex lyrics, skipping notes

But when the repeated section has different words, a repeat
construct cannot be used around the words and @code{\skip} commands
have to be inserted manually to skip over the notes in the
alternative sections which do not apply.

Note: do not use an underscore, @code{_}, to skip notes -- an
underscore indicates a melisma, causing the preceding syllable
to be left-aligned.

@warning{The @code{@bs{}skip} command must be followed by a number,
but this number is ignored in lyrics which derive their durations
from the notes in an associated melody through @code{\addlyrics} or
@code{\lyricsto}.  Each @code{@bs{}skip} skips a single note of any
value, irrespective of the value of the following number.}

@lilypond[verbatim,quote,ragged-right]
\score {
  <<
    \new Staff {
      \time 2/4
      \new Voice = "melody" {
        \relative c'' {
          \repeat volta 2 { b4 b }
          \alternative { { b b } { b c } }
          c4 c
        }
      }
    }
    \new Lyrics {
      \lyricsto "melody" {
        The first time words.
        \repeat unfold 2 { \skip 1 }
        End here.
      }
    }
    \new Lyrics {
      \lyricsto "melody" {
        Sec -- ond
        \repeat unfold 2 { \skip 1 }
        time words.
      }
    }
  >>
}
@end lilypond

@cindex lyrics and tied notes
@funindex \repeatTie

When a note is tied over into two or more alternative endings a
tie is used to carry the note into the first alternative ending and
a @code{\repeatTie} is used in the second and subsequent endings.
This structure causes difficult alignment problems when lyrics are
involved and increasing the length of the alternative sections so
the tied notes are contained wholly within them may give a more
acceptable result.

The tie creates a melisma into the first alternative, but not into
the second and subsequent alternatives, so to align the lyrics
correctly it is necessary to disable the automatic creation of
melismata over the volta section and insert manual skips.

@lilypond[quote,verbatim]
\score {
  <<
    \new Staff {
      \time 2/4
      \new Voice = "melody" {
        \relative c'' {
          \set melismaBusyProperties = #'()
          \repeat volta 2 { b4 b ~}
          \alternative { { b b } { b \repeatTie c } }
          \unset melismaBusyProperties
          c4 c
        }
      }
    }
    \new Lyrics {
      \lyricsto "melody" {
        \repeat volta 2 { Here's a __ }
        \alternative {
          { \skip 1 verse }
          { \skip 1 sec }
        }
        ond one.
      }
    }
  >>
}
@end lilypond

Note that if @code{\unfoldRepeats} is used around a section
containing @code{\repeatTie}, the @code{\repeatTie} should be
removed to avoid both types of tie being printed.

When the repeated section has different words a @code{\repeat}
cannot be used around the lyrics and @code{\skip} commands need to
be inserted manually, as before.

@lilypond[quote,verbatim]
\score {
  <<
    \new Staff {
      \time 2/4
      \new Voice = "melody" {
        \relative c'' {
          \repeat volta 2 { b4 b ~}
          \alternative { { b b } { b \repeatTie c } }
          c4 c
        }
      }
    }
    \new Lyrics {
      \lyricsto "melody" {
        Here's a __ verse.
        \repeat unfold 2 { \skip 1 }
      }
    }
    \new Lyrics {
      \lyricsto "melody" {
        Here's one
        \repeat unfold 2 { \skip 1 }
        more to sing.
      }
    }
  >>
}
@end lilypond

If you wish to show extenders and hyphens into and out of
alternative sections these must be inserted manually.

@lilypond[quote,verbatim]
\score {
  <<
    \new Staff {
      \time 2/4
      \new Voice = "melody" {
        \relative c'' {
          \repeat volta 2 { b4 b ~}
          \alternative { { b b } { b \repeatTie c } }
          c4 c
        }
      }
    }
    \new Lyrics {
      \lyricsto "melody" {
        Here's a __ verse.
        \repeat unfold 2 { \skip 1 }
      }
    }
    \new Lyrics {
      \lyricsto "melody" {
        Here's "a_"
        \skip 1
        "_" sec -- ond one.
      }
    }
  >>
}
@end lilypond

@seealso
Notation Reference:
@ref{Keeping contexts alive},
@ref{Repeats}.


@node Divisi lyrics
@unnumberedsubsubsec Divisi lyrics

@cindex divided lyrics
@cindex lyrics, divided

When just the words and rhythms of the two parts differ with the
pitches remaining the same, temporarily turning off the automatic
detection of melismata and indicating the melisma in the lyrics
may be the appropriate method to use:

@lilypond[quote,verbatim]
\score {
  <<
    \new Voice = "melody" {
      \relative c' {
        \set melismaBusyProperties = #'()
        \slurDown
        \slurDashed
        e4 e8 ( e ) c4 c |
        \unset melismaBusyProperties
        c
      }
    }
    \new Lyrics \lyricsto "melody" {
      They shall not o -- ver -- come
    }
    \new Lyrics \lyricsto "melody" {
      We will _
    }
  >>
}
@end lilypond

When both music and words differ it may be better to display
the differing music and lyrics by naming voice contexts and
attaching lyrics to those specific contexts:

@lilypond[verbatim,ragged-right,quote]
\score {
  <<
    \new Voice = "melody" {
      \relative c' {
        <<
          {
            \voiceOne
            e4 e8 e
          }
          \new Voice = "splitpart" {
            \voiceTwo
            c4 c
          }
        >>
        \oneVoice
        c4 c |
        c
      }
    }
    \new Lyrics \lyricsto "melody" {
      They shall not o -- ver -- come
    }
    \new Lyrics \lyricsto "splitpart" {
      We will
    }
  >>
}
@end lilypond

It is common in choral music to have a voice part split for
several measures.  The @code{<< @{@dots{}@} \\ @{@dots{}@} >>}
construct, where the two (or more) musical expressions are
separated by double backslashes, might seem the proper way to
set the split voices.  This construct, however, will assign
@strong{all} the expressions within it to @strong{NEW Voice
contexts} which will result in @emph{no lyrics} being set for
them since the lyrics will be set to the original voice context
-- not, typically, what one wants.  The temporary polyphonic
passage is the proper construct to use, see section
@emph{Temporary polyphonic passages} in @ref{Single-staff polyphony}.


@node Polyphony with shared lyrics
@unnumberedsubsubsec Polyphony with shared lyrics

@cindex NullVoice
@cindex polyphony, shared lyrics
@cindex lyrics, shared among voices
@cindex \partcombine and lyrics
@funindex \partcombine

When two voices with different rhythms share the same lyrics,
aligning the lyrics to one of the voices may lead to problems in
the other voice.  For example, the second lyric extender below is
too short, since the lyrics are aligned only to the top voice:

@lilypond[quote,verbatim]
soprano = \relative { b'8( c d c) d2 }
alto = \relative { g'2 b8( a g a) }
words = \lyricmode { la __ la __ }

\new Staff <<
  \new Voice = "sopranoVoice" { \voiceOne \soprano }
  \new Voice { \voiceTwo \alto }
  \new Lyrics \lyricsto "sopranoVoice" \words
>>
@end lilypond

To get the desired result, align the lyrics to a new
@code{NullVoice} context containing a suitable combination of the
two voices.  The notes of the @code{NullVoice} context do not
appear on the printed page, but can be used to align the lyrics
appropriately:

@lilypond[quote,verbatim]
soprano = \relative { b'8( c d c) d2 }
alto = \relative { g'2 b8( a g a) }
aligner = \relative { b'8( c d c) b( a g a) }
words = \lyricmode { la __ la __ }

\new Staff <<
  \new Voice { \voiceOne \soprano }
  \new Voice { \voiceTwo \alto }
  \new NullVoice = "aligner" \aligner
  \new Lyrics \lyricsto "aligner" \words
>>
@end lilypond

The @code{NullVoice} context must be inside a @code{Staff}
context, and should only contain notes that are already being
displayed in that staff, and in the same octave.  Otherwise the
@code{NullVoice} may interact with the printed voices in
unexpected ways.  For example, arbitrary notes in the
@code{NullVoice} may cause accidentals to appear (or disappear) on
the staff.

This method also can be used with the @code{\partcombine}
function, which does not allow lyrics on its own:

@lilypond[quote,verbatim]
soprano = \relative { b'8( c d c) d2 }
alto = \relative { g'2 b8( a g a) }
aligner = \relative { b'8( c d c) b( a g a) }
words = \lyricmode { la __ la __ }

\new Staff <<
  \new Voice \partcombine \soprano \alto
  \new NullVoice = "aligner" \aligner
  \new Lyrics \lyricsto "aligner" \words
>>
@end lilypond

@noindent
The @code{\partcombine} function is described in
@ref{Automatic part combining}.

Lastly, this method can be used even when the voices are in
different staves, and is not limited to only two voices:

@lilypond[quote,verbatim]
soprano = \relative { b'8( c d c) d2 }
altoOne = \relative { g'2 b8( a b4) }
altoTwo = \relative { d'2 g4( fis8 g) }
aligner = \relative { b'8( c d c) d( d d d) }
words = \lyricmode { la __ la __ }

\new ChoirStaff <<
  \new Staff <<
    \soprano
    \new NullVoice = "aligner" \aligner
  >>
  \new Lyrics \lyricsto "aligner" \words
  \new Staff \partcombine \altoOne \altoTwo
>>
@end lilypond

However, note that in the second half of the measure above, the
notes in the @code{NullVoice} context reflect the rhythm of the
lower staff, but they do not deviate from the single pitch being
displayed in the staff to which the @code{NullVoice} belongs.
While not actually required in this particular example, it is a
good idea in general to enter the notes in this way.


@node Stanzas
@subsection Stanzas

@menu
* Adding stanza numbers::
* Adding dynamics marks to stanzas::
* Adding singers' names to stanzas::
* Stanzas with different rhythms::
* Printing stanzas at the end::
* Printing stanzas at the end in multiple columns::
@end menu


@node Adding stanza numbers
@unnumberedsubsubsec Adding stanza numbers

@cindex stanza number

Stanza numbers can be added by setting @code{stanza}, e.g.,

@lilypond[quote,ragged-right,verbatim,relative=2]
\new Voice {
  \time 3/4 g2 e4 a2 f4 g2.
} \addlyrics {
  \set stanza = #"1. "
  Hi, my name is Bert.
} \addlyrics {
  \set stanza = #"2. "
  Oh, ché -- ri, je t'aime
}
@end lilypond


@noindent
These numbers are put just before the start of the first syllable.

@c TODO Create and add snippet to show how two lines of a
@c stanza can be grouped together, along these lines:
@c (might need improving a bit) -td

@ignore
leftbrace = \markup { \override #'(font-encoding . fetaBraces) \lookup
#"brace105" }

stanzaOneOne = {
  \set stanza = \markup { "1. " \leftbrace }
  \lyricmode { Child, you're mine and I love you.
    Lend thine ear to what I say.

  }
}

stanzaOneThree =  {
%  \set stanza = \markup { "   "}
  \lyricmode { Child, I have no great -- er joy
    Than to have you walk in truth.

  }
}

\new Voice {
  \repeat volta 2 { c'8 c' c' c' c' c' c'4
                    c'8 c' c' c' c' c' c'4   }
}  \addlyrics { \stanzaOneOne }
   \addlyrics { \stanzaOneThree }

@end ignore

@node Adding dynamics marks to stanzas
@unnumberedsubsubsec Adding dynamics marks to stanzas

Stanzas differing in loudness may be indicated by putting a
dynamics mark before each stanza.  In LilyPond, everything coming in
front of a stanza goes into the @code{StanzaNumber} object; dynamics
marks are no different.  For technical reasons, you have to set the
stanza outside @code{\lyricmode}:

@lilypond[quote,ragged-right,verbatim]
text = {
  \set stanza = \markup { \dynamic "ff" "1. " }
  \lyricmode {
    Big bang
  }
}

<<
  \new Voice = "tune" {
    \time 3/4
    g'4 c'2
  }
\new Lyrics \lyricsto "tune" \text
>>
@end lilypond

@node Adding singers' names to stanzas
@unnumberedsubsubsec Adding singers' names to stanzas

@cindex singer name
@cindex name of singer

Names of singers can also be added.  They are printed at the start of
the line, just like instrument names.  They are created by setting
@code{vocalName}.  A short version may be entered as
@code{shortVocalName}.

@lilypond[ragged-right,quote,verbatim,relative=2]
\new Voice {
  \time 3/4 g2 e4 a2 f4 g2.
} \addlyrics {
  \set vocalName = #"Bert "
  Hi, my name is Bert.
} \addlyrics {
  \set vocalName = #"Ernie "
  Oh, ché -- ri, je t'aime
}
@end lilypond

@node Stanzas with different rhythms
@unnumberedsubsubsec Stanzas with different rhythms

Often, different stanzas of one song are put to one melody in slightly
differing ways.  Such variations can still be captured with
@code{\lyricsto}.

@subsubheading Ignoring melismata

One possibility is that the text has a melisma in one stanza, but
multiple syllables in another.  One solution is to make the faster
voice ignore the melisma.  This is done by setting
@code{ignoreMelismata} in the Lyrics context.

@lilypond[verbatim,ragged-right,quote]
<<
  \relative c' \new Voice = "lahlah" {
    \set Staff.autoBeaming = ##f
    c4
    \slurDotted
    f8.[( g16])
    a4
  }
  \new Lyrics \lyricsto "lahlah" {
    more slow -- ly
  }
  \new Lyrics \lyricsto "lahlah" {
    go
    \set ignoreMelismata = ##t
    fas -- ter
    \unset ignoreMelismata
    still
  }
>>
@end lilypond

@knownissues
Unlike most @code{\set} commands, @code{\set ignoreMelismata} does
not work if prefixed with @code{\once}.  It is necessary to use
@code{\set} and @code{\unset} to bracket the lyrics where melismata
are to be ignored.

@subsubheading Adding syllables to grace notes

@cindex grace notes and lyrics
@cindex lyrics on grace notes

By default, grace notes (e.g. via @code{\grace}) do not get assigned
syllables when using @code{\lyricsto}, but this behavior can be
changed:

@lilypond[verbatim,ragged-right,quote]
<<
  \new Voice = melody \relative c' {
    f4 \appoggiatura a32 b4
    \grace { f16[ a16] } b2
    \afterGrace b2 { f16[ a16] }
    \appoggiatura a32 b4
    \acciaccatura a8 b4
  }
  \new Lyrics
  \lyricsto melody {
    normal
    \set includeGraceNotes = ##t
    case,
    gra -- ce case,
    after -- grace case,
    \set ignoreMelismata = ##t
    app. case,
    acc. case.
  }
>>
@end lilypond

@knownissues
Like @code{associatedVoice}, @code{includeGraceNotes} needs to be
set at latest one syllable before the one which is to be put under a
grace note.  For the case of a grace note at the very beginning of a
piece of music, consider using a @code{\with} or @code{\context}
block:

@lilypond[verbatim,ragged-right,quote]
<<
  \new Voice = melody \relative c' {
    \grace { c16[( d e f] }
    g1) f
  }
  \new Lyrics \with { includeGraceNotes = ##t }
  \lyricsto melody {
    Ah __ fa
  }
>>
@end lilypond

@subsubheading Switching to an alternative melody

@cindex associatedVoice
@cindex alternative melody, switching to

More complex variations in setting lyrics to music are possible.
The melody to which the lyrics are being set can be changed from
within the lyrics by setting the @code{associatedVoice} property:

@lilypond[verbatim,quote]
<<
  \relative c' \new Voice = "lahlah" {
    \set Staff.autoBeaming = ##f
    c4
    <<
      \new Voice = "alternative" {
        \voiceOne
        \tuplet 3/2 {
          % show associations clearly.
          \override NoteColumn.force-hshift = #-3
          f8 f g
        }
      }
      {
        \voiceTwo
        f8.[ g16]
        \oneVoice
      } >>
    a8( b) c
  }
  \new Lyrics \lyricsto "lahlah" {
    Ju -- ras -- sic Park
  }
  \new Lyrics \lyricsto "lahlah" {
    % Tricky: need to set associatedVoice
    % one syllable too soon!
    \set associatedVoice = "alternative" % applies to "ran"
    Ty --
    ran --
    no --
    \set associatedVoice = "lahlah" % applies to "rus"
    sau -- rus Rex
  } >>
@end lilypond

@noindent
The text for the first stanza is set to the melody called
@q{lahlah} in the usual way, but the second stanza is set initally
to the @code{lahlah} context and is then switched to the
@code{alternative} melody for the syllables @q{ran} to @q{sau} by
the lines:

@example
\set associatedVoice = "alternative" % applies to "ran"
Ty --
ran --
no --
\set associatedVoice = "lahlah" % applies to "rus"
sau -- rus Rex
@end example

@noindent
Here, @code{alternative} is the name of the @code{Voice} context
containing the triplet.

Note the placement of the @code{\set associatedVoice} command --
it appears to be one syllable too early, but this is correct.

@warning{The @code{\set associatedVoice} command must be placed
one syllable @emph{before} the one at which the switch to the new
voice is to occur.  In other words, changing the associated Voice
happens one syllable later than expected.  This is for technical
reasons, and it is not a bug.}


@node Printing stanzas at the end
@unnumberedsubsubsec Printing stanzas at the end

Sometimes it is appropriate to have one stanza set
to the music, and the rest added in verse form at
the end of the piece.  This can be accomplished by adding
the extra verses into a @code{\markup} section outside
of the main score block.  Notice that there are two
different ways to force linebreaks when using
@code{\markup}.

@lilypond[ragged-right,verbatim,quote]
melody = \relative c' {
e d c d | e e e e |
d d e d | c1 |
}

text = \lyricmode {
\set stanza = #"1." Ma- ry had a lit- tle lamb,
its fleece was white as snow.
}

\score{ <<
  \new Voice = "one" { \melody }
  \new Lyrics \lyricsto "one" \text
>>
  \layout { }
}
\markup { \column{
  \line{ Verse 2. }
  \line{ All the children laughed and played }
  \line{ To see a lamb at school. }
  }
}
\markup{
  \wordwrap-string #"
  Verse 3.

  Mary took it home again,

  It was against the rule."
}
@end lilypond


@node Printing stanzas at the end in multiple columns
@unnumberedsubsubsec Printing stanzas at the end in multiple columns

When a piece of music has many verses, they are often printed in
multiple columns across the page.  An outdented verse number often
introduces each verse.  The following example shows how to produce such
output in LilyPond.

@lilypond[ragged-right,quote,verbatim]
melody = \relative c' {
  c4 c c c | d d d d
}

text = \lyricmode {
  \set stanza = #"1." This is verse one.
  It has two lines.
}

\score {
  <<
    \new Voice = "one" { \melody }
    \new Lyrics \lyricsto "one" \text
  >>
  \layout { }
}

\markup {
  \fill-line {
    \hspace #0.1 % moves the column off the left margin;
     % can be removed if space on the page is tight
     \column {
      \line { \bold "2."
        \column {
          "This is verse two."
          "It has two lines."
        }
      }
      \combine \null \vspace #0.1 % adds vertical spacing between verses
      \line { \bold "3."
        \column {
          "This is verse three."
          "It has two lines."
        }
      }
    }
    \hspace #0.1 % adds horizontal spacing between columns;
    \column {
      \line { \bold "4."
        \column {
          "This is verse four."
          "It has two lines."
        }
      }
      \combine \null \vspace #0.1 % adds vertical spacing between verses
      \line { \bold "5."
        \column {
          "This is verse five."
          "It has two lines."
        }
      }
    }
  \hspace #0.1 % gives some extra space on the right margin;
  % can be removed if page space is tight
  }
}
@end lilypond


@seealso
Internals Reference:
@rinternals{LyricText},
@rinternals{StanzaNumber}.


@node Songs
@subsection Songs

@menu
* References for songs::
* Lead sheets::
@end menu

@node References for songs
@unnumberedsubsubsec References for songs

Songs are usually written on three staves with the melody for the
singer on the top staff and two staves of piano accompaniment at
the bottom.  The lyrics of the first stanza are printed immediately
underneath the top staff.  If there are just a small number of
further stanzas these can be printed immediately under the first
one, but if there are more stanzas than can be easily accommodated
there the second and subsequent stanzas are printed after the music
as stand-alone text.

All the notational elements needed to write songs are fully described
elsewhere:

@itemize

@item
For constructing the staff layout, see @ref{Displaying staves}.

@item
For writing piano music, see
@ref{Keyboard and other multi-staff instruments}.

@item
For writing the lyrics to a melody line, see
@ref{Common notation for vocal music}.

@item
For placing the lyrics, see @ref{Placing lyrics vertically}.

@item
For entering stanzas, see @ref{Stanzas}.

@item
Songs are frequently printed with the chording indicated by chord
names above the staves.  This is described in @ref{Displaying chords}.

@item
To print fret diagrams of the chords for guitar accompaniment or
accompaniment by other fretted instruments, see @qq{Fret diagram
markups} in @ref{Common notation for fretted strings}.

@end itemize

@seealso
Learning Manual:
@rlearning{Songs}.

Notation Reference:
@ref{Common notation for vocal music},
@ref{Displaying chords},
@ref{Displaying staves},
@ref{Keyboard and other multi-staff instruments},
@ref{Placing lyrics vertically},
@ref{Stanzas}.

Snippets:
@rlsr{Vocal music}.


@node Lead sheets
@unnumberedsubsubsec Lead sheets

Lead sheets may be printed by combining vocal parts and
@q{chord mode}; this syntax is explained in @ref{Chord notation}.

@snippets
@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
{simple-lead-sheet.ly}

@seealso
Notation Reference:
@ref{Chord notation}.


@node Choral
@subsection Choral

@cindex anthems
@cindex part songs
@cindex oratorio
@cindex SATB

This section discusses notation issues that relate most directly
to choral music.  This includes anthems, part songs, oratorio,
etc.

@menu
* References for choral::
* Score layouts for choral::
* Divided voices::
@end menu

@node References for choral
@unnumberedsubsubsec References for choral

Choral music is usually notated on two, three or four staves within
a @code{ChoirStaff} group.  Accompaniment, if required, is placed
beneath in a @code{PianoStaff} group, which is usually reduced in
size for rehearsal of @emph{a cappella} choral works.  The notes for
each vocal part are placed in a @code{Voice} context, with each staff
being given either a single vocal part (i.e., one @code{Voice}) or
a pair of vocal parts (i.e., two @code{Voice}s).

Words are placed in @code{Lyrics} contexts, either underneath each
corresponding music staff, or one above and one below the music
staff if this contains the music for two parts.

Several common topics in choral music are described fully elsewhere:

@itemize

@item
An introduction to creating an SATB vocal score can be found in
the Learning Manual, see @rlearning{Four-part SATB vocal score}.

@item
Several templates suitable for various styles of choral music can
also be found in the Learning Manual, see
@rlearning{Vocal ensembles templates}.

@item
For information about @code{ChoirStaff} and @code{PianoStaff} see
@ref{Grouping staves}.

@item
Shape note heads, as used in Sacred Harp and similar notation, are
described in @ref{Shape note heads}.

@item
When two vocal parts share a staff the stems, ties, slurs, etc., of
the higher part will be directed up and those of the lower part
down.  To do this, use @code{\voiceOne} and @code{\voiceTwo}.  See
@ref{Single-staff polyphony}.

@item
When a vocal part temporarily splits, you should use
@emph{Temporary polyphonic passages}
(see @ref{Single-staff polyphony}).

@end itemize

@predefined
@code{\oneVoice},
@code{\voiceOne},
@code{\voiceTwo}.

@seealso
Learning Manual:
@rlearning{Four-part SATB vocal score},
@rlearning{Vocal ensembles templates}.

Notation Reference:
@ref{Context layout order},
@ref{Grouping staves},
@ref{Shape note heads},
@ref{Single-staff polyphony}.

Snippets:
@rlsr{Vocal music}.

Internals Reference:
@rinternals{ChoirStaff},
@rinternals{Lyrics},
@rinternals{PianoStaff}.


@node Score layouts for choral
@unnumberedsubsubsec Score layouts for choral

Choral music containing four staves, with or without piano
accompaniment, is usually laid out with two systems per page.
Depending on the page size, achieving this may require changes
to several default settings.  The following settings should be
considered:

@itemize

@item
The global staff size can be modified to change the overall size
of the elements of the score.  See @ref{Setting the staff size}.

@item
The distances between the systems, the staves and the lyrics can
all be adjusted independently.  See @ref{Vertical spacing}.

@item
The dimensions of the vertical layout variables can be displayed as
an aid to adjusting the vertical spacing.  This and other
possibilities for fitting the music onto fewer pages are described
in @ref{Fitting music onto fewer pages}.

@item
If the number of systems per page changes from one to two it is
customary to indicate this with a system separator mark between
the two systems.  See @ref{Separating systems}.

@item
For details of other page formatting properties, see
@ref{Page layout}.

@end itemize


Dynamic markings by default are placed below the staff, but in
choral music they are usually placed above the staff in order to
avoid the lyrics.  The predefined command @code{\dynamicUp} does
this for the dynamic markings in a single @code{Voice} context.
If there are many @code{Voice} contexts this predefined command
would have to be placed in every one.  Alternatively its expanded
form can be used to place all dynamic markings in the entire score
above their respective staves, as shown here:

@lilypond[verbatim,quote]
\score {
  \new ChoirStaff <<
    \new Staff {
      \new Voice {
        \relative c'' { g4\f g g g }
      }
    }
    \new Staff {
      \new Voice {
        \relative c' { d4 d d\p d }
      }
    }
  >>
  \layout {
    \context {
      \Score
      \override DynamicText.direction = #UP
      \override DynamicLineSpanner.direction = #UP
    }
  }
}
@end lilypond

@predefined
@code{\dynamicUp}, @code{\dynamicDown}, @code{\dynamicNeutral}.

@seealso
Notation Reference:
@ref{Changing spacing},
@ref{Displaying spacing},
@ref{Fitting music onto fewer pages},
@ref{Page layout},
@ref{Score layout},
@ref{Separating systems},
@ref{Setting the staff size},
@ref{Using an extra voice for breaks},
@ref{Vertical spacing}.

Internals Reference:
@rinternals{VerticalAxisGroup},
@rinternals{StaffGrouper}.


@node Divided voices
@unnumberedsubsubsec Divided voices

@cindex voices, divided

@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
{using-arpeggiobracket-to-make-divisi-more-visible.ly}

@seealso
Notation Reference:
@ref{Expressive marks as lines}.


@node Opera and stage musicals
@subsection Opera and stage musicals

The music, lyrics and dialogue to opera and stage musicals are
usually set out in one or more of the following forms:

@itemize

@item
A @emph{Conductors' Score} containing the full orchestral and vocal
parts, together with libretto cues if there are spoken passages.

@item
@emph{Orchestral Parts} containing the music for the individual
instruments of the orchestra or band.

@item
A @emph{Vocal Score} containing all vocal parts with piano
accompaniment.  The accompaniment is usually an orchestral
reduction, and if so the name of the original orchestral instrument
is often indicated.  Vocal scores sometimes includes stage
directions and libretto cues.

@item
A @emph{Vocal Book} containing just the vocal parts
(no accompaniment), sometimes combined with the libretto.

@item
A @emph{Libretto} containing the extended passages of spoken
dialogue usually found in musicals, together with the words to the
sung parts.  Stage directions are usually included.  LilyPond can
be used to typeset libretti but as they contain no music
alternative methods may be preferable.

@end itemize

The sections in the LilyPond documentation which cover the topics
needed to create scores in the styles commonly found in opera and
musicals are indicated in the References below.  This is followed
by sections covering those techniques which are peculiar to
typesetting opera and musical scores.

@menu
* References for opera and stage musicals::
* Character names::
* Musical cues::
* Spoken music::
* Dialogue over music::
@end menu

@node References for opera and stage musicals
@unnumberedsubsubsec References for opera and stage musicals

@itemize

@item
A conductors' score contains many grouped staves and lyrics.  Ways
of grouping staves is shown in @ref{Grouping staves}.  To nest
groups of staves see @ref{Nested staff groups}.

@item
The printing of empty staves in conductors' scores and vocal scores
is often suppressed.  To create such a @qq{Frenched score} see
@ref{Hiding staves}.

@item
Writing orchestral parts is covered in @ref{Writing parts}.
Other sections in the Specialist notation chapter may be relevant,
depending on the orchestration used.  Many instruments are
transposing instruments, see @ref{Instrument transpositions}.

@item
If the number of systems per page changes from page to page it is
customary to separate the systems with a system separator mark.
See @ref{Separating systems}.

@item
For details of other page formatting properties, see
@ref{Page layout}.

@item
Dialogue cues, stage directions and footnotes can be inserted, see
@ref{Creating footnotes} and @ref{Text}.  Extensive stage directions
can also be added with a section of stand-alone markups between two
@code{\score} blocks, see @ref{Separate text}.

@end itemize

@seealso
Musical Glossary:
@rglos{Frenched score},
@rglos{Frenched staves},
@rglos{transposing instrument}.

Notation Reference:
@ref{Creating footnotes},
@ref{Grouping staves},
@ref{Hiding staves},
@ref{Instrument transpositions},
@ref{Nested staff groups},
@ref{Page layout},
@ref{Separating systems},
@ref{Transpose},
@ref{Writing parts},
@ref{Writing text}.

Snippets:
@rlsr{Vocal music}.


@node Character names
@unnumberedsubsubsec Character names

@cindex character names
@cindex names, character

Character names are usually shown to the left of the staff when the
staff is dedicated to that character alone:

@lilypond[quote,verbatim,ragged-right]
\score {
  <<
    \new Staff {
      \set Staff.vocalName = \markup \smallCaps Kaspar
      \set Staff.shortVocalName = \markup \smallCaps Kas.
      \relative c' {
        \clef "G_8"
        c4 c c c
        \break
        c4 c c c
      }
    }
    \new Staff {
      \set Staff.vocalName = \markup \smallCaps Melchior
      \set Staff.shortVocalName = \markup \smallCaps Mel
      \clef "bass"
      \relative c' {
        a4 a a a
        a4 a a a
      }
    }
  >>
}
@end lilypond

When two or more characters share a staff the character's name is
usually printed above the staff at the start of every section
applying to that character.  This can be done with markup.  Often a
specific font is used for this purpose.

@lilypond[quote,verbatim,relative=1]
\clef "G_8"
c4^\markup \fontsize #1 \smallCaps Kaspar
c c c
\clef "bass"
a4^\markup \fontsize #1 \smallCaps Melchior
a a a
\clef "G_8"
c4^\markup \fontsize #1 \smallCaps Kaspar
c c c
@end lilypond

Alternatively, if there are many character changes, it may be
easier to set up @qq{instrument} definitions for each character at
the top level so that @code{\instrumentSwitch} can be used to
indicate each change.

@lilypond[quote,verbatim]
\addInstrumentDefinition #"kaspar"
  #`((instrumentTransposition . ,(ly:make-pitch -1 0 0))
     (shortInstrumentName . "Kas.")
     (clefGlyph . "clefs.G")
     (clefTransposition . -7)
     (middleCPosition . 1)
     (clefPosition . -2)
     (instrumentCueName . ,(markup #:fontsize 1 #:smallCaps "Kaspar"))
     (midiInstrument . "voice oohs"))

\addInstrumentDefinition #"melchior"
  #`((instrumentTransposition . ,(ly:make-pitch 0 0 0))
     (shortInstrumentName . "Mel.")
     (clefGlyph . "clefs.F")
     (clefTransposition . 0)
     (middleCPosition . 6)
     (clefPosition . 2)
     (instrumentCueName . ,(markup #:fontsize 1 #:smallCaps "Melchior"))
     (midiInstrument . "choir aahs"))

\relative c' {
  \instrumentSwitch "kaspar"
  c4 c c c
  \instrumentSwitch "melchior"
  a4 a a a
  \instrumentSwitch "kaspar"
  c4 c c c
}
@end lilypond

@seealso
Notation Reference:
@ref{Instrument names},
@ref{Scheme functions},
@ref{Text},
@ref{Text markup commands}.

Extending LilyPond:
@rextend{Markup construction in Scheme}.


@node Musical cues
@unnumberedsubsubsec Musical cues

@cindex musical cues
@cindex cues, musical

Musical cues can be inserted in Vocal Scores, Vocal Books and
Orchestral Parts to indicate what music in another part
immediately precedes an entry.  Also, cues are often inserted in the
piano reduction in Vocal Scores to indicate what each orchestral
instrument is playing.  This aids the conductor when a full
Conductors' Score is not available.

The basic mechanism for inserting cues is fully explained in the
main text, see @ref{Quoting other voices} and
@ref{Formatting cue notes}.  But when many cues have to be
inserted, for example, as an aid to a conductor in a vocal score,
the instrument name must be positioned carefully just before and
close to the start of the cue notes.  The following example shows
how this is done.

@lilypond[quote,verbatim]
flute = \relative c'' {
  s4 s4 e g
}
\addQuote "flute" { \flute }

pianoRH = \relative c'' {
  c4. g8
  % position name of cue-ing instrument just before the cue notes,
  % and above the staff
  \new CueVoice {
    \override InstrumentSwitch.self-alignment-X = #RIGHT
    \set instrumentCueName = "Flute"
  }
  \cueDuring "flute" #UP { g4 bes4 }
}
pianoLH = \relative c { c4 <c' e> e, <g c> }

\score {
  \new PianoStaff <<
    \new Staff {
      \pianoRH
    }
    \new Staff {
      \clef "bass"
      \pianoLH
    }
  >>
}
@end lilypond

If a transposing instrument is being quoted the instrument part should
specify its key so the conversion of its cue notes will be done
automatically.  The example below shows this transposition for a
B-flat clarinet.  The notes in this example are low on the staff so
@code{DOWN} is specified in @code{\cueDuring} (so the stems are
down) and the instrument name is positioned below the staff.  Note
also that the piano right-hand voice is explicitly declared.  This
is because the cue notes in this example begin at the start of the
first bar and this would otherwise cause the entire piano right-hand
notes to be placed in a @code{CueVoice} context.

@lilypond[quote,verbatim]
clarinet = \relative c' {
  \transposition bes
  fis4 d d c
}
\addQuote "clarinet" { \clarinet }

pianoRH = \relative c'' {
  \transposition c'
  % position name of cue-ing instrument below the staff
  \new CueVoice {
    \override InstrumentSwitch.self-alignment-X = #RIGHT
    \override InstrumentSwitch.direction = #DOWN
    \set instrumentCueName = "Clar."
  }
  \cueDuring "clarinet" #DOWN { c4. g8 }
  g4 bes4
}
pianoLH = \relative c { c4 <c' e> e, <g c> }

\score {
  <<
    \new PianoStaff <<
      \new Staff {
        \new Voice {
          \pianoRH
        }
      }
      \new Staff {
        \clef "bass"
        \pianoLH
      }
    >>
  >>
}
@end lilypond

From these two examples it is clear that inserting many cues in a
Vocal Score would be tedious, and the notes of the piano part would
become obscured.  However, as the following snippet shows, it is
possible to define a music function to reduce the amount of typing
and to make the piano notes clearer.

@snippets
@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
{adding-orchestral-cues-to-a-vocal-score.ly}

@seealso
Musical Glossary:
@rglos{cue-notes}.

Notation Reference:
@ref{Aligning objects},
@ref{Direction and placement},
@ref{Formatting cue notes},
@ref{Quoting other voices},
@ref{Using music functions}.

Snippets:
@rlsr{Vocal music}.

Internals Reference:
@rinternals{InstrumentSwitch},
@rinternals{CueVoice}.

@knownissues
@code{\cueDuring} automatically inserts a @code{CueVoice} context
and all cue notes are placed in that context.  This means it is not
possible to have two overlapping sequences of cue notes by this
technique.  Overlapping sequences could be entered by explicitly
declaring separate @code{CueVoice} contexts and using
@code{\quoteDuring} to extract and insert the cue notes.


@node Spoken music
@unnumberedsubsubsec Spoken music

@cindex parlato
@cindex Sprechgesang
Such effects as @q{parlato} or @q{Sprechgesang} require performers to
speak without pitch but still with rhythm; these are notated by cross
note heads, as demonstrated in @ref{Special note heads}.

@c TODO add "marking-notes-on-spoken-parts" snippet -vv
@c add "showing the rhythm of a melody" snip
@c add "one staff-line notation"
@c add "improvisation" ref
@c add "lyrics independents of notes" ref

@node Dialogue over music
@unnumberedsubsubsec Dialogue over music

Dialogue over music is usually printed over the staves in an italic
font, with the start of each phrase keyed in to a particular music
moment.

For short interjections a simple markup suffices.

@lilypond[quote,verbatim,relative=2]
a4^\markup { \smallCaps { Alex - } \italic { He's gone } } a a a
a4 a a^\markup { \smallCaps { Bethan - } \italic Where? } a
a4 a a a
@end lilypond

For longer phrases it may be necessary to expand the music to make
the words fit neatly.  There is no provision in LilyPond to do this
fully automatically, and some manual intervention to layout the
page will be necessary.

For long phrases or for passages with a lot of closely packed
dialogue, using a Lyrics context will give better results.  The
Lyrics context should not be associated with a music Voice; instead
each section of dialogue should be given an explicit duration.  If
there is a gap in the dialogue, the final word should be separated
from the rest and the duration split between them so that the
underlying music spaces out smoothly.

If the dialogue extends for more than one line it will be necessary
to manually insert @code{\break}s and adjust the placing of the
dialogue to avoid running into the right margin.  The final word of
the last measure on a line should also be separated out, as above.

Here is an example illustrating how this might be done.

@c This should be a snippet, but it can't be as it needs to be
@c manually adjusted to suit the imposed line length.  -td

@lilypond[quote,verbatim,ragged-right]
music = \relative c'' {
  \repeat unfold 3 { a4 a a a }
}

dialogue = \lyricmode {
  \markup {
    \fontsize #1 \upright \smallCaps Abe:
    "Say this over measures one and"
  }4*7
  "two"4 |
  \break
  "and this over measure"4*3
  "three"4 |
}

\score {
  <<
    \new Lyrics \with {
      \override LyricText.font-shape = #'italic
      \override LyricText.self-alignment-X = #LEFT
    }
    { \dialogue }
    \new Staff {
      \new Voice { \music }
    }
  >>
}
@end lilypond

@c TODO show use of \column to produce dialogue on two lines

@seealso
Notation Reference:
@ref{Manual syllable durations},
@ref{Text}.

Internal Reference:
@rinternals{LyricText}.


@node Chants psalms and hymns
@subsection Chants psalms and hymns

@cindex chants
@cindex psalms
@cindex hymns
@cindex religious music

The music and words for chants, psalms and hymns usually follow a
well-established format in any particular church.  Although the
formats may differ from church to church the type-setting problems
which arise are broadly similar, and are covered in this section.

@menu
* References for chants and psalms::
* Setting a chant::
* Pointing a psalm::
* Partial measures in hymn tunes::
@end menu

@node References for chants and psalms
@unnumberedsubsubsec References for chants and psalms

Typesetting Gregorian chant in various styles of ancient notation
is described in @ref{Ancient notation}.

@seealso
Notation reference:
@ref{Ancient notation}.

Snippets:
@rlsr{Vocal music}.


@node Setting a chant
@unnumberedsubsubsec Setting a chant

Modern chant settings use modern notation with varying numbers of
elements taken from ancient notation.  Some of the elements and
methods to consider are shown here.

Chants often use quarter notes without stems to indicate the pitch,
with the rhythm being taken from the spoken rhythm of the words.

@lilypond[verbatim,quote]
stemOff = { \override Staff.Stem.transparent = ##t }

\relative c' {
  \stemOff
  a'4 b c2 |
}

@end lilypond

Chants often omit the bar lines or use shortened or dotted bar
lines to indicate pauses in the music.  To omit all bar lines from
all staves remove the bar line engraver completely:

@lilypond[verbatim,quote]
\score {
  \new StaffGroup <<
    \new Staff {
      \relative c'' {
        a4 b c2 |
        a4 b c2 |
        a4 b c2 |
      }
    }
    \new Staff {
      \relative c'' {
        a4 b c2 |
        a4 b c2 |
        a4 b c2 |
      }
    }
  >>
  \layout {
    \context {
      \Staff
      \remove "Bar_engraver"
    }
  }
}
@end lilypond

Bar lines can also be removed on a staff-by-staff basis:

@lilypond[verbatim, quote]
\score {
  \new ChoirStaff <<
    \new Staff
    \with { \remove "Bar_engraver" } {
      \relative c'' {
        a4 b c2 |
        a4 b c2 |
        a4 b c2 |
      }
    }
    \new Staff {
      \relative c'' {
        a4 b c2 |
        a4 b c2 |
        a4 b c2 |
      }
    }
  >>
}
@end lilypond

To remove bar lines from just a section of music treat it as a
cadenza.  If the section is long you may need to insert dummy
bar lines with @code{\bar ""} to show where the line should break.

@lilypond[verbatim,quote,relative=2]
a4 b c2 |
\cadenzaOn
a4 b c2
a4 b c2
\bar ""
a4 b c2
a4 b c2
\cadenzaOff
a4 b c2 |
a4 b c2 |
@end lilypond

Rests or pauses in chants can be indicated by modified bar lines.

@lilypond[verbatim, quote,relative=2]
a4
\cadenzaOn
b c2
a4 b c2
\bar "'"
a4 b c2
a4 b c2
\bar ";"
a4 b c2
\bar "!"
a4 b c2
\bar "||"
@end lilypond

Alternatively, the notation used in Gregorian chant for pauses or
rests is sometimes used even though the rest of the notation is
modern.  This uses a modified @code{\breathe} mark:

@lilypond[verbatim,quote]
divisioMinima = {
  \once \override BreathingSign.stencil = #ly:breathing-sign::divisio-minima
  \once \override BreathingSign.Y-offset = #0
  \breathe
}
divisioMaior = {
  \once \override BreathingSign.stencil = #ly:breathing-sign::divisio-maior
  \once \override BreathingSign.Y-offset = #0
  \breathe
}
divisioMaxima = {
  \once \override BreathingSign.stencil = #ly:breathing-sign::divisio-maxima
  \once \override BreathingSign.Y-offset = #0
  \breathe
}
finalis = {
  \once \override BreathingSign.stencil = #ly:breathing-sign::finalis
  \once \override BreathingSign.Y-offset = #0
  \breathe
}

\score {
  \relative c'' {
    g2 a4 g
    \divisioMinima
    g2 a4 g
    \divisioMaior
    g2 a4 g
    \divisioMaxima
    g2 a4 g
    \finalis
  }
  \layout {
    \context {
      \Staff
      \remove "Bar_engraver"
    }
  }
}
@end lilypond

Chants usually omit the time signature and often omit the clef too.

@lilypond[verbatim,quote]
\score {
  \new Staff {
    \relative c'' {
      a4 b c2 |
      a4 b c2 |
      a4 b c2 |
    }
  }
  \layout {
    \context {
      \Staff
      \remove "Bar_engraver"
      \remove "Time_signature_engraver"
      \remove "Clef_engraver"
    }
  }
}
@end lilypond

Chants for psalms in the Anglican tradition are usually either
@emph{single}, with 7 bars of music, or @emph{double}, with two lots
of 7 bars.  Each group of 7 bars is divided into two halves,
corresponding to the two halves of each verse, usually separated by
a double bar line.  Only whole and half notes are used.  The 1st bar
in each half always contains a single chord of whole notes.  This is
the @qq{reciting note}.  Chants are usually centered on the page.

@lilypond[verbatim,quote]
SopranoMusic = \relative g' {
  g1 | c2 b | a1 | \bar "||"
  a1 | d2 c | c b | c1 | \bar "||"
}

AltoMusic = \relative c' {
  e1 | g2 g | f1 |
  f1 | f2 e | d d | e1 |
}

TenorMusic = \relative a {
  c1 | c2 c | c1 |
  d1 | g,2 g | g g | g1 |
}

BassMusic =  \relative c {
  c1 | e2 e | f1 |
  d1 | b2 c | g' g | c,1 |
}

global = {
  \time 2/2
}

% Use markup to center the chant on the page
\markup {
  \fill-line {
    \score {  % centered
      <<
        \new ChoirStaff <<
          \new Staff <<
            \global
            \clef "treble"
            \new Voice = "Soprano" <<
              \voiceOne
              \SopranoMusic
            >>
            \new Voice = "Alto" <<
              \voiceTwo
              \AltoMusic
            >>
          >>
          \new Staff <<
            \clef "bass"
            \global
            \new Voice = "Tenor" <<
              \voiceOne
              \TenorMusic
            >>
            \new Voice = "Bass" <<
              \voiceTwo
              \BassMusic
            >>
          >>
        >>
      >>
      \layout {
        \context {
          \Score
          \override SpacingSpanner.base-shortest-duration = #(ly:make-moment 1/2)
        }
        \context {
          \Staff
          \remove "Time_signature_engraver"
        }
      }
    }  % End score
  }
}  % End markup
@end lilypond

Some other approaches to setting such a chant are shown in the first
of the following snippets.

@snippets

@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
{chant-or-psalms-notation.ly}

Canticles and other liturgical texts may be set more freely, and
may use notational elements from ancient music.  Often the words
are shown underneath and aligned with the notes.  If so, the notes
are spaced in accordance with the syllables rather than the notes'
durations.

@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
{ancient-notation-template----modern-transcription-of-gregorian-music.ly}

@seealso
Learning Manual:
@rlearning{Visibility and color of objects},
@rlearning{Vocal ensembles templates}.

Notation Reference:
@ref{Ancient notation},
@ref{Bar lines},
@ref{Modifying context plug-ins},
@ref{Typesetting Gregorian chant},
@ref{Unmetered music},
@ref{Visibility of objects}.


@node Pointing a psalm
@unnumberedsubsubsec Pointing a psalm

The words to an Anglican psalm are usually printed in separate
verses centered underneath the chant.

Single chants (with 7 bars) are repeated for every verse.  Double
chants (with 14 bars) are repeated for every pair of verses.  Marks
are inserted in the words to show how they should be fitted to the
chant.  Each verse is divided into two halves.  A colon is usually
used to indicate this division.  This corresponds to the double bar
line in the music.  The words before the colon are sung to the first
three bars of music; the words after the colon are sung to the last
four bars.

Single bar lines (or in some psalters an inverted comma or similar
symbol) are inserted between words to indicate where the bar lines
in the music fall.  In markup mode a single bar line can be entered
with the bar check symbol, @code{|}.

@lilypond[verbatim,quote]
\markup {
  \fill-line {
    \column {
      \left-align {
        \line { O come let us sing | unto the | Lord : let }
        \line { us heartily rejoice in the | strength of | our }
        \line { sal- | -vation. }
      }
    }
  }
}
@end lilypond

Other symbols may require glyphs from the @code{fetaMusic} fonts.
For details, see @ref{Fonts}.

@lilypond[verbatim,quote]
tick = \markup {
  \raise #1 \fontsize #-5 \musicglyph #"scripts.rvarcomma"
}
\markup {
  \fill-line {
    \column {
      \left-align {
        \line { O come let us sing \tick unto the \tick Lord : let }
        \line {
          us heartily rejoice in the \tick strength of \tick our
        }
        \line { sal \tick vation. }
      }
    }
  }
}
@end lilypond

Where there is one whole note in a bar all the words corresponding
to that bar are recited on that one note in speech rhythm.  Where
there are two notes in a bar there will usually be only one or two
corresponding syllables.  If there are more that two syllables a
dot is usually inserted to indicate where the change in note occurs.

@lilypond[verbatim,quote]
dot = \markup {
  \raise #0.7 \musicglyph #"dots.dot"
}
tick = \markup {
  \raise #1 \fontsize #-5 \musicglyph #"scripts.rvarcomma"
}
\markup {
  \fill-line {
    \column {
      \left-align {
        \line {
          O come let us sing \tick unto \dot the \tick Lord : let
        }
        \line {
          us heartily rejoice in the \tick strength of \tick our
        }
        \line { sal \tick vation. }
      }
    }
  }
}
@end lilypond

In some psalters an asterisk is used to indicate a break in a
recited section instead of a comma, and stressed or slightly
lengthened syllables are indicated in bold text.

@lilypond[verbatim,quote]
dot = \markup {
  \raise #0.7 \musicglyph #"dots.dot"
}
tick = \markup {
  \raise #1 \fontsize #-5 \musicglyph #"scripts.rvarcomma"
}
\markup {
  \fill-line {
    \column {
      \left-align {
        \line { Today if ye will hear his voice * }
        \line {
          \concat { \bold hard en }
          | not your | hearts : as in the pro-
        }
        \line { vocation * and as in the \bold day of tempt- | }
        \line { -ation | in the | wilderness. }
      }
    }
  }
}
@end lilypond

In other psalters an accent is placed over the syllable to indicate
stress.

@lilypond[verbatim,quote]
tick = \markup {
  \raise #2 \fontsize #-5 \musicglyph #"scripts.rvarcomma"
}
\markup {
  \fill-line {
    \column {
      \left-align {
        \line {
          O come let us \concat {
            si \combine \tick ng
          }
          | unto the | Lord : let
        }
        \line {
          us heartily \concat {
            rejo \combine \tick ice
          }
          in the | strength of | our
        }
        \line { sal- | -vation. }
      }
    }
  }
}
@end lilypond

The use of markup to center text, and arrange lines in columns is
described in @ref{Formatting text}.

Most of these elements are shown in one or other of the two verses
in the template, see @rlearning{Psalms}.

@seealso
Learning Manual:
@rlearning{Psalms},
@rlearning{Vocal ensembles templates}.

Notation Reference:
@ref{Fonts},
@ref{Formatting text}.


@node Partial measures in hymn tunes
@unnumberedsubsubsec Partial measures in hymn tunes

Hymn tunes frequently start and end every line of music with
partial measures so that each line of music corresponds exactly
with a line of text.  This requires a @code{\partial} command at
the start of the music and @code{\bar "|"} or @code{\bar "||"}
commands at the end of each line.

@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
{hymn-template.ly}


@node Ancient vocal music
@subsection Ancient vocal music

Ancient vocal music is supported, as explained in
@ref{Ancient notation}.

@c TODO

@c Add "Printing both the ancient and the modern clef in vocal music" snippet,
@c and "Transcription of Ancient music with incipit" snippet. -vv

@seealso
Notation Reference:
@ref{Ancient notation}.