]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/notation/vocal.itely
Doc: use nested contexts for repeated lyrics
[lilypond.git] / Documentation / notation / vocal.itely
1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @ignore
3     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
4
5     When revising a translation, copy the HEAD committish of the
6     version that you are working on.  For details, see the Contributors'
7     Guide, node Updating translation committishes..
8 @end ignore
9
10 @c \version "2.13.36"
11
12 @node Vocal music
13 @section Vocal music
14
15 @lilypondfile[quote]{vocal-headword.ly}
16
17 This section explains how to typeset vocal music, and make sure
18 that the lyrics will be aligned with the notes of their melody.
19
20 @menu
21 * Common notation for vocal music::
22 * Techniques specific to lyrics::
23 * Stanzas::
24 * Songs::
25 * Choral::
26 * Opera and stage musicals::
27 * Chants psalms and hymns::
28 * Ancient vocal music::
29
30 @end menu
31
32
33 @node Common notation for vocal music
34 @subsection Common notation for vocal music
35
36 This section discusses issues common to most types of vocal music.
37
38 @menu
39 * References for vocal music::
40 * Entering lyrics::
41 * Aligning lyrics to a melody::
42 * Automatic syllable durations::
43 * Manual syllable durations::
44 * Multiple syllables to one note::
45 * Multiple notes to one syllable::
46 * Skipping notes::
47 * Extenders and hyphens::
48 @end menu
49
50
51 @node References for vocal music
52 @unnumberedsubsubsec References for vocal music
53
54 This section indicates where to find details of notation issues
55 that may arise in any type of vocal music.
56
57 @itemize
58
59 @item
60 Most styles of vocal music use written text as lyrics.  An
61 introduction to this notation is to be found in
62 @rlearning{Setting simple songs}.
63
64 @item
65 Vocal music is likely to require the use of @code{markup} mode,
66 either for lyrics or for other text elements (characters' names,
67 etc.)  This syntax is described in @ref{Text markup introduction}.
68
69 @item
70 @notation{Ambitus} may be added at the beginning of vocal staves,
71 as explained in @ref{Ambitus}.
72
73 @item
74 Dynamic markings by default are placed below the staff, but in
75 choral music they are usually placed above the staff in order to
76 avoid the lyrics, as explained in @ref{Score layouts for choral}.
77
78 @end itemize
79
80 @seealso
81 Music Glossary:
82 @rglos{ambitus}.
83
84 Learning Manual:
85 @rlearning{Setting simple songs}.
86
87 Notation Reference:
88 @ref{Text markup introduction},
89 @ref{Ambitus},
90 @ref{Score layouts for choral}.
91
92 Snippets:
93 @rlsr{Vocal music}.
94
95 @node Entering lyrics
96 @unnumberedsubsubsec Entering lyrics
97
98 @cindex lyrics, entering
99 @cindex entering lyrics
100 @cindex punctuation in lyrics
101 @cindex lyrics punctuation
102 @cindex spaces in lyrics
103 @cindex quotes in lyrics
104 @funindex \lyricmode
105
106 @c TODO should we explain hyphens here
107
108 Lyrics are entered in a special input mode, which can be introduced
109 by the keyword @code{\lyricmode}, or by using @code{\addlyrics} or
110 @code{\lyricsto}.  In this special input mode, the input @code{d}
111 is not parsed as the pitch @notation{D}, but rather as a one-letter
112 syllable of text.  In other words, syllables are entered like notes
113 but with pitches replaced by text.
114
115 For example:
116
117 @example
118 \lyricmode @{ Three4 blind mice,2 three4 blind mice2 @}
119 @end example
120
121 There are two main methods for specifying the horizontal placement
122 of the syllables, either by specifying the duration of each syllable
123 explicitly, as in the example above, or by leaving the lyrics to be
124 aligned automatically to a melody or other voice of music, using
125 @code{\addlyrics} or @code{\lyricsto}.  The former method is
126 described below in @ref{Manual syllable durations}.  The latter
127 method is described in @ref{Automatic syllable durations}.
128
129 A word or syllable of lyrics begins with an alphabetic character
130 (plus some other characters, see below) and is terminated by any
131 white space or a digit.  Later characters in the syllable can be any
132 character that is not a digit or white space.
133
134 Because any character that is not a digit or white space is regarded
135 as part of the syllable, a word is valid even if it ends with
136 @code{@}}, which often leads to the following mistake:
137
138 @example
139 \lyricmode @{ lah lah lah@}
140 @end example
141
142 In this example, the @code{@}} is included in the final syllable, so the
143 opening brace is not balanced and the input file will probably not
144 compile.  Instead, braces should always be surrounded with white space:
145
146 @example
147 \lyricmode @{ lah lah lah @}
148 @end example
149
150 @cindex overrides in lyric mode
151 @funindex \override in \lyricmode
152
153 Similarly, in lyric mode, a period will be included in the
154 alphabetic sequence that it follows.  As a consequence, spaces
155 must be inserted around the period in @code{\override} commands.
156 Do @emph{not} write
157
158 @example
159 \override Score.LyricText #'font-shape = #'italic
160 @end example
161
162 @noindent
163 but instead use
164
165 @example
166 \override Score . LyricText #'font-shape = #'italic
167 @end example
168
169 Punctuation, lyrics with accented characters, characters from
170 non-English languages, or special characters (such as the heart
171 symbol or slanted quotes), may simply be inserted directly
172 into the input file, providing it is saved with UTF-8 encoding.
173 For more information, see @ref{Text encoding}.
174
175 @lilypond[quote,verbatim]
176 \relative c'' { d8 c16 a bes8 f e' d c4 }
177 \addlyrics { „Schad’ um das schö -- ne grü -- ne Band, }
178 @end lilypond
179
180 Normal quotes may be used in lyrics, but they have to be preceded
181 with a backslash character and the whole syllable has to be
182 enclosed between additional quotes.  For example,
183
184 @lilypond[quote,verbatim]
185 \relative c' { \time 3/4 e4 e4. e8 d4 e d c2. }
186 \addlyrics { "\"I" am so lone -- "ly,\"" said she }
187 @end lilypond
188
189 The full definition of a word start in lyrics mode is somewhat more
190 complex.  A word in lyrics mode is one that begins with an
191 alphabetic character, @code{_}, @code{?}, @code{!}, @code{:},
192 @code{'}, the control characters @code{^A} through @code{^F},
193 @code{^Q} through @code{^W}, @code{^Y}, @code{^^}, any 8-bit
194 character with an ASCII code over 127, or a two-character
195 combination of a backslash followed by one of @code{`}, @code{'},
196 @code{"}, or @code{^}.
197
198 @c " to balance double quotes for not-so-bright context-sensitive editors
199
200 @seealso
201 Learning Manual:
202 @rlearning{Songs}.
203
204 Notation Reference:
205 @ref{Automatic syllable durations},
206 @ref{Fonts},
207 @ref{Input modes},
208 @ref{Manual syllable durations},
209 @ref{Text encoding}.
210
211 Internals Reference:
212 @rinternals{LyricText}.
213
214
215 @node Aligning lyrics to a melody
216 @unnumberedsubsubsec Aligning lyrics to a melody
217
218 @cindex lyrics, aligning to a melody
219 @cindex @code{associatedVoice}
220 @funindex \lyricmode
221 @funindex \addlyrics
222 @funindex \lyricsto
223
224 Lyrics are printed by interpreting them in the context called
225 @code{Lyrics}, see @ref{Contexts explained}.
226
227 @example
228 \new Lyrics \lyricmode @{ @dots{} @}
229 @end example
230
231 Lyrics can be aligned with melodies in two main ways:
232
233 @itemize
234
235 @item
236 Lyrics can be aligned automatically, with the durations of the
237 syllables being taken from another voice of music or (in special
238 circumstances) an associated melody, using @code{\addlyrics},
239 @code{\lyricsto}, or by setting the @code{associatedVoice} property.
240 For more details, see @ref{Automatic syllable durations}.
241
242 @lilypond[quote,ragged-right,verbatim]
243 <<
244   \new Staff <<
245     \time 2/4
246     \new Voice = "one" \relative c'' {
247       \voiceOne
248       c4 b8. a16 g4. r8 a4 ( b ) c2
249     }
250     \new Voice = "two" \relative c' {
251       \voiceTwo
252        s2 s4. f8 e4 d c2
253     }
254   >>
255
256 % takes durations and alignment from notes in "one"
257   \new Lyrics \lyricsto "one" {
258     Life is __ _ love, live __ life.
259   }
260
261 % takes durations and alignment from notes in "one" initially
262 % then switches to "two"
263   \new Lyrics \lyricsto "one" {
264     No more let
265     \set associatedVoice = "two"  % must be set one syllable early
266     sins and sor -- rows grow.
267   }
268 >>
269 @end lilypond
270
271 The first stanza shows the normal way of entering lyrics.
272
273 The second stanza shows how the voice from which the lyric
274 durations are taken can be changed.  This is useful if the words to
275 different stanzas fit the notes in different ways and all the
276 durations are available in Voice contexts.  For more details, see
277 @ref{Stanzas}.
278
279 @item
280 Lyrics can be aligned independently of the duration of any notes
281 if the durations of the syllables are specified explicitly,
282 and entered with @code{\lyricmode}.
283
284 @lilypond[quote,ragged-right,verbatim]
285 <<
286   \new Voice = "one" \relative c'' {
287     \time 2/4
288     c4 b8. a16 g4. f8 e4 d c2
289   }
290
291 % uses previous explicit duration of 2;
292   \new Lyrics \lyricmode {
293     Joy to the earth!
294   }
295
296 % explicit durations, set to a different rhythm
297   \new Lyrics \lyricmode {
298     Life4 is love,2. live4 life.2
299   }
300 >>
301 @end lilypond
302
303 The first stanza is not aligned with the notes because the durations
304 were not specified, and the previous value of 2 is used for each
305 word.
306
307 The second stanza shows how the words can be aligned quite
308 independently from the notes.  This is useful if the words to
309 different stanzas fit the notes in different ways and the required
310 durations are not available in a music context.  For more details
311 see @ref{Manual syllable durations}.  This technique is also useful
312 when setting dialogue over music; for examples showing this, see
313 @ref{Dialogue over music}.
314
315 When entered in this way the words are left-aligned to the notes
316 by default, but may be center-aligned to the notes of a melody by
317 specifying an associated voice, if one exists.  For details, see
318 @ref{Manual syllable durations}.
319
320 @end itemize
321
322 @seealso
323 Learning Manual:
324 @rlearning{Aligning lyrics to a melody}.
325
326 Notation Reference:
327 @ref{Contexts explained},
328 @ref{Automatic syllable durations}.
329 @ref{Stanzas},
330 @ref{Manual syllable durations},
331 @ref{Dialogue over music},
332 @ref{Manual syllable durations}.
333
334 Internals Reference:
335 @rinternals{Lyrics}.
336
337 @node Automatic syllable durations
338 @unnumberedsubsubsec Automatic syllable durations
339
340 @cindex syllable durations, automatic
341 @cindex lyrics and melodies
342 @cindex associatedVoice
343 @funindex \addlyrics
344 @funindex \lyricsto
345
346 Lyrics can be automatically aligned to the notes of a melody in
347 three ways:
348
349 @itemize
350
351 @item
352 by specifying the named Voice context containing the melody with
353 @code{\lyricsto},
354
355 @item
356 by introducing the lyrics with @code{\addlyrics} and placing them
357 immediately after the Voice context containing the melody,
358
359 @item
360 by setting the @code{associatedVoice} property, the alignment of
361 the lyrics may be switched to a different named Voice context at
362 any musical moment.
363
364 @end itemize
365
366 In all three methods hyphens can be drawn between the syllables of
367 a word and extender lines can be drawn beyond the end of a word.  For
368 details, see @ref{Extenders and hyphens}.
369
370 The @code{Voice} context containing the melody to which the lyrics
371 are being aligned must not have @qq{died}, or the lyrics after that
372 point will be lost.  This can happen if there are periods when that
373 voice has nothing to do.  For methods of keeping contexts alive, see
374 @ref{Keeping contexts alive}.
375
376 @subheading Using @code{\lyricsto}
377
378 @cindex \lyricsto
379 @funindex \lyricsto
380
381 Lyrics can be aligned under a melody automatically by specifying
382 the named Voice context containing the melody with
383 @code{\lyricsto}:
384
385 @lilypond[quote,verbatim,relative=2]
386 <<
387   \new Voice = "melody" {
388     a4 a a a
389   }
390   \new Lyrics \lyricsto "melody" {
391     These are the words
392   }
393 >>
394 @end lilypond
395
396 @noindent
397 This aligns the lyrics to the notes of the named @code{Voice}
398 context, which must already exist.  Therefore normally the
399 @code{Voice} context is specified first, followed by the
400 @code{Lyrics} context.  The lyrics themselves follow the
401 @code{\lyricsto} command.  The @code{\lyricsto} command
402 invokes lyric mode automatically, so the @code{\lyricmode} keyword
403 may be omitted.  By default, the lyrics are placed underneath the
404 notes.  For other placements, see @ref{Placing lyrics vertically}.
405
406 @subheading Using @code{\addlyrics}
407
408 @cindex \addlyrics
409 @funindex \addlyrics
410
411 The @code{\addlyrics} command is just a convenient shortcut that
412 can sometimes be used instead of having to set up the lyrics
413 through a more complicated LilyPond structure.
414
415 @example
416 @{ MUSIC @}
417 \addlyrics @{ LYRICS @}
418 @end example
419
420 @noindent
421 is the same as
422
423 @example
424 \new Voice = "blah" @{ MUSIC @}
425 \new Lyrics \lyricsto "blah" @{ LYRICS @}
426 @end example
427
428 Here is an example,
429
430 @lilypond[verbatim,quote]
431 {
432   \time 3/4
433   \relative c' { c2 e4 g2. }
434   \addlyrics { play the game }
435 }
436 @end lilypond
437
438 More stanzas can be added by adding more
439 @code{\addlyrics} sections:
440
441
442 @lilypond[ragged-right,verbatim,quote]
443 {
444   \time 3/4
445   \relative c' { c2 e4 g2. }
446   \addlyrics { play the game }
447   \addlyrics { speel het spel }
448   \addlyrics { joue le jeu }
449 }
450 @end lilypond
451
452 The command @code{\addlyrics} cannot handle polyphonic settings.
453 For these cases one should use @code{\lyricsto}.
454
455 @subheading Using associatedVoice
456
457 The melody to which the lyrics are being aligned can be changed by
458 setting the @code{associatedVoice} property,
459
460 @example
461 \set associatedVoice = #"lala"
462 @end example
463
464 @noindent
465
466 The value of the property (here: @code{"lala"}) should be the name
467 of a @code{Voice} context.  For technical reasons, the @code{\set}
468 command must be placed one syllable before the one to which the
469 change in voice is to apply.
470
471 Here is an example demonstrating its use:
472
473 @lilypond[quote,ragged-right,verbatim]
474 <<
475   \new Staff <<
476     \time 2/4
477     \new Voice = "one" \relative c'' {
478       \voiceOne
479       c4 b8. a16 g4. r8 a4 ( b ) c2
480     }
481     \new Voice = "two" \relative c' {
482       \voiceTwo
483        s2 s4. f8 e8 d4. c2
484     }
485   >>
486 % takes durations and alignment from notes in "one" initially
487 % then switches to "two"
488   \new Lyrics \lyricsto "one" {
489     No more let
490     \set associatedVoice = "two"  % must be set one syllable early
491     sins and sor -- rows grow.
492   }
493 >>
494 @end lilypond
495
496 @seealso
497 Notation Reference:
498 @ref{Extenders and hyphens},
499 @ref{Keeping contexts alive},
500 @ref{Placing lyrics vertically}.
501
502 @node Manual syllable durations
503 @unnumberedsubsubsec Manual syllable durations
504
505 In some complex vocal music, it may be desirable to place lyrics
506 completely independently of notes.  In this case do not use
507 @code{\lyricsto} or @code{\addlyrics} and do not set
508 @code{associatedVoice}.  Syllables are entered like notes --
509 but with pitches replaced by text -- and the duration of each
510 syllable is entered explicitly after the syllable.
511
512 By default, syllables will be left-aligned to the corresponding
513 musical moment.  Hyphenated lines may be drawn between syllables
514 as usual, but extender lines cannot be drawn when there is no
515 associated voice.
516
517 Here are two examples:
518
519 @lilypond[relative=1,verbatim,quote]
520 <<
521   \new Voice = "melody" {
522     \time 3/4
523     c2 e4 g2 f
524   }
525   \new Lyrics \lyricmode {
526     play1 the4 game4
527   }
528 >>
529 @end lilypond
530
531
532 @lilypond[quote,verbatim,ragged-right]
533 <<
534   \new Staff {
535     \relative c'' {
536       c2 c2
537       d1
538     }
539   }
540   \new Lyrics {
541     \lyricmode {
542       I2 like4. my8 cat!1
543     }
544   }
545   \new Staff {
546     \relative c' {
547       c8 c c c c c c c
548       c8 c c c c c c c
549     }
550   }
551 >>
552 @end lilypond
553
554 This technique is useful when writing dialogue over music, see
555 @ref{Dialogue over music}.
556
557 To center-align syllables on the notes at the corresponding musical
558 moments, set @code{associatedVoice} to the name of the Voice context
559 containing those notes.  When @code{associatedVoice} is set, both
560 double hyphens and double underscores can be used to draw
561 hyphenated lines and extenders under melismata correctly.
562
563 @lilypond[relative=1,verbatim,quote]
564 <<
565   \new Voice = "melody" {
566     \time 3/4
567     c2 e4 g f g
568   }
569   \new Lyrics \lyricmode {
570     \set associatedVoice = #"melody"
571     play2 the4 game2. __
572   }
573 >>
574 @end lilypond
575
576 @c TODO see also feature request 707 - show how to do this with manual durations
577
578 @seealso
579 Notation Reference:
580 @ref{Dialogue over music}.
581
582 Internals Reference:
583 @rinternals{Lyrics},
584 @rinternals{Voice}.
585
586
587 @node Multiple syllables to one note
588 @unnumberedsubsubsec Multiple syllables to one note
589
590 @funindex _
591 @cindex spaces, in lyrics
592 @cindex quotes, in lyrics
593 @cindex ties, in lyrics
594
595 In order to assign more than one syllable to a single note with
596 spaces between the syllables, you can surround the phrase with
597 quotes or use a @code{_} character.  Alternatively, you can use
598 code the tilde symbol (@code{~}) to get a lyric tie.  The lyric
599 tie is implemented with the Unicode character U+203F, so be
600 sure to have a font (like DejaVuLGC) installed that includes this
601 glyph.
602
603 @lilypond[quote,ragged-right,verbatim]
604 {
605   \time 3/4
606   \relative c' { c2 e4 g2 e4 }
607   \addlyrics { gran- de_a- mi- go }
608   \addlyrics { pu- "ro y ho-" nes- to }
609   \addlyrics { pu- ro~y~ho- nes- to }
610 }
611 @end lilypond
612
613
614 @seealso
615 Internals Reference:
616 @rinternals{LyricCombineMusic}.
617
618
619 @node Multiple notes to one syllable
620 @unnumberedsubsubsec Multiple notes to one syllable
621
622 @cindex melisma
623 @cindex melismata
624 @cindex phrasing, in lyrics
625 @funindex \melisma
626 @funindex \melismaEnd
627
628 Sometimes, particularly in Medieval music, several notes are to be
629 sung on one syllable; such vocalises are called melismata, or
630 @rglos{melisma}s.  The syllable to a melisma is usually
631 left-aligned with the first note of the melisma.
632
633 When a melisma occurs on a syllable other that the last one in a
634 word, that syllable is usually joined to the following one with a
635 hyphenated line.  This is indicated by placing a double hyphen,
636 @code{--}, immediately after the syllable.
637
638 Alternatively, when a melisma occurs on the last or only syllable in
639 a word an extender line is usually drawn from the end of the syllable
640 to the last note of the melisma.  This is indicated by placing a
641 double underscore, @code{__}, immediately after the word.
642
643 There are five ways in which melismata can be indicated:
644
645 @itemize
646
647 @item
648 Melismata are created automatically over notes which are tied
649 together:
650
651 @lilypond[quote,relative=2,verbatim]
652 <<
653   \new Voice = "melody" {
654     \time 3/4
655     f4 g2 ~ |
656     g4 e2 ~ |
657     e8
658   }
659   \new Lyrics \lyricsto "melody" {
660     Ky -- ri -- e __
661   }
662 >>
663 @end lilypond
664
665 @item
666 Melismata can be created automatically from the music by placing
667 slurs over the notes of each melisma.  This is the usual way of
668 entering lyrics:
669
670 @lilypond[quote,relative=2,verbatim]
671 <<
672   \new Voice = "melody" {
673     \time 3/4
674     f4 g8 ( f e f )
675     e8 ( d e2 )
676   }
677   \new Lyrics \lyricsto "melody" {
678     Ky -- ri -- e __
679   }
680 >>
681 @end lilypond
682
683 @item
684 Notes are considered a melisma if they are manually beamed,
685 providing automatic beaming is switched off.  See
686 @ref{Setting automatic beam behavior}.
687
688 @lilypond[quote,relative=2,verbatim]
689 <<
690   \new Voice = "melody" {
691     \time 3/4
692     \autoBeamOff
693     f4 g8[ f e f]
694     e2.
695   }
696   \new Lyrics \lyricsto "melody" {
697     Ky -- ri -- e
698   }
699 >>
700 @end lilypond
701
702 Clearly this is not suited to melismata over notes which are longer
703 than eighth notes.
704
705 @item
706 An unslurred group of notes will be treated as a melisma if they
707 are bracketed between @code{\melisma} and @code{\melismaEnd}.
708
709 @lilypond[quote,relative=2,verbatim]
710 <<
711   \new Voice = "melody" {
712     \time 3/4
713     f4 g8
714     \melisma
715     f e f
716     \melismaEnd
717     e2.
718   }
719   \new Lyrics \lyricsto "melody" {
720     Ky -- ri -- e
721   }
722 >>
723 @end lilypond
724
725 Note that this method cannot be used to indicate two melismata if
726 the first one is immediately followed by another.
727
728 @item
729 A melisma can be defined entirely in the lyrics by entering a
730 single underscore character, @code{_}, for every extra note that has
731 to be added to the melisma.
732
733 @lilypond[verbatim, quote, relative=2]
734 <<
735   \new Voice = "melody" {
736     \time 3/4
737     f4 g8 f e f
738     e8 d e2
739   }
740   \new Lyrics \lyricsto "melody" {
741     Ky -- ri -- _ _ _ e __ _ _
742   }
743 >>
744 @end lilypond
745
746 @end itemize
747
748 It is possible to have ties, slurs and manual beams in the melody
749 without their indicating melismata.  To do this, set
750 @code{melismaBusyProperties}:
751
752 @lilypond[relative=1,verbatim,quote]
753 <<
754   \new Voice = "melody" {
755     \time 3/4
756     \set melismaBusyProperties = #'()
757     c4 d ( e )
758     g8 [ f ] f4 ~ f
759   }
760   \new Lyrics \lyricsto "melody" {
761     Ky -- ri -- e e -- le -- i -- son
762   }
763 >>
764 @end lilypond
765
766 Other settings for @code{melismaBusyProperties} can be used to
767 selectively include or exclude ties, slurs, and beams from the
768 automatic detection of melismata; see @code{melismaBusyProperties}
769 in @rinternals{Tunable context properties}.
770
771 Alternatively, if all melismata indications are to be ignored,
772 @code{ignoreMelismata} may be set true;
773 see @ref{Stanzas with different rhythms}.
774
775 If a melisma is required during a passage in which
776 @code{melismaBusyProperties} is active, it may be indicated by
777 placing a single underscore in the lyrics for each note which
778 should be included in the melisma:
779
780 @lilypond[relative=1,verbatim,quote]
781 <<
782   \new Voice = "melody" {
783     \time 3/4
784     \set melismaBusyProperties = #'()
785     c4 d ( e )
786     g8 [ f ] ~ f4 ~ f
787   }
788   \new Lyrics \lyricsto "melody" {
789     Ky -- ri -- _ e __ _ _ _
790   }
791 >>
792 @end lilypond
793
794
795 @predefined
796
797 @code{\autoBeamOff},
798 @code{\autoBeamOn},
799 @code{\melisma},
800 @code{\melismaEnd}.
801
802 @seealso
803 Musical Glossary:
804 @rglos{melisma}.
805
806 Learning Manual:
807 @rlearning{Aligning lyrics to a melody}.
808
809 Notation Reference:
810 @ref{Aligning lyrics to a melody},
811 @ref{Automatic syllable durations},
812 @ref{Setting automatic beam behavior},
813 @ref{Stanzas with different rhythms}.
814
815 Internals Reference:
816 @rinternals{Tunable context properties}.
817
818 @knownissues
819
820 Extender lines under melismata are not created automatically; they
821 must be inserted manually with a double underscore.
822
823 @node Skipping notes
824 @unnumberedsubsubsec Skipping notes
825
826 Making a lyric line run slower than the melody can be achieved by
827 inserting @code{\skip}s into the lyrics.  For every @code{\skip},
828 the text will be delayed by another note.  The @code{\skip} command
829 must be followed by a valid duration, but this is ignored when
830 @code{\skip} is used in lyrics which derive their durations from the
831 notes in an associated melody through @code{\addlyrics} or
832 @code{\lyricsto}.
833
834 @lilypond[verbatim,ragged-right,quote]
835 \relative c' { c c g' }
836 \addlyrics {
837   twin -- \skip 4
838   kle
839 }
840 @end lilypond
841
842
843 @node Extenders and hyphens
844 @unnumberedsubsubsec Extenders and hyphens
845
846 @cindex melisma
847 @cindex extender
848
849 @c TODO cf Multiple notes to one syllable; should this be merged in?
850
851 @c leave this as samp. -gp
852 In the last syllable of a word, melismata are sometimes indicated with
853 a long horizontal line starting in the melisma syllable, and ending in
854 the next one.  Such a line is called an extender line, and it is
855 entered as @samp{ __ } (note the spaces before and after the two
856 underscore characters).
857
858 @warning{Melismata are indicated in the score with extender lines,
859 which are entered as one double underscore; but short melismata can
860 also be entered by skipping individual notes, which are entered as
861 single underscore characters; these do not make an extender line to be
862 typeset by default.}
863
864 @cindex hyphens
865
866 @c leave this as samp. -gp
867 Centered hyphens are entered as @samp{ -- } between syllables of a
868 same word (note the spaces before and after the two hyphen
869 characters).  The hyphen will be centered between the syllables, and
870 its length will be adjusted depending on the space between the
871 syllables.
872
873 In tightly engraved music, hyphens can be removed.  Whether this
874 happens can be controlled with the @code{minimum-distance} (minimum
875 distance between two syllables) and the @code{minimum-length}
876 (threshold below which hyphens are removed) properties of
877 @code{LyricHyphen}.
878
879
880 @seealso
881 Internals Reference:
882 @rinternals{LyricExtender},
883 @rinternals{LyricHyphen}.
884
885
886 @node Techniques specific to lyrics
887 @subsection Techniques specific to lyrics
888
889 @c TODO this whole section is to be reorganised
890
891 @menu
892 * Working with lyrics and variables::
893 * Placing lyrics vertically::
894 * Placing syllables horizontally::
895 * Lyrics and repeats::
896 * Divisi lyrics::
897 @end menu
898
899
900
901 @node Working with lyrics and variables
902 @unnumberedsubsubsec Working with lyrics and variables
903
904 @cindex lyrics, using variables
905
906 Variables containing lyrics can be created, but the lyrics must be
907 entered in lyric mode:
908
909 @lilypond[quote,verbatim]
910 musicOne = \relative c'' {
911   c4 b8. a16 g4. f8 e4 d c2
912 }
913 verseOne = \lyricmode {
914   Joy to the world, the Lord is come.
915 }
916 \score {
917   <<
918     \new Voice = "one" {
919       \time 2/4
920       \musicOne
921     }
922     \new Lyrics \lyricsto "one" {
923       \verseOne
924     }
925   >>
926 }
927 @end lilypond
928
929 Durations do not need to be added if the variable is to be invoked
930 with @code{\addlyrics} or @code{\lyricsto}.
931
932 For different or more complex orderings, the best way is to define
933 the music and lyric variables first, then set up the hierarchy of
934 staves and lyrics, omitting the lyrics themselves, and then add the
935 lyrics using @code{\context} underneath.  This ensures that the
936 voices referenced by @code{\lyricsto} have always been defined
937 earlier.  For example:
938
939 @lilypond[quote,verbatim]
940 sopranoMusic = \relative c'' { c4 c c c }
941 contraltoMusic = \relative c'' { a4 a a a }
942 sopranoWords = \lyricmode { Sop -- ra -- no words }
943 contraltoWords = \lyricmode { Con -- tral -- to words }
944
945 \score {
946   \new ChoirStaff <<
947     \new Staff {
948       \new Voice = "sopranos" {
949         \sopranoMusic
950       }
951     }
952     \new Lyrics = "sopranos"
953     \new Lyrics = "contraltos"
954     \new Staff {
955       \new Voice = "contraltos" {
956         \contraltoMusic
957       }
958     }
959     \context Lyrics = "sopranos" {
960       \lyricsto "sopranos" {
961         \sopranoWords
962       }
963     }
964     \context Lyrics = "contraltos" {
965       \lyricsto "contraltos" {
966         \contraltoWords
967       }
968     }
969   >>
970 }
971 @end lilypond
972
973
974 @seealso
975 Notation Reference:
976 @ref{Placing lyrics vertically}.
977
978 Internals Reference:
979 @rinternals{LyricCombineMusic},
980 @rinternals{Lyrics}.
981
982
983 @node Placing lyrics vertically
984 @unnumberedsubsubsec Placing lyrics vertically
985
986 @cindex placement of lyrics
987 @cindex lyrics, positioning
988
989 Depending on the type of music, lyrics may be positioned
990 above the staff, below the staff, or between staves.  Placing
991 lyrics below the associated staff is the easiest, and can be
992 achieved by simply defining the Lyrics context below the Staff
993 context:
994
995 @lilypond[quote,verbatim]
996 \score {
997   <<
998     \new Staff {
999       \new Voice = "melody" {
1000         \relative c'' { c4 c c c }
1001       }
1002     }
1003     \new Lyrics {
1004       \lyricsto "melody" {
1005         Here are the words
1006       }
1007     }
1008   >>
1009 }
1010 @end lilypond
1011
1012 Lyrics may be positioned above the staff using one of
1013 two methods.  The simplest (and preferred) method
1014 is to use the same syntax as above and explicitly
1015 specify the position of the lyrics:
1016
1017 @lilypond[quote,verbatim]
1018 \score {
1019   <<
1020     \new Staff = "staff" {
1021       \new Voice = "melody" {
1022         \relative c'' { c4 c c c }
1023       }
1024     }
1025     \new Lyrics \with { alignAboveContext = "staff" } {
1026       \lyricsto "melody" {
1027         Here are the words
1028       }
1029     }
1030   >>
1031 }
1032 @end lilypond
1033
1034 Alternatively, a two-step process may be used.  First the Lyrics
1035 context is declared (without any content) before the Staff and
1036 Voice contexts, then the @code{\lyricsto} command is placed after
1037 the Voice declaration it references by using @code{\context}, as
1038 follows:
1039
1040 @lilypond[quote,verbatim]
1041 \score {
1042   <<
1043     \new Lyrics = "lyrics" \with {
1044       % lyrics above a staff should have this override
1045       \override VerticalAxisGroup #'staff-affinity = #DOWN
1046     }
1047     \new Staff {
1048       \new Voice = "melody" {
1049         \relative c'' { c4 c c c }
1050       }
1051     }
1052     \context Lyrics = "lyrics" {
1053       \lyricsto "melody" {
1054         Here are the words
1055       }
1056     }
1057   >>
1058 }
1059 @end lilypond
1060
1061 When there are two voices on separate staves the lyrics may be
1062 placed between the staves using either of these methods.  Here
1063 is an example of the second method:
1064
1065 @lilypond[quote,verbatim]
1066 \score {
1067   \new ChoirStaff <<
1068     \new Staff {
1069       \new Voice = "sopranos" {
1070         \relative c'' { c4 c c c }
1071       }
1072     }
1073     \new Lyrics = "sopranos"
1074     \new Lyrics = "contraltos" \with {
1075       % lyrics above a staff should have this override
1076       \override VerticalAxisGroup #'staff-affinity = #DOWN
1077     }
1078     \new Staff {
1079       \new Voice = "contraltos" {
1080         \relative c'' { a4 a a a }
1081       }
1082     }
1083     \context Lyrics = "sopranos" {
1084       \lyricsto "sopranos" {
1085         Sop -- ra -- no words
1086       }
1087     }
1088     \context Lyrics = "contraltos" {
1089       \lyricsto "contraltos" {
1090         Con -- tral -- to words
1091       }
1092     }
1093   >>
1094 }
1095 @end lilypond
1096
1097 Other combinations of lyrics and staves may be generated by
1098 elaborating these examples, or by examining the
1099 @rlearning{Vocal ensembles} templates in the Learning Manual.
1100
1101 @snippets
1102 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
1103 {lyrics-old-spacing-settings.ly}
1104
1105 @seealso
1106 Learning Manual:
1107 @rlearning{Vocal ensembles}.
1108
1109 Notation Reference:
1110 @ref{Aligning contexts},
1111 @ref{Creating contexts}.
1112
1113 @node Placing syllables horizontally
1114 @unnumberedsubsubsec Placing syllables horizontally
1115
1116 @cindex Spacing lyrics
1117 @cindex Lyrics, increasing space between
1118
1119 To increase the spacing between lyrics, set the
1120 @code{minimum-distance} property of @code{LyricSpace}.
1121
1122 @lilypond[relative=1,verbatim,quote,ragged-right]
1123 {
1124   c c c c
1125   \override Lyrics.LyricSpace #'minimum-distance = #1.0
1126   c c c c
1127 }
1128 \addlyrics {
1129   longtext longtext longtext longtext
1130   longtext longtext longtext longtext
1131 }
1132 @end lilypond
1133
1134 @noindent
1135 To make this change for all lyrics in the score, set the property in the
1136 @code{\layout} block.
1137
1138 @lilypond[verbatim,quote,ragged-right]
1139 \score {
1140   \relative c' {
1141   c c c c
1142   c c c c
1143   }
1144   \addlyrics {
1145   longtext longtext longtext longtext
1146   longtext longtext longtext longtext
1147   }
1148   \layout {
1149     \context {
1150       \Lyrics
1151       \override LyricSpace #'minimum-distance = #1.0
1152     }
1153   }
1154 }
1155 @end lilypond
1156
1157 @snippets
1158 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
1159 {lyrics-alignment.ly}
1160
1161 @c TODO: move to LSR -vv
1162
1163 Checking to make sure that text scripts and lyrics are within the
1164 margins is a relatively large computational task.  To speed up processing,
1165 LilyPond does not perform such calculations by default; to enable it, use
1166
1167 @example
1168 \override Score.PaperColumn #'keep-inside-line = ##t
1169 @end example
1170
1171 To make lyrics avoid bar lines as well, use
1172
1173 @example
1174 \layout @{
1175   \context @{
1176     \Lyrics
1177       \consists "Bar_engraver"
1178       \consists "Separating_line_group_engraver"
1179       \override BarLine #'transparent = ##t
1180   @}
1181 @}
1182 @end example
1183
1184 @c TODO Create and add lsr example of lyricMelismaAlignment
1185 @c It's used like this to center-align all lyric syllables,
1186 @c even when notes are tied. -td
1187
1188 @ignore
1189 \layout
1190 {
1191      \context { \Score lyricMelismaAlignment = #0 }
1192 }
1193 @end ignore
1194
1195
1196 @node Lyrics and repeats
1197 @unnumberedsubsubsec Lyrics and repeats
1198
1199 @cindex repeats and lyrics
1200 @cindex lyrics, repeating
1201
1202 @subheading Simple repeats
1203
1204 Repeats in @emph{music} are fully described elsewhere; see
1205 @ref{Repeats}.  This section explains how to add lyrics to repeated
1206 sections of music.
1207
1208 Lyrics to a section of music that is repeated should be surrounded
1209 by exactly the same repeat construct as the music, if the words are
1210 unchanged.
1211
1212 @lilypond[verbatim,quote]
1213 \score {
1214   <<
1215     \new Staff {
1216       \new Voice = "melody" {
1217         \relative c'' {
1218           a4 a a a
1219           \repeat volta 2 { b4 b b b }
1220         }
1221       }
1222     }
1223     \new Lyrics {
1224       \lyricsto "melody" {
1225         Not re -- peat -- ed.
1226         \repeat volta 2 { Re -- peat -- ed twice. }
1227       }
1228     }
1229   >>
1230 }
1231 @end lilypond
1232
1233 The words will then be correctly expanded if the repeats are
1234 unfolded.
1235
1236 @lilypond[verbatim,quote]
1237 \score {
1238   \unfoldRepeats {
1239     <<
1240       \new Staff {
1241         \new Voice = "melody" {
1242           \relative c'' {
1243             a4 a a a
1244             \repeat volta 2 { b4 b b b }
1245           }
1246         }
1247       }
1248       \new Lyrics {
1249         \lyricsto "melody" {
1250           Not re -- peat -- ed.
1251           \repeat volta 2 { Re -- peat -- ed twice. }
1252         }
1253       }
1254     >>
1255   }
1256 }
1257 @end lilypond
1258
1259 If the repeated section is to be unfolded and has different words,
1260 simply enter all the words:
1261
1262 @lilypond[verbatim,quote,ragged-right]
1263 \score {
1264   <<
1265     \new Staff {
1266       \new Voice = "melody" {
1267         \relative c'' {
1268           a4 a a a
1269           \repeat unfold 2 { b4 b b b }
1270         }
1271       }
1272     }
1273     \new Lyrics {
1274       \lyricsto "melody" {
1275         Not re -- peat -- ed.
1276         The first time words.
1277         Sec -- ond time words.
1278       }
1279     }
1280   >>
1281 }
1282 @end lilypond
1283
1284 When the words to a repeated volta section are different, the words
1285 to each repeat must be entered in separate @code{Lyrics} contexts,
1286 correctly nested in parallel sections:
1287
1288 @lilypond[verbatim,quote]
1289 \score {
1290   <<
1291     \new Staff {
1292       \new Voice = "melody" {
1293         \relative c'' {
1294           a4 a a a
1295           \repeat volta 2 { b4 b b b }
1296         }
1297       }
1298     }
1299     \new Lyrics \lyricsto "melody" {
1300       Not re -- peat -- ed.
1301       <<
1302         { The first time words. }
1303         \new Lyrics {
1304           \set associatedVoice = "melody"
1305           Sec -- ond time words.
1306         }
1307       >>
1308     }
1309   >>
1310 }
1311 @end lilypond
1312
1313 More verses may be added in a similar way:
1314
1315 @lilypond[verbatim,quote]
1316 \score {
1317   <<
1318     \new Staff {
1319       \new Voice = "singleVoice" {
1320         \relative c'' {
1321           a4 a a a
1322           \repeat volta 3 { b4 b b b }
1323           c4 c c c
1324         }
1325       }
1326     }
1327     \new Lyrics \lyricsto "singleVoice" {
1328       Not re -- peat -- ed.
1329       <<
1330         { The first time words. }
1331         \new Lyrics {
1332           \set associatedVoice = "singleVoice"
1333           Sec -- ond time words.
1334         }
1335         \new Lyrics {
1336           \set associatedVoice = "singleVoice"
1337           The third time words.
1338         }
1339       >>
1340       The end sec -- tion.
1341     }
1342   >>
1343 }
1344 @end lilypond
1345
1346
1347 @c TODO positioning a common line of lyrics
1348
1349 @subheading Repeats with alternative endings
1350
1351 @cindex lyrics, repeats with alternative endings
1352 @cindex repeating lyrics with alternative endings
1353 @cindex alternative endings and lyrics
1354
1355 If the words of the repeated section are the same, exactly the
1356 same structure can be used for both the lyrics and music.
1357
1358 @lilypond[quote,verbatim]
1359 \score {
1360   <<
1361     \new Staff {
1362       \time 2/4
1363       \new Voice = "melody" {
1364         \relative c'' {
1365           a4 a a a
1366           \repeat volta 2 { b4 b }
1367           \alternative { { b b } { b c } }
1368         }
1369       }
1370     }
1371     \new Lyrics {
1372       \lyricsto "melody" {
1373         Not re -- peat -- ed.
1374         \repeat volta 2 { Re -- peat -- }
1375         \alternative { { ed twice. } { ed twice. } }
1376       }
1377     }
1378   >>
1379 }
1380 @end lilypond
1381
1382 But when the repeated section has different words, a repeat
1383 construct cannot be used around the words and @code{\skip} commands
1384 have to be inserted manually to skip over the notes in the
1385 alternative sections which do not apply.
1386
1387 @lilypond[verbatim,quote,ragged-right]
1388 \score {
1389   <<
1390     \new Staff {
1391       \time 2/4
1392       \new Voice = "melody" {
1393         \relative c'' {
1394           \repeat volta 2 { b4 b }
1395           \alternative { { b b } { b c } }
1396           c4 c
1397         }
1398       }
1399     }
1400     \new Lyrics {
1401       \lyricsto "melody" {
1402         The first time words.
1403         \repeat unfold 2 { \skip 1 }
1404         End here.
1405       }
1406     }
1407     \new Lyrics {
1408       \lyricsto "melody" {
1409         Sec -- ond
1410         \repeat unfold 2 { \skip 1 }
1411         time words.
1412       }
1413     }
1414   >>
1415 }
1416 @end lilypond
1417
1418 @cindex lyrics and tied notes
1419 @funindex \repeatTie
1420
1421 When a note is tied over into two or more alternative endings a
1422 tie is used to carry the note into the first alternative ending and
1423 a @code{\repeatTie} is used in the second and subsequent endings.
1424 This structure causes difficult alignment problems when lyrics are
1425 involved and increasing the length of the alternative sections so
1426 the tied notes are contained wholly within them may give a more
1427 acceptable result.
1428
1429 The tie creates a melisma into the first alternative, but not into
1430 the second and subsequent alternatives, so to align the lyrics
1431 correctly it is necessary to disable the automatic creation of
1432 melismata over the volta section and insert manual skips.
1433
1434 @lilypond[quote,verbatim]
1435 \score {
1436   <<
1437     \new Staff {
1438       \time 2/4
1439       \new Voice = "melody" {
1440         \relative c'' {
1441           \set melismaBusyProperties = #'()
1442           \repeat volta 2 { b4 b ~}
1443           \alternative { { b b } { b \repeatTie c } }
1444           \unset melismaBusyProperties
1445           c4 c
1446         }
1447       }
1448     }
1449     \new Lyrics {
1450       \lyricsto "melody" {
1451         \repeat volta 2 { Here's a __ }
1452         \alternative {
1453           { \skip 1 verse }
1454           { \skip 1 sec }
1455         }
1456         ond one.
1457       }
1458     }
1459   >>
1460 }
1461 @end lilypond
1462
1463 Note that if @code{\unfoldRepeats} is used around a section
1464 containing @code{\repeatTie}, the @code{\repeatTie} should be
1465 removed to avoid both types of tie being printed.
1466
1467 When the repeated section has different words a @code{\repeat}
1468 cannot be used around the lyrics and @code{\skip} commands need to
1469 be inserted manually, as before.
1470
1471 @lilypond[quote,verbatim]
1472 \score {
1473   <<
1474     \new Staff {
1475       \time 2/4
1476       \new Voice = "melody" {
1477         \relative c'' {
1478           \repeat volta 2 { b4 b ~}
1479           \alternative { { b b } { b \repeatTie c } }
1480           c4 c
1481         }
1482       }
1483     }
1484     \new Lyrics {
1485       \lyricsto "melody" {
1486         Here's a __ verse.
1487         \repeat unfold 2 { \skip 1 }
1488       }
1489     }
1490     \new Lyrics {
1491       \lyricsto "melody" {
1492         Here's one
1493         \repeat unfold 2 { \skip 1 }
1494         more to sing.
1495       }
1496     }
1497   >>
1498 }
1499 @end lilypond
1500
1501 If you wish to show extenders and hyphens into and out of
1502 alternative sections these must be inserted manually.
1503
1504 @lilypond[quote,verbatim]
1505 \score {
1506   <<
1507     \new Staff {
1508       \time 2/4
1509       \new Voice = "melody" {
1510         \relative c'' {
1511           \repeat volta 2 { b4 b ~}
1512           \alternative { { b b } { b \repeatTie c } }
1513           c4 c
1514         }
1515       }
1516     }
1517     \new Lyrics {
1518       \lyricsto "melody" {
1519         Here's a __ verse.
1520         \repeat unfold 2 { \skip 1 }
1521       }
1522     }
1523     \new Lyrics {
1524       \lyricsto "melody" {
1525         Here's "a_"
1526         \skip 1
1527         "_" sec -- ond one.
1528       }
1529     }
1530   >>
1531 }
1532 @end lilypond
1533
1534 @seealso
1535 Notation Reference:
1536 @ref{Keeping contexts alive},
1537 @ref{Repeats}.
1538
1539
1540 @node Divisi lyrics
1541 @unnumberedsubsubsec Divisi lyrics
1542
1543 @cindex divided lyrics
1544 @cindex lyrics, divided
1545
1546 When just the words and rhythms of the two parts differ with the
1547 pitches remaining the same, temporarily turning off the automatic
1548 detection of melismata and indicating the melisma in the lyrics
1549 may be the appropriate method to use:
1550
1551 @lilypond[quote,verbatim]
1552 \score {
1553   <<
1554     \new Voice = "melody" {
1555       \relative c' {
1556         \set melismaBusyProperties = #'()
1557         \slurDown
1558         \slurDashed
1559         e4 e8 ( e ) c4 c |
1560         \unset melismaBusyProperties
1561         c
1562       }
1563     }
1564     \new Lyrics \lyricsto "melody" {
1565       They shall not o -- ver -- come
1566     }
1567     \new Lyrics \lyricsto "melody" {
1568       We will _
1569     }
1570   >>
1571 }
1572 @end lilypond
1573
1574 When both music and words differ it may be better to display
1575 the differing music and lyrics by naming voice contexts and
1576 attaching lyrics to those specific contexts:
1577
1578 @lilypond[verbatim,ragged-right,quote]
1579 \score {
1580   <<
1581     \new Voice = "melody" {
1582       \relative c' {
1583         <<
1584           {
1585             \voiceOne
1586             e4 e8 e
1587           }
1588           \new Voice = "splitpart" {
1589             \voiceTwo
1590             c4 c
1591           }
1592         >>
1593         \oneVoice
1594         c4 c |
1595         c
1596       }
1597     }
1598     \new Lyrics \lyricsto "melody" {
1599       They shall not o -- ver -- come
1600     }
1601     \new Lyrics \lyricsto "splitpart" {
1602       We will
1603     }
1604   >>
1605 }
1606 @end lilypond
1607
1608
1609 @node Stanzas
1610 @subsection Stanzas
1611
1612 @menu
1613 * Adding stanza numbers::
1614 * Adding dynamics marks to stanzas::
1615 * Adding singers' names to stanzas::
1616 * Stanzas with different rhythms::
1617 * Printing stanzas at the end::
1618 * Printing stanzas at the end in multiple columns::
1619 @end menu
1620
1621
1622 @node Adding stanza numbers
1623 @unnumberedsubsubsec Adding stanza numbers
1624
1625 @cindex stanza number
1626
1627 Stanza numbers can be added by setting @code{stanza}, e.g.,
1628
1629 @lilypond[quote,ragged-right,verbatim,relative=2]
1630 \new Voice {
1631   \time 3/4 g2 e4 a2 f4 g2.
1632 } \addlyrics {
1633   \set stanza = #"1. "
1634   Hi, my name is Bert.
1635 } \addlyrics {
1636   \set stanza = #"2. "
1637   Oh, ché -- ri, je t'aime
1638 }
1639 @end lilypond
1640
1641
1642 @noindent
1643 These numbers are put just before the start of the first syllable.
1644
1645 @c TODO Create and add snippet to show how two lines of a
1646 @c stanza can be grouped together, along these lines:
1647 @c (might need improving a bit) -td
1648
1649 @ignore
1650 leftbrace = \markup { \override #'(font-encoding . fetaBraces) \lookup
1651 #"brace105" }
1652
1653 stanzaOneOne = {
1654   \set stanza = \markup { "1. " \leftbrace }
1655   \lyricmode { Child, you're mine and I love you.
1656     Lend thine ear to what I say.
1657
1658   }
1659 }
1660
1661 stanzaOneThree =  {
1662 %  \set stanza = \markup { "   "}
1663   \lyricmode { Child, I have no great -- er joy
1664     Than to have you walk in truth.
1665
1666   }
1667 }
1668
1669 \new Voice {
1670   \repeat volta 2 { c'8 c' c' c' c' c' c'4
1671                     c'8 c' c' c' c' c' c'4   }
1672 }  \addlyrics { \stanzaOneOne }
1673    \addlyrics { \stanzaOneThree }
1674
1675 @end ignore
1676
1677 @node Adding dynamics marks to stanzas
1678 @unnumberedsubsubsec Adding dynamics marks to stanzas
1679
1680 Stanzas differing in loudness may be indicated by putting a
1681 dynamics mark before each stanza.  In LilyPond, everything coming in
1682 front of a stanza goes into the @code{StanzaNumber} object; dynamics
1683 marks are no different.  For technical reasons, you have to set the
1684 stanza outside @code{\lyricmode}:
1685
1686 @lilypond[quote,ragged-right,verbatim]
1687 text = {
1688   \set stanza = \markup { \dynamic "ff" "1. " }
1689   \lyricmode {
1690     Big bang
1691   }
1692 }
1693
1694 <<
1695   \new Voice = "tune" {
1696     \time 3/4
1697     g'4 c'2
1698   }
1699 \new Lyrics \lyricsto "tune" \text
1700 >>
1701 @end lilypond
1702
1703 @node Adding singers' names to stanzas
1704 @unnumberedsubsubsec Adding singers' names to stanzas
1705
1706 @cindex singer name
1707 @cindex name of singer
1708
1709 Names of singers can also be added.  They are printed at the start of
1710 the line, just like instrument names.  They are created by setting
1711 @code{vocalName}.  A short version may be entered as
1712 @code{shortVocalName}.
1713
1714 @lilypond[ragged-right,quote,verbatim,relative=2]
1715 \new Voice {
1716   \time 3/4 g2 e4 a2 f4 g2.
1717 } \addlyrics {
1718   \set vocalName = #"Bert "
1719   Hi, my name is Bert.
1720 } \addlyrics {
1721   \set vocalName = #"Ernie "
1722   Oh, ché -- ri, je t'aime
1723 }
1724 @end lilypond
1725
1726 @node Stanzas with different rhythms
1727 @unnumberedsubsubsec Stanzas with different rhythms
1728
1729 Often, different stanzas of one song are put to one melody in slightly
1730 differing ways.  Such variations can still be captured with
1731 @code{\lyricsto}.
1732
1733 @subsubheading Ignoring melismata
1734
1735 One possibility is that the text has a melisma in one stanza, but
1736 multiple syllables in another.  One solution is to make the faster
1737 voice ignore the melisma.  This is done by setting
1738 @code{ignoreMelismata} in the Lyrics context.
1739
1740 @lilypond[verbatim,ragged-right,quote]
1741 <<
1742   \relative c' \new Voice = "lahlah" {
1743     \set Staff.autoBeaming = ##f
1744     c4
1745     \slurDotted
1746     f8.[( g16])
1747     a4
1748   }
1749   \new Lyrics \lyricsto "lahlah" {
1750     more slow -- ly
1751   }
1752   \new Lyrics \lyricsto "lahlah" {
1753     go
1754     \set ignoreMelismata = ##t
1755     fas -- ter
1756     \unset ignoreMelismata
1757     still
1758   }
1759 >>
1760 @end lilypond
1761
1762 @knownissues
1763 Unlike most @code{\set} commands, @code{\set ignoreMelismata} does
1764 not work if prefixed with @code{\once}.  It is necessary to use
1765 @code{\set} and @code{\unset} to bracket the lyrics where melismata
1766 are to be ignored.
1767
1768 @subsubheading Adding syllables to grace notes
1769
1770 @cindex grace notes and lyrics
1771 @cindex lyrics on grace notes
1772
1773 By default, grace notes (e.g. via @code{\grace}) do not get assigned
1774 syllables when using @code{\lyricsto}, but this behavior can be
1775 changed:
1776
1777 @lilypond[verbatim,ragged-right,quote]
1778 <<
1779   \new Voice = melody \relative c' {
1780     f4 \appoggiatura a32 b4
1781     \grace { f16[ a16] } b2
1782     \afterGrace b2 { f16[ a16] }
1783     \appoggiatura a32 b4
1784     \acciaccatura a8 b4
1785   }
1786   \new Lyrics
1787   \lyricsto melody {
1788     normal
1789     \set includeGraceNotes = ##t
1790     case,
1791     gra -- ce case,
1792     after -- grace case,
1793     \set ignoreMelismata = ##t
1794     app. case,
1795     acc. case.
1796   }
1797 >>
1798 @end lilypond
1799
1800 @knownissues
1801 Like @code{associatedVoice}, @code{includeGraceNotes} needs to be
1802 set at latest one syllable before the one which is to be put under a
1803 grace note.  For the case of a grace note at the very beginning of a
1804 piece of music, consider using a @code{\with} or @code{\context}
1805 block:
1806
1807 @lilypond[verbatim,ragged-right,quote]
1808 <<
1809   \new Voice = melody \relative c' {
1810     \grace { c16[( d e f] }
1811     g1) f
1812   }
1813   \new Lyrics \with { includeGraceNotes = ##t }
1814   \lyricsto melody {
1815     Ah __ fa
1816   }
1817 >>
1818 @end lilypond
1819
1820 @subsubheading Switching to an alternative melody
1821
1822 @cindex associatedVoice
1823 @cindex alternative melody, switching to
1824
1825 More complex variations in setting lyrics to music are possible.
1826 The melody to which the lyrics are being set can be changed from
1827 within the lyrics by setting the @code{associatedVoice} property:
1828
1829 @lilypond[verbatim,quote]
1830 <<
1831   \relative c' \new Voice = "lahlah" {
1832     \set Staff.autoBeaming = ##f
1833     c4
1834     <<
1835       \new Voice = "alternative" {
1836         \voiceOne
1837         \times 2/3 {
1838           % show associations clearly.
1839           \override NoteColumn #'force-hshift = #-3
1840           f8 f g
1841         }
1842       }
1843       {
1844         \voiceTwo
1845         f8.[ g16]
1846         \oneVoice
1847       } >>
1848     a8( b) c
1849   }
1850   \new Lyrics \lyricsto "lahlah" {
1851     Ju -- ras -- sic Park
1852   }
1853   \new Lyrics \lyricsto "lahlah" {
1854     % Tricky: need to set associatedVoice
1855     % one syllable too soon!
1856     \set associatedVoice = "alternative" % applies to "ran"
1857     Ty --
1858     ran --
1859     no --
1860     \set associatedVoice = "lahlah" % applies to "rus"
1861     sau -- rus Rex
1862   } >>
1863 @end lilypond
1864
1865 @noindent
1866 The text for the first stanza is set to the melody called
1867 @q{lahlah} in the usual way, but the second stanza is set initally
1868 to the @code{lahlah} context and is then switched to the
1869 @code{alternative} melody for the syllables @q{ran} to @q{sau} by
1870 the lines:
1871
1872 @example
1873 \set associatedVoice = "alternative" % applies to "ran"
1874 Ty --
1875 ran --
1876 no --
1877 \set associatedVoice = "lahlah" % applies to "rus"
1878 sau -- rus Rex
1879 @end example
1880
1881 @noindent
1882 Here, @code{alternative} is the name of the @code{Voice} context
1883 containing the triplet.
1884
1885 Note the placement of the @code{\set associatedVoice} command --
1886 it appears to be one syllable too early, but this is correct.
1887
1888 @warning{The @code{\set associatedVoice} command must be placed
1889 one syllable @emph{before} the one at which the switch to the new
1890 voice is to occur.  In other words, changing the associated Voice
1891 happens one syllable later than expected.  This is for technical
1892 reasons, and it is not a bug.}
1893
1894
1895 @node Printing stanzas at the end
1896 @unnumberedsubsubsec Printing stanzas at the end
1897
1898 Sometimes it is appropriate to have one stanza set
1899 to the music, and the rest added in verse form at
1900 the end of the piece.  This can be accomplished by adding
1901 the extra verses into a @code{\markup} section outside
1902 of the main score block.  Notice that there are two
1903 different ways to force linebreaks when using
1904 @code{\markup}.
1905
1906 @lilypond[ragged-right,verbatim,quote]
1907 melody = \relative c' {
1908 e d c d | e e e e |
1909 d d e d | c1 |
1910 }
1911
1912 text = \lyricmode {
1913 \set stanza = #"1." Ma- ry had a lit- tle lamb,
1914 its fleece was white as snow.
1915 }
1916
1917 \score{ <<
1918   \new Voice = "one" { \melody }
1919   \new Lyrics \lyricsto "one" \text
1920 >>
1921   \layout { }
1922 }
1923 \markup { \column{
1924   \line{ Verse 2. }
1925   \line{ All the children laughed and played }
1926   \line{ To see a lamb at school. }
1927   }
1928 }
1929 \markup{
1930   \wordwrap-string #"
1931   Verse 3.
1932
1933   Mary took it home again,
1934
1935   It was against the rule."
1936 }
1937 @end lilypond
1938
1939
1940 @node Printing stanzas at the end in multiple columns
1941 @unnumberedsubsubsec Printing stanzas at the end in multiple columns
1942
1943 When a piece of music has many verses, they are often printed in
1944 multiple columns across the page.  An outdented verse number often
1945 introduces each verse.  The following example shows how to produce such
1946 output in LilyPond.
1947
1948 @lilypond[ragged-right,quote,verbatim]
1949 melody = \relative c' {
1950   c c c c | d d d d
1951 }
1952
1953 text = \lyricmode {
1954   \set stanza = #"1." This is verse one.
1955   It has two lines.
1956 }
1957
1958 \score {
1959   <<
1960     \new Voice = "one" { \melody }
1961     \new Lyrics \lyricsto "one" \text
1962   >>
1963   \layout { }
1964 }
1965
1966 \markup {
1967   \fill-line {
1968     \hspace #0.1 % moves the column off the left margin;
1969         % can be removed if space on the page is tight
1970      \column {
1971       \line { \bold "2."
1972         \column {
1973           "This is verse two."
1974           "It has two lines."
1975         }
1976       }
1977       \hspace #0.1 % adds vertical spacing between verses
1978       \line { \bold "3."
1979         \column {
1980           "This is verse three."
1981           "It has two lines."
1982         }
1983       }
1984     }
1985     \hspace #0.1  % adds horizontal spacing between columns;
1986         % if they are still too close, add more " " pairs
1987         % until the result looks good
1988      \column {
1989       \line { \bold "4."
1990         \column {
1991           "This is verse four."
1992           "It has two lines."
1993         }
1994       }
1995       \hspace #0.1 % adds vertical spacing between verses
1996       \line { \bold "5."
1997         \column {
1998           "This is verse five."
1999           "It has two lines."
2000         }
2001       }
2002     }
2003   \hspace #0.1 % gives some extra space on the right margin;
2004       % can be removed if page space is tight
2005   }
2006 }
2007 @end lilypond
2008
2009
2010 @seealso
2011 Internals Reference:
2012 @rinternals{LyricText},
2013 @rinternals{StanzaNumber}.
2014
2015
2016 @node Songs
2017 @subsection Songs
2018
2019 @menu
2020 * References for songs::
2021 * Lead sheets::
2022 @end menu
2023
2024 @node References for songs
2025 @unnumberedsubsubsec References for songs
2026
2027 Songs are usually written on three staves with the melody for the
2028 singer on the top staff and two staves of piano accompaniment at
2029 the bottom.  The lyrics of the first stanza are printed immediately
2030 underneath the top staff.  If there are just a small number of
2031 further stanzas these can be printed immediately under the first
2032 one, but if there are more stanzas than can be easily accommodated
2033 there the second and subsequent stanzas are printed after the music
2034 as stand-alone text.
2035
2036 All the notational elements needed to write songs are fully described
2037 elsewhere:
2038
2039 @itemize
2040
2041 @item
2042 For constructing the staff layout, see @ref{Displaying staves}.
2043
2044 @item
2045 For writing piano music, see
2046 @ref{Keyboard and other multi-staff instruments}.
2047
2048 @item
2049 For writing the lyrics to a melody line, see
2050 @ref{Common notation for vocal music}.
2051
2052 @item
2053 For placing the lyrics, see @ref{Placing lyrics vertically}.
2054
2055 @item
2056 For entering stanzas, see @ref{Stanzas}.
2057
2058 @item
2059 Songs are frequently printed with the chording indicated by chord
2060 names above the staves.  This is described in @ref{Displaying chords}.
2061
2062 @item
2063 To print fret diagrams of the chords for guitar accompaniment or
2064 accompaniment by other fretted instruments, see @qq{Fret diagram
2065 markups} in @ref{Common notation for fretted strings}.
2066
2067 @end itemize
2068
2069 @seealso
2070 Learning Manual:
2071 @rlearning{Songs}.
2072
2073 Notation Reference:
2074 @ref{Common notation for vocal music},
2075 @ref{Displaying chords},
2076 @ref{Displaying staves},
2077 @ref{Keyboard and other multi-staff instruments},
2078 @ref{Placing lyrics vertically},
2079 @ref{Stanzas}.
2080
2081 Snippets:
2082 @rlsr{Vocal music}.
2083
2084 @node Lead sheets
2085 @unnumberedsubsubsec Lead sheets
2086
2087 Lead sheets may be printed by combining vocal parts and
2088 @q{chord mode}; this syntax is explained in @ref{Chord notation}.
2089
2090 @snippets
2091 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
2092 {simple-lead-sheet.ly}
2093
2094 @seealso
2095 Notation Reference:
2096 @ref{Chord notation}.
2097
2098
2099 @node Choral
2100 @subsection Choral
2101
2102 @cindex anthems
2103 @cindex part songs
2104 @cindex oratorio
2105 @cindex SATB
2106
2107 This section discusses notation issues that relate most directly
2108 to choral music.  This includes anthems, part songs, oratorio,
2109 etc.
2110
2111 @menu
2112 * References for choral::
2113 * Score layouts for choral::
2114 * Divided voices::
2115 @end menu
2116
2117 @node References for choral
2118 @unnumberedsubsubsec References for choral
2119
2120 Choral music is usually notated on two, three or four staves within
2121 a @code{ChoirStaff} group.  Accompaniment, if required, is placed
2122 beneath in a @code{PianoStaff} group, which is usually reduced in
2123 size for @emph{a capella} choral works.  The notes for each vocal
2124 part are placed in a @code{Voice} context, with each staff
2125 being given either a single vocal part (i.e., one @code{Voice}) or
2126 a pair of vocal parts (i.e., two @code{Voice}s).
2127
2128 Words are placed in @code{Lyrics} contexts, either underneath each
2129 corresponding music staff, or one above and one below the music
2130 staff if this contains the music for two parts.
2131
2132 Several common topics in choral music are described fully elsewhere:
2133
2134 @itemize
2135
2136 @item
2137 An introduction to creating an SATB vocal score can be found in
2138 the Learning Manual, see @rlearning{Four-part SATB vocal score}.
2139
2140 @item
2141 Several templates suitable for various styles of choral music can
2142 also be found in the Learning Manual, see
2143 @rlearning{Vocal ensembles}.
2144
2145 @item
2146 For information about @code{ChoirStaff} and @code{PianoStaff} see
2147 @ref{Grouping staves}.
2148
2149 @item
2150 Shape note heads, as used in Sacred Harp and similar notation, are
2151 described in @ref{Shape note heads}.
2152
2153 @item
2154 When two vocal parts share a staff the stems, ties, slurs, etc., of
2155 the higher part will be directed up and those of the lower part
2156 down.  To do this, use @code{\voiceOne} and @code{\voiceTwo}.  See
2157 @ref{Single-staff polyphony}.
2158
2159 @end itemize
2160
2161 @predefined
2162 @code{\oneVoice},
2163 @code{\voiceOne},
2164 @code{\voiceTwo}.
2165
2166 @seealso
2167 Learning Manual:
2168 @rlearning{Four-part SATB vocal score},
2169 @rlearning{Vocal ensembles}.
2170
2171 Notation Reference:
2172 @ref{Context layout order},
2173 @ref{Grouping staves},
2174 @ref{Shape note heads},
2175 @ref{Single-staff polyphony}.
2176
2177 Snippets:
2178 @rlsr{Vocal music}.
2179
2180 Internals Reference:
2181 @rinternals{ChoirStaff},
2182 @rinternals{Lyrics},
2183 @rinternals{PianoStaff}.
2184
2185 @node Score layouts for choral
2186 @unnumberedsubsubsec Score layouts for choral
2187
2188 Choral music containing four staves, with or without piano
2189 accompaniment, is usually laid out with two systems per page.
2190 Depending on the page size, achieving this may require changes
2191 to several default settings.  The following settings should be
2192 considered:
2193
2194 @itemize
2195
2196 @item
2197 The global staff size can be modified to change the overall size
2198 of the elements of the score.  See @ref{Setting the staff size}.
2199
2200 @item
2201 The distances between the systems, the staves and the lyrics can
2202 all be adjusted independently.  See @ref{Vertical spacing}.
2203
2204 @item
2205 The dimensions of the vertical layout variables can be displayed as
2206 an aid to adjusting the vertical spacing.  This and other
2207 possibilities for fitting the music onto fewer pages are described
2208 in @ref{Fitting music onto fewer pages}.
2209
2210 @item
2211 If the number of systems per page changes from one to two it is
2212 customary to indicate this with a system separator mark between
2213 the two systems.  See @ref{Separating systems}.
2214
2215 @item
2216 For details of other page formatting properties, see
2217 @ref{Page layout}.
2218
2219 @end itemize
2220
2221
2222 Dynamic markings by default are placed below the staff, but in
2223 choral music they are usually placed above the staff in order to
2224 avoid the lyrics.  The predefined command @code{\dynamicUp} does
2225 this for the dynamic markings in a single @code{Voice} context.
2226 If there are many @code{Voice} contexts this predefined command
2227 would have to be placed in every one.  Alternatively its expanded
2228 form can be used to place all dynamic markings in the entire score
2229 above their respective staves, as shown here:
2230
2231 @lilypond[verbatim,quote]
2232 \score {
2233   \new ChoirStaff <<
2234     \new Staff {
2235       \new Voice {
2236         \relative c'' { g4\f g g g }
2237       }
2238     }
2239     \new Staff {
2240       \new Voice {
2241         \relative c' { d4 d d\p d }
2242       }
2243     }
2244   >>
2245   \layout {
2246     \context {
2247       \Score
2248       \override DynamicText #'direction = #UP
2249       \override DynamicLineSpanner #'direction = #UP
2250     }
2251   }
2252 }
2253 @end lilypond
2254
2255 @predefined
2256 @code{\dynamicUp}, @code{\dynamicDown}, @code{\dynamicNeutral}.
2257
2258 @seealso
2259 Notation Reference:
2260 @ref{Changing spacing},
2261 @ref{Displaying spacing},
2262 @ref{Fitting music onto fewer pages},
2263 @ref{Page layout},
2264 @ref{Score layout},
2265 @ref{Separating systems},
2266 @ref{Setting the staff size},
2267 @ref{Using an extra voice for breaks},
2268 @ref{Vertical spacing}.
2269
2270 Internals Reference:
2271 @rinternals{VerticalAxisGroup},
2272 @rinternals{StaffGrouper}.
2273
2274
2275 @node Divided voices
2276 @unnumberedsubsubsec Divided voices
2277
2278 @cindex voices, divided
2279
2280 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
2281 {using-arpeggiobracket-to-make-divisi-more-visible.ly}
2282
2283 @seealso
2284 Notation Reference:
2285 @ref{Expressive marks as lines}.
2286
2287
2288 @node Opera and stage musicals
2289 @subsection Opera and stage musicals
2290
2291 The music, lyrics and dialogue to opera and stage musicals are
2292 usually set out in one or more of the following forms:
2293
2294 @itemize
2295
2296 @item
2297 A @emph{Conductors' Score} containing the full orchestral and vocal
2298 parts, together with libretto cues if there are spoken passages.
2299
2300 @item
2301 @emph{Orchestral Parts} containing the music for the individual
2302 instruments of the orchestra or band.
2303
2304 @item
2305 A @emph{Vocal Score} containing all vocal parts with piano
2306 accompaniment.  The accompaniment is usually an orchestral
2307 reduction, and if so the name of the original orchestral instrument
2308 is often indicated.  Vocal scores sometimes includes stage
2309 directions and libretto cues.
2310
2311 @item
2312 A @emph{Vocal Book} containing just the vocal parts
2313 (no accompaniment), sometimes combined with the libretto.
2314
2315 @item
2316 A @emph{Libretto} containing the extended passages of spoken
2317 dialogue usually found in musicals, together with the words to the
2318 sung parts.  Stage directions are usually included.  LilyPond can
2319 be used to typeset libretti but as they contain no music
2320 alternative methods may be preferable.
2321
2322 @end itemize
2323
2324 The sections in the LilyPond documentation which cover the topics
2325 needed to create scores in the styles commonly found in opera and
2326 musicals are indicated in the References below.  This is followed
2327 by sections covering those techniques which are peculiar to
2328 typesetting opera and musical scores.
2329
2330 @menu
2331 * References for opera and stage musicals::
2332 * Character names::
2333 * Musical cues::
2334 * Spoken music::
2335 * Dialogue over music::
2336 @end menu
2337
2338 @node References for opera and stage musicals
2339 @unnumberedsubsubsec References for opera and stage musicals
2340
2341 @itemize
2342
2343 @item
2344 A conductors' score contains many grouped staves and lyrics.  Ways
2345 of grouping staves is shown in @ref{Grouping staves}.  To nest
2346 groups of staves see @ref{Nested staff groups}.
2347
2348 @item
2349 The printing of empty staves in conductors' scores and vocal scores
2350 is often suppressed.  To create such a @qq{Frenched score} see
2351 @ref{Hiding staves}.
2352
2353 @item
2354 Writing orchestral parts is covered in @ref{Writing parts}.
2355 Other sections in the Specialist notation chapter may be relevant,
2356 depending on the orchestration used.  Many instruments are
2357 transposing instruments, see @ref{Instrument transpositions}.
2358
2359 @item
2360 If the number of systems per page changes from page to page it is
2361 customary to separate the systems with a system separator mark.
2362 See @ref{Separating systems}.
2363
2364 @item
2365 For details of other page formatting properties, see
2366 @ref{Page layout}.
2367
2368 @item
2369 Dialogue cues and stage directions can be inserted with markup.
2370 See @ref{Text}.  Extensive stage directions can be inserted with
2371 a section of stand-alone markup between two @code{\score} blocks.
2372 See @ref{Separate text}.
2373
2374 @end itemize
2375
2376 @seealso
2377 Musical Glossary:
2378 @rglos{Frenched score},
2379 @rglos{Frenched staves},
2380 @rglos{transposing instrument}.
2381
2382 Notation Reference:
2383 @ref{Grouping staves},
2384 @ref{Hiding staves},
2385 @ref{Instrument transpositions},
2386 @ref{Nested staff groups},
2387 @ref{Page layout},
2388 @ref{Separating systems},
2389 @ref{Transpose},
2390 @ref{Writing parts},
2391 @ref{Writing text}.
2392
2393 Snippets:
2394 @rlsr{Vocal music}.
2395
2396
2397 @node Character names
2398 @unnumberedsubsubsec Character names
2399
2400 @cindex character names
2401 @cindex names, character
2402
2403 Character names are usually shown to the left of the staff when the
2404 staff is dedicated to that character alone:
2405
2406 @lilypond[quote,verbatim,ragged-right]
2407 \score {
2408   <<
2409     \new Staff {
2410       \set Staff.vocalName = \markup \smallCaps Kaspar
2411       \set Staff.shortVocalName = \markup \smallCaps Kas.
2412       \relative c' {
2413         \clef "G_8"
2414         c4 c c c
2415         \break
2416         c4 c c c
2417       }
2418     }
2419     \new Staff {
2420       \set Staff.vocalName = \markup \smallCaps Melchior
2421       \set Staff.shortVocalName = \markup \smallCaps Mel
2422       \clef "bass"
2423       \relative c' {
2424         a4 a a a
2425         a4 a a a
2426       }
2427     }
2428   >>
2429 }
2430 @end lilypond
2431
2432 When two or more characters share a staff the character's name is
2433 usually printed above the staff at the start of every section
2434 applying to that character.  This can be done with markup.  Often a
2435 specific font is used for this purpose.
2436
2437 @lilypond[quote,verbatim,relative=1]
2438 \clef "G_8"
2439 c4^\markup \fontsize #1 \smallCaps Kaspar
2440 c c c
2441 \clef "bass"
2442 a4^\markup \fontsize #1 \smallCaps Melchior
2443 a a a
2444 \clef "G_8"
2445 c4^\markup \fontsize #1 \smallCaps Kaspar
2446 c c c
2447 @end lilypond
2448
2449 Alternatively, if there are many character changes, it may be
2450 easier to set up @qq{instrument} definitions for each character at
2451 the top level so that @code{\instrumentSwitch} can be used to
2452 indicate each change.
2453
2454 @lilypond[quote,verbatim]
2455 \addInstrumentDefinition #"kaspar"
2456   #`((instrumentTransposition . ,(ly:make-pitch -1 0 0))
2457      (shortInstrumentName . "Kas.")
2458      (clefGlyph . "clefs.G")
2459      (clefOctavation . -7)
2460      (middleCPosition . 1)
2461      (clefPosition . -2)
2462      (instrumentCueName . ,(markup #:fontsize 1 #:smallCaps "Kaspar"))
2463      (midiInstrument . "voice oohs"))
2464
2465 \addInstrumentDefinition #"melchior"
2466   #`((instrumentTransposition . ,(ly:make-pitch 0 0 0))
2467      (shortInstrumentName . "Mel.")
2468      (clefGlyph . "clefs.F")
2469      (clefOctavation . 0)
2470      (middleCPosition . 6)
2471      (clefPosition . 2)
2472      (instrumentCueName . ,(markup #:fontsize 1 #:smallCaps "Melchior"))
2473      (midiInstrument . "voice aahs"))
2474
2475 \relative c' {
2476   \instrumentSwitch "kaspar"
2477   c4 c c c
2478   \instrumentSwitch "melchior"
2479   a4 a a a
2480   \instrumentSwitch "kaspar"
2481   c4 c c c
2482 }
2483 @end lilypond
2484
2485 @seealso
2486 Notation Reference:
2487 @ref{Instrument names},
2488 @ref{Scheme functions},
2489 @ref{Text},
2490 @ref{Text markup commands}.
2491
2492 Extending LilyPond:
2493 @rextend{Markup construction in Scheme}.
2494
2495 @node Musical cues
2496 @unnumberedsubsubsec Musical cues
2497
2498 @cindex musical cues
2499 @cindex cues, musical
2500
2501 Musical cues can be inserted in Vocal Scores, Vocal Books and
2502 Orchestral Parts to indicate what music in another part
2503 immediately precedes an entry.  Also, cues are often inserted in the
2504 piano reduction in Vocal Scores to indicate what each orchestral
2505 instrument is playing.  This aids the conductor when a full
2506 Conductors' Score is not available.
2507
2508 The basic mechanism for inserting cues is fully explained in the
2509 main text, see @ref{Quoting other voices} and
2510 @ref{Formatting cue notes}.  But when many cues have to be
2511 inserted, for example, as an aid to a conductor in a vocal score,
2512 the instrument name must be positioned carefully just before and
2513 close to the start of the cue notes.  The following example shows
2514 how this is done.
2515
2516 @lilypond[quote,verbatim]
2517 flute = \relative c'' {
2518   s4 s4 e g
2519 }
2520 \addQuote "flute" { \flute }
2521
2522 pianoRH = \relative c'' {
2523   c4. g8
2524   % position name of cue-ing instrument just before the cue notes,
2525   % and above the staff
2526   s1*0^\markup { \right-align { \tiny "Flute" } }
2527   \cueDuring "flute" #UP { g4 bes4 }
2528 }
2529 pianoLH = \relative c { c4 <c' e> e, <g c> }
2530
2531 \score {
2532   \new PianoStaff <<
2533     \new Staff {
2534       \pianoRH
2535     }
2536     \new Staff {
2537       \clef "bass"
2538       \pianoLH
2539     }
2540   >>
2541 }
2542 @end lilypond
2543
2544 If a transposing instrument is being quoted the instrument part should
2545 specify its key so the conversion of its cue notes will be done
2546 automatically.  The example below shows this transposition for a
2547 B-flat clarinet.  The notes in this example are low on the staff so
2548 @code{#DOWN} is specified in @code{\cueDuring} (so the stems are
2549 down) and the instrument name is positioned below the staff.  Note
2550 also that the piano right-hand voice is explicitly declared.  This
2551 is because the cue notes in this example begin at the start of the
2552 first bar and this would otherwise cause the entire piano right-hand
2553 notes to be placed in a @code{CueVoice} context.
2554
2555 @lilypond[quote,verbatim]
2556 clarinet = \relative c' {
2557   \transposition bes
2558   fis4 d d c
2559 }
2560 \addQuote "clarinet" { \clarinet }
2561
2562 pianoRH = \relative c'' {
2563   \transposition c'
2564   % position name of cue-ing instrument below the staff
2565   s1*0_\markup { \right-align { \tiny "Clar." } }
2566   \cueDuring "clarinet" #DOWN { c4. g8 }
2567   g4 bes4
2568 }
2569 pianoLH = \relative c { c4 <c' e> e, <g c> }
2570
2571 \score {
2572   <<
2573     \new PianoStaff <<
2574       \new Staff {
2575         \new Voice {
2576           \pianoRH
2577         }
2578       }
2579       \new Staff {
2580         \clef "bass"
2581         \pianoLH
2582       }
2583     >>
2584   >>
2585 }
2586 @end lilypond
2587
2588 From these two examples it is clear that inserting many cues in a
2589 Vocal Score would be tedious, and the notes of the piano part would
2590 become obscured.  However, as the following snippet shows, it is
2591 possible to define a music function to reduce the amount of typing
2592 and to make the piano notes clearer.
2593
2594 @snippets
2595 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
2596 {adding-orchestral-cues-to-a-vocal-score.ly}
2597
2598 @seealso
2599 Musical Glossary:
2600 @rglos{cue-notes}.
2601
2602 Notation Reference:
2603 @ref{Aligning objects},
2604 @ref{Direction and placement},
2605 @ref{Formatting cue notes},
2606 @ref{Quoting other voices},
2607 @ref{Using music functions}.
2608
2609 Snippets:
2610 @rlsr{Vocal music}.
2611
2612 Internals Reference:
2613 @rinternals{InstrumentSwitch},
2614 @rinternals{CueVoice}.
2615
2616 @knownissues
2617 @code{\cueDuring} automatically inserts a @code{CueVoice} context
2618 and all cue notes are placed in that context.  This means it is not
2619 possible to have two overlapping sequences of cue notes by this
2620 technique.  Overlapping sequences could be entered by explicitly
2621 declaring separate @code{CueVoice} contexts and using
2622 @code{\quoteDuring} to extract and insert the cue notes.
2623
2624
2625 @node Spoken music
2626 @unnumberedsubsubsec Spoken music
2627
2628 @cindex parlato
2629 @cindex Sprechgesang
2630 Such effects as @q{parlato} or @q{Sprechgesang} require performers to
2631 speak without pitch but still with rhythm; these are notated by cross
2632 note heads, as demonstrated in @ref{Special note heads}.
2633
2634 @c TODO add "marking-notes-on-spoken-parts" snippet -vv
2635 @c add "showing the rhythm of a melody" snip
2636 @c add "one staff-line notation"
2637 @c add "improvisation" ref
2638 @c add "lyrics independents of notes" ref
2639
2640 @node Dialogue over music
2641 @unnumberedsubsubsec Dialogue over music
2642
2643 Dialogue over music is usually printed over the staves in an italic
2644 font, with the start of each phrase keyed in to a particular music
2645 moment.
2646
2647 For short interjections a simple markup suffices.
2648
2649 @lilypond[quote,verbatim,relative=2]
2650 a4^\markup { \smallCaps { Alex - } \italic { He's gone } } a a a
2651 a4 a a^\markup { \smallCaps { Bethan - } \italic Where? } a
2652 a4 a a a
2653 @end lilypond
2654
2655 For longer phrases it may be necessary to expand the music to make
2656 the words fit neatly.  There is no provision in LilyPond to do this
2657 fully automatically, and some manual intervention to layout the
2658 page will be necessary.
2659
2660 For long phrases or for passages with a lot of closely packed
2661 dialogue, using a Lyrics context will give better results.  The
2662 Lyrics context should not be associated with a music Voice; instead
2663 each section of dialogue should be given an explicit duration.  If
2664 there is a gap in the dialogue, the final word should be separated
2665 from the rest and the duration split between them so that the
2666 underlying music spaces out smoothly.
2667
2668 If the dialogue extends for more than one line it will be necessary
2669 to manually insert @code{\break}s and adjust the placing of the
2670 dialogue to avoid running into the right margin.  The final word of
2671 the last measure on a line should also be separated out, as above.
2672
2673 Here is an example illustrating how this might be done.
2674
2675 @c This should be a snippet, but it can't be as it needs to be
2676 @c manually adjusted to suit the imposed line length.  -td
2677
2678 @lilypond[quote,verbatim,ragged-right]
2679 music = \relative c'' {
2680   \repeat unfold 3 { a4 a a a }
2681 }
2682
2683 dialogue = \lyricmode {
2684   \markup {
2685     \fontsize #1 \upright \smallCaps Abe:
2686     "Say this over measures one and"
2687   }4*7
2688   "two"4 |
2689   \break
2690   "and this over measure"4*3
2691   "three"4 |
2692 }
2693
2694 \score {
2695   <<
2696     \new Lyrics \with {
2697       \override LyricText #'font-shape = #'italic
2698       \override LyricText #'self-alignment-X = #LEFT
2699     }
2700     { \dialogue }
2701     \new Staff {
2702       \new Voice { \music }
2703     }
2704   >>
2705 }
2706 @end lilypond
2707
2708 @c TODO show use of \column to produce dialogue on two lines
2709
2710 @seealso
2711 Notation Reference:
2712 @ref{Manual syllable durations},
2713 @ref{Text}.
2714
2715 Internal Reference:
2716 @rinternals{LyricText}.
2717
2718
2719 @node Chants psalms and hymns
2720 @subsection Chants psalms and hymns
2721
2722 @cindex chants
2723 @cindex psalms
2724 @cindex hymns
2725 @cindex religious music
2726
2727 The music and words for chants, psalms and hymns usually follow a
2728 well-established format in any particular church.  Although the
2729 formats may differ from church to church the type-setting problems
2730 which arise are broadly similar, and are covered in this section.
2731
2732 @menu
2733 * References for chants and psalms::
2734 * Setting a chant::
2735 * Pointing a psalm::
2736 * Partial measures in hymn tunes::
2737 @end menu
2738
2739 @node References for chants and psalms
2740 @unnumberedsubsubsec References for chants and psalms
2741
2742 Typesetting Gregorian chant in various styles of ancient notation
2743 is described in @ref{Ancient notation}.
2744
2745 @seealso
2746 Notation reference:
2747 @ref{Ancient notation}.
2748
2749 Snippets:
2750 @rlsr{Vocal music}.
2751
2752
2753 @node Setting a chant
2754 @unnumberedsubsubsec Setting a chant
2755
2756 Modern chant settings use modern notation with varying numbers of
2757 elements taken from ancient notation.  Some of the elements and
2758 methods to consider are shown here.
2759
2760 Chants often use quarter notes without stems to indicate the pitch,
2761 with the rhythm being taken from the spoken rhythm of the words.
2762
2763 @lilypond[verbatim,quote]
2764 stemOff = { \override Staff.Stem #'transparent = ##t }
2765
2766 \relative c' {
2767   \stemOff
2768   a'4 b c2 |
2769 }
2770
2771 @end lilypond
2772
2773 Chants often omit the bar lines or use shortened or dotted bar
2774 lines to indicate pauses in the music.  To omit all bar lines from
2775 all staves remove the bar line engraver completely:
2776
2777 @lilypond[verbatim,quote]
2778 \score {
2779   \new StaffGroup <<
2780     \new Staff {
2781       \relative c'' {
2782         a4 b c2 |
2783         a4 b c2 |
2784         a4 b c2 |
2785       }
2786     }
2787     \new Staff {
2788       \relative c'' {
2789         a4 b c2 |
2790         a4 b c2 |
2791         a4 b c2 |
2792       }
2793     }
2794   >>
2795   \layout {
2796     \context {
2797       \Staff
2798       \remove Bar_engraver
2799     }
2800   }
2801 }
2802 @end lilypond
2803
2804 Bar lines can also be removed on a staff-by-staff basis:
2805
2806 @lilypond[verbatim, quote]
2807 \score {
2808   \new ChoirStaff <<
2809     \new Staff
2810     \with { \remove Bar_engraver } {
2811       \relative c'' {
2812         a4 b c2 |
2813         a4 b c2 |
2814         a4 b c2 |
2815       }
2816     }
2817     \new Staff {
2818       \relative c'' {
2819         a4 b c2 |
2820         a4 b c2 |
2821         a4 b c2 |
2822       }
2823     }
2824   >>
2825 }
2826 @end lilypond
2827
2828 To remove bar lines from just a section of music treat it as a
2829 cadenza.  If the section is long you may need to insert dummy
2830 bar lines with @code{\bar ""} to show where the line should break.
2831
2832 @lilypond[verbatim,quote,relative=2]
2833 a4 b c2 |
2834 \cadenzaOn
2835 a4 b c2
2836 a4 b c2
2837 \bar ""
2838 a4 b c2
2839 a4 b c2
2840 \cadenzaOff
2841 a4 b c2 |
2842 a4 b c2 |
2843 @end lilypond
2844
2845 Rests or pauses in chants can be indicated by modified bar lines.
2846
2847 @lilypond[verbatim, quote,relative=2]
2848 a4
2849 \cadenzaOn
2850 b c2
2851 a4 b c2
2852 \bar "'"
2853 a4 b c2
2854 a4 b c2
2855 \bar ":"
2856 a4 b c2
2857 \bar "dashed"
2858 a4 b c2
2859 \bar "||"
2860 @end lilypond
2861
2862 Alternatively, the notation used in Gregorian chant for pauses or
2863 rests is sometimes used even though the rest of the notation is
2864 modern.  This uses a modified @code{\breathe} mark:
2865
2866 @lilypond[verbatim,quote]
2867 divisioMinima = {
2868   \once \override BreathingSign  #'stencil = #ly:breathing-sign::divisio-minima
2869   \once \override BreathingSign  #'Y-offset = #0
2870   \breathe
2871 }
2872 divisioMaior = {
2873   \once \override BreathingSign  #'stencil = #ly:breathing-sign::divisio-maior
2874   \once \override BreathingSign  #'Y-offset = #0
2875   \breathe
2876 }
2877 divisioMaxima = {
2878   \once \override BreathingSign  #'stencil = #ly:breathing-sign::divisio-maxima
2879   \once \override BreathingSign  #'Y-offset = #0
2880   \breathe
2881 }
2882 finalis = {
2883   \once \override BreathingSign  #'stencil = #ly:breathing-sign::finalis
2884   \once \override BreathingSign  #'Y-offset = #0
2885   \breathe
2886 }
2887
2888 \score {
2889   \relative c'' {
2890     g2 a4 g
2891     \divisioMinima
2892     g2 a4 g
2893     \divisioMaior
2894     g2 a4 g
2895     \divisioMaxima
2896     g2 a4 g
2897     \finalis
2898   }
2899   \layout {
2900     \context {
2901       \Staff
2902       \remove Bar_engraver
2903     }
2904   }
2905 }
2906 @end lilypond
2907
2908 Chants usually omit the time signature and often omit the clef too.
2909
2910 @lilypond[verbatim,quote]
2911 \score {
2912   \new Staff {
2913     \relative c'' {
2914       a4 b c2 |
2915       a4 b c2 |
2916       a4 b c2 |
2917     }
2918   }
2919   \layout {
2920     \context {
2921       \Staff
2922       \remove Bar_engraver
2923       \remove Time_signature_engraver
2924       \remove Clef_engraver
2925     }
2926   }
2927 }
2928 @end lilypond
2929
2930 Chants for psalms in the Anglican tradition are usually either
2931 @emph{single}, with 7 bars of music, or @emph{double}, with two lots
2932 of 7 bars.  Each group of 7 bars is divided into two halves,
2933 corresponding to the two halves of each verse, usually separated by
2934 a double bar line.  Only whole and half notes are used.  The 1st bar
2935 in each half always contains a single chord of whole notes.  This is
2936 the @qq{reciting note}.  Chants are usually centered on the page.
2937
2938 @lilypond[verbatim,quote]
2939 SopranoMusic = \relative g' {
2940   g1 | c2 b | a1 | \bar "||"
2941   a1 | d2 c | c b | c1 | \bar "||"
2942 }
2943
2944 AltoMusic = \relative c' {
2945   e1 | g2 g | f1 |
2946   f1 | f2 e | d d | e1 |
2947 }
2948
2949 TenorMusic = \relative a {
2950   c1 | c2 c | c1 |
2951   d1 | g,2 g | g g | g1 |
2952 }
2953
2954 BassMusic =  \relative c {
2955   c1 | e2 e | f1 |
2956   d1 | b2 c | g' g | c,1 |
2957 }
2958
2959 global = {
2960   \time 2/2
2961 }
2962
2963 % Use markup to center the chant on the page
2964 \markup {
2965   \fill-line {
2966     \score {  % centered
2967       <<
2968         \new ChoirStaff <<
2969           \new Staff <<
2970             \global
2971             \clef "treble"
2972             \new Voice = "Soprano" <<
2973               \voiceOne
2974               \SopranoMusic
2975             >>
2976             \new Voice = "Alto" <<
2977               \voiceTwo
2978               \AltoMusic
2979             >>
2980           >>
2981           \new Staff <<
2982             \clef "bass"
2983             \global
2984             \new Voice = "Tenor" <<
2985               \voiceOne
2986               \TenorMusic
2987             >>
2988             \new Voice = "Bass" <<
2989               \voiceTwo
2990               \BassMusic
2991             >>
2992           >>
2993         >>
2994       >>
2995       \layout {
2996         \context {
2997           \Score
2998           \override SpacingSpanner
2999           #'base-shortest-duration = #(ly:make-moment 1 2)
3000         }
3001         \context {
3002           \Staff
3003           \remove "Time_signature_engraver"
3004         }
3005       }
3006     }  % End score
3007   }
3008 }  % End markup
3009 @end lilypond
3010
3011 Some other approaches to setting such a chant are shown in the first
3012 of the following snippets.
3013
3014 @snippets
3015
3016 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
3017 {chant-or-psalms-notation.ly}
3018
3019 Canticles and other liturgical texts may be set more freely, and
3020 may use notational elements from ancient music.  Often the words
3021 are shown underneath and aligned with the notes.  If so, the notes
3022 are spaced in accordance with the syllables rather than the notes'
3023 durations.
3024
3025 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
3026 {ancient-notation-template----modern-transcription-of-gregorian-music.ly}
3027
3028 @seealso
3029 Learning Manual:
3030 @rlearning{Visibility and color of objects},
3031 @rlearning{Vocal ensembles}.
3032
3033 Notation Reference:
3034 @ref{Ancient notation},
3035 @ref{Bar lines},
3036 @ref{Modifying context plug-ins},
3037 @ref{Typesetting Gregorian chant},
3038 @ref{Unmetered music},
3039 @ref{Visibility of objects}.
3040
3041
3042 @node Pointing a psalm
3043 @unnumberedsubsubsec Pointing a psalm
3044
3045 The words to an Anglican psalm are usually printed in separate
3046 verses centered underneath the chant.
3047
3048 Single chants (with 7 bars) are repeated for every verse.  Double
3049 chants (with 14 bars) are repeated for every pair of verses.  Marks
3050 are inserted in the words to show how they should be fitted to the
3051 chant.  Each verse is divided into two halves.  A colon is usually
3052 used to indicate this division.  This corresponds to the double bar
3053 line in the music.  The words before the colon are sung to the first
3054 three bars of music; the words after the colon are sung to the last
3055 four bars.
3056
3057 Single bar lines (or in some psalters an inverted comma or similar
3058 symbol) are inserted between words to indicate where the bar lines
3059 in the music fall.  In markup mode a single bar line can be entered
3060 with the bar check symbol, @code{|}.
3061
3062 @lilypond[verbatim,quote]
3063 \markup {
3064   \fill-line {
3065     \column {
3066       \left-align {
3067         \line { O come let us sing | unto the | Lord : let }
3068         \line { us heartily rejoice in the | strength of | our }
3069         \line { sal- | -vation. }
3070       }
3071     }
3072   }
3073 }
3074 @end lilypond
3075
3076 Other symbols may require glyphs from the @code{fetaMusic} fonts.
3077 For details, see @ref{Fonts}.
3078
3079 @lilypond[verbatim,quote]
3080 tick = \markup {
3081   \raise #1 \fontsize #-5 \musicglyph #"scripts.rvarcomma"
3082 }
3083 \markup {
3084   \fill-line {
3085     \column {
3086       \left-align {
3087         \line { O come let us sing \tick unto the \tick Lord : let }
3088         \line {
3089           us heartily rejoice in the \tick strength of \tick our
3090         }
3091         \line { sal \tick vation. }
3092       }
3093     }
3094   }
3095 }
3096 @end lilypond
3097
3098 Where there is one whole note in a bar all the words corresponding
3099 to that bar are recited on that one note in speech rhythm.  Where
3100 there are two notes in a bar there will usually be only one or two
3101 corresponding syllables.  If there are more that two syllables a
3102 dot is usually inserted to indicate where the change in note occurs.
3103
3104 @lilypond[verbatim,quote]
3105 dot = \markup {
3106   \raise #0.7 \musicglyph #"dots.dot"
3107 }
3108 tick = \markup {
3109   \raise #1 \fontsize #-5 \musicglyph #"scripts.rvarcomma"
3110 }
3111 \markup {
3112   \fill-line {
3113     \column {
3114       \left-align {
3115         \line {
3116           O come let us sing \tick unto \dot the \tick Lord : let
3117         }
3118         \line {
3119           us heartily rejoice in the \tick strength of \tick our
3120         }
3121         \line { sal \tick vation. }
3122       }
3123     }
3124   }
3125 }
3126 @end lilypond
3127
3128 In some psalters an asterisk is used to indicate a break in a
3129 recited section instead of a comma, and stressed or slightly
3130 lengthened syllables are indicated in bold text.
3131
3132 @lilypond[verbatim,quote]
3133 dot = \markup {
3134   \raise #0.7 \musicglyph #"dots.dot"
3135 }
3136 tick = \markup {
3137   \raise #1 \fontsize #-5 \musicglyph #"scripts.rvarcomma"
3138 }
3139 \markup {
3140   \fill-line {
3141     \column {
3142       \left-align {
3143         \line { Today if ye will hear his voice * }
3144         \line {
3145           \concat { \bold hard en }
3146           | not your | hearts : as in the pro-
3147         }
3148         \line { vocation * and as in the \bold day of tempt- | }
3149         \line { -ation | in the | wilderness. }
3150       }
3151     }
3152   }
3153 }
3154 @end lilypond
3155
3156 In other psalters an accent is placed over the syllable to indicate
3157 stress.
3158
3159 @lilypond[verbatim,quote]
3160 tick = \markup {
3161   \raise #2 \fontsize #-5 \musicglyph #"scripts.rvarcomma"
3162 }
3163 \markup {
3164   \fill-line {
3165     \column {
3166       \left-align {
3167         \line {
3168           O come let us \concat {
3169             si \combine \tick ng
3170           }
3171           | unto the | Lord : let
3172         }
3173         \line {
3174           us heartily \concat {
3175             rejo \combine \tick ice
3176           }
3177           in the | strength of | our
3178         }
3179         \line { sal- | -vation. }
3180       }
3181     }
3182   }
3183 }
3184 @end lilypond
3185
3186 The use of markup to center text, and arrange lines in columns is
3187 described in @ref{Formatting text}.
3188
3189 Most of these elements are shown in one or other of the two verses
3190 in the template, see @qq{Psalms} in @rlearning{Vocal ensembles}.
3191
3192 @seealso
3193 Learning Manual:
3194 @rlearning{Vocal ensembles}.
3195
3196 Notation Reference:
3197 @ref{Fonts},
3198 @ref{Formatting text}.
3199
3200
3201 @node Partial measures in hymn tunes
3202 @unnumberedsubsubsec Partial measures in hymn tunes
3203
3204 Hymn tunes frequently start and end every line of music with
3205 partial measures so that each line of music corresponds exactly
3206 with a line of text.  This requires a @code{\partial} command at
3207 the start of the music and @code{\bar "|"} or @code{\bar "||"}
3208 commands at the end of each line.
3209
3210 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
3211 {hymn-template.ly}
3212
3213
3214 @node Ancient vocal music
3215 @subsection Ancient vocal music
3216
3217 Ancient vocal music is supported, as explained in
3218 @ref{Ancient notation}.
3219
3220 @c TODO
3221
3222 @c Add "Printing both the ancient and the modern clef in vocal music" snippet,
3223 @c and "Transcription of Ancient music with incipit" snippet. -vv
3224
3225 @seealso
3226 Notation Reference:
3227 @ref{Ancient notation}.
3228
3229
3230
3231