Update from Carl.

[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 in chord mode, which recognizes some
traditional European chord naming conventions.  Chord names can also
be displayed.  In addition, figured bass notation can be displayed.

@menu
* Chord mode::                  
* Displaying chords::           
* old Modern chords::           
* Figured bass::                
@end menu


@node Chord mode
@subsection Chord mode

@cindex chord chords

Chord mode is used to enter chords using an indicator of the chord
structure, rather than the chord pitches.

@menu
* Chord mode overview::         
* Common chords::               
* Extended and altered chords::  
@end menu

@node Chord mode overview
@unnumberedsubsubsec Chord mode overview

@cindex chord names
@cindex chord mode

Chords can be entered as simultaneous music, as discussed in
@ref{Chorded notes}.

@c need to decide about @qq{FOO mode} or @emph{} or whatever.
Chords can also be entered in @qq{chord mode}, which is an input
mode that focuses on the structures of chords in traditional
European music, rather than on specific pitches.  This is
convenient for those who are familiar with using chord names to
describe chords.  More information on different input modes can be
found at @ref{Input modes}.

@lilypond[verbatim,quote,ragged-right,relative=1]
\chordmode { c1 g a g c }
@end lilypond

Chords entered using chord mode are music elements, and can be
transposed just like chords entered using simultaneous music.

@seealso

Music Glossary:
@rglos{chord}.

Notation Reference:
@ref{Chorded notes},
@ref{Input modes}.

Snippets:
@rlsr{Chords}

@node Common chords
@unnumberedsubsubsec Common chords

@cindex triads
@cindex seventh chords
@cindex root of chord
@cindex modifiers, in chords.
@cindex chord quality

Major triads are entered by including the root and an
optional duration:

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

@noindent
If no duration is entered, the duration of the previous
note (or chord) will be used.

Minor, augmented, and diminished triads are entered by placing
@code{:} and a quality modifier string after the duration:

@lilypond[verbatim,quote,ragged-right,relative=1]
\chordmode { c2:m f4:aug g4:dim }
@end lilypond

Seventh chords are created by adding the number 7 at the beginning
of the modifier string (for the dominant seventh chord) or after the
quality modifier (for the other named seventh chords).

@lilypond[quote,ragged-right,fragment,verbatim,relative=1]
\chordmode {
c1 |  c:7 | c:m7 | c:maj7 |
c:dim | c:dim7 | c:aug7 | c:maj |
}
@end lilypond

@funindex aug
@funindex dim
@funindex maj
@funindex m

The table belows shows the actions of the quality modifiers on
triads and seventh chords.

@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 7th step.  The
@code{7} following @code{maj} is optional.  Do NOT use this modifier
to create a major triad.

@end table

@seealso

Snippets:
@rlsr{Chords}

@node Extended and altered chords
@unnumberedsubsubsec Extended and altered chords

@cindex extended chords
@cindex altered chords

Chord structures of arbitrary complexity can be created in chord
mode.  The modifier string can be used to extend a 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 @code{:} 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.  If the
extent is not a third (e.g., 6), thirds are added up to the highest
third below the extent, and then the step of the extent is added.

@lilypond[quote,ragged-right,fragment,verbatim,relative=1]
\chordmode {
c4:2 c:3 c:4 c:5
c:6 c:7 c:8 c:9
c:10 c:11 c:12 c:13
}
@end lilypond

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

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

The largest possible value for the extent is 13.  Any larger value
is interpreted as 13.

@cindex additions, in chords

Individual steps can be added to a chord.  Additions follow the
extent and are prefixed by a dot (@code{.}).

@lilypond[quote,verbatim,fragment,relative=1]
\chordmode { c1:5.6 c:3.7.8 c:3.6.13 }
@end lilypond

Added steps can be as high as desired.

@lilypond[quote,verbatim,fragment,relative=1]
\chordmode { c4:5.15 c:5.20 c:5.25 c:5.30 }
@end lilypond

@cindex chord steps, altering

Added chord steps can be altered by suffixing a @code{-} or @code{+}
sign to the number.  To alter a step that is lower than the extent,
add it as an altered step.

@lilypond[quote,verbatim,fragment,relative=1]
\chordmode { c1:7+ c:5+.3- c:3-.5-.7- }
@end lilypond

@cindex removals, in chords

@funindex ^

A step to be removed from the chord  must come at the end of a
modifier string and be by @code{^}.  Only one removal with @code{^}
is allowed in a modifier string.

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

@funindex sus

The modifier @code{sus} can be added to the modifier string to
create suspended chords.  This removes the 3rd step from the chord.
Append either @code{2} or @code{4} to add the 2nd or 4th step to the
chord.@code{sus} is equivalent to @code{^3}; @code{sus4} is
equivalent to @code{.4^3}.

@lilypond[quote,ragged-right,fragment,verbatim]
\chordmode { c1:sus c:sus2 c:sus4 c:5.4^3 }
@end lilypond

It is possible to remove the 3rd step with @code{sus} and remove
another step with @code{^} in one modifier string.

@funindex /
@cindex chord inversions
@cindex bass note, for chords

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, relative=2]
\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

Snippets:
@rlsr{Chords}

@knownissues

Each step can only be present in a chord once.  The following
simply produces the augmented chord, since @code{5+} is
interpreted last.

@lilypond[quote,ragged-right,verbatim,fragment]
\chordmode { c1:5.5-.5+ }
@end lilypond

Only one step can be removed from a chord.  If a chord with multiple
removed steps is desired, it must be built through addition of
multiple steps.


@node Displaying chords
@subsection Displaying chords

Chords can be displayed by name, in addition to the standard display
as notes on a staff.

@menu
* Printing chord names::        
@end menu

@node Printing chord names
@unnumberedsubsubsec Printing chord names

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

LilyPond has support for printing chord names.  Chord names are
printed in a special context, called @rinternals{ChordNames}.

@lilypond[verbatim,quote,relative=1,ragged-right]
\new ChordNames \chordmode { c2 f4. g8 }
@end lilypond

To display both chord names and the notes of chords, use the
technique in @ref{Writing music in parallel}.

@lilypond[verbatim,quote,ragged-right]
myChords = \chordmode { c2 f4. g8 }
<<
\new ChordNames \myChords
\myChords
>>
@end lilypond

Chords can be entered as simultaneous notes or through the use of
chord mode.  The displayed chord name will be the same, regardless
of the mode of entry:

@lilypond[quote,ragged-right,verbatim]
twoWays = \relative c' {
  \chordmode { c2 f:sus4 }
  { <c e g>  <f bes c> }
}
<<
\new ChordNames \twoWays
\new Voice \twoWays
>>
@end lilypond


If repeats are used in the music, and the volta brackets are to be
dispayed above the chord names, @code{voltaOnThisStaff} must be set
to @code{##t}.  To add bar indications in the @code{ChordNames}
context, add @rinternals{Bar_engraver}.

@lilypond[ragged-right,verbatim]
\new ChordNames \with {
  \override BarLine #'bar-size = #4
  voltaOnThisStaff = ##t
  \consists "Bar_engraver"
}
\chordmode { \repeat volta 2 {
  f1:maj7 f:7 bes:7
  c:maj7
} \alternative {
  ees 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, relative=1]
\chords { c2 f4.:m g8:maj7 }
@end lilypond


@seealso

Music Glossary:
@rglos{chord}.


Notation Reference:
@ref{Writing music in parallel}.


Snippets:
@c @rlsr{Chords}.

Internals Reference:
@rinternals{ChordNames},
@rinternals{Volta_engraver},
@rinternals{Bar_engraver}.

@knownissues

Chords containing inversions or altered bass notes are not named
properly.

@ignore

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

@C TODO - this paragraph is moved here from an earlier section
@c and needs to be corrected.
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.

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
* Entering chord names::        
* Lead sheets::                 
* old Printing chord names::    
@end menu

@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 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 old Printing chord names
@subsubsection old 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