This chapter explains how to use notation for specific instruments.
@menu
-* Piano music::
-* Chord names::
* Vocal music::
-* Rhythmic music::
+* Chord names::
+* Piano music::
+* Percussion::
* Guitar::
-* Bagpipe::
+* Other instrument-specific::
* Ancient notation::
-* Other instrument specific notation::
@end menu
-@node Piano music
-@section Piano music
+@node Vocal music
+@section Vocal music
-Piano staves are two normal staves coupled with a brace. The staves
-are largely independent, but sometimes voices can cross between the
-two staves. The same notation is also used for harps and other key
-instruments. The @internalsref{PianoStaff} is especially built to
-handle this cross-staffing behavior. In this section we discuss the
-@internalsref{PianoStaff} and some other pianistic peculiarities.
+Since LilyPond input files are text, there are two issues to
+consider when working with vocal music:
-@menu
-* Automatic staff changes::
-* Manual staff switches::
-* Pedals::
-* Staff switch lines::
-* Cross staff stems::
-@end menu
+@itemize @bullet
+@item
+Song texts must be entered as text, not notes. For example, the
+input@tie{}@code{d} should be interpreted as a one letter syllable, not the
+note@tie{}D.
-@refbugs
+@item
+Song texts must be aligned with the notes of their melody.
+@end itemize
-Dynamics are not centered, but workarounds do exist. See the
-@q{piano centered dynamics} template in @ref{Piano templates}.
+There are a few different ways to define lyrics; we shall begin
+by examining the simplest method, and gradually increase complexity.
-@cindex cross staff stem
-@cindex stem, cross staff
-@cindex distance between staves in piano music
+@menu
+* Setting simple songs::
+* Entering lyrics::
+* Aligning lyrics to a melody::
+* Automatic syllable durations::
+* Another way of entering lyrics::
+* Assigning more than one syllable to a single note::
+* More than one note on a single syllable::
+* Extenders and hyphens::
+* Working with lyrics and identifiers::
+* Flexibility in placement::
+* Lyrics to multiple notes of a melisma::
+* Divisi lyrics::
+* Switching the melody associated with a lyrics line::
+* Lyrics independent of notes::
+* Spacing lyrics::
+* More about stanzas::
+* Ambitus::
+* Other vocal issues::
+@end menu
-@anchor{Automatic staff changes}
-@unnumberedsubsubsec Automatic staff changes
-@cindex Automatic staff changes
+@commonprop
-Voices can be made to switch automatically between the top and the bottom
-staff. The syntax for this is
+Checking to make sure that text scripts and lyrics are within the margins is
+a relatively large computational task. To speed up processing, lilypond does
+not perform such calculations by default; to enable it, use
-@quotation
@example
-\autochange @dots{}@var{music}@dots{}
+\override Score.PaperColumn #'keep-inside-line = ##t
@end example
-@end quotation
-@noindent
-This will create two staves inside the current PianoStaff, called
-@code{up} and @code{down}. The lower staff will be in bass clef by
-default.
+To make lyrics avoid barlines as well, use
+@example
+\layout @{
+ \context @{
+ \Lyrics
+ \consists "Bar_engraver"
+ \consists "Separating_line_group_engraver"
+ \override BarLine #'transparent = ##t
+ @}
+@}
+@end example
-A @code{\relative} section that is outside of @code{\autochange} has
-no effect on the pitches of @var{music}, so, if necessary, put
-@code{\relative} inside @code{\autochange} like
-@quotation
+@anchor{Setting simple songs}
+@unnumberedsubsubsec Setting simple songs
+
+@cindex \addlyrics
+
+The easiest way to add lyrics to a melody is to append
+
@example
-\autochange \relative @dots{} @dots{}
+\addlyrics @{ @var{the lyrics} @}
@end example
-@end quotation
+@noindent
+to a melody. Here is an example,
-The autochanger switches on basis of the pitch (middle C is the turning
-point), and it looks ahead skipping over rests to switch in
-advance. Here is a practical example
-
-@lilypond[quote,verbatim,ragged-right]
-\new PianoStaff
- \autochange \relative c'
- {
- g4 a b c d r4 a g
- }
+@lilypond[ragged-right,verbatim,fragment,quote]
+\time 3/4
+\relative { c2 e4 g2. }
+\addlyrics { play the game }
@end lilypond
+More stanzas can be added by adding more
+@code{\addlyrics} sections
-@seealso
-
-In this manual: @ref{Manual staff switches}.
+@lilypond[ragged-right,verbatim,fragment,quote]
+\time 3/4
+\relative { c2 e4 g2. }
+\addlyrics { play the game }
+\addlyrics { speel het spel }
+\addlyrics { joue le jeu }
+@end lilypond
-Program reference: @internalsref{AutoChangeMusic}.
+The command @code{\addlyrics} cannot handle polyphony settings. For these
+cases you should use @code{\lyricsto} and @code{\lyricmode}, as will be
+introduced in @ref{Entering lyrics}.
-@refbugs
+@anchor{Entering lyrics}
+@unnumberedsubsubsec Entering lyrics
-The staff switches may not end up in optimal places. For high
-quality output, staff switches should be specified manually.
+@cindex lyrics
+@funindex \lyricmode
+@cindex punctuation
+@cindex spaces, in lyrics
+@cindex quotes, in lyrics
+Lyrics are entered in a special input mode, which can be introduced
+by the keyword @code{\lyricmode}, or by using @code{\addlyrics} or
+@code{\lyricsto}. In this mode you can enter lyrics,
+with punctuation and accents, and the input @code{d} is not parsed as
+a pitch, but rather as a one letter syllable. Syllables are entered
+like notes, but with pitches replaced by text. For example,
-@code{\autochange} cannot be inside @code{\times}.
+@example
+\lyricmode @{ Twin-4 kle4 twin- kle litt- le star2 @}
+@end example
+There are two main methods to specify the horizontal placement
+of the syllables, either by specifying the duration of each syllable
+explicitly, like in the example above, or by automatically aligning
+the lyrics to a melody or other voice of music, using @code{\addlyrics}
+or @code{\lyricsto}.
+@c TODO: broken
+@c For more details see @ref{The Lyrics context}.
-@anchor{Manual staff switches}
-@unnumberedsubsubsec Manual staff switches
+A word or syllable of lyrics begins with an alphabetic character, and ends
+with
+any space or digit. The following characters can be any character
+that is not a digit or white space.
-@cindex manual staff switches
-@cindex staff switch, manual
+Any character that is not a digit or white space will be regarded as
+part of the syllable; one important consequence of this is that a word
+can end with @code{@}}, which often leads to the following mistake:
-Voices can be switched between staves manually, using the command
@example
-\change Staff = @var{staffname} @var{music}
+\lyricmode @{ lah- lah@}
@end example
+In this example, the @code{@}} is included in the final syllable, so the
+opening brace is not balanced and the input file will probably not
+compile.
+
+
+@funindex \property in \lyricmode
+
@noindent
-The string @var{staffname} is the name of the staff. It switches the
-current voice from its current staff to the Staff called
-@var{staffname}. Typically @var{staffname} is @code{"up"} or
-@code{"down"}. The @context{Staff} referred to must already exist, so
-usually the setup for a score will start with a setup of the staves,
+Similarly, a period which follows an alphabetic sequence is included in
+the resulting string. As a consequence, spaces must be inserted around
+property commands: do @emph{not} write
@example
-<<
- \new Staff = "up" @{
- \skip 1 * 10 % @emph{keep staff alive}
- @}
- \new Staff = "down" @{
- \skip 1 * 10 % @emph{idem}
- @}
->>
+\override Score.LyricText #'font-shape = #'italic
@end example
-
-and the @context{Voice} is inserted afterwards
+@noindent
+but instead use
@example
-\context Staff = down
- \new Voice @{ @dots{} \change Staff = up @dots{} @}
+\override Score . LyricText #'font-shape = #'italic
@end example
+@funindex _
+@cindex spaces, in lyrics
+@cindex quotes, in lyrics
+@cindex ties, in lyrics
-@anchor{Pedals}
-@unnumberedsubsubsec Pedals
-@cindex Pedals
+In order to assign more than one syllable to a single note, you can
+surround them with quotes or use a @code{_} character, to get spaces
+between syllables, or use tilde symbol (@code{~}) to get a lyric tie.
-Pianos have pedals that alter the way sound is produced. Generally, a
-piano has three pedals, sustain, una corda, and sostenuto.
+@lilypond[quote,relative=2,ragged-right,fragment,verbatim]
+\time 3/4
+\relative { c2 e4 g2 e4 }
+\addlyrics { gran- de_a- mi- go }
+\addlyrics { pu- "ro y ho-" nes- to }
+\addlyrics { pu- ro~y~ho- nes- to }
+@end lilypond
+The lyric tie is implemented with the Unicode character U+203F, so be
+sure to have a font (Like DejaVuLGC) installed that includes this
+glyph.
-Piano pedal instruction can be expressed by attaching
-@code{\sustainDown}, @code{\sustainUp}, @code{\unaCorda},
-@code{\treCorde}, @code{\sostenutoDown} and @code{\sostenutoUp} to a
-note or chord
+
+To enter lyrics with characters from non-English languages, or with
+accented and special characters (such as the heart symbol or slanted quotes),
+simply insert the characters directly into the input file and save
+it with utf-8 encoding. See @ref{Text encoding}, for more info.
@lilypond[quote,ragged-right,fragment,verbatim]
-c'4\sustainDown c'4\sustainUp
+\relative { e4 f e d e f e2 }
+\addlyrics { He said: “Let my peo ple go”. }
@end lilypond
-What is printed can be modified by setting @code{pedal@var{X}Strings},
-where @var{X} is one of the pedal types: @code{Sustain},
-@code{Sostenuto} or @code{UnaCorda}. Refer to
-@internalsref{SustainPedal} in the program reference for more
-information.
+To use normal quotes in lyrics, add a backslash before the
+quotes. For example,
-Pedals can also be indicated by a sequence of brackets, by setting the
-@code{pedalSustainStyle} property to bracket objects
+@lilypond[quote,ragged-right,fragment,verbatim]
+\relative c' { \time 3/4 e4 e4. e8 d4 e d c2. }
+\addlyrics { "\"I" am so lone- "ly\"" said she }
+@end lilypond
-@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
-\set Staff.pedalSustainStyle = #'bracket
-c\sustainDown d e
-b\sustainUp\sustainDown
-b g \sustainUp a \sustainDown \bar "|."
-@end lilypond
-
-A third style of pedal notation is a mixture of text and brackets,
-obtained by setting the @code{pedalSustainStyle} property to
-@code{mixed}
-
-@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
-\set Staff.pedalSustainStyle = #'mixed
-c\sustainDown d e
-b\sustainUp\sustainDown
-b g \sustainUp a \sustainDown \bar "|."
-@end lilypond
+The full definition of a word start in Lyrics mode is somewhat more
+complex.
-The default @q{*Ped.} style for sustain and damper pedals corresponds to
-style @code{#'text}. The sostenuto pedal uses @code{mixed} style by
-default.
+A word in Lyrics mode begins with: an alphabetic character, @code{_},
+@code{?}, @code{!}, @code{:}, @code{'}, the control characters @code{^A}
+through @code{^F}, @code{^Q} through @code{^W}, @code{^Y}, @code{^^},
+any 8-bit character with ASCII code over 127, or a two-character
+combination of a backslash followed by one of @code{`}, @code{'},
+@code{"}, or @code{^}.
-@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
-c\sostenutoDown d e c, f g a\sostenutoUp
-@end lilypond
+To define identifiers containing lyrics, the function @code{lyricmode}
+must be used.
-For fine-tuning the appearance of a pedal bracket, the properties
-@code{edge-width}, @code{edge-height}, and @code{shorten-pair} of
-@code{PianoPedalBracket} objects (see
-@internalsref{PianoPedalBracket} in the Program reference) can be
-modified. For example, the bracket may be extended to the right edge
-of the note head
+@example
+verseOne = \lyricmode @{ Joy to the world the Lord is come @}
+\score @{
+ <<
+ \new Voice = "one" \relative c'' @{
+ \autoBeamOff
+ \time 2/4
+ c4 b8. a16 g4. f8 e4 d c2
+ @}
+ \addlyrics @{ \verseOne @}
+ >>
+@}
+@end example
-@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
-\override Staff.PianoPedalBracket #'shorten-pair = #'(0 . -1.0)
-c\sostenutoDown d e c, f g a\sostenutoUp
-@end lilypond
@seealso
-In this manual: @ref{Laissez vibrer ties}.
-
-@anchor{Staff switch lines}
-@unnumberedsubsubsec Staff switch lines
-
-
-@cindex follow voice
-@cindex staff switching
-@cindex cross staff
-
-@funindex followVoice
-
-Whenever a voice switches to another staff, a line connecting the notes
-can be printed automatically. This is switched on by setting
-@code{followVoice} to true
-
-@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
-\new PianoStaff <<
- \new Staff="one" {
- \set followVoice = ##t
- c1
- \change Staff=two
- b2 a
- }
- \new Staff="two" { \clef bass \skip 1*2 }
->>
-@end lilypond
-
-@seealso
+Program reference: @internalsref{LyricText}, @internalsref{LyricSpace}.
-Program reference: @internalsref{VoiceFollower}.
-@refcommands
-@funindex \showStaffSwitch
-@code{\showStaffSwitch},
-@funindex \hideStaffSwitch
-@code{\hideStaffSwitch}.
+@anchor{Aligning lyrics to a melody}
+@unnumberedsubsubsec Aligning lyrics to a melody
+@funindex \lyricmode
+@funindex \addlyrics
+@funindex \lyricsto
-@anchor{Cross staff stems}
-@unnumberedsubsubsec Cross staff stems
-Chords that cross staves may be produced by increasing the length
-of the stem in the lower staff, so it reaches the stem in the upper
-staff, or vice versa.
+Lyrics are printed by interpreting them in the context called
+@internalsref{Lyrics}.
-@lilypond[ragged-right,verbatim,quote]
-stemExtend = {
- \once \override Stem #'length = #10
- \once \override Stem #'cross-staff = ##t
-}
-noFlag = \once \override Stem #'flag-style = #'no-flag
-\new PianoStaff <<
- \new Staff {
- \stemDown \stemExtend
- f'4
- \stemExtend \noFlag
- f'8
- }
- \new Staff {
- \clef bass
- a4 a8
- }
->>
-@end lilypond
+@example
+\new Lyrics \lyricmode @dots{}
+@end example
+There are two main methods to specify the horizontal placement
+of the syllables:
+@itemize @bullet
+@item
+by automatically aligning
+the lyrics to a melody or other voice of music, using @code{\addlyrics}
+or @code{\lyricsto}.
-@node Chord names
-@section Chord names
+@item
+or by specifying the duration of each syllable
+explicitly, using @code{\lyricmode}
+@end itemize
@menu
-* Introducing chord names::
-* Chords mode::
-* Printing chord names::
+* Automatic syllable durations::
+* Another way of entering lyrics::
+* Assigning more than one syllable to a single note::
+* More than one note on a single syllable::
+* Extenders and hyphens::
@end menu
+@anchor{Automatic syllable durations}
+@unnumberedsubsubsec Automatic syllable durations
-@c awkward name; awkward section name.
-@c still, the Basic "chords" seems like a good name... :(
-@anchor{Introducing chord names}
-@unnumberedsubsubsec Introducing chord names
-@cindex chord names
+@cindex automatic syllable durations
+@cindex lyrics and melodies
-LilyPond has support for printing chord names. Chords may be entered
-in musical chord notation, i.e., @code{< .. >}, but they can also be
-entered by name. Internally, the chords are represented as a set of
-pitches, so they can be transposed
+The lyrics can be aligned under a given melody
+automatically. This is achieved by combining the
+melody and the lyrics with the @code{\lyricsto} expression
+@example
+\new Lyrics \lyricsto @var{name} @dots{}
+@end example
-@lilypond[quote,ragged-right,verbatim,ragged-right]
-twoWays = \transpose c c' {
- \chordmode {
- c1 f:sus4 bes/f
- }
- <c e g>
- <f bes c'>
- <f bes d'>
-}
+This aligns the lyrics to the
+notes of the @internalsref{Voice} context called @var{name}, which must
+already exist. Therefore normally the @code{Voice} is specified first, and
+then the lyrics are specified with @code{\lyricsto}. The command
+@code{\lyricsto} switches to @code{\lyricmode} mode automatically, so the
+@code{\lyricmode} keyword may be omitted.
-<< \new ChordNames \twoWays
- \new Voice \twoWays >>
+The following example uses different commands for entering lyrics.
+
+@lilypond[quote,fragment,ragged-right,verbatim]
+<<
+ \new Voice = "one" \relative c'' {
+ \autoBeamOff
+ \time 2/4
+ c4 b8. a16 g4. f8 e4 d c2
+ }
+ \new Lyrics \lyricmode { Joy4 to8. the16 world!4. the8 Lord4 is come.2 }
+ \new Lyrics \lyricmode { Joy to the earth! the Sa -- viour reigns. }
+ \new Lyrics \lyricsto "one" { No more let sins and sor -- rows grow. }
+>>
@end lilypond
-This example also shows that the chord printing routines do not try to
-be intelligent. The last chord (@code{f bes d}) is not interpreted as
-an inversion.
+The second stanza is not properly aligned because the durations
+were not specified. A solution for that would be to use @code{\lyricsto}.
-Note that the duration of chords must be specified outside the
-@code{<>}.
+The @code{\addlyrics} command is actually just a convenient way
+to write a more complicated LilyPond structure that sets up the
+lyrics.
@example
-<c e g>2
+@{ MUSIC @}
+\addlyrics @{ LYRICS @}
@end example
+@noindent
+is the same as
-@anchor{Chords mode}
-@unnumberedsubsubsec Chords mode
-@cindex Chords mode
+@example
+\new Voice = "blah" @{ music @}
+\new Lyrics \lyricsto "blah" @{ LYRICS @}
+@end example
-In chord mode sets of pitches (chords) are entered with normal note
-names. A chord is entered by the root, which is entered like a
-normal pitch
+@anchor{Another way of entering lyrics}
+@unnumberedsubsubsec Another way of entering lyrics
-@lilypond[quote,ragged-right,fragment,verbatim]
-\chordmode { es4. d8 c2 }
+Lyrics can also be entered without @code{\addlyrics} or
+@code{\lyricsto}. In this case,
+syllables are entered like notes -- but with pitches replaced by text -- and the
+duration of each syllable must be entered explicitly. For example:
+
+@example
+play2 the4 game2.
+sink2 or4 swim2.
+@end example
+
+The alignment to a melody can be specified with the
+@code{associatedVoice} property,
+
+@example
+\set associatedVoice = #"lala"
+@end example
+
+@noindent
+The value of the property (here: @code{"lala"}) should be the name of
+a @internalsref{Voice} context. Without this setting, extender lines
+will not be formatted properly.
+
+Here is an example demonstrating manual lyric durations,
+
+@lilypond[relative=1,ragged-right,verbatim,fragment,quote]
+<< \new Voice = "melody" {
+ \time 3/4
+ c2 e4 g2.
+ }
+ \new Lyrics \lyricmode {
+ \set associatedVoice = #"melody"
+ play2 the4 game2.
+ } >>
@end lilypond
-@noindent
-The mode is introduced by the keyword @code{\chordmode}.
-
-@cindex chord entry
-@cindex chord mode
-
-Other chords may be entered by suffixing a colon and introducing a
-modifier (which may include a number if desired)
+@seealso
+
+Program reference: @internalsref{Lyrics}.
-@lilypond[quote,fragment,verbatim]
-\chordmode { e1:m e1:7 e1:m7 }
-@end lilypond
-The first number following the root is taken to be the @q{type} of the
-chord, thirds are added to the root until it reaches the specified
-number. The exception is @code{c:13}, for which the 11 is omitted.
+@anchor{Assigning more than one syllable to a single note}
+@unnumberedsubsubsec Assigning more than one syllable to a single note
-@lilypond[quote,fragment,verbatim]
-\chordmode { c:3 c:5 c:6 c:7 c:8 c:9 c:10 c:11 c:13 }
-@end lilypond
-@cindex root of chord
-@cindex additions, in chords
-@cindex removals, in chords
+@funindex _
+@cindex ties, in lyrics
-More complex chords may also be constructed adding separate steps
-to a chord. Additions are added after the number following
-the colon and are separated by dots
+In order to assign more than one syllable to a single note, you can
+surround them with quotes or use a @code{_} character, to get spaces
+between syllables, or use tilde symbol (@code{~}) to get a lyric
+tie@footnote{The lyric ties is implemented with the Unicode character
+U+203F, so be
+sure to have a font (Like DejaVuLGC) installed that includes this
+glyph.}.
-@lilypond[quote,verbatim,fragment]
-\chordmode { c:5.6 c:3.7.8 c:3.6.13 }
+@lilypond[quote,relative=2,ragged-right,fragment,verbatim]
+\time 3/4
+\relative { c2 e4 g2 e4 }
+\addlyrics { gran- de_a- mi- go }
+\addlyrics { pu- "ro y ho-" nes- to }
+\addlyrics { pu- ro~y~ho- nes- to }
@end lilypond
-Chord steps can be altered by suffixing a @code{-} or @code{+} sign
-to the number
-
-@lilypond[quote,verbatim,fragment]
-\chordmode { c:7+ c:5+.3- c:3-.5-.7- }
-@end lilypond
+@seealso
-Removals are specified similarly and are introduced by a caret. They
-must come after the additions
+Program reference: @internalsref{LyricCombineMusic}.
-@lilypond[quote,verbatim,fragment]
-\chordmode { c^3 c:7^5 c:9^3.5 }
-@end lilypond
+@c Here come the section which used to be "Melismata"
+@c the new title might be more self-explanatory
-Modifiers can be used to change pitches. The following modifiers are
-supported
-@table @code
-@item m
-The minor chord. This modifier lowers the 3rd and (if present) the 7th step.
+@anchor{More than one note on a single syllable}
+@unnumberedsubsubsec More than one note on a single syllable
-@item dim
-The diminished chord. This modifier lowers the 3rd, 5th and (if present)
-the 7th step.
+@cindex melisma
+@cindex melismata
+@cindex phrasing, in lyrics
-@item aug
-The augmented chord. This modifier raises the 5th step.
+Sometimes, particularly in Medieval music, several notes are to be sung on one
+single syllable; such vocalises are called melismas, or melismata.
-@item maj
-The major 7th chord. This modifier raises the 7th step if present.
+@c this method seems to be the simplest; therefore
+@c it might be better to present it first - vv
-@item sus
-The suspended 4th or 2nd. This modifier removes the 3rd
-step. Append either @code{2} or @code{4} to add the 2nd or 4th step to
-the chord.
-@end table
+You can define melismata entirely in the lyrics, by entering @code{_}
+for every note
+that is part of the melisma.
-Modifiers can be mixed with additions
-@lilypond[quote,verbatim,fragment]
- \chordmode { c:sus4 c:7sus4 c:dim7 c:m6 }
+@lilypond[relative=1,verbatim,fragment,quote]
+{ \set melismaBusyProperties = #'()
+ c d( e) f f( e) e e }
+\addlyrics
+ { Ky -- _ _ ri __ _ _ _ e }
@end lilypond
-@cindex modifiers, in chords.
-@funindex aug
-@funindex dim
-@funindex maj
-@funindex sus
-@funindex m
-
-Since an unaltered 11 does not sound good when combined with an
-unaltered 13, the 11 is removed in this case (unless it is added
-explicitly)
-@lilypond[quote,ragged-right,fragment,verbatim]
-\chordmode { c:13 c:13.11 c:m13 }
-@end lilypond
+In this case, you can also have ties and slurs in the melody if you
+set @code{melismaBusyProperties}, as is done in the example above.
-@funindex /
+However, the @code{\lyricsto} command can also
+detect melismata automatically: it only puts one
+syllable under a tied or slurred group of notes. If you want to force
+an unslurred group of notes to be a melisma, insert @code{\melisma}
+after the first note of the group, and @code{\melismaEnd} after the
+last one, e.g.,
-An inversion (putting one pitch of the chord on the bottom), as well
-as bass notes, can be specified by appending
-@code{/}@var{pitch} to the chord
-@lilypond[quote,ragged-right,fragment,verbatim]
-\chordmode { c1 c/g c/f }
+@lilypond[quote,relative=2,ragged-right,fragment,verbatim]
+<<
+ \new Voice = "lala" {
+ \time 3/4
+ f4 g8
+ \melisma
+ f e f
+ \melismaEnd
+ e2
+ }
+ \new Lyrics \lyricsto "lala" {
+ la di __ daah
+ }
+>>
@end lilypond
-@funindex /+
-A bass note can be added instead of transposed out of the chord,
-by using @code{/+}@var{pitch}.
+In addition, notes are considered a melisma if they are manually
+beamed, and automatic beaming (see @ref{Setting automatic beam
+behavior}) is switched off.
-@lilypond[quote,ragged-right,fragment,verbatim]
-\chordmode { c1 c/+g c/+f }
-@end lilypond
+@c TODO: there might be some more relevant place for
+@c the following link (?)
-Chords is a mode similar to @code{\lyricmode}, etc. Most
-of the commands continue to work, for example, @code{r} and
-@code{\skip} can be used to insert rests and spaces, and property
-commands may be used to change various settings.
+@cindex SATB
+@cindex choral score
+A complete example of a SATB score setup is in section
+@ref{Vocal ensembles}.
-@refbugs
+@refcommands
-Each step can only be present in a chord once. The following
-simply produces the augmented chord, since @code{5+} is interpreted
-last
-@cindex clusters
-@lilypond[quote,ragged-right,verbatim,fragment]
-\chordmode { c:5.5-.5+ }
-@end lilypond
+@code{\melisma}, @code{\melismaEnd}
+@funindex \melismaEnd
+@funindex \melisma
+@seealso
-@anchor{Printing chord names}
-@unnumberedsubsubsec Printing chord names
+Program reference: @internalsref{Melisma_translator}.
-@cindex printing chord names
-@cindex chord names
-@cindex chords
+@lsr{vocal,lyric@/-combine.ly}.
-For displaying printed chord names, use the @internalsref{ChordNames} context.
-The chords may be entered either using the notation
-described above, or directly using @code{<} and @code{>}
+@refbugs
-@lilypond[quote,verbatim,ragged-right]
-harmonies = {
- \chordmode {a1 b c} <d' f' a'> <e' g' b'>
-}
-<<
- \new ChordNames \harmonies
- \new Staff \harmonies
->>
-@end lilypond
+Melismata are not detected automatically, and extender lines must be
+inserted by hand.
-You can make the chord changes stand out by setting
-@internalsref{ChordNames}.@code{chordChanges} to true. This will only
-display chord names when there is a change in the chords scheme and at
-the start of a new line
+@anchor{Extenders and hyphens}
+@unnumberedsubsubsec Extenders and hyphens
-@lilypond[quote,verbatim,ragged-right]
-harmonies = \chordmode {
- c1:m c:m \break c:m c:m d
-}
-<<
- \new ChordNames {
- \set chordChanges = ##t
- \harmonies }
- \new Staff \transpose c c' \harmonies
->>
-@end lilypond
+@cindex melisma
+@cindex extender
-The previous examples all show chords over a staff. This is not
-necessary. Chords may also be printed separately. It may be necessary
-to add @internalsref{Volta_engraver} and @internalsref{Bar_engraver}
-for showing repeats.
+Melismata are indicated with a horizontal line centered between a syllable
+and the next one. Such a line is called an extender line, and it is entered
+as @samp{ __ } (note the spaces before and after the two underscore
+characters).
-@lilypond[ragged-right,verbatim]
-\new ChordNames \with {
- \override BarLine #'bar-size = #4
- \consists Bar_engraver
- \consists "Volta_engraver"
-}
-\chordmode { \repeat volta 2 {
- f1:maj7 f:7 bes:7
- c:maj7
-} \alternative {
- es e
-}
-}
-@end lilypond
+@cindex hyphens
+Centered hyphens are entered as @samp{ -- } between syllables of a same word
+(note the spaces before and after the two hyphen characters). The hyphen
+will be centered between the syllables, and its length will be adjusted
+depending on the space between the syllables.
-The default chord name layout is a system for Jazz music, proposed by
-Klaus Ignatzek (see @ref{Literature list}). It can be tuned through the
-following properties
+In tighly engraved music, hyphens can be removed. Whether this
+happens can be controlled with the @code{minimum-distance} (minimum
+distance between two syllables) and the @code{minimum-length}
+(threshold below which hyphens are removed).
-@table @code
-@funindex chordNameExceptions
-@item chordNameExceptions
-This is a list that contains the chords that have special formatting.
+@seealso
-The exceptions list should be encoded as
-@example
-@{ <c f g bes>1 \markup @{ \super "7" "wahh" @} @}
-@end example
+Program reference: @internalsref{LyricExtender},
+@internalsref{LyricHyphen}
-To get this information into @code{chordNameExceptions} takes a little
-manoeuvring. The following code transforms @code{chExceptionMusic}
-(which is a sequential music) into a list of exceptions.
+
+@anchor{Working with lyrics and identifiers}
+@unnumberedsubsubsec Working with lyrics and identifiers
+@cindex lyrics, identifiers
+
+To define identifiers containing lyrics, the function @code{\lyricmode}
+must be used. You do not have to enter durations though, if you add
+@code{\addlyrics} or @code{\lyricsto}
+when invoking your identifier.
+
@example
-(sequential-music-to-chord-exceptions chExceptionMusic #t)
+verseOne = \lyricmode @{ Joy to the world the Lord is come @}
+\score @{
+ <<
+ \new Voice = "one" \relative c'' @{
+ \autoBeamOff
+ \time 2/4
+ c4 b8. a16 g4. f8 e4 d c2
+ @}
+ \addlyrics @{ \verseOne @}
+ >>
+@}
@end example
-Then,
+
+For different or more complex orderings, the best way is to setup the
+hierarchy of staves and lyrics first, e.g.,
@example
-(append
- (sequential-music-to-chord-exceptions chExceptionMusic #t)
- ignatzekExceptions)
+\new ChoirStaff <<
+ \new Voice = "soprano" @{ @emph{music} @}
+ \new Lyrics = "sopranoLyrics" @{ s1 @}
+ \new Lyrics = "tenorLyrics" @{ s1 @}
+ \new Voice = "tenor" @{ @emph{music} @}
+>>
@end example
-adds the new exceptions to the default ones, which are defined in
-@file{ly/@/chord@/-modifier@/-init@/.ly}.
-
-For an example of tuning this property, see also
-@lsr{chords,chord@/-name@/-exceptions@/.ly}
-@cindex exceptions, chord names.
-
-
-@funindex majorSevenSymbol
-@item majorSevenSymbol
-This property contains the markup object used for the 7th step, when
-it is major. Predefined options are @code{whiteTriangleMarkup} and
-@code{blackTriangleMarkup}. See
-@lsr{chords,chord@/-name@/-major7@/.ly} for an example.
-
-@funindex chordNameSeparator
-@item chordNameSeparator
-Different parts of a chord name are normally separated by a
-slash. By setting @code{chordNameSeparator}, you can specify other
-separators, e.g.,
-@lilypond[quote,ragged-right,fragment,verbatim]
-\new ChordNames \chordmode {
- c:7sus4
- \set chordNameSeparator
- = \markup { \typewriter "|" }
- c:7sus4
-}
-@end lilypond
-
-@funindex chordRootNamer
-@item chordRootNamer
-The root of a chord is usually printed as a letter with an optional
-alteration. The transformation from pitch to letter is done by this
-function. Special note names (for example, the German @q{H} for a
-B-chord) can be produced by storing a new function in this property.
-
-@funindex chordNoteNamer
-@item chordNoteNamer
-The default is to print single pitch, e.g., the bass note, using the
-@code{chordRootNamer}. The @code{chordNoteNamer} property can be set
-to a specialized function to change this behavior. For example, the
-base can be printed in lower case.
-
-@funindex chordPrefixSpacer
-@item chordPrefixSpacer
-The @q{m} for minor chords is usually printed right after the root of
-the chord. By setting @code{chordPrefixSpacer}, you can fix a spacer
-between the root and @q{m}. The spacer is not used when the root
-is altered.
-
-@end table
-
-The predefined variables @code{\germanChords},
-@code{\semiGermanChords}, @code{\italianChords} and @code{\frenchChords}
-set these variables. The effect is
-demonstrated here,
+
+and then combine the appropriate melodies and lyric lines
+
+@example
+\context Lyrics = sopranoLyrics \lyricsto "soprano"
+@emph{the lyrics}
+@end example
+
+@noindent
-@lilypondfile[ragged-right]{chord-names-languages.ly}
+The final input would resemble
+
+@example
+<<\new ChoirStaff << @emph{setup the music} >>
+ \lyricsto "soprano" @emph{etc}
+ \lyricsto "alto" @emph{etc}
+@emph{etc}
+>>
+@end example
+
+@seealso
+
+@c TODO: document \new Staff << Voice \lyricsto >> bug
+Program reference: @internalsref{LyricCombineMusic},
+@internalsref{Lyrics}.
-There are also two other chord name schemes implemented: an alternate
-Jazz chord notation, and a systematic scheme called Banter chords. The
-alternate Jazz notation is also shown on the chart in @ref{Chord name
-chart}. Turning on these styles is demonstrated in
-@lsr{chords,chord-names-jazz.ly}.
-@cindex Banter
-@cindex jazz chords
-@cindex chords, jazz
+@anchor{Flexibility in placement}
+@unnumberedsubsubsec Flexibility in placement
+Often, different stanzas of one song are put to one melody in slightly
+differing ways. Such variations can still be captured with
+@code{\lyricsto}.
-@refcommands
+@menu
+* Lyrics to multiple notes of a melisma::
+* Divisi lyrics::
+* Switching the melody associated with a lyrics line::
+* Lyrics independent of notes::
+@end menu
-@funindex \germanChords
-@code{\germanChords},
-@funindex \semiGermanChords
-@code{\semiGermanChords}.
-@funindex \italianChords
-@code{\italianChords}.
-@funindex \frenchChords
-@code{\frenchChords}.
+@anchor{Lyrics to multiple notes of a melisma}
+@unnumberedsubsubsec Lyrics to multiple notes of a melisma
+One possibility is that the text has a melisma in one stanza, but
+multiple syllables in another one. One solution is to make the faster
+voice ignore the melisma. This is done by setting
+@code{ignoreMelismata} in the Lyrics context.
+There is one tricky aspect: the setting for @code{ignoreMelismata}
+must be set one syllable @emph{before} the non-melismatic syllable
+in the text, as shown here,
-@seealso
+@c FIXME: breaks compile
+@lilypond[verbatim,ragged-right,quote]
+%{
+<<
+ \relative \new Voice = "lahlah" {
+ \set Staff.autoBeaming = ##f
+ c4
+ \slurDotted
+ f8.[( g16])
+ a4
+ }
+ \new Lyrics \lyricsto "lahlah" {
+ more slow -- ly
+ }
+ \new Lyrics \lyricsto "lahlah" {
+ \set ignoreMelismata = ##t % applies to "fas"
+ go fas -- ter
+ \unset ignoreMelismata
+ still
+ }
+>>
+%}
+@end lilypond
-Examples:
-@lsrdir{chords}
-Init files: @file{scm/@/chords@/-ignatzek@/.scm}, and
-@file{scm/@/chord@/-entry@/.scm}.
+The @code{ignoreMelismata} applies to the syllable @q{fas}, so it
+should be entered before @q{go}.
+The reverse is also possible: making a lyric line slower than the
+standard. This can be achieved by insert @code{\skip}s into the
+lyrics. For every @code{\skip}, the text will be delayed another note.
+For example,
-@refbugs
+@lilypond[verbatim,ragged-right,quote]
+\relative { c c g' }
+\addlyrics {
+ twin -- \skip 4
+ kle
+}
+@end lilypond
-Chord names are determined solely from the list of pitches. Chord
-inversions are not identified, and neither are added bass notes. This
-may result in strange chord names when chords are entered with the
-@code{< .. >} syntax.
+@anchor{Divisi lyrics}
+@unnumberedsubsubsec Divisi lyrics
+You can display alternate (or divisi) lyrics by naming voice
+contexts and attaching lyrics to those specific contexts.
-@node Vocal music
-@section Vocal music
+@lilypond[verbatim,ragged-right,quote]
+\score{ <<
+ \new Voice = "melody" {
+ \relative c' {
+ c4
+ <<
+ { \voiceOne c8 e }
+ \new Voice = "splitpart" { \voiceTwo c4 }
+ >>
+ \oneVoice c4 c | c
+ }
+ }
+ \new Lyrics \lyricsto "melody" { we shall not o- ver- come }
+ \new Lyrics \lyricsto "splitpart" { will }
+>> }
+@end lilypond
-Since LilyPond input files are text, there are two issues to
-consider when working with vocal music:
-@itemize @bullet
-@item
-Song texts must be entered as text, not notes. For example, the
-input@tie{}@code{d} should be interpreted as a one letter syllable, not the
-note@tie{}D.
+You can use this trick to display different lyrics for a repeated
+section.
-@item
-Song texts must be aligned with the notes of their melody.
-@end itemize
+@lilypond[verbatim,ragged-right,quote]
+\score{ <<
+ \new Voice = "melody" \relative c' {
+ c2 e | g e | c1 |
+ \new Voice = "verse" \repeat volta 2 {c4 d e f | g1 | }
+ a2 b | c1}
+ \new Lyrics = "mainlyrics" \lyricsto melody \lyricmode {
+ do mi sol mi do
+ la si do }
+ \context Lyrics = "mainlyrics" \lyricsto verse \lyricmode {
+ do re mi fa sol }
+ \new Lyrics = "repeatlyrics" \lyricsto verse \lyricmode {
+ dodo rere mimi fafa solsol }
+>>
+}
+@end lilypond
-There are a few different ways to define lyrics; we shall begin
-by examining the simplest method, and gradually increase complexity.
-@menu
-* Setting simple songs::
-* Entering lyrics::
-* Aligning lyrics to a melody::
-* Automatic syllable durations::
-* Another way of entering lyrics::
-* Assigning more than one syllable to a single note::
-* More than one note on a single syllable::
-* Extenders and hyphens::
-* Working with lyrics and identifiers::
-* Flexibility in placement::
-* Lyrics to multiple notes of a melisma::
-* Divisi lyrics::
-* Switching the melody associated with a lyrics line::
-* Lyrics independent of notes::
-* Spacing lyrics::
-* More about stanzas::
-* Ambitus::
-* Other vocal issues::
-@end menu
+@anchor{Switching the melody associated with a lyrics line}
+@unnumberedsubsubsec Switching the melody associated with a lyrics line
-@commonprop
+More complex variations in text underlay are possible. It is possible
+to switch the melody for a line of lyrics during the text. This is
+done by setting the @code{associatedVoice} property. In the example
-Checking to make sure that text scripts and lyrics are within the margins is
-a relatively large computational task. To speed up processing, lilypond does
-not perform such calculations by default; to enable it, use
+@lilypond[ragged-right,quote]
+<<
+ \relative \new Voice = "lahlah" {
+ \set Staff.autoBeaming = ##f
+ c4
+ <<
+ \new Voice = "alternative" {
+ \voiceOne
+ \times 2/3 {
+ % show associations clearly.
+ \override NoteColumn #'force-hshift = #-3
+ f8 f g
+ }
+ }
+ {
+ \voiceTwo
+ f8.[ g16]
+ \oneVoice
+ } >>
+ a8( b) c
+ }
+ \new Lyrics \lyricsto "lahlah" {
+ Ju -- ras -- sic Park
+ }
+ \new Lyrics \lyricsto "lahlah" {
+ % Tricky: need to set associatedVoice
+ % one syllable too soon!
+ \set associatedVoice = alternative % applies to "ran"
+ Ty --
+ ran --
+ no --
+ \set associatedVoice = lahlah % applies to "rus"
+ sau -- rus Rex
+ } >>
+@end lilypond
-@example
-\override Score.PaperColumn #'keep-inside-line = ##t
-@end example
+@noindent
+the text for the first stanza is set to a melody called @q{lahlah},
-To make lyrics avoid barlines as well, use
@example
-\layout @{
- \context @{
- \Lyrics
- \consists "Bar_engraver"
- \consists "Separating_line_group_engraver"
- \override BarLine #'transparent = ##t
- @}
+\new Lyrics \lyricsto "lahlah" @{
+ Ju -- ras -- sic Park
@}
@end example
-@anchor{Setting simple songs}
-@unnumberedsubsubsec Setting simple songs
+The second stanza initially is set to the @code{lahlah} context, but
+for the syllable @q{ran}, it switches to a different melody.
+This is achieved with
+@example
+\set associatedVoice = alternative
+@end example
-@cindex \addlyrics
+@noindent
+Here, @code{alternative} is the name of the @code{Voice} context
+containing the triplet.
-The easiest way to add lyrics to a melody is to append
+Again, the command must be one syllable too early, before @q{Ty} in
+this case.
@example
-\addlyrics @{ @var{the lyrics} @}
+\new Lyrics \lyricsto "lahlah" @{
+ \set associatedVoice = alternative % applies to "ran"
+ Ty --
+ ran --
+ no --
+ \set associatedVoice = lahlah % applies to "rus"
+ sau -- rus Rex
+@}
@end example
@noindent
-to a melody. Here is an example,
+The underlay is switched back to the starting situation by assigning
+@code{lahlah} to @code{associatedVoice}.
-@lilypond[ragged-right,verbatim,fragment,quote]
-\time 3/4
-\relative { c2 e4 g2. }
-\addlyrics { play the game }
-@end lilypond
-More stanzas can be added by adding more
-@code{\addlyrics} sections
+@anchor{Lyrics independent of notes}
+@unnumberedsubsubsec Lyrics independent of notes
-@lilypond[ragged-right,verbatim,fragment,quote]
-\time 3/4
-\relative { c2 e4 g2. }
-\addlyrics { play the game }
-\addlyrics { speel het spel }
-\addlyrics { joue le jeu }
-@end lilypond
+In some complex vocal music, it may be desirable to place
+lyrics completely independently of notes. Music defined
+inside @code{lyricrhythm} disappears into the
+@code{Devnull} context, but the rhythms can still be used
+to place the lyrics.
-The command @code{\addlyrics} cannot handle polyphony settings. For these
-cases you should use @code{\lyricsto} and @code{\lyricmode}, as will be
-introduced in @ref{Entering lyrics}.
+@lilypond[quote,verbatim,ragged-right]
+voice = {
+ c''2
+ \tag #'music { c''2 }
+ \tag #'lyricrhythm { c''4. c''8 }
+ d''1
+}
+lyr = \lyricmode { I like my cat! }
+<<
+ \new Staff \keepWithTag #'music \voice
+ \new Devnull="nowhere" \keepWithTag #'lyricrhythm \voice
+ \new Lyrics \lyricsto "nowhere" \lyr
+ \new Staff { c'8 c' c' c' c' c' c' c'
+ c' c' c' c' c' c' c' c' }
+>>
+@end lilypond
-@anchor{Entering lyrics}
-@unnumberedsubsubsec Entering lyrics
-@cindex lyrics
-@funindex \lyricmode
-@cindex punctuation
-@cindex spaces, in lyrics
-@cindex quotes, in lyrics
+@anchor{Spacing lyrics}
+@unnumberedsubsubsec Spacing lyrics
-Lyrics are entered in a special input mode, which can be introduced
-by the keyword @code{\lyricmode}, or by using @code{\addlyrics} or
-@code{\lyricsto}. In this mode you can enter lyrics,
-with punctuation and accents, and the input @code{d} is not parsed as
-a pitch, but rather as a one letter syllable. Syllables are entered
-like notes, but with pitches replaced by text. For example,
+@cindex Spacing lyrics
+@cindex Lyrics, increasing space between
-@example
-\lyricmode @{ Twin-4 kle4 twin- kle litt- le star2 @}
-@end example
+To increase the spacing between lyrics, set the minimum-distance property of
+LyricSpace.
-There are two main methods to specify the horizontal placement
-of the syllables, either by specifying the duration of each syllable
-explicitly, like in the example above, or by automatically aligning
-the lyrics to a melody or other voice of music, using @code{\addlyrics}
-or @code{\lyricsto}.
-@c TODO: broken
-@c For more details see @ref{The Lyrics context}.
+@lilypond[relative,verbatim,fragment,quote,ragged-right]
+{
+ c c c c
+ \override Lyrics.LyricSpace #'minimum-distance = #1.0
+ c c c c
+}
+\addlyrics {
+ longtext longtext longtext longtext
+ longtext longtext longtext longtext
+}
+@end lilypond
-A word or syllable of lyrics begins with an alphabetic character, and ends
-with
-any space or digit. The following characters can be any character
-that is not a digit or white space.
+To make this change for all lyrics in the score, set the property in the
+layout.
-Any character that is not a digit or white space will be regarded as
-part of the syllable; one important consequence of this is that a word
-can end with @code{@}}, which often leads to the following mistake:
+@lilypond[relative,verbatim,quote,ragged-right]
+\score {
+ \relative c' {
+ c c c c
+ c c c c
+ }
+ \addlyrics {
+ longtext longtext longtext longtext
+ longtext longtext longtext longtext
+ }
+ \layout {
+ \context {
+ \Lyrics
+ \override LyricSpace #'minimum-distance = #1.0
+ }
+ }
+}
+@end lilypond
-@example
-\lyricmode @{ lah- lah@}
-@end example
-In this example, the @code{@}} is included in the final syllable, so the
-opening brace is not balanced and the input file will probably not
-compile.
+@anchor{More about stanzas}
+@unnumberedsubsubsec More about stanzas
+
+@cindex stanza number
+@unnumberedsubsubsec Adding stanza numbers
+Stanza numbers can be added by setting @code{stanza}, e.g.,
-@funindex \property in \lyricmode
+@lilypond[quote,ragged-right,verbatim,relative=2,fragment]
+\new Voice {
+ \time 3/4 g2 e4 a2 f4 g2.
+} \addlyrics {
+ \set stanza = "1. "
+ Hi, my name is Bert.
+} \addlyrics {
+ \set stanza = "2. "
+ Oh, ché -- ri, je t'aime
+}
+@end lilypond
@noindent
-Similarly, a period which follows an alphabetic sequence is included in
-the resulting string. As a consequence, spaces must be inserted around
-property commands: do @emph{not} write
+These numbers are put just before the start of the first syllable.
-@example
-\override Score.LyricText #'font-shape = #'italic
-@end example
-@noindent
-but instead use
+@unnumberedsubsubsec Adding dynamics marks
-@example
-\override Score . LyricText #'font-shape = #'italic
-@end example
+Stanzas differing in loudness may be indicated by putting a
+dynamics mark before each stanza. In Lilypond, everthing coming in
+front of a stanza goes into the @code{StanzaNumber} object; dynamics marks
+are no different. For technical reasons, you have to set the stanza
+outside @code{\lyricmode}:
-@funindex _
-@cindex spaces, in lyrics
-@cindex quotes, in lyrics
-@cindex ties, in lyrics
+@lilypond[quote,ragged-right,verbatim]
+text = {
+ \set stanza = \markup { \dynamic "ff" "1. " }
+ \lyricmode {
+ Big bang
+ }
+}
-In order to assign more than one syllable to a single note, you can
-surround them with quotes or use a @code{_} character, to get spaces
-between syllables, or use tilde symbol (@code{~}) to get a lyric tie.
+<<
+ \new Voice = "tune" {
+ \time 3/4
+ g'4 c'2
+ }
+\new Lyrics \lyricsto "tune" \text
+>>
+@end lilypond
-@lilypond[quote,relative=2,ragged-right,fragment,verbatim]
-\time 3/4
-\relative { c2 e4 g2 e4 }
-\addlyrics { gran- de_a- mi- go }
-\addlyrics { pu- "ro y ho-" nes- to }
-\addlyrics { pu- ro~y~ho- nes- to }
+@cindex singer name
+@cindex name of singer
+@unnumberedsubsubsec Adding singer names
+
+Names of singers can also be added. They are printed at the start of
+the line, just like instrument names. They are created by setting
+@code{vocalName}. A short version may be entered as @code{shortVocalName}.
+
+@lilypond[fragment,ragged-right,quote,verbatim,relative=2]
+\new Voice {
+ \time 3/4 g2 e4 a2 f4 g2.
+} \addlyrics {
+ \set vocalName = "Bert "
+ Hi, my name is Bert.
+} \addlyrics {
+ \set vocalName = "Ernie "
+ Oh, che -- ri, je t'aime
+}
@end lilypond
-The lyric tie is implemented with the Unicode character U+203F, so be
-sure to have a font (Like DejaVuLGC) installed that includes this
-glyph.
+@unnumberedsubsubsec Printing stanzas at the end
-To enter lyrics with characters from non-English languages, or with
-accented and special characters (such as the heart symbol or slanted quotes),
-simply insert the characters directly into the input file and save
-it with utf-8 encoding. See @ref{Text encoding}, for more info.
+Sometimes it is appropriate to have one stanza set
+to the music, and the rest added in verse form at
+the end of the piece. This can be accomplished by adding
+the extra verses into a @code{\markup} section outside
+of the main score block. Notice that there are two
+different ways to force linebreaks when using
+@code{\markup}.
+
+@lilypond[ragged-right,verbatim,quote]
+melody = \relative c' {
+e d c d | e e e e |
+d d e d | c1 |
+}
+
+text = \lyricmode {
+\set stanza = "1." Ma- ry had a lit- tle lamb,
+its fleece was white as snow.
+}
+
+\score{ <<
+ \new Voice = "one" { \melody }
+ \new Lyrics \lyricsto "one" \text
+>>
+ \layout { }
+}
+\markup { \column{
+ \line{ Verse 2. }
+ \line{ All the children laughed and played }
+ \line{ To see a lamb at school. }
+ }
+}
+\markup{
+ \wordwrap-string #"
+ Verse 3.
-@lilypond[quote,ragged-right,fragment,verbatim]
-\relative { e4 f e d e f e2 }
-\addlyrics { He said: “Let my peo ple go”. }
+ Mary took it home again,
+
+ It was against the rule."
+}
@end lilypond
-To use normal quotes in lyrics, add a backslash before the
-quotes. For example,
-@lilypond[quote,ragged-right,fragment,verbatim]
-\relative c' { \time 3/4 e4 e4. e8 d4 e d c2. }
-\addlyrics { "\"I" am so lone- "ly\"" said she }
-@end lilypond
+@unnumberedsubsubsec Printing stanzas at the end in multiple columns
-The full definition of a word start in Lyrics mode is somewhat more
-complex.
+When a piece of music has many verses, they are often printed in
+multiple columns across the page. An outdented verse number often
+introduces each verse. The following example shows how to produce such
+output in Lilypond.
-A word in Lyrics mode begins with: an alphabetic character, @code{_},
-@code{?}, @code{!}, @code{:}, @code{'}, the control characters @code{^A}
-through @code{^F}, @code{^Q} through @code{^W}, @code{^Y}, @code{^^},
-any 8-bit character with ASCII code over 127, or a two-character
-combination of a backslash followed by one of @code{`}, @code{'},
-@code{"}, or @code{^}.
+@lilypond[ragged-right,quote,verbatim]
+melody = \relative c' {
+ c c c c | d d d d
+}
+
+text = \lyricmode {
+ \set stanza = "1." This is verse one.
+ It has two lines.
+}
-To define identifiers containing lyrics, the function @code{lyricmode}
-must be used.
+\score{ <<
+ \new Voice = "one" { \melody }
+ \new Lyrics \lyricsto "one" \text
+ >>
+ \layout { }
+}
-@example
-verseOne = \lyricmode @{ Joy to the world the Lord is come @}
-\score @{
- <<
- \new Voice = "one" \relative c'' @{
- \autoBeamOff
- \time 2/4
- c4 b8. a16 g4. f8 e4 d c2
- @}
- \addlyrics @{ \verseOne @}
- >>
-@}
-@end example
+\markup {
+ \fill-line {
+ \hspace #0.1 % moves the column off the left margin; can be removed if
+ % space on the page is tight
+ \column {
+ \line { \bold "2."
+ \column {
+ "This is verse two."
+ "It has two lines."
+ }
+ }
+ \hspace #0.1 % adds vertical spacing between verses
+ \line { \bold "3."
+ \column {
+ "This is verse three."
+ "It has two lines."
+ }
+ }
+ }
+ \hspace #0.1 % adds horizontal spacing between columns; if they are
+ % still too close, add more " " pairs until the result
+ % looks good
+ \column {
+ \line { \bold "4."
+ \column {
+ "This is verse four."
+ "It has two lines."
+ }
+ }
+ \hspace #0.1 % adds vertical spacing between verses
+ \line { \bold "5."
+ \column {
+ "This is verse five."
+ "It has two lines."
+ }
+ }
+ }
+ \hspace #0.1 % gives some extra space on the right margin; can
+ % be removed if page space is tight
+ }
+}
+@end lilypond
@seealso
-Program reference: @internalsref{LyricText}, @internalsref{LyricSpace}.
-
+Program reference: @internalsref{LyricText}, @internalsref{StanzaNumber},
+@internalsref{VocalName}.
-@anchor{Aligning lyrics to a melody}
-@unnumberedsubsubsec Aligning lyrics to a melody
-@funindex \lyricmode
-@funindex \addlyrics
-@funindex \lyricsto
+@anchor{Other vocal issues}
+@unnumberedsubsubsec Other vocal issues
+@ignore
+yeah, I'm giving up somewhat by stuffing a bunch of things in
+here. But at least they're in the manual now; it's easier to
+move them around in the manual once they're already here.
-Lyrics are printed by interpreting them in the context called
-@internalsref{Lyrics}.
+Besides, if users complain about everything stuffed in here, I
+can ask them for specific instructions about where to move these
+examples, and that might get them more involved in the docs. -gp
+@end ignore
-@example
-\new Lyrics \lyricmode @dots{}
-@end example
+@q{Parlato} is spoken without pitch but still with rhythm; it is
+notated by cross noteheads. This is demonstrated in
+@ref{Special noteheads}.
-There are two main methods to specify the horizontal placement
-of the syllables:
-@itemize @bullet
-@item
-by automatically aligning
-the lyrics to a melody or other voice of music, using @code{\addlyrics}
-or @code{\lyricsto}.
-@item
-or by specifying the duration of each syllable
-explicitly, using @code{\lyricmode}
-@end itemize
+@node Chord names
+@section Chord names
@menu
-* Automatic syllable durations::
-* Another way of entering lyrics::
-* Assigning more than one syllable to a single note::
-* More than one note on a single syllable::
-* Extenders and hyphens::
+* Introducing chord names::
+* Chords mode::
+* Printing chord names::
@end menu
-@anchor{Automatic syllable durations}
-@unnumberedsubsubsec Automatic syllable durations
-
-@cindex automatic syllable durations
-@cindex lyrics and melodies
-
-The lyrics can be aligned under a given melody
-automatically. This is achieved by combining the
-melody and the lyrics with the @code{\lyricsto} expression
-@example
-\new Lyrics \lyricsto @var{name} @dots{}
-@end example
+@c awkward name; awkward section name.
+@c still, the Basic "chords" seems like a good name... :(
+@anchor{Introducing chord names}
+@unnumberedsubsubsec Introducing chord names
+@cindex chord names
-This aligns the lyrics to the
-notes of the @internalsref{Voice} context called @var{name}, which must
-already exist. Therefore normally the @code{Voice} is specified first, and
-then the lyrics are specified with @code{\lyricsto}. The command
-@code{\lyricsto} switches to @code{\lyricmode} mode automatically, so the
-@code{\lyricmode} keyword may be omitted.
+LilyPond has support for printing chord names. Chords may be entered
+in musical chord notation, i.e., @code{< .. >}, but they can also be
+entered by name. Internally, the chords are represented as a set of
+pitches, so they can be transposed
-The following example uses different commands for entering lyrics.
-@lilypond[quote,fragment,ragged-right,verbatim]
-<<
- \new Voice = "one" \relative c'' {
- \autoBeamOff
- \time 2/4
- c4 b8. a16 g4. f8 e4 d c2
+@lilypond[quote,ragged-right,verbatim,ragged-right]
+twoWays = \transpose c c' {
+ \chordmode {
+ c1 f:sus4 bes/f
}
- \new Lyrics \lyricmode { Joy4 to8. the16 world!4. the8 Lord4 is come.2 }
- \new Lyrics \lyricmode { Joy to the earth! the Sa -- viour reigns. }
- \new Lyrics \lyricsto "one" { No more let sins and sor -- rows grow. }
->>
-@end lilypond
-
-The second stanza is not properly aligned because the durations
-were not specified. A solution for that would be to use @code{\lyricsto}.
-
-The @code{\addlyrics} command is actually just a convenient way
-to write a more complicated LilyPond structure that sets up the
-lyrics.
-
-@example
-@{ MUSIC @}
-\addlyrics @{ LYRICS @}
-@end example
-
-@noindent
-is the same as
-
-@example
-\new Voice = "blah" @{ music @}
-\new Lyrics \lyricsto "blah" @{ LYRICS @}
-@end example
-
-@anchor{Another way of entering lyrics}
-@unnumberedsubsubsec Another way of entering lyrics
+ <c e g>
+ <f bes c'>
+ <f bes d'>
+}
-Lyrics can also be entered without @code{\addlyrics} or
-@code{\lyricsto}. In this case,
-syllables are entered like notes -- but with pitches replaced by text -- and the
-duration of each syllable must be entered explicitly. For example:
-
-@example
-play2 the4 game2.
-sink2 or4 swim2.
-@end example
-
-The alignment to a melody can be specified with the
-@code{associatedVoice} property,
-
-@example
-\set associatedVoice = #"lala"
-@end example
-
-@noindent
-The value of the property (here: @code{"lala"}) should be the name of
-a @internalsref{Voice} context. Without this setting, extender lines
-will not be formatted properly.
-
-Here is an example demonstrating manual lyric durations,
-
-@lilypond[relative=1,ragged-right,verbatim,fragment,quote]
-<< \new Voice = "melody" {
- \time 3/4
- c2 e4 g2.
- }
- \new Lyrics \lyricmode {
- \set associatedVoice = #"melody"
- play2 the4 game2.
- } >>
+<< \new ChordNames \twoWays
+ \new Voice \twoWays >>
@end lilypond
-@seealso
-
-Program reference: @internalsref{Lyrics}.
-
+This example also shows that the chord printing routines do not try to
+be intelligent. The last chord (@code{f bes d}) is not interpreted as
+an inversion.
-@anchor{Assigning more than one syllable to a single note}
-@unnumberedsubsubsec Assigning more than one syllable to a single note
+Note that the duration of chords must be specified outside the
+@code{<>}.
+@example
+<c e g>2
+@end example
-@funindex _
-@cindex ties, in lyrics
-In order to assign more than one syllable to a single note, you can
-surround them with quotes or use a @code{_} character, to get spaces
-between syllables, or use tilde symbol (@code{~}) to get a lyric
-tie@footnote{The lyric ties is implemented with the Unicode character
-U+203F, so be
-sure to have a font (Like DejaVuLGC) installed that includes this
-glyph.}.
+@anchor{Chords mode}
+@unnumberedsubsubsec Chords mode
+@cindex Chords mode
-@lilypond[quote,relative=2,ragged-right,fragment,verbatim]
-\time 3/4
-\relative { c2 e4 g2 e4 }
-\addlyrics { gran- de_a- mi- go }
-\addlyrics { pu- "ro y ho-" nes- to }
-\addlyrics { pu- ro~y~ho- nes- to }
-@end lilypond
+In chord mode sets of pitches (chords) are entered with normal note
+names. A chord is entered by the root, which is entered like a
+normal pitch
-@seealso
+@lilypond[quote,ragged-right,fragment,verbatim]
+\chordmode { es4. d8 c2 }
+@end lilypond
-Program reference: @internalsref{LyricCombineMusic}.
+@noindent
+The mode is introduced by the keyword @code{\chordmode}.
-@c Here come the section which used to be "Melismata"
-@c the new title might be more self-explanatory
+@cindex chord entry
+@cindex chord mode
+Other chords may be entered by suffixing a colon and introducing a
+modifier (which may include a number if desired)
-@anchor{More than one note on a single syllable}
-@unnumberedsubsubsec More than one note on a single syllable
+@lilypond[quote,fragment,verbatim]
+\chordmode { e1:m e1:7 e1:m7 }
+@end lilypond
-@cindex melisma
-@cindex melismata
-@cindex phrasing, in lyrics
+The first number following the root is taken to be the @q{type} of the
+chord, thirds are added to the root until it reaches the specified
+number. The exception is @code{c:13}, for which the 11 is omitted.
-Sometimes, particularly in Medieval music, several notes are to be sung on one
-single syllable; such vocalises are called melismas, or melismata.
+@lilypond[quote,fragment,verbatim]
+\chordmode { c:3 c:5 c:6 c:7 c:8 c:9 c:10 c:11 c:13 }
+@end lilypond
-@c this method seems to be the simplest; therefore
-@c it might be better to present it first - vv
+@cindex root of chord
+@cindex additions, in chords
+@cindex removals, in chords
-You can define melismata entirely in the lyrics, by entering @code{_}
-for every note
-that is part of the melisma.
+More complex chords may also be constructed adding separate steps
+to a chord. Additions are added after the number following
+the colon and are separated by dots
-@lilypond[relative=1,verbatim,fragment,quote]
-{ \set melismaBusyProperties = #'()
- c d( e) f f( e) e e }
-\addlyrics
- { Ky -- _ _ ri __ _ _ _ e }
+@lilypond[quote,verbatim,fragment]
+\chordmode { c:5.6 c:3.7.8 c:3.6.13 }
@end lilypond
-In this case, you can also have ties and slurs in the melody if you
-set @code{melismaBusyProperties}, as is done in the example above.
+Chord steps can be altered by suffixing a @code{-} or @code{+} sign
+to the number
-However, the @code{\lyricsto} command can also
-detect melismata automatically: it only puts one
-syllable under a tied or slurred group of notes. If you want to force
-an unslurred group of notes to be a melisma, insert @code{\melisma}
-after the first note of the group, and @code{\melismaEnd} after the
-last one, e.g.,
+@lilypond[quote,verbatim,fragment]
+\chordmode { c:7+ c:5+.3- c:3-.5-.7- }
+@end lilypond
-@lilypond[quote,relative=2,ragged-right,fragment,verbatim]
-<<
- \new Voice = "lala" {
- \time 3/4
- f4 g8
- \melisma
- f e f
- \melismaEnd
- e2
- }
- \new Lyrics \lyricsto "lala" {
- la di __ daah
- }
->>
+Removals are specified similarly and are introduced by a caret. They
+must come after the additions
+
+@lilypond[quote,verbatim,fragment]
+\chordmode { c^3 c:7^5 c:9^3.5 }
@end lilypond
-In addition, notes are considered a melisma if they are manually
-beamed, and automatic beaming (see @ref{Setting automatic beam
-behavior}) is switched off.
+Modifiers can be used to change pitches. The following modifiers are
+supported
-@c TODO: there might be some more relevant place for
-@c the following link (?)
+@table @code
+@item m
+The minor chord. This modifier lowers the 3rd and (if present) the 7th step.
-@cindex SATB
-@cindex choral score
+@item dim
+The diminished chord. This modifier lowers the 3rd, 5th and (if present)
+the 7th step.
-A complete example of a SATB score setup is in section
-@ref{Vocal ensembles}.
+@item aug
+The augmented chord. This modifier raises the 5th step.
+@item maj
+The major 7th chord. This modifier raises the 7th step if present.
-@refcommands
+@item sus
+The suspended 4th or 2nd. This modifier removes the 3rd
+step. Append either @code{2} or @code{4} to add the 2nd or 4th step to
+the chord.
+@end table
-@code{\melisma}, @code{\melismaEnd}
-@funindex \melismaEnd
-@funindex \melisma
+Modifiers can be mixed with additions
+@lilypond[quote,verbatim,fragment]
+ \chordmode { c:sus4 c:7sus4 c:dim7 c:m6 }
+@end lilypond
-@seealso
+@cindex modifiers, in chords.
+@funindex aug
+@funindex dim
+@funindex maj
+@funindex sus
+@funindex m
+
+Since an unaltered 11 does not sound good when combined with an
+unaltered 13, the 11 is removed in this case (unless it is added
+explicitly)
+@lilypond[quote,ragged-right,fragment,verbatim]
+\chordmode { c:13 c:13.11 c:m13 }
+@end lilypond
+
+@funindex /
+
+An inversion (putting one pitch of the chord on the bottom), as well
+as bass notes, can be specified by appending
+@code{/}@var{pitch} to the chord
+@lilypond[quote,ragged-right,fragment,verbatim]
+\chordmode { c1 c/g c/f }
+@end lilypond
+@funindex /+
+
+A bass note can be added instead of transposed out of the chord,
+by using @code{/+}@var{pitch}.
+
+@lilypond[quote,ragged-right,fragment,verbatim]
+\chordmode { c1 c/+g c/+f }
+@end lilypond
+
+Chords is a mode similar to @code{\lyricmode}, etc. Most
+of the commands continue to work, for example, @code{r} and
+@code{\skip} can be used to insert rests and spaces, and property
+commands may be used to change various settings.
-Program reference: @internalsref{Melisma_translator}.
-@lsr{vocal,lyric@/-combine.ly}.
@refbugs
-Melismata are not detected automatically, and extender lines must be
-inserted by hand.
+Each step can only be present in a chord once. The following
+simply produces the augmented chord, since @code{5+} is interpreted
+last
+@cindex clusters
+@lilypond[quote,ragged-right,verbatim,fragment]
+\chordmode { c:5.5-.5+ }
+@end lilypond
-@anchor{Extenders and hyphens}
-@unnumberedsubsubsec Extenders and hyphens
-@cindex melisma
-@cindex extender
+@anchor{Printing chord names}
+@unnumberedsubsubsec Printing chord names
-Melismata are indicated with a horizontal line centered between a syllable
-and the next one. Such a line is called an extender line, and it is entered
-as @samp{ __ } (note the spaces before and after the two underscore
-characters).
+@cindex printing chord names
+@cindex chord names
+@cindex chords
-@cindex hyphens
+For displaying printed chord names, use the @internalsref{ChordNames} context.
+The chords may be entered either using the notation
+described above, or directly using @code{<} and @code{>}
-Centered hyphens are entered as @samp{ -- } between syllables of a same word
-(note the spaces before and after the two hyphen characters). The hyphen
-will be centered between the syllables, and its length will be adjusted
-depending on the space between the syllables.
+@lilypond[quote,verbatim,ragged-right]
+harmonies = {
+ \chordmode {a1 b c} <d' f' a'> <e' g' b'>
+}
+<<
+ \new ChordNames \harmonies
+ \new Staff \harmonies
+>>
+@end lilypond
-In tighly engraved music, hyphens can be removed. Whether this
-happens can be controlled with the @code{minimum-distance} (minimum
-distance between two syllables) and the @code{minimum-length}
-(threshold below which hyphens are removed).
+You can make the chord changes stand out by setting
+@internalsref{ChordNames}.@code{chordChanges} to true. This will only
+display chord names when there is a change in the chords scheme and at
+the start of a new line
-@seealso
+@lilypond[quote,verbatim,ragged-right]
+harmonies = \chordmode {
+ c1:m c:m \break c:m c:m d
+}
+<<
+ \new ChordNames {
+ \set chordChanges = ##t
+ \harmonies }
+ \new Staff \transpose c c' \harmonies
+>>
+@end lilypond
+
+The previous examples all show chords over a staff. This is not
+necessary. Chords may also be printed separately. It may be necessary
+to add @internalsref{Volta_engraver} and @internalsref{Bar_engraver}
+for showing repeats.
+
+@lilypond[ragged-right,verbatim]
+\new ChordNames \with {
+ \override BarLine #'bar-size = #4
+ \consists Bar_engraver
+ \consists "Volta_engraver"
+}
+\chordmode { \repeat volta 2 {
+ f1:maj7 f:7 bes:7
+ c:maj7
+} \alternative {
+ es e
+}
+}
+@end lilypond
-Program reference: @internalsref{LyricExtender},
-@internalsref{LyricHyphen}
+The default chord name layout is a system for Jazz music, proposed by
+Klaus Ignatzek (see @ref{Literature list}). It can be tuned through the
+following properties
-@anchor{Working with lyrics and identifiers}
-@unnumberedsubsubsec Working with lyrics and identifiers
-@cindex lyrics, identifiers
+@table @code
+@funindex chordNameExceptions
+@item chordNameExceptions
+This is a list that contains the chords that have special formatting.
-To define identifiers containing lyrics, the function @code{\lyricmode}
-must be used. You do not have to enter durations though, if you add
-@code{\addlyrics} or @code{\lyricsto}
-when invoking your identifier.
-
+The exceptions list should be encoded as
@example
-verseOne = \lyricmode @{ Joy to the world the Lord is come @}
-\score @{
- <<
- \new Voice = "one" \relative c'' @{
- \autoBeamOff
- \time 2/4
- c4 b8. a16 g4. f8 e4 d c2
- @}
- \addlyrics @{ \verseOne @}
- >>
-@}
+@{ <c f g bes>1 \markup @{ \super "7" "wahh" @} @}
@end example
-
-For different or more complex orderings, the best way is to setup the
-hierarchy of staves and lyrics first, e.g.,
+
+To get this information into @code{chordNameExceptions} takes a little
+manoeuvring. The following code transforms @code{chExceptionMusic}
+(which is a sequential music) into a list of exceptions.
@example
-\new ChoirStaff <<
- \new Voice = "soprano" @{ @emph{music} @}
- \new Lyrics = "sopranoLyrics" @{ s1 @}
- \new Lyrics = "tenorLyrics" @{ s1 @}
- \new Voice = "tenor" @{ @emph{music} @}
->>
+(sequential-music-to-chord-exceptions chExceptionMusic #t)
@end example
-
-and then combine the appropriate melodies and lyric lines
-
+Then,
@example
-\context Lyrics = sopranoLyrics \lyricsto "soprano"
-@emph{the lyrics}
+(append
+ (sequential-music-to-chord-exceptions chExceptionMusic #t)
+ ignatzekExceptions)
@end example
-
-@noindent
+adds the new exceptions to the default ones, which are defined in
+@file{ly/@/chord@/-modifier@/-init@/.ly}.
-The final input would resemble
-
-@example
-<<\new ChoirStaff << @emph{setup the music} >>
- \lyricsto "soprano" @emph{etc}
- \lyricsto "alto" @emph{etc}
-@emph{etc}
->>
-@end example
-
-@seealso
-
-@c TODO: document \new Staff << Voice \lyricsto >> bug
-Program reference: @internalsref{LyricCombineMusic},
-@internalsref{Lyrics}.
+For an example of tuning this property, see also
+@lsr{chords,chord@/-name@/-exceptions@/.ly}
+@cindex exceptions, chord names.
-@anchor{Flexibility in placement}
-@unnumberedsubsubsec Flexibility in placement
+@funindex majorSevenSymbol
+@item majorSevenSymbol
+This property contains the markup object used for the 7th step, when
+it is major. Predefined options are @code{whiteTriangleMarkup} and
+@code{blackTriangleMarkup}. See
+@lsr{chords,chord@/-name@/-major7@/.ly} for an example.
-Often, different stanzas of one song are put to one melody in slightly
-differing ways. Such variations can still be captured with
-@code{\lyricsto}.
+@funindex chordNameSeparator
+@item chordNameSeparator
+Different parts of a chord name are normally separated by a
+slash. By setting @code{chordNameSeparator}, you can specify other
+separators, e.g.,
+@lilypond[quote,ragged-right,fragment,verbatim]
+\new ChordNames \chordmode {
+ c:7sus4
+ \set chordNameSeparator
+ = \markup { \typewriter "|" }
+ c:7sus4
+}
+@end lilypond
-@menu
-* Lyrics to multiple notes of a melisma::
-* Divisi lyrics::
-* Switching the melody associated with a lyrics line::
-* Lyrics independent of notes::
-@end menu
+@funindex chordRootNamer
+@item chordRootNamer
+The root of a chord is usually printed as a letter with an optional
+alteration. The transformation from pitch to letter is done by this
+function. Special note names (for example, the German @q{H} for a
+B-chord) can be produced by storing a new function in this property.
+@funindex chordNoteNamer
+@item chordNoteNamer
+The default is to print single pitch, e.g., the bass note, using the
+@code{chordRootNamer}. The @code{chordNoteNamer} property can be set
+to a specialized function to change this behavior. For example, the
+base can be printed in lower case.
-@anchor{Lyrics to multiple notes of a melisma}
-@unnumberedsubsubsec Lyrics to multiple notes of a melisma
+@funindex chordPrefixSpacer
+@item chordPrefixSpacer
+The @q{m} for minor chords is usually printed right after the root of
+the chord. By setting @code{chordPrefixSpacer}, you can fix a spacer
+between the root and @q{m}. The spacer is not used when the root
+is altered.
-One possibility is that the text has a melisma in one stanza, but
-multiple syllables in another one. One solution is to make the faster
-voice ignore the melisma. This is done by setting
-@code{ignoreMelismata} in the Lyrics context.
+@end table
-There is one tricky aspect: the setting for @code{ignoreMelismata}
-must be set one syllable @emph{before} the non-melismatic syllable
-in the text, as shown here,
+The predefined variables @code{\germanChords},
+@code{\semiGermanChords}, @code{\italianChords} and @code{\frenchChords}
+set these variables. The effect is
+demonstrated here,
-@c FIXME: breaks compile
-@lilypond[verbatim,ragged-right,quote]
-%{
-<<
- \relative \new Voice = "lahlah" {
- \set Staff.autoBeaming = ##f
- c4
- \slurDotted
- f8.[( g16])
- a4
- }
- \new Lyrics \lyricsto "lahlah" {
- more slow -- ly
- }
- \new Lyrics \lyricsto "lahlah" {
- \set ignoreMelismata = ##t % applies to "fas"
- go fas -- ter
- \unset ignoreMelismata
- still
- }
->>
-%}
-@end lilypond
+@lilypondfile[ragged-right]{chord-names-languages.ly}
+There are also two other chord name schemes implemented: an alternate
+Jazz chord notation, and a systematic scheme called Banter chords. The
+alternate Jazz notation is also shown on the chart in @ref{Chord name
+chart}. Turning on these styles is demonstrated in
+@lsr{chords,chord-names-jazz.ly}.
-The @code{ignoreMelismata} applies to the syllable @q{fas}, so it
-should be entered before @q{go}.
+@cindex Banter
+@cindex jazz chords
+@cindex chords, jazz
-The reverse is also possible: making a lyric line slower than the
-standard. This can be achieved by insert @code{\skip}s into the
-lyrics. For every @code{\skip}, the text will be delayed another note.
-For example,
-@lilypond[verbatim,ragged-right,quote]
-\relative { c c g' }
-\addlyrics {
- twin -- \skip 4
- kle
-}
-@end lilypond
+@refcommands
+
+@funindex \germanChords
+@code{\germanChords},
+@funindex \semiGermanChords
+@code{\semiGermanChords}.
+@funindex \italianChords
+@code{\italianChords}.
+@funindex \frenchChords
+@code{\frenchChords}.
-@anchor{Divisi lyrics}
-@unnumberedsubsubsec Divisi lyrics
-You can display alternate (or divisi) lyrics by naming voice
-contexts and attaching lyrics to those specific contexts.
-@lilypond[verbatim,ragged-right,quote]
-\score{ <<
- \new Voice = "melody" {
- \relative c' {
- c4
- <<
- { \voiceOne c8 e }
- \new Voice = "splitpart" { \voiceTwo c4 }
- >>
- \oneVoice c4 c | c
- }
- }
- \new Lyrics \lyricsto "melody" { we shall not o- ver- come }
- \new Lyrics \lyricsto "splitpart" { will }
->> }
-@end lilypond
+@seealso
+Examples:
+@lsrdir{chords}
-You can use this trick to display different lyrics for a repeated
-section.
+Init files: @file{scm/@/chords@/-ignatzek@/.scm}, and
+@file{scm/@/chord@/-entry@/.scm}.
-@lilypond[verbatim,ragged-right,quote]
-\score{ <<
- \new Voice = "melody" \relative c' {
- c2 e | g e | c1 |
- \new Voice = "verse" \repeat volta 2 {c4 d e f | g1 | }
- a2 b | c1}
- \new Lyrics = "mainlyrics" \lyricsto melody \lyricmode {
- do mi sol mi do
- la si do }
- \context Lyrics = "mainlyrics" \lyricsto verse \lyricmode {
- do re mi fa sol }
- \new Lyrics = "repeatlyrics" \lyricsto verse \lyricmode {
- dodo rere mimi fafa solsol }
->>
-}
-@end lilypond
+@refbugs
+
+Chord names are determined solely from the list of pitches. Chord
+inversions are not identified, and neither are added bass notes. This
+may result in strange chord names when chords are entered with the
+@code{< .. >} syntax.
+
+
+
+
+
+@node Piano music
+@section Piano music
+
+Piano staves are two normal staves coupled with a brace. The staves
+are largely independent, but sometimes voices can cross between the
+two staves. The same notation is also used for harps and other key
+instruments. The @internalsref{PianoStaff} is especially built to
+handle this cross-staffing behavior. In this section we discuss the
+@internalsref{PianoStaff} and some other pianistic peculiarities.
+@menu
+* Automatic staff changes::
+* Manual staff switches::
+* Pedals::
+* Staff switch lines::
+* Cross staff stems::
+@end menu
-@anchor{Switching the melody associated with a lyrics line}
-@unnumberedsubsubsec Switching the melody associated with a lyrics line
+@refbugs
-More complex variations in text underlay are possible. It is possible
-to switch the melody for a line of lyrics during the text. This is
-done by setting the @code{associatedVoice} property. In the example
+Dynamics are not centered, but workarounds do exist. See the
+@q{piano centered dynamics} template in @ref{Piano templates}.
-@lilypond[ragged-right,quote]
-<<
- \relative \new Voice = "lahlah" {
- \set Staff.autoBeaming = ##f
- c4
- <<
- \new Voice = "alternative" {
- \voiceOne
- \times 2/3 {
- % show associations clearly.
- \override NoteColumn #'force-hshift = #-3
- f8 f g
- }
- }
- {
- \voiceTwo
- f8.[ g16]
- \oneVoice
- } >>
- a8( b) c
- }
- \new Lyrics \lyricsto "lahlah" {
- Ju -- ras -- sic Park
- }
- \new Lyrics \lyricsto "lahlah" {
- % Tricky: need to set associatedVoice
- % one syllable too soon!
- \set associatedVoice = alternative % applies to "ran"
- Ty --
- ran --
- no --
- \set associatedVoice = lahlah % applies to "rus"
- sau -- rus Rex
- } >>
-@end lilypond
+@cindex cross staff stem
+@cindex stem, cross staff
+@cindex distance between staves in piano music
-@noindent
-the text for the first stanza is set to a melody called @q{lahlah},
-@example
-\new Lyrics \lyricsto "lahlah" @{
- Ju -- ras -- sic Park
-@}
-@end example
+@anchor{Automatic staff changes}
+@unnumberedsubsubsec Automatic staff changes
+@cindex Automatic staff changes
+Voices can be made to switch automatically between the top and the bottom
+staff. The syntax for this is
-The second stanza initially is set to the @code{lahlah} context, but
-for the syllable @q{ran}, it switches to a different melody.
-This is achieved with
+@quotation
@example
-\set associatedVoice = alternative
+\autochange @dots{}@var{music}@dots{}
@end example
+@end quotation
@noindent
-Here, @code{alternative} is the name of the @code{Voice} context
-containing the triplet.
+This will create two staves inside the current PianoStaff, called
+@code{up} and @code{down}. The lower staff will be in bass clef by
+default.
-Again, the command must be one syllable too early, before @q{Ty} in
-this case.
+A @code{\relative} section that is outside of @code{\autochange} has
+no effect on the pitches of @var{music}, so, if necessary, put
+@code{\relative} inside @code{\autochange} like
+@quotation
@example
-\new Lyrics \lyricsto "lahlah" @{
- \set associatedVoice = alternative % applies to "ran"
- Ty --
- ran --
- no --
- \set associatedVoice = lahlah % applies to "rus"
- sau -- rus Rex
-@}
+\autochange \relative @dots{} @dots{}
@end example
+@end quotation
-@noindent
-The underlay is switched back to the starting situation by assigning
-@code{lahlah} to @code{associatedVoice}.
-
-
-@anchor{Lyrics independent of notes}
-@unnumberedsubsubsec Lyrics independent of notes
-In some complex vocal music, it may be desirable to place
-lyrics completely independently of notes. Music defined
-inside @code{lyricrhythm} disappears into the
-@code{Devnull} context, but the rhythms can still be used
-to place the lyrics.
+The autochanger switches on basis of the pitch (middle C is the turning
+point), and it looks ahead skipping over rests to switch in
+advance. Here is a practical example
@lilypond[quote,verbatim,ragged-right]
-voice = {
- c''2
- \tag #'music { c''2 }
- \tag #'lyricrhythm { c''4. c''8 }
- d''1
-}
+\new PianoStaff
+ \autochange \relative c'
+ {
+ g4 a b c d r4 a g
+ }
+@end lilypond
-lyr = \lyricmode { I like my cat! }
-<<
- \new Staff \keepWithTag #'music \voice
- \new Devnull="nowhere" \keepWithTag #'lyricrhythm \voice
- \new Lyrics \lyricsto "nowhere" \lyr
- \new Staff { c'8 c' c' c' c' c' c' c'
- c' c' c' c' c' c' c' c' }
->>
-@end lilypond
+@seealso
+In this manual: @ref{Manual staff switches}.
-@anchor{Spacing lyrics}
-@unnumberedsubsubsec Spacing lyrics
+Program reference: @internalsref{AutoChangeMusic}.
-@cindex Spacing lyrics
-@cindex Lyrics, increasing space between
-To increase the spacing between lyrics, set the minimum-distance property of
-LyricSpace.
-@lilypond[relative,verbatim,fragment,quote,ragged-right]
-{
- c c c c
- \override Lyrics.LyricSpace #'minimum-distance = #1.0
- c c c c
-}
-\addlyrics {
- longtext longtext longtext longtext
- longtext longtext longtext longtext
-}
-@end lilypond
+@refbugs
-To make this change for all lyrics in the score, set the property in the
-layout.
+The staff switches may not end up in optimal places. For high
+quality output, staff switches should be specified manually.
-@lilypond[relative,verbatim,quote,ragged-right]
-\score {
- \relative c' {
- c c c c
- c c c c
- }
- \addlyrics {
- longtext longtext longtext longtext
- longtext longtext longtext longtext
- }
- \layout {
- \context {
- \Lyrics
- \override LyricSpace #'minimum-distance = #1.0
- }
- }
-}
-@end lilypond
+@code{\autochange} cannot be inside @code{\times}.
-@anchor{More about stanzas}
-@unnumberedsubsubsec More about stanzas
-@cindex stanza number
-@unnumberedsubsubsec Adding stanza numbers
+@anchor{Manual staff switches}
+@unnumberedsubsubsec Manual staff switches
-Stanza numbers can be added by setting @code{stanza}, e.g.,
+@cindex manual staff switches
+@cindex staff switch, manual
-@lilypond[quote,ragged-right,verbatim,relative=2,fragment]
-\new Voice {
- \time 3/4 g2 e4 a2 f4 g2.
-} \addlyrics {
- \set stanza = "1. "
- Hi, my name is Bert.
-} \addlyrics {
- \set stanza = "2. "
- Oh, ché -- ri, je t'aime
-}
-@end lilypond
+Voices can be switched between staves manually, using the command
+@example
+\change Staff = @var{staffname} @var{music}
+@end example
@noindent
-These numbers are put just before the start of the first syllable.
+The string @var{staffname} is the name of the staff. It switches the
+current voice from its current staff to the Staff called
+@var{staffname}. Typically @var{staffname} is @code{"up"} or
+@code{"down"}. The @context{Staff} referred to must already exist, so
+usually the setup for a score will start with a setup of the staves,
+@example
+<<
+ \new Staff = "up" @{
+ \skip 1 * 10 % @emph{keep staff alive}
+ @}
+ \new Staff = "down" @{
+ \skip 1 * 10 % @emph{idem}
+ @}
+>>
+@end example
-@unnumberedsubsubsec Adding dynamics marks
-Stanzas differing in loudness may be indicated by putting a
-dynamics mark before each stanza. In Lilypond, everthing coming in
-front of a stanza goes into the @code{StanzaNumber} object; dynamics marks
-are no different. For technical reasons, you have to set the stanza
-outside @code{\lyricmode}:
+and the @context{Voice} is inserted afterwards
-@lilypond[quote,ragged-right,verbatim]
-text = {
- \set stanza = \markup { \dynamic "ff" "1. " }
- \lyricmode {
- Big bang
- }
-}
+@example
+\context Staff = down
+ \new Voice @{ @dots{} \change Staff = up @dots{} @}
+@end example
-<<
- \new Voice = "tune" {
- \time 3/4
- g'4 c'2
- }
-\new Lyrics \lyricsto "tune" \text
->>
+
+@anchor{Pedals}
+@unnumberedsubsubsec Pedals
+@cindex Pedals
+
+Pianos have pedals that alter the way sound is produced. Generally, a
+piano has three pedals, sustain, una corda, and sostenuto.
+
+
+Piano pedal instruction can be expressed by attaching
+@code{\sustainDown}, @code{\sustainUp}, @code{\unaCorda},
+@code{\treCorde}, @code{\sostenutoDown} and @code{\sostenutoUp} to a
+note or chord
+
+@lilypond[quote,ragged-right,fragment,verbatim]
+c'4\sustainDown c'4\sustainUp
@end lilypond
-@cindex singer name
-@cindex name of singer
-@unnumberedsubsubsec Adding singer names
+What is printed can be modified by setting @code{pedal@var{X}Strings},
+where @var{X} is one of the pedal types: @code{Sustain},
+@code{Sostenuto} or @code{UnaCorda}. Refer to
+@internalsref{SustainPedal} in the program reference for more
+information.
-Names of singers can also be added. They are printed at the start of
-the line, just like instrument names. They are created by setting
-@code{vocalName}. A short version may be entered as @code{shortVocalName}.
+Pedals can also be indicated by a sequence of brackets, by setting the
+@code{pedalSustainStyle} property to bracket objects
-@lilypond[fragment,ragged-right,quote,verbatim,relative=2]
-\new Voice {
- \time 3/4 g2 e4 a2 f4 g2.
-} \addlyrics {
- \set vocalName = "Bert "
- Hi, my name is Bert.
-} \addlyrics {
- \set vocalName = "Ernie "
- Oh, che -- ri, je t'aime
-}
+@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
+\set Staff.pedalSustainStyle = #'bracket
+c\sustainDown d e
+b\sustainUp\sustainDown
+b g \sustainUp a \sustainDown \bar "|."
@end lilypond
+A third style of pedal notation is a mixture of text and brackets,
+obtained by setting the @code{pedalSustainStyle} property to
+@code{mixed}
-@unnumberedsubsubsec Printing stanzas at the end
+@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
+\set Staff.pedalSustainStyle = #'mixed
+c\sustainDown d e
+b\sustainUp\sustainDown
+b g \sustainUp a \sustainDown \bar "|."
+@end lilypond
-Sometimes it is appropriate to have one stanza set
-to the music, and the rest added in verse form at
-the end of the piece. This can be accomplished by adding
-the extra verses into a @code{\markup} section outside
-of the main score block. Notice that there are two
-different ways to force linebreaks when using
-@code{\markup}.
+The default @q{*Ped.} style for sustain and damper pedals corresponds to
+style @code{#'text}. The sostenuto pedal uses @code{mixed} style by
+default.
-@lilypond[ragged-right,verbatim,quote]
-melody = \relative c' {
-e d c d | e e e e |
-d d e d | c1 |
-}
+@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
+c\sostenutoDown d e c, f g a\sostenutoUp
+@end lilypond
-text = \lyricmode {
-\set stanza = "1." Ma- ry had a lit- tle lamb,
-its fleece was white as snow.
-}
+For fine-tuning the appearance of a pedal bracket, the properties
+@code{edge-width}, @code{edge-height}, and @code{shorten-pair} of
+@code{PianoPedalBracket} objects (see
+@internalsref{PianoPedalBracket} in the Program reference) can be
+modified. For example, the bracket may be extended to the right edge
+of the note head
-\score{ <<
- \new Voice = "one" { \melody }
- \new Lyrics \lyricsto "one" \text
->>
- \layout { }
-}
-\markup { \column{
- \line{ Verse 2. }
- \line{ All the children laughed and played }
- \line{ To see a lamb at school. }
- }
-}
-\markup{
- \wordwrap-string #"
- Verse 3.
+@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
+\override Staff.PianoPedalBracket #'shorten-pair = #'(0 . -1.0)
+c\sostenutoDown d e c, f g a\sostenutoUp
+@end lilypond
- Mary took it home again,
+@seealso
- It was against the rule."
-}
-@end lilypond
+In this manual: @ref{Laissez vibrer ties}.
+@anchor{Staff switch lines}
+@unnumberedsubsubsec Staff switch lines
-@unnumberedsubsubsec Printing stanzas at the end in multiple columns
-When a piece of music has many verses, they are often printed in
-multiple columns across the page. An outdented verse number often
-introduces each verse. The following example shows how to produce such
-output in Lilypond.
+@cindex follow voice
+@cindex staff switching
+@cindex cross staff
-@lilypond[ragged-right,quote,verbatim]
-melody = \relative c' {
- c c c c | d d d d
-}
-
-text = \lyricmode {
- \set stanza = "1." This is verse one.
- It has two lines.
-}
+@funindex followVoice
-\score{ <<
- \new Voice = "one" { \melody }
- \new Lyrics \lyricsto "one" \text
- >>
- \layout { }
-}
+Whenever a voice switches to another staff, a line connecting the notes
+can be printed automatically. This is switched on by setting
+@code{followVoice} to true
-\markup {
- \fill-line {
- \hspace #0.1 % moves the column off the left margin; can be removed if
- % space on the page is tight
- \column {
- \line { \bold "2."
- \column {
- "This is verse two."
- "It has two lines."
- }
- }
- \hspace #0.1 % adds vertical spacing between verses
- \line { \bold "3."
- \column {
- "This is verse three."
- "It has two lines."
- }
- }
- }
- \hspace #0.1 % adds horizontal spacing between columns; if they are
- % still too close, add more " " pairs until the result
- % looks good
- \column {
- \line { \bold "4."
- \column {
- "This is verse four."
- "It has two lines."
- }
- }
- \hspace #0.1 % adds vertical spacing between verses
- \line { \bold "5."
- \column {
- "This is verse five."
- "It has two lines."
- }
- }
- }
- \hspace #0.1 % gives some extra space on the right margin; can
- % be removed if page space is tight
+@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
+\new PianoStaff <<
+ \new Staff="one" {
+ \set followVoice = ##t
+ c1
+ \change Staff=two
+ b2 a
}
-}
+ \new Staff="two" { \clef bass \skip 1*2 }
+>>
@end lilypond
-
@seealso
-Program reference: @internalsref{LyricText}, @internalsref{StanzaNumber},
-@internalsref{VocalName}.
-
-
+Program reference: @internalsref{VoiceFollower}.
-@anchor{Other vocal issues}
-@unnumberedsubsubsec Other vocal issues
+@refcommands
-@ignore
-yeah, I'm giving up somewhat by stuffing a bunch of things in
-here. But at least they're in the manual now; it's easier to
-move them around in the manual once they're already here.
+@funindex \showStaffSwitch
+@code{\showStaffSwitch},
+@funindex \hideStaffSwitch
+@code{\hideStaffSwitch}.
-Besides, if users complain about everything stuffed in here, I
-can ask them for specific instructions about where to move these
-examples, and that might get them more involved in the docs. -gp
-@end ignore
-@q{Parlato} is spoken without pitch but still with rhythm; it is
-notated by cross noteheads. This is demonstrated in
-@ref{Special noteheads}.
+@anchor{Cross staff stems}
+@unnumberedsubsubsec Cross staff stems
+Chords that cross staves may be produced by increasing the length
+of the stem in the lower staff, so it reaches the stem in the upper
+staff, or vice versa.
+@lilypond[ragged-right,verbatim,quote]
+stemExtend = {
+ \once \override Stem #'length = #10
+ \once \override Stem #'cross-staff = ##t
+}
+noFlag = \once \override Stem #'flag-style = #'no-flag
+\new PianoStaff <<
+ \new Staff {
+ \stemDown \stemExtend
+ f'4
+ \stemExtend \noFlag
+ f'8
+ }
+ \new Staff {
+ \clef bass
+ a4 a8
+ }
+>>
+@end lilypond
-@node Rhythmic music
-@section Rhythmic music
+@node Percussion
+@section Percussion
Rhythmic music is primarily used for percussion and drum notation, but it can
also be used to show the rhythms of melodies.
demonstrated in @ref{Special noteheads}.
-@node Bagpipe
-@section Bagpipe
+@node Other instrument-specific
+@section Other instrument-specific
-@cindex Bagpipe
+This section includes extra information for writing for instruments.
@menu
-* Bagpipe definitions::
-* Bagpipe example::
+* Orchestral strings::
+* Bagpipe::
@end menu
+@node Orchestral strings
+@subsection Orchestral strings
+
+@anchor{Artificial harmonics (strings)}
+@unnumberedsubsubsec Artificial harmonics (strings)
+
+@cindex artificial harmonics
+
+Artificial harmonics are notated with a different notehead style. They
+are entered by marking the harmonic pitch with @code{\harmonic}.
+
+@lilypond[ragged-right,verbatim,quote,fragment,relative=1]
+<c g'\harmonic>4
+@end lilypond
+
+
+@node Bagpipe
+@subsection Bagpipe
+
@anchor{Bagpipe definitions}
@unnumberedsubsubsec Bagpipe definitions
-@node Other instrument specific notation
-@section Other instrument specific notation
-
-This section includes extra information for writing for instruments.
-
-@menu
-* Artificial harmonics (strings)::
-@end menu
-
-@anchor{Artificial harmonics (strings)}
-@unnumberedsubsubsec Artificial harmonics (strings)
-
-@cindex artificial harmonics
-
-Artificial harmonics are notated with a different notehead style. They
-are entered by marking the harmonic pitch with @code{\harmonic}.
-
-@lilypond[ragged-right,verbatim,quote,fragment,relative=1]
-<c g'\harmonic>4
-@end lilypond
projects / lilypond.git / commitdiff