Doc: NR 2.1 Vocal: use vocalName rather than instrumentName

[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.12.0"

@node Vocal music
@section Vocal music

@c TODO: inspirational headword

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::
* Skipping notes::
* 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 of for other text elements (character's 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}.

@end itemize

@seealso
Music Glossary:
@rglos{ambitus}.

@node Entering lyrics
@unnumberedsubsubsec Entering lyrics

@cindex lyrics, entering
@cindex entering lyrics
@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 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

@cindex overrides in lyric mode
@funindex \override in \lyricmode

Similarly, in lyric mode, a period will be included in the
alphabetic sequence that it follows.  As a consequence, spaces
must be inserted around the period in @code{\override} commands.
Do @emph{not} write

@example
\override Score.LyricText #'font-shape = #'italic
@end example

@noindent
but instead use

@example
\override Score . LyricText #'font-shape = #'italic
@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{Text encoding}.

@lilypond[quote,verbatim]
\relative c' { e4 f e d e f e2 }
\addlyrics { He said: “Let my peo -- ple go.” }
@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

@seealso
Learning Manual:
@rlearning{Songs}.

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

Internals Reference:
@rinternals{LyricText}.


@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 default durations 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 default 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 technical 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}.

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" {
    a4 a a a
  }
  \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,fragment,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.
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}.

@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},
@ref{Keeping contexts alive}.

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
code the tilde symbol (@code{~}) to get a lyric tie.  The lyric
tie is implemented with the Unicode character U+203F, so be
sure to have a font (like DejaVuLGC) installed that includes this
glyph.

@lilypond[quote,ragged-right,fragment,verbatim]
\time 3/4
\relative c' { c2 e4 g2 e4 }
\addlyrics { gran- de_a- mi- go }
\addlyrics { pu- "ro y ho-" nes- to }
\addlyrics { pu- ro~y~ho- nes- to }
@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 music, several notes are to be
sung on one syllable; such vocalises are called melismata, or
@rglos{melisma}s.  The syllable to a melisma is usually
left-aligned with the first note of the melisma.

When a melisma occurs on a syllable other that 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,
@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" {
    Ki -- 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" {
    Ki -- ri -- e __
  }
>>
@end lilypond

@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" {
    Ki -- ri -- e
  }
>>
@end lilypond

Clearly this is not suited to melisma 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" {
    Ki -- ri -- e
  }
>>
@end lilypond

Note that this method cannot be used to indicate two melismata if
the first one is immediately followed by another.

@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" {
    Ki -- 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} and indicate the melismata with single
underscores in the lyrics, one underscore for each extra note:

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

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

@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}.

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 Skipping notes
@unnumberedsubsubsec Skipping notes

Making a lyric line run slower than the melody can be achieved by
inserting @code{\skip}s into the lyrics.  For every @code{\skip},
the text will be delayed by another note.  The @code{\skip} command
must be followed by a valid duration, but this is ignored when
@code{\skip} is used in lyrics which derive their durations from the
notes in an associated melody through @code{\addlyrics} or
@code{\lyricsto}.

@lilypond[verbatim,ragged-right,quote]
\relative c' { c c g' }
\addlyrics {
  twin -- \skip 4
  kle
}
@end lilypond


@node Extenders and hyphens
@unnumberedsubsubsec Extenders and hyphens

@cindex melisma
@cindex extender

@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).


@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::
@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 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 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 comes after
the Voice declaration it references, as follows:

@lilypond[quote,verbatim]
\score {
  <<
    \new Lyrics = "lyrics"
    \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"
    \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
@rlearning{Vocal ensembles} templates in the Learning Manual.

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

Notation Reference:
@ref{Aligning contexts},
@ref{Creating 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,verbatim,fragment,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
layout.

@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

@c @snippets
@c This snippet has been renamed to "lyrics-alignment.ly"
@c update as soon as lsr/is updated -vv
@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
@c {lyrics-alignment.ly}

@c TODO: move to LSR -vv
@snippets

Checking to make sure that text scripts and lyrics are within the margins is
a relatively large computational task.  To speed up processing, LilyPond does
not perform such calculations by default; to enable it, use

@example
\override Score.PaperColumn #'keep-inside-line = ##t
@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

@c TODO Create and add lsr example of lyricMelismaAlignment
@c It's used like this to center-align all lyric syllables,
@c even when notes are tied. -td

@ignore
\layout
{
     \context { \Score lyricMelismaAlignment = #0 }
}
@end ignore


@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

@cindex lyric skip
@funindex \skip

When the words to a repeated volta section are different, the words
to each repeat must be entered in separate @code{Lyrics} contexts.
Earlier unrepeated sections must be skipped in the second and
subsequent repeats.  The easiest way to skip several notes is to
use @code{\repeat unfold} around the @code{\skip} command.

Note: do not use an underscore, @code{_}, to skip notes in this
particular case.  As this syntax indicates a melisma, it will cause
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]
\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 {
      \lyricsto "melody" {
        % skip 4 notes of any duration
        \repeat unfold 4 { \skip 1 }
        Sec -- ond time words.
      }
    }
  >>
}
@end lilypond

@cindex lyrics, repeating with a temporary voice

An alternative way, which avoids skips and having to count notes,
is to use a temporary voice for the repeated section.  This may be
preferable if the earlier sections are still subject to change.  A
temporary voice can be inserted anywhere in the main music stream
in parallel with it, as shown below, but it may be necessary to
keep the main voice alive in complex scores when using this
technique; see @ref{Keeping contexts alive}.

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

@c TODO lowering 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

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 as described in the previous section to
skip over the notes in the alternative sections which do not apply.

@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



@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


@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,fragment]
\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[fragment,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.  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

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]
\relative c' {
  f4 \appoggiatura a32 b4
  \grace { f16[ a16] } b2
  \afterGrace b2 { f16[ a16] }
  \appoggiatura a32 b4
  \acciaccatura a8 b4
}
\addlyrics {
  normal
  \set includeGraceNotes = ##t
  case,
  gra -- ce case,
  after -- grace case,
  \set ignoreMelismata = ##t
  app. case,
  acc. case.
}
@end lilypond

@knownissues
Like for @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

More complex variations in text underlay are possible.  It is possible
to switch the melody for a line of lyrics during the text.  This is
done by setting the @code{associatedVoice} property.  In the example

@lilypond[ragged-right,quote]
<<
  \relative c' \new Voice = "lahlah" {
    \set Staff.autoBeaming = ##f
    c4
    <<
      \new Voice = "alternative" {
        \voiceOne
        \times 2/3 {
          % 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 a melody called @q{lahlah},

@example
\new Lyrics \lyricsto "lahlah" @{
  Ju -- ras -- sic Park
@}
@end example


The second stanza initially is set to the @code{lahlah} context, but
for the syllable @q{ran}, it switches to a different melody.
This is achieved with
@example
\set associatedVoice = alternative
@end example

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

@c TODO: make this easier to understand -vv
This command must be one syllable too early, before @q{Ty} in this
case.  In other words, changing the associatedVoice happens one step
later than expected.  This is for technical reasons, and it is not a
bug.

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

@noindent
The underlay is switched back to the starting situation by assigning
@code{lahlah} to @code{associatedVoice}.


@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' {
  c 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."
        }
      }
      \hspace #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;
        % if they are still too close, add more " " pairs
        % until the result looks good
     \column {
      \line { \bold "4."
        \column {
          "This is verse four."
          "It has two lines."
        }
      }
      \hspace #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}.

@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,lilyquote,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 @emph{a capella} 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}.

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

@item
Shape noteheads, 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}.

@end itemize

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

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

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

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 formatting}.

@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 formatting},
@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,lilyquote,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 formatting}.

@item
Dialogue cues and stage directions can be inserted with markup.
See @ref{Text}.  Extensive stage directions can be inserted with
a section of stand-alone markup 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{Grouping staves},
@ref{Hiding staves},
@ref{Instrument transpositions},
@ref{Nested staff groups},
@ref{Page formatting},
@ref{Separating systems},
@ref{Transpose},
@ref{Writing parts},
@ref{Writing text}.


@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")
     (clefOctavation . -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")
     (clefOctavation . 0)
     (middleCPosition . 6)
     (clefPosition . 2)
     (instrumentCueName . ,(markup #:fontsize 1 #:smallCaps "Melchior"))
     (midiInstrument . "voice 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
  s1*0^\markup { \right-align { \tiny "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
  s1*0_\markup { \right-align { \tiny "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,lilyquote,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 illustating 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}.


@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
barlines 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 "dashed"
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,lilyquote,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,lilyquote,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}.

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 @qq{Psalms} in @rlearning{Vocal ensembles}.

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

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,lilyquote,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}.