Merge branch 'master' of git://git.sv.gnu.org/lilypond.git into td-lily

[lilypond.git] / Documentation / user / chords.itely

@c -*- coding: utf-8; mode: texinfo; -*-
@ignore
    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  See TRANSLATION for details.
@end ignore

@c \version "2.11.38"


@node Chord notation
@section Chord notation

Chords can be entered and displayed both as notes on a staff and
as a chord name.  In addition, figured bass notation can be
displayed.

@menu
* Entering chords::             
* old Modern chords::           
* Figured bass::                
@end menu


@node Entering chords
@subsection Entering chords

@cindex entering chords

@c I'm testing a @longcode{} that does @w{@code{}}; this should be
@c easier than writing @code{}@tie[}@code[}... -gp
@c stay tuned about this
Chords can be entered explicity through the use of the chord
constructors @code{<}@tie{}@code{>}.  They can also be entered in
chord mode, which allows chord pitches to be automatically
added to the specified root.

@menu
* Explicitly stating pitches::  
* Chord mode::                  
@end menu

@node Explicitly stating pitches
@unnumberedsubsubsec Explicitly stating pitches

The simplest method for entering chords is to enclose all of the
pitches for the chord in angle brackets, with the duration of the
chord specified outside the @code{<>}.

@lilypond[quote,ragged-right,fragment,verbatim]
<c e g>2
@end lilypond

@noindent
This construction causes all of the notes inside of the @code{<>}
to occur at the same moment and have the same duration.

In traditional European music, there is more to a chord than just
the occurence of simultaneous notes.  Chords are identified by a
root, and may have inversions.  Standard modifiers to the chords
are also widely used.  Bass notes may be added to a chord.  The
@code{<>} method for entering chords knows only the pitches, and
is unable to support any of these extra characteristics.  If these
characteristics are important, it is better to follow the method
described in @ref{Chord mode}.

@seealso

Music Glossary:
@rglos{chord}.

Notation Reference:
@ref{Chord mode}.


@node Chord mode
@unnumberedsubsubsec Chord mode

@cindex chord names
@cindex chord mode

Chord mode is an input mode that understands the usage of chords
in traditional european music.  Such chords can be entered like
notes,

@lilypond[verbatim,quote,ragged-right]
\chordmode { c2 f4. g8 }
@end lilypond

In chord mode each pitch is read as the root of a triad instead of a note.
This mode is switched on with @code{\chordmode}.

@cindex root of chord

@code{\chordmode} is 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.

Chords entered using chord mode are music elements, and can be
transposed.

Chord mode is not limited to simple triads.  More complex chords
can be created by adding modifiers after a colon. The following
example shows a few common modifiers:

@lilypond[verbatim,quote,ragged-right]
\chordmode { c2 f4:m g4:maj7 gis1:dim7 }
@end lilypond

@noindent
Note that the colon and the modifiers follow the duration of the
chord.

Modifiers can be used to extend a chord, specify the @q{quality} of
the chord, add or remove chord steps, raise or lower chord steps,
and add a bass note or create an inversion.

The first number following the colon is taken to be the extent of
the chord. The chord is constructed by sequentially adding thirds
to the root until the specified number has been reached.

@lilypond[quote,ragged-right,fragment,verbatim]
\chordmode { c:3 c:5 c:6 c:7 c:8 c:9 c:10 c:11}
@end lilypond

Since an unaltered 11 does not sound good when combined with an
unaltered 13, the 11 is removed from a :13 chord (unless it is
added explicitly).

@lilypond[quote,ragged-right,fragment,verbatim]
\chordmode { c:13 c:13.11 c:m13 }
@end lilypond

@cindex additions, in chords

The quality of a chord can be set according to standard chord naming
conventions. The following quality modifiers are supported:


@table @code
@item m The minor chord.  This modifier lowers the 3rd
and (if present) the 7th step.

@item dim The diminished chord.  This modifier lowers the 3rd, 5th
and (if present) the 7th step.

@item aug
The augmented chord.  This modifier raises the 5th step.

@item maj
The major 7th chord.  This modifier adds a raised the 7th step
to the chord.  The @code{7} following @code{maj} is optional.

@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

@cindex modifiers, in chords.
@cindex chord quality
@funindex aug
@funindex dim
@funindex maj
@funindex sus
@funindex m


Individual steps can be added to or removed from a chord.
Additions are added after the chord type and are prefixed by dots.

@lilypond[quote,verbatim,fragment]
\chordmode { c:5.6 c:3.7.8 c:3.6.13 }
@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

@cindex chord steps, altering

@cindex removals, in chords

@funindex ^
Steps to be removed are listed following the additions and are
prefixed by @code{^}.

@lilypond[quote,verbatim,fragment]
\chordmode { c^3 c:7^5 c:9^3.5 }
@end lilypond

@funindex /

Inversions (putting a pitch other than the root on the bottom of
the chord) and added 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 that is part of the chord can be added, instead of
moved as part of an inversion, by using @code{/+}@var{pitch}.

@lilypond[quote,ragged-right,fragment,verbatim]
\chordmode { c1 c/+g c/+f }
@end lilypond

@seealso


@knownissues

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



@ignore
@n ode Displaying chords
@s ubsection Displaying chords



@menu
* Printing chord names::        
* Customizing chord names::     
* Lead sheets::                 
@end menu

@n ode Printing chord names
@u nnumberedsubsubsec Printing chord names

@cindex printing chord names
@cindex chord names
@cindex chords

LilyPond has support for printing chord names.  Because chords are
music elements, they can be transposed, and the chord names will be
transposed along with the chords.

Chords can be entered using @code{< .. >} or through the use of
chord mode.  The displayed chord name will sometimes be different
depending upon the entry mode:

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

<< \new ChordNames \twoWays
   \new Voice \twoWays >>
@end lilypond

This example also shows that the chord printing routines cannot
correctly identify the root of a chord if it has been entered using
@code{< .. >} instead of named chord entry.  Therefore, the sixth
chord (@code{f bes d}) is not interpreted as an inversion.   In
contrast, the third chord, which contains the same notes as the sixth
chord, is correctly identified because it was entered in the named
chord mode.

For displaying printed chord names, use the @rinternals{ChordNames}
context.

@lilypond[quote,verbatim,ragged-right]
harmonies = {
  \chordmode {a1 b c} <d' f' a'> <e' g' b'>
}
<<
  \new ChordNames \harmonies
  \new Staff \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 @rinternals{Volta_engraver} and @rinternals{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

@code{\chords} is a shortcut method used to change the input mode to
@code{\chordmode} and create a @code{ChordNames} context, with the
following result:

@lilypond[verbatim,quote,ragged-right]
\chords { c2 f4.:m g4.:maj7 gis8:dim7 }
@end lilypond

@c @predefined

@c @snippets

@seealso
@c Music Glossary:
@c @rglos{}.

@c Learning Manual:
@c @rlearning{}.

@c Notation Reference:
@c @ruser{}.

@c Application Usage:
@c @rprogram{}.

@c Installed Files:
@c @file{}.

@c Snippets:
@c @rlsr{}.

@c Internals Reference:
@c @rinternals{}.

@c @knownissues


@n ode Customizing chord names
@u nnumberedsubsubsec Customizing chord names

@cindex customizing chord names

There is no unique system for naming chords.  Different musical
traditions use different names for the same set of chords. There are
also different symbols displayed for a given chord name.   The names
and symbols displayed for chord names are customizable.

The default chord name layout is a system for Jazz music, proposed
by Klaus Ignatzek (see @ref{Literature list}).  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}.

In addition to the different naming systems, different note names
are used for the root in different languages.  The predefined
variables @code{\germanChords}, @code{\semiGermanChords},
@code{\italianChords} and @code{\frenchChords} set these variables.
The effect is demonstrated here:

@lilypondfile[ragged-right]{chord-names-languages.ly}

If none of the default settings give the desired output, the chord
name display can be tuned through the following properties.

@c TODO Generate snippet based on the following
@c      and add explanation -td

@table
@item
@funindex chordNameExceptions

@code{chordNameExceptions} contains a list of markups used to follow
the root note name based on the pitches in the chord.  Creating the
list requires four steps.

The first step is to define sequential music that has the chords to
be named with the desired markup (except for the root name) attached
to the chord:

@example
FGGChordNames = @{
  <c e g b d'>1-\markup @{ \super "maj9" @}
  <c e g a d'>1-\markup @{ \super "6(add9)" @}
@}
@end example

The second step is to convert the music from the first step to an
exceptions list:

@example
FGGExceptions = #(sequential-music-to-chord-exceptions
FGGChordNames #t)
@end example

The third step is to append the default exceptions list (in this
case, the Ignatzek exceptions) to the newly-defined exceptions list:

@example
chExceptions = #(append FGGExceptions ignatzekExceptions)
@end example

The final step is to set @code{chordNameExceptions} to the
newly-created exceptions list:

@example
\set chordNameExceptions = #chExceptions
@end example

The entire process is illustrated below:

@lilypond[quote,ragged-right,verbatim,ragged-right]
FGGChordNames = {
  <c e g b d'>1-\markup { \super "maj9" }
  <c e g a d'>1-\markup { \super "6(add9)" }
}
FGGExceptions = #(sequential-music-to-chord-exceptions
FGGChordNames #t)
chExceptions = #(append FGGChordNames
 ignatzekExceptions)

chordStuff = \chordmode
{
% standard names
g1:maj9
g1:6.9
% names with FGG's custom exceptions
\set chordNameExceptions = #chExceptions
g1:maj9
g1:6.9
}

\score
{
\new ChordNames \chordStuff
}
@end lilypond


@funindex majorSevenSymbol
@item majorSevenSymbol
This property contains the markup object used as part of the printed
chord name to identify a major 7 chord. Predefined options are
@code{whiteTriangleMarkup} and @code{blackTriangleMarkup}.

@funindex chordNameSeparator
@item chordNameSeparator
Different parts of a chord name are normally separated by a slash.
By setting @code{chordNameSeparator}, you can use any desired markup
for a separator, 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 chord name is usually printed as a letter for the root 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
When the chord name contains an additional pitch besides the root
(e.g., an added bass note), this function is used to print the
additional pitch. By default the pitch is printed using
@code{chordRootNamer}. The @code{chordNoteNamer} property can be set
to a specialized function to change this behavior.  For example, the
bass note can be printed in lower case.

@funindex chordPrefixSpacer
@item chordPrefixSpacer
The @q{m} for minor chords is usually printed immediately to the
right of 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




@cindex Banter
@cindex jazz chords
@cindex chords, jazz

@predefined
@funindex major seven symbols
@code{\whiteTriangleMarkup}
@code{\blackTriangleMarkup}
@funindex \germanChords
@code{\germanChords},
@funindex \semiGermanChords
@code{\semiGermanChords},
@funindex \italianChords
@code{\italianChords},
@funindex \frenchChords
@code{\frenchChords}.


@snippets
@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
{chord-names-jazz.ly}

@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
{chord-name-exceptions.ly}
@cindex exceptions, chord names.

@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
{chord-name-major7.ly}

@seealso
@c Music Glossary:
@c @rglos{}.

@c Learning Manual:
@c @rlearning{}.

@c Notation Reference:
@c @ruser{}.

@c Application Usage:
@c @rprogram{}.

Installed Files:
@file{scm/@/chords@/-ignatzek@/.scm},
@file{scm/@/chord@/-entry@/.scm},
@file{ly/@/chord@/-modifier@/-init@/.ly}.

@c Snippets: @c @rlsr{}.

@c Internals Reference:
@c @rinternals{}.

@knownissues

When chords are entered with the @code{< .. >} syntax, the root and
any added bass notes are not identified.  In this  case, chord names
are determined solely from the list of pitches.  This may result in
strange chord names

@n ode Lead sheets
@u nnumberedsubsubsec Lead sheets

@cindex lead sheet

For lead sheets, chords are not printed on staves, but as names on a
line for themselves.  This is achieved by using a @code{ChordNames}
context simultaneously with the @code{Staff} context.  The
@code{\chords} keyword can be used as a shortcut for @code{\new
ChordNames \chordmode}.

When put together, chord names, a melody, and lyrics form a lead
sheet:

@lilypond[verbatim,quote,ragged-right]
<<
  \chords { c2 g:sus4 f e }
  \relative c'' {
    a4 e c8 e r4
    b2 c4( d)
  }
  \addlyrics { One day this shall be free __ }
>>
@end lilypond

@c @predefined

@c @snippets

@seealso
@c Music Glossary:
@c @rglos{}.

@c Learning Manual:
@c @rlearning{}.

@c Notation Reference:
@c @ruser{}.

@c Application Usage:
@c @rprogram{}.

@c Installed Files:
@c @file{}.

@c Snippets:
@c @rlsr{}.

@c Internals Reference:
@c @rinternals{}.

@c @knownissues




@end ignore


@node old Modern chords
@subsection old Modern chords

@menu
* Chord modes::                 
* Entering chord names::        
* Building chords::             
* Lead sheets::                 
* Printing chord names::        
@end menu

@cindex chords
@cindex chord names

@node Chord modes
@subsubsection Chord modes

In popular music it is common to denote accompaniment with chord
names.  Such chords can be entered like notes,

@lilypond[verbatim,quote,ragged-right]
\chordmode { c2 f4. g8 }
@end lilypond

Now each pitch is read as the root of a chord instead of a note.
This mode is switched on with @code{\chordmode}.  Other chords can
be created by adding modifiers after a colon.  The following
example shows a few common modifiers:

@lilypond[verbatim,quote,ragged-right]
\chordmode { c2 f4:m g4:maj7 gis1:dim7 }
@end lilypond

@cindex Chords mode

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

@lilypond[quote,ragged-right,fragment,verbatim]
\chordmode { es4. d8 c2 }
@end lilypond

@noindent
The mode is introduced by the keyword @code{\chordmode}.

@cindex chord entry
@cindex chord mode

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.
It uses the same syntax as
@code{\chordmode}, but renders the notes in a @code{ChordNames}
context, with the following result:

@lilypond[verbatim,quote,ragged-right]
\chords { c2 f4.:m g4.:maj7 gis8:dim7 }
@end lilypond


@knownissues

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


@node Entering chord names
@subsubsection Entering chord names
@cindex chord names

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


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

<< \new ChordNames \twoWays
   \new Voice \twoWays >>
@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.

Note that the duration of chords must be specified outside the
@code{<>}.

@example
<c e g>2
@end example

@c TODO Generate snippet based on the following
@c      and add explanation -td

Custom chord names may be generated:

@lilypond[quote,ragged-right,verbatim,ragged-right]
FGGChordNames = {
  <c e g b d'>1-\markup { \super "maj9" }
  <c e g a d'>1-\markup { \super "6(add9)" }
}
chExceptions = #(append
(sequential-music-to-chord-exceptions
FGGChordNames #t) ignatzekExceptions)

chordStuff = \chordmode
{
% standard names
g1:maj9
g1:6.9
% names with FGG's custom exceptions
\set chordNameExceptions = #chExceptions
g1:maj9
g1:6.9
}

\score
{
\new ChordNames \chordStuff
}
@end lilypond

@node Building chords
@subsubsection Building chords

Other chords may be entered by suffixing a colon and introducing a
modifier (which may include a number if desired)

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

@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

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[quote,verbatim,fragment]
\chordmode { c:5.6 c:3.7.8 c:3.6.13 }
@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

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

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.

@item dim
The diminished chord.  This modifier lowers the 3rd, 5th and (if present)
the 7th step.

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

@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

Modifiers can be mixed with additions
@lilypond[quote,verbatim,fragment]
  \chordmode { c:sus4 c:7sus4 c:dim7 c:m6 }
@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

@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


@node Lead sheets
@subsubsection Lead sheets

@cindex lead sheet

For lead sheets, chords are not printed on staves, but as names on
a line for themselves.  This is achieved by using @code{\chords}
instead of @code{\chordmode}.

When put together, chord names, lyrics and a melody form a lead
sheet,

@lilypond[verbatim,quote,ragged-right]
<<
  \chords { c2 g:sus4 f e }
  \relative c'' {
    a4 e c8 e r4
    b2 c4( d)
  }
  \addlyrics { One day this shall be free __ }
>>
@end lilypond



@node Printing chord names
@subsubsection Printing chord names

@cindex printing chord names
@cindex chord names
@cindex chords

For displaying printed chord names, use the @rinternals{ChordNames} context.
The chords may be entered either using the notation
described above, or directly using @code{<} and @code{>}

@lilypond[quote,verbatim,ragged-right]
harmonies = {
  \chordmode {a1 b c} <d' f' a'> <e' g' b'>
}
<<
  \new ChordNames \harmonies
  \new Staff \harmonies
>>
@end lilypond

You can make the chord changes stand out by setting
@rinternals{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

@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 @rinternals{Volta_engraver} and @rinternals{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


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

@table @code
@funindex chordNameExceptions
@item chordNameExceptions
This is a list that contains the chords that have special formatting.

The exceptions list should be encoded as
@example
@{ <c f g bes>1 \markup @{ \super "7" "wahh" @} @}
@end example

To get this information into @code{chordNameExceptions} takes a little
maneuvering.  The following code transforms @code{chExceptionMusic}
(which is a sequential music) into a list of exceptions.
@example
(sequential-music-to-chord-exceptions chExceptionMusic #t)
@end example
Then,
@example
(append
 (sequential-music-to-chord-exceptions chExceptionMusic #t)
 ignatzekExceptions)
@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
@c @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
@c @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,

@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
@c @lsr{chords,chord-names-jazz.ly}.

@cindex Banter
@cindex jazz chords
@cindex chords, jazz


@predefined

@funindex \germanChords
@code{\germanChords},
@funindex \semiGermanChords
@code{\semiGermanChords}.
@funindex \italianChords
@code{\italianChords}.
@funindex \frenchChords
@code{\frenchChords}.




@seealso

Examples:

Init files: @file{scm/@/chords@/-ignatzek@/.scm}, and
@file{scm/@/chord@/-entry@/.scm}.


@knownissues

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 Figured bass
@subsection Figured bass

@menu
* Introduction to figured bass::  
* Entering figured bass::       
* Displaying figured bass::     
@end menu

@node Introduction to figured bass
@subsubsection Introduction to figured bass

@cindex Basso continuo

@c TODO: musicological blurb about FB

LilyPond has support for figured bass

@lilypond[quote,ragged-right,verbatim,fragment]
<<
  \new Voice { \clef bass dis4 c d ais g fis}
  \new FiguredBass \figuremode {
    < 6 >4 < 7\+ >8 < 6+ [_!] >
    < 6 >4 <6 5 [3+] >
    < _ >4 < 6 5/>4
  }
>>
@end lilypond

The support for figured bass consists of two parts: there is an
input mode, introduced by @code{\figuremode}, where you can enter
bass figures as numbers, and there is a context named
@rinternals{FiguredBass} that takes care of making
@rinternals{BassFigure} objects.

Although the support for figured bass may superficially resemble chord
support, it is much simpler.  The @code{\figuremode} mode simply
stores the numbers and @rinternals{FiguredBass} context prints them
as entered.  There is no conversion to pitches and no realizations of
the bass are played in the MIDI file.

Internally, the code produces markup texts.  You can use any of the
markup text properties to override formatting.  For example, the
vertical spacing of the figures may be set with @code{baseline-skip}.


@menu
* Entering figured bass::
* Displaying figured bass::
@end menu

@node Entering figured bass
@unnumberedsubsubsec Entering figured bass


In figures input mode, a group of bass figures is delimited by
@code{<} and @code{>}.  The duration is entered after the @code{>}
@example
<4 6>2
@end example
@lilypond[quote,ragged-right,fragment]
\new FiguredBass
\figuremode { <4 6>2 }
@end lilypond

Accidentals are added when you append @code{-}, @code{!}, and @code{+}
to the numbers.  A plus sign is added when you append @code{\+}, and
diminished fifths and sevenths can be obtained with @code{5/} and @code{7/}.

@example
<4- 6+ 7!>3 <5++> <3--> <7/> r <6\+ 5/>
@end example
@lilypond[quote,ragged-right,fragment]
\figures { <4- 6+ 7!>4 <5++> <3--> <7/> r <6\+ 5/> }
@end lilypond

Spaces may be inserted by using @code{_}.  Brackets are
introduced with @code{[} and @code{]}.  You can also include text
strings and text markups, see @ref{Text markup commands}.

@example
< [4 6] 8 [_! 12] >4 < 5 \markup @{ \number 6 \super (1) @} >
@end example
@lilypond[quote,ragged-right,fragment]
\new FiguredBass
\figuremode { < [4 6] 8 [_! 12] >4 < 5 \markup{ \tiny \number 6 \super (1)} > }
@end lilypond


It is also possible to use continuation lines for repeated figures,

@lilypond[verbatim,relative=1]
<<
  \new Staff {
    \clef bass
    c4 c c
  }
  \figures {
    \set useBassFigureExtenders = ##t
    <4 6>4 <3 6> <3 7>
  }
>>
@end lilypond

@noindent
In this case, the extender lines always replace existing figures.

The @code{FiguredBass} context doesn't pay attention to the actual
bass line.  As a consequence, you may have to insert extra figures to
get extender lines below all notes, and you may have to add @code{\!}
to avoid getting an extender line, e.g.

@lilypond[relative=1]
<<
  \new Voice
  \figures {
    \set useBassFigureExtenders = ##t
    <6 4->4. <6 4->16. <6 4->32 <5>8. r16 <6>8 <6\! 5->
  }
  {
    \clef bass
    f16. g32 f16. g32 f16. g32 f16. g32 f8. es16 d8 es
  }
>>
@end lilypond

When using continuation lines, common figures are always put in the
same vertical position.  When this is unwanted, you can insert a rest
with @code{r}.  The rest will clear any previous alignment.  For
example, you can write

@example
<4 6>8 r8
@end example

@noindent
instead of
@example
<4 6>4
@end example

Accidentals and plus signs can appear before or after the numbers,
depending on the @code{figuredBassAlterationDirection} and
@code{figuredBassPlusDirection}
properties

@lilypond
  \figures {
    <6\+> <5+> <6 4-> r
    \set figuredBassAlterationDirection = #1
    <6\+> <5+> <6 4-> r
    \set figuredBassPlusDirection = #1
    <6\+> <5+> <6 4-> r
    \set figuredBassAlterationDirection = #-1
    <6\+> <5+> <6 4-> r
  }
@end lilypond


Figured bass can also be added to @code{Staff} contexts
directly.  In this case, their vertical position is adjusted
automatically.

@lilypond[ragged-right,fragment,quote]
<<
  \new Staff = someUniqueName
  \relative c'' {
    c4 c'8 r8 c,4 c'
  }

  %% send to existing Staff.
  \context Staff = someUniqueName
  \figuremode {
    <4>4 <6 10>8 s8

    \set Staff.useBassFigureExtenders = ##t
    <4 6>4 <4 6>
  }
>>
@end lilypond

@c @predefined

@c @snippets

@seealso
@c Music Glossary:
@c @rglos{}.

@c Learning Manual:
@c @rlearning{}.

@c Notation Reference:
@c @ruser{}.

@c Application Usage:
@c @rprogram{}.

@c Installed Files:
@c @file{}.

@c Snippets:
@c @rlsr{}.

@c Internals Reference:
@c @rinternals{}.

@c @knownissues

@node Displaying figured bass
@unnumberedsubsubsec Displaying figured bass

Figured bass is displayed using the @code{FiguredBass} context.

@c @predefined

@c @snippets

@seealso
@c Music Glossary:
@c @rglos{}.

@c Learning Manual:
@c @rlearning{}.

@c Notation Reference:
@c @ruser{}.

@c Application Usage:
@c @rprogram{}.

@c Installed Files:
@c @file{}.

@c Snippets:
@c @rlsr{}.

Internals Reference:
@rinternals{NewBassFigure},
@rinternals{BassFigureAlignment},
@rinternals{BassFigureLine},
@rinternals{BassFigureBracket},
@rinternals{BassFigureContinuation},
@rinternals{FiguredBass}.

@knownissues

By default, this method produces figures above the notes.  To get
figures below the notes, use

@example
\override Staff.BassFigureAlignmentPositioning #'direction = #DOWN
@end example

When using figured bass above the staff with extender lines and
@code{implicitBassFigures} the lines may become swapped around.
Maintaining order consistently will be impossible when multiple figures
have overlapping extender lines.  To avoid this problem, please
use @code{stacking-dir} on @code{BassFigureAlignment}.


@seealso