Documentation/user/chords.itely

   1 @c -*- coding: utf-8; mode: texinfo; -*-
   2 @ignore
   3     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
   4
   5     When revising a translation, copy the HEAD committish of the
   6     version that you are working on.  See TRANSLATION for details.
   7 @end ignore
   8
   9 @c \version "2.11.38"
  10
  11
  12 @node Chord notation
  13 @section Chord notation
  14
  15 Chords can be entered in chord mode, which recognizes some
  16 traditional European chord naming conventions.  Chord names can also
  17 be displayed.  In addition, figured bass notation can be displayed.
  18
  19 @menu
  20 * Chord mode::
  21 * Displaying chords::
  22 * old Modern chords::
  23 * Figured bass::
  24 @end menu
  25
  26
  27 @node Chord mode
  28 @subsection Chord mode
  29
  30 @cindex chord chords
  31
  32 Chord mode is used to enter chords using an indicator of the chord
  33 structure, rather than the chord pitches.
  34
  35 @menu
  36 * Chord mode overview::
  37 * Common chords::
  38 * Extended and altered chords::
  39 @end menu
  40
  41 @node Chord mode overview
  42 @unnumberedsubsubsec Chord mode overview
  43
  44 @cindex chord names
  45 @cindex chord mode
  46
  47 Chords can be entered as simultaneous music, as discussed in
  48 @ref{Chorded notes}.
  49
  50 Chords can also be entered in @qq{chord mode}, which is an input
  51 mode that focuses on the structures of chords in traditional
  52 European music, rather than on specific pitches.  This is
  53 convenient for those who are familiar with using chord names to
  54 describe chords.  More information on different input modes can be
  55 found at @ref{Input modes}.
  56
  57 @lilypond[verbatim,quote,ragged-right,relative=1]
  58 \chordmode { c1 g a g c }
  59 @end lilypond
  60
  61 Chords entered using chord mode are music elements, and can be
  62 transposed just like chords entered using simultaneous music.
  63
  64 @seealso
  65
  66 Music Glossary:
  67 @rglos{chord}.
  68
  69 Notation Reference:
  70 @ref{Chorded notes},
  71 @ref{Input modes}.
  72
  73 Snippets:
  74 @rlsr{Chords}
  75
  76 @node Common chords
  77 @unnumberedsubsubsec Common chords
  78
  79 @cindex triads
  80 @cindex seventh chords
  81 @cindex root of chord
  82 @cindex modifiers, in chords.
  83 @cindex chord quality
  84
  85 Major triads are entered by including the root and an
  86 optional duration:
  87
  88 @lilypond[verbatim,quote,relative=1,ragged-right]
  89 \chordmode { c2 f4 g }
  90 @end lilypond
  91
  92 Minor, augmented, and diminished triads are entered by placing
  93 @code{:} and a quality modifier string after the duration:
  94
  95 @lilypond[verbatim,quote,ragged-right,relative=1]
  96 \chordmode { c2:m f4:aug g:dim }
  97 @end lilypond
  98
  99 Seventh chords may be created:
 100
 101 @lilypond[quote,ragged-right,fragment,verbatim,relative=1]
 102 \chordmode {
 103   c1:7 c:m7 c:maj7 c:dim7 c:aug7
 104 }
 105 @end lilypond
 106
 107 @funindex aug
 108 @funindex dim
 109 @funindex maj
 110 @funindex m
 111
 112 The table belows shows the actions of the quality modifiers on
 113 triads and seventh chords.
 114
 115 @table @code
 116
 117 @item m
 118 The minor chord.  This modifier lowers the 3rd and (if present) the
 119 7th step.
 120
 121 @item dim
 122 The diminished chord.  This modifier lowers the 3rd, 5th and (if
 123 present) the 7th step.
 124
 125 @item aug
 126 The augmented chord.  This modifier raises the 5th step.
 127
 128 @item maj
 129 The major 7th chord.  This modifier adds a raised 7th step.  The
 130 @code{7} following @code{maj} is optional.  Do NOT use this modifier
 131 to create a major triad.
 132
 133 @end table
 134
 135 @seealso
 136
 137 Snippets:
 138 @rlsr{Chords}
 139
 140 @node Extended and altered chords
 141 @unnumberedsubsubsec Extended and altered chords
 142
 143 @cindex extended chords
 144 @cindex altered chords
 145
 146 Chord structures of arbitrary complexity can be created in chord
 147 mode.  The modifier string can be used to extend a chord, add or
 148 remove chord steps, raise or lower chord steps, and add a bass note
 149 or create an inversion.
 150
 151 The first number following the @code{:} is taken to be the extent
 152 of the chord.  The chord is constructed by sequentially adding
 153 thirds to the root until the specified number has been reached.
 154 If the extent is not a third (e.g., 6), thirds are added up to the
 155 highest third below the extent, and then the step of the extent is
 156 added.  The largest possible value for the extent is 13.  Any
 157 larger value is interpreted as 13.
 158
 159 @lilypond[quote,ragged-right,fragment,verbatim,relative=1]
 160 \chordmode {
 161 c:2 c:3 c:4 c:5
 162 c:6 c:7 c:8 c:9
 163 c:10 c:11 c:12 c:13
 164 }
 165 @end lilypond
 166
 167 Since an unaltered 11 does not sound good when combined with an
 168 unaltered 13, the 11 is removed from a @code{:13} chord (unless it
 169 is added explicitly).
 170
 171 @lilypond[quote,ragged-right,fragment,verbatim,relative=1]
 172 \chordmode { c1:13 c:13.11 c:m13 }
 173 @end lilypond
 174
 175 @cindex additions, in chords
 176
 177 Individual steps can be added to a chord.  Additions follow the
 178 extent and are prefixed by a dot (@code{.}).
 179
 180 @lilypond[quote,verbatim,fragment,relative=1]
 181 \chordmode { c1:5.6 c:3.7.8 c:3.6.13 }
 182 @end lilypond
 183
 184 Added steps can be as high as desired.
 185
 186 @lilypond[quote,verbatim,fragment,relative=1]
 187 \chordmode { c4:5.15 c:5.20 c:5.25 c:5.30 }
 188 @end lilypond
 189
 190 @cindex chord steps, altering
 191
 192 Added chord steps can be altered by suffixing a @code{-} or @code{+}
 193 sign to the number.  To alter a step that is lower than the extent,
 194 add it as an altered step.
 195
 196 @lilypond[quote,verbatim,fragment,relative=1]
 197 \chordmode { c1:7+ c:5+.3- c:3-.5-.7- }
 198 @end lilypond
 199
 200 @cindex removals, in chords
 201
 202 @funindex ^
 203
 204 A step to be removed from the chord  must come at the end of a
 205 modifier string and be by @code{^}.  Only one removal with @code{^}
 206 is allowed in a modifier string.
 207
 208 @lilypond[quote,verbatim,fragment,relative=1]
 209 \chordmode { c1^3 c:7^5 c:9^3.5 }
 210 @end lilypond
 211
 212 @funindex sus
 213
 214 The modifier @code{sus} can be added to the modifier string to
 215 create suspended chords.  This removes the 3rd step from the chord.
 216 Append either @code{2} or @code{4} to add the 2nd or 4th step to the
 217 chord.@code{sus} is equivalent to @code{^3}; @code{sus4} is
 218 equivalent to @code{.4^3}.
 219
 220 @lilypond[quote,ragged-right,fragment,verbatim]
 221 \chordmode { c1:sus c:sus2 c:sus4 c:5.4^3 }
 222 @end lilypond
 223
 224 It is possible to remove the 3rd step with @code{sus} and remove
 225 another step with @code{^} in one modifier string.
 226
 227 @funindex /
 228 @cindex chord inversions
 229 @cindex bass note, for chords
 230
 231 Inversions (putting a pitch other than the root on the bottom of the
 232 chord) and added bass notes can be specified by appending
 233 @code{/}@var{pitch} to the chord.
 234
 235 @lilypond[quote,ragged-right,fragment,verbatim, relative=2]
 236 \chordmode { c1 c/g c/f }
 237 @end lilypond
 238
 239 @funindex /+
 240
 241 A bass note that is part of the chord can be added, instead of
 242 moved as part of an inversion, by using @code{/+}@var{pitch}.
 243
 244 @lilypond[quote,ragged-right,fragment,verbatim]
 245 \chordmode { c1 c/+g c/+f }
 246 @end lilypond
 247
 248 @seealso
 249
 250 Snippets:
 251 @rlsr{Chords}
 252
 253 @knownissues
 254
 255 Each step can only be present in a chord once.  The following
 256 simply produces the augmented chord, since @code{5+} is
 257 interpreted last.
 258
 259 @lilypond[quote,ragged-right,verbatim,fragment]
 260 \chordmode { c1:5.5-.5+ }
 261 @end lilypond
 262
 263 Only one step can be removed from a chord.  If a chord with multiple
 264 removed steps is desired, it must be built through addition of
 265 multiple steps.
 266
 267
 268 @node Displaying chords
 269 @subsection Displaying chords
 270
 271 Chords can be displayed by name, in addition to the standard display
 272 as notes on a staff.
 273
 274 @menu
 275 * Printing chord names::
 276 * Customizing chord names::
 277 * Lead sheets::
 278 @end menu
 279
 280 @node Printing chord names
 281 @unnumberedsubsubsec Printing chord names
 282
 283 @cindex printing chord names
 284 @cindex chord names
 285 @cindex chords
 286
 287 LilyPond has support for printing chord names.  Chord names are
 288 printed in a special context, called @rinternals{ChordNames}.
 289
 290 @lilypond[verbatim,quote,relative=1,ragged-right]
 291 \new ChordNames \chordmode { c2 f4. g8 }
 292 @end lilypond
 293
 294 To display both chord names and the notes of chords, use the
 295 technique in @ref{Writing music in parallel}.
 296
 297 @lilypond[verbatim,quote,ragged-right]
 298 myChords = \chordmode { c2 f4. g8 }
 299 <<
 300 \new ChordNames \myChords
 301 \myChords
 302 >>
 303 @end lilypond
 304
 305 Chords can be entered as simultaneous notes or through the use of
 306 chord mode.  The displayed chord name will be the same, regardless
 307 of the mode of entry:
 308
 309 @lilypond[quote,ragged-right,verbatim]
 310 twoWays = \relative c' {
 311   \chordmode { c2 f:sus4 }
 312   { <c e g>  <f bes c> }
 313 }
 314 <<
 315 \new ChordNames \twoWays
 316 \new Voice \twoWays
 317 >>
 318 @end lilypond
 319
 320
 321 If repeats are used in the music, and the volta brackets are to be
 322 dispayed above the chord names, @code{voltaOnThisStaff} must be set
 323 to @code{##t}.  To add bar indications in the @code{ChordNames}
 324 context, add @rinternals{Bar_engraver}.
 325
 326 @lilypond[ragged-right,verbatim]
 327 \new ChordNames \with {
 328   \override BarLine #'bar-size = #4
 329   voltaOnThisStaff = ##t
 330   \consists "Bar_engraver"
 331 }
 332 \chordmode { \repeat volta 2 {
 333   f1:maj7 f:7 bes:7
 334   c:maj7
 335 } \alternative {
 336   ees e
 337 }
 338 }
 339 @end lilypond
 340
 341 @code{\chords} is a shortcut method used to change the input mode to
 342 @code{\chordmode} and create a @code{ChordNames} context, with the
 343 following result:
 344
 345 @lilypond[verbatim,quote,ragged-right, relative=1]
 346 \chords { c2 f4.:m g8:maj7 }
 347 @end lilypond
 348
 349
 350 @seealso
 351
 352 Music Glossary:
 353 @rglos{chord}.
 354
 355
 356 Notation Reference:
 357 @ref{Writing music in parallel}.
 358
 359
 360 Snippets:
 361 @c @rlsr{Chords}.
 362
 363 Internals Reference:
 364 @rinternals{ChordNames},
 365 @rinternals{Volta_engraver},
 366 @rinternals{Bar_engraver}.
 367
 368 @knownissues
 369
 370 Chords containing inversions or altered bass notes are not named
 371 properly.
 372
 373
 374 @node Customizing chord names
 375 @unnumberedsubsubsec Customizing chord names
 376
 377 @cindex customizing chord names
 378
 379 There is no unique system for naming chords.  Different musical
 380 traditions use different names for the same set of chords.  There
 381 are also different symbols displayed for a given chord name.   The
 382 names and symbols displayed for chord names are customizable.
 383
 384 The default chord name layout is a system for Jazz music, proposed
 385 by Klaus Ignatzek (see @ref{Literature list}).  There are also two
 386 other chord name schemes implemented: an alternate Jazz chord
 387 notation, and a systematic scheme called Banter chords.  The
 388 alternate Jazz notation is also shown on the chart in @ref{Chord
 389 name chart}.
 390
 391 In addition to the different naming systems, different note names
 392 are used for the root in different languages.  The predefined
 393 variables @code{\germanChords}, @code{\semiGermanChords},
 394 @code{\italianChords} and @code{\frenchChords} set these variables.
 395 The effect is demonstrated here:
 396
 397 @lilypondfile[ragged-right]{chord-names-languages.ly}
 398
 399 @c TODO - this paragraph is moved here from an earlier section
 400 @c and needs to be corrected.
 401 This example also shows that the chord printing routines cannot
 402 correctly identify the root of a chord if it has been entered using
 403 @code{< .. >} instead of named chord entry.  Therefore, the sixth
 404 chord (@code{f bes d}) is not interpreted as an inversion.   In
 405 contrast, the third chord, which contains the same notes as the sixth
 406 chord, is correctly identified because it was entered in the named
 407 chord mode.
 408
 409 If none of the default settings give the desired output, the chord
 410 name display can be tuned through the following properties.
 411
 412 @ignore
 413 @c TODO Generate snippet based on the following
 414 @c      and add explanation -td
 415
 416 @funindex chordNameExceptions
 417
 418 @table @code
 419 @item chordNameExceptions
 420
 421 contains a list of markups used to follow the root note name based
 422 on the pitches in the chord.  Creating the list requires four
 423 steps.
 424
 425 The first step is to define sequential music that has the chords to
 426 be named with the desired markup (except for the root name) attached
 427 to the chord:
 428
 429 @example
 430 FGGChordNames = @{
 431   <c e g b d'>1-\markup @{ \super "maj9" @}
 432   <c e g a d'>1-\markup @{ \super "6(add9)" @}
 433 @}
 434 @end example
 435
 436 The second step is to convert the music from the first step to an
 437 exceptions list:
 438
 439 @example
 440 FGGExceptions = #(sequential-music-to-chord-exceptions
 441 FGGChordNames #t)
 442 @end example
 443
 444 The third step is to append the default exceptions list (in this
 445 case, the Ignatzek exceptions) to the newly-defined exceptions list:
 446
 447 @example
 448 chExceptions = #(append FGGExceptions ignatzekExceptions)
 449 @end example
 450
 451 The final step is to set @code{chordNameExceptions} to the
 452 newly-created exceptions list:
 453
 454 @example
 455 \set chordNameExceptions = #chExceptions
 456 @end example
 457
 458 The entire process is illustrated below:
 459
 460 @lilypond[quote,ragged-right,verbatim]
 461 FGGChordNames = {
 462   <c e g b d'>1-\markup { \super "maj9" }
 463   <c e g a d'>1-\markup { \super "6(add9)" }
 464 }
 465 FGGExceptions = #(sequential-music-to-chord-exceptions
 466 FGGChordNames #t)
 467 chExceptions = #(append FGGChordNames
 468  ignatzekExceptions)
 469
 470 chordStuff = \chordmode
 471 {
 472 % standard names
 473 g1:maj9
 474 g1:6.9
 475 % names with FGG's custom exceptions
 476 \set chordNameExceptions = #chExceptions
 477 g1:maj9
 478 g1:6.9
 479 }
 480
 481 \score
 482 {
 483 \new ChordNames \chordStuff
 484 }
 485 @end lilypond
 486
 487
 488 @funindex majorSevenSymbol
 489
 490 @item majorSevenSymbol
 491
 492 This property contains the markup object used as part of the
 493 printed chord name to identify a major 7 chord.  Predefined
 494 options are @code{whiteTriangleMarkup} and
 495 @code{blackTriangleMarkup}.
 496
 497 @funindex chordNameSeparator
 498 @item chordNameSeparator
 499
 500 Different parts of a chord name are normally separated by a slash.
 501 By setting @code{chordNameSeparator}, you can use any desired
 502 markup for a separator, e.g.,
 503
 504 @lilypond[quote,ragged-right,fragment,verbatim]
 505 \new ChordNames \chordmode {
 506   c:7sus4
 507   \set chordNameSeparator
 508     = \markup { \typewriter "|" }
 509   c:7sus4
 510 }
 511 @end lilypond
 512
 513 @funindex chordRootNamer
 514 @item chordRootNamer
 515
 516 The chord name is usually printed as a letter for the root with an
 517 optional alteration.  The transformation from pitch to letter is
 518 done by this function.  Special note names (for example, the
 519 German @q{H} for a B-chord) can be produced by storing a new
 520 function in this property.
 521
 522 @funindex chordNoteNamer
 523 @item chordNoteNamer
 524
 525 When the chord name contains an additional pitch besides the root
 526 (e.g., an added bass note), this function is used to print the
 527 additional pitch.  By default the pitch is printed using
 528 @code{chordRootNamer}.  The @code{chordNoteNamer} property can be
 529 set to a specialized function to change this behavior.  For
 530 example, the bass note can be printed in lower case.
 531
 532 @funindex chordPrefixSpacer
 533 @item chordPrefixSpacer
 534
 535 The @q{m} for minor chords is usually printed immediately to the
 536 right of the root of the chord.  By setting
 537 @code{chordPrefixSpacer}, you can fix a spacer between the root
 538 and @q{m}.  The spacer is not used when the root is altered.
 539
 540 @end table
 541 @end ignore
 542
 543
 544
 545 @cindex Banter
 546 @cindex jazz chords
 547 @cindex chords, jazz
 548
 549 @predefined
 550
 551 @funindex major seven symbols
 552 @code{\whiteTriangleMarkup}
 553 @code{\blackTriangleMarkup}
 554 @funindex \germanChords
 555 @code{\germanChords},
 556 @funindex \semiGermanChords
 557 @code{\semiGermanChords},
 558 @funindex \italianChords
 559 @code{\italianChords},
 560 @funindex \frenchChords
 561 @code{\frenchChords}.
 562
 563
 564 @snippets
 565 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 566 {chord-names-jazz.ly}
 567
 568 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 569 {chord-name-exceptions.ly}
 570 @cindex exceptions, chord names.
 571
 572 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 573 {chord-name-major7.ly}
 574
 575 @seealso
 576 @c Music Glossary:
 577 @c @rglos{}.
 578
 579 @c Learning Manual:
 580 @c @rlearning{}.
 581
 582 @c Notation Reference:
 583 @c @ruser{}.
 584
 585 @c Application Usage:
 586 @c @rprogram{}.
 587
 588 Installed Files:
 589 @file{scm/@/chords@/-ignatzek@/.scm},
 590 @file{scm/@/chord@/-entry@/.scm},
 591 @file{ly/@/chord@/-modifier@/-init@/.ly}.
 592
 593 @c Snippets: @c @rlsr{}.
 594
 595 @c Internals Reference:
 596 @c @rinternals{}.
 597
 598 @knownissues
 599
 600 When chords are entered with the @code{< .. >} syntax, the root and
 601 any added bass notes are not identified.  In this  case, chord names
 602 are determined solely from the list of pitches.  This may result in
 603 strange chord names
 604
 605 @node Lead sheets
 606 @unnumberedsubsubsec Lead sheets
 607
 608 @cindex lead sheet
 609
 610 For lead sheets, chords are not printed on staves, but as names on a
 611 line for themselves.  This is achieved by using a @code{ChordNames}
 612 context simultaneously with the @code{Staff} context.  The
 613 @code{\chords} keyword can be used as a shortcut for @code{\new
 614 ChordNames \chordmode}.
 615
 616 When put together, chord names, a melody, and lyrics form a lead
 617 sheet:
 618
 619 @lilypond[verbatim,quote,ragged-right]
 620 <<
 621   \chords { c2 g:sus4 f e }
 622   \relative c'' {
 623     a4 e c8 e r4
 624     b2 c4( d)
 625   }
 626   \addlyrics { One day this shall be free __ }
 627 >>
 628 @end lilypond
 629
 630 @c @predefined
 631
 632 @c @snippets
 633
 634 @seealso
 635 @c Music Glossary:
 636 @c @rglos{}.
 637
 638 @c Learning Manual:
 639 @c @rlearning{}.
 640
 641 @c Notation Reference:
 642 @c @ruser{}.
 643
 644 @c Application Usage:
 645 @c @rprogram{}.
 646
 647 @c Installed Files:
 648 @c @file{}.
 649
 650 @c Snippets:
 651 @c @rlsr{}.
 652
 653 @c Internals Reference:
 654 @c @rinternals{}.
 655
 656 @c @knownissues
 657
 658
 659
 660
 661 @node old Modern chords
 662 @subsection old Modern chords
 663
 664 @menu
 665 * Entering chord names::
 666 * old Lead sheets::
 667 * old Printing chord names::
 668 @end menu
 669
 670 @node Entering chord names
 671 @subsubsection Entering chord names
 672 @cindex chord names
 673
 674 LilyPond has support for printing chord names.  Chords may be entered
 675 in musical chord notation, i.e., @code{< .. >}, but they can also be
 676 entered by name.  Internally, the chords are represented as a set of
 677 pitches, so they can be transposed
 678
 679
 680 @lilypond[quote,ragged-right,verbatim,ragged-right]
 681 twoWays = \transpose c c' {
 682   \chordmode {
 683     c1 f:sus4 bes/f
 684   }
 685   <c e g>
 686   <f bes c'>
 687   <f bes d'>
 688 }
 689
 690 << \new ChordNames \twoWays
 691    \new Voice \twoWays >>
 692 @end lilypond
 693
 694 This example also shows that the chord printing routines do not try to
 695 be intelligent.  The last chord (@code{f bes d}) is not interpreted as
 696 an inversion.
 697
 698 Note that the duration of chords must be specified outside the
 699 @code{<>}.
 700
 701 @example
 702 <c e g>2
 703 @end example
 704
 705 @c TODO Generate snippet based on the following
 706 @c      and add explanation -td
 707
 708 Custom chord names may be generated:
 709
 710 @lilypond[quote,ragged-right,verbatim,ragged-right]
 711 FGGChordNames = {
 712   <c e g b d'>1-\markup { \super "maj9" }
 713   <c e g a d'>1-\markup { \super "6(add9)" }
 714 }
 715 chExceptions = #(append
 716 (sequential-music-to-chord-exceptions
 717 FGGChordNames #t) ignatzekExceptions)
 718
 719 chordStuff = \chordmode
 720 {
 721 % standard names
 722 g1:maj9
 723 g1:6.9
 724 % names with FGG's custom exceptions
 725 \set chordNameExceptions = #chExceptions
 726 g1:maj9
 727 g1:6.9
 728 }
 729
 730 \score
 731 {
 732 \new ChordNames \chordStuff
 733 }
 734 @end lilypond
 735
 736
 737
 738 @node old Lead sheets
 739 @subsubsection old Lead sheets
 740
 741 @cindex lead sheet
 742
 743 For lead sheets, chords are not printed on staves, but as names on
 744 a line for themselves.  This is achieved by using @code{\chords}
 745 instead of @code{\chordmode}.
 746
 747 When put together, chord names, lyrics and a melody form a lead
 748 sheet,
 749
 750 @lilypond[verbatim,quote,ragged-right]
 751 <<
 752   \chords { c2 g:sus4 f e }
 753   \relative c'' {
 754     a4 e c8 e r4
 755     b2 c4( d)
 756   }
 757   \addlyrics { One day this shall be free __ }
 758 >>
 759 @end lilypond
 760
 761
 762
 763 @node old Printing chord names
 764 @subsubsection old Printing chord names
 765
 766 @cindex printing chord names
 767 @cindex chord names
 768 @cindex chords
 769
 770 For displaying printed chord names, use the @rinternals{ChordNames} context.
 771 The chords may be entered either using the notation
 772 described above, or directly using @code{<} and @code{>}
 773
 774 @lilypond[quote,verbatim,ragged-right]
 775 harmonies = {
 776   \chordmode {a1 b c} <d' f' a'> <e' g' b'>
 777 }
 778 <<
 779   \new ChordNames \harmonies
 780   \new Staff \harmonies
 781 >>
 782 @end lilypond
 783
 784 You can make the chord changes stand out by setting
 785 @rinternals{ChordNames}.@code{chordChanges} to true.  This will only
 786 display chord names when there is a change in the chords scheme and at
 787 the start of a new line
 788
 789 @lilypond[quote,verbatim,ragged-right]
 790 harmonies = \chordmode {
 791   c1:m c:m \break c:m c:m d
 792 }
 793 <<
 794   \new ChordNames {
 795     \set chordChanges = ##t
 796     \harmonies }
 797   \new Staff \transpose c c' \harmonies
 798 >>
 799 @end lilypond
 800
 801 The previous examples all show chords over a staff.  This is not
 802 necessary.  Chords may also be printed separately.  It may be necessary
 803 to add @rinternals{Volta_engraver} and @rinternals{Bar_engraver}
 804 for showing repeats.
 805
 806 @lilypond[ragged-right,verbatim]
 807 \new ChordNames \with {
 808   \override BarLine #'bar-size = #4
 809   \consists Bar_engraver
 810   \consists "Volta_engraver"
 811 }
 812 \chordmode { \repeat volta 2 {
 813   f1:maj7 f:7 bes:7
 814   c:maj7
 815 } \alternative {
 816   es e
 817 }
 818 }
 819 @end lilypond
 820
 821
 822 The default chord name layout is a system for Jazz music, proposed by
 823 Klaus Ignatzek (see @ref{Literature list}).  It can be tuned through the
 824 following properties
 825
 826 @table @code
 827 @funindex chordNameExceptions
 828 @item chordNameExceptions
 829 This is a list that contains the chords that have special formatting.
 830
 831 The exceptions list should be encoded as
 832 @example
 833 @{ <c f g bes>1 \markup @{ \super "7" "wahh" @} @}
 834 @end example
 835
 836 To get this information into @code{chordNameExceptions} takes a little
 837 maneuvering.  The following code transforms @code{chExceptionMusic}
 838 (which is a sequential music) into a list of exceptions.
 839 @example
 840 (sequential-music-to-chord-exceptions chExceptionMusic #t)
 841 @end example
 842 Then,
 843 @example
 844 (append
 845  (sequential-music-to-chord-exceptions chExceptionMusic #t)
 846  ignatzekExceptions)
 847 @end example
 848 adds the new exceptions to the default ones, which are defined in
 849 @file{ly/@/chord@/-modifier@/-init@/.ly}.
 850
 851 For an example of tuning this property, see also
 852 @c @lsr{chords,chord@/-name@/-exceptions@/.ly}
 853 @cindex exceptions, chord names.
 854
 855
 856 @funindex majorSevenSymbol
 857 @item majorSevenSymbol
 858 This property contains the markup object used for the 7th step, when
 859 it is major.  Predefined options are @code{whiteTriangleMarkup} and
 860 @code{blackTriangleMarkup}.  See
 861 @c @lsr{chords,chord@/-name@/-major7@/.ly} for an example.
 862
 863 @funindex chordNameSeparator
 864 @item chordNameSeparator
 865 Different parts of a chord name are normally separated by a
 866 slash.  By setting @code{chordNameSeparator}, you can specify other
 867 separators, e.g.,
 868 @lilypond[quote,ragged-right,fragment,verbatim]
 869 \new ChordNames \chordmode {
 870   c:7sus4
 871   \set chordNameSeparator
 872     = \markup { \typewriter "|" }
 873   c:7sus4
 874 }
 875 @end lilypond
 876
 877 @funindex chordRootNamer
 878 @item chordRootNamer
 879 The root of a chord is usually printed as a letter with an optional
 880 alteration.  The transformation from pitch to letter is done by this
 881 function.  Special note names (for example, the German @q{H} for a
 882 B-chord) can be produced by storing a new function in this property.
 883
 884 @funindex chordNoteNamer
 885 @item chordNoteNamer
 886 The default is to print single pitch, e.g., the bass note, using the
 887 @code{chordRootNamer}.  The @code{chordNoteNamer} property can be set
 888 to a specialized function to change this behavior.  For example, the
 889 base can be printed in lower case.
 890
 891 @funindex chordPrefixSpacer
 892 @item chordPrefixSpacer
 893 The @q{m} for minor chords is usually printed right after the root of
 894 the chord.  By setting @code{chordPrefixSpacer}, you can fix a spacer
 895 between the root and @q{m}.  The spacer is not used when the root
 896 is altered.
 897
 898 @end table
 899
 900 The predefined variables @code{\germanChords},
 901 @code{\semiGermanChords}, @code{\italianChords} and @code{\frenchChords}
 902 set these variables.  The effect is
 903 demonstrated here,
 904
 905 @lilypondfile[ragged-right]{chord-names-languages.ly}
 906
 907 There are also two other chord name schemes implemented: an alternate
 908 Jazz chord notation, and a systematic scheme called Banter chords.  The
 909 alternate Jazz notation is also shown on the chart in @ref{Chord name
 910 chart}.  Turning on these styles is demonstrated in
 911 @c @lsr{chords,chord-names-jazz.ly}.
 912
 913 @cindex Banter
 914 @cindex jazz chords
 915 @cindex chords, jazz
 916
 917
 918 @predefined
 919
 920 @funindex \germanChords
 921 @code{\germanChords},
 922 @funindex \semiGermanChords
 923 @code{\semiGermanChords}.
 924 @funindex \italianChords
 925 @code{\italianChords}.
 926 @funindex \frenchChords
 927 @code{\frenchChords}.
 928
 929
 930
 931
 932 @seealso
 933
 934 Examples:
 935
 936 Init files: @file{scm/@/chords@/-ignatzek@/.scm}, and
 937 @file{scm/@/chord@/-entry@/.scm}.
 938
 939
 940 @knownissues
 941
 942 Chord names are determined solely from the list of pitches.  Chord
 943 inversions are not identified, and neither are added bass notes.  This
 944 may result in strange chord names when chords are entered with the
 945 @code{< .. >} syntax.
 946
 947
 948 @node Figured bass
 949 @subsection Figured bass
 950
 951 @menu
 952 * Introduction to figured bass::
 953 * Entering figured bass::
 954 * Displaying figured bass::
 955 @end menu
 956
 957 @node Introduction to figured bass
 958 @subsubsection Introduction to figured bass
 959
 960 @cindex Basso continuo
 961
 962 @c TODO: musicological blurb about FB
 963
 964 LilyPond has support for figured bass
 965
 966 @lilypond[quote,ragged-right,verbatim,fragment]
 967 <<
 968   \new Voice { \clef bass dis4 c d ais g fis}
 969   \new FiguredBass \figuremode {
 970     < 6 >4 < 7\+ >8 < 6+ [_!] >
 971     < 6 >4 <6 5 [3+] >
 972     < _ >4 < 6 5/>4
 973   }
 974 >>
 975 @end lilypond
 976
 977 The support for figured bass consists of two parts: there is an
 978 input mode, introduced by @code{\figuremode}, where you can enter
 979 bass figures as numbers, and there is a context named
 980 @rinternals{FiguredBass} that takes care of making
 981 @rinternals{BassFigure} objects.
 982
 983 Although the support for figured bass may superficially resemble chord
 984 support, it is much simpler.  The @code{\figuremode} mode simply
 985 stores the numbers and @rinternals{FiguredBass} context prints them
 986 as entered.  There is no conversion to pitches and no realizations of
 987 the bass are played in the MIDI file.
 988
 989 Internally, the code produces markup texts.  You can use any of the
 990 markup text properties to override formatting.  For example, the
 991 vertical spacing of the figures may be set with @code{baseline-skip}.
 992
 993
 994 @menu
 995 * Entering figured bass::
 996 * Displaying figured bass::
 997 @end menu
 998
 999 @node Entering figured bass
1000 @unnumberedsubsubsec Entering figured bass
1001
1002
1003 In figures input mode, a group of bass figures is delimited by
1004 @code{<} and @code{>}.  The duration is entered after the @code{>}
1005 @example
1006 <4 6>2
1007 @end example
1008 @lilypond[quote,ragged-right,fragment]
1009 \new FiguredBass
1010 \figuremode { <4 6>2 }
1011 @end lilypond
1012
1013 Accidentals are added when you append @code{-}, @code{!}, and @code{+}
1014 to the numbers.  A plus sign is added when you append @code{\+}, and
1015 diminished fifths and sevenths can be obtained with @code{5/} and @code{7/}.
1016
1017 @example
1018 <4- 6+ 7!>3 <5++> <3--> <7/> r <6\+ 5/>
1019 @end example
1020 @lilypond[quote,ragged-right,fragment]
1021 \figures { <4- 6+ 7!>4 <5++> <3--> <7/> r <6\+ 5/> }
1022 @end lilypond
1023
1024 Spaces may be inserted by using @code{_}.  Brackets are
1025 introduced with @code{[} and @code{]}.  You can also include text
1026 strings and text markups, see @ref{Text markup commands}.
1027
1028 @example
1029 < [4 6] 8 [_! 12] >4 < 5 \markup @{ \number 6 \super (1) @} >
1030 @end example
1031 @lilypond[quote,ragged-right,fragment]
1032 \new FiguredBass
1033 \figuremode { < [4 6] 8 [_! 12] >4 < 5 \markup{ \tiny \number 6 \super (1)} > }
1034 @end lilypond
1035
1036
1037 It is also possible to use continuation lines for repeated figures,
1038
1039 @lilypond[verbatim,relative=1]
1040 <<
1041   \new Staff {
1042     \clef bass
1043     c4 c c
1044   }
1045   \figures {
1046     \set useBassFigureExtenders = ##t
1047     <4 6>4 <3 6> <3 7>
1048   }
1049 >>
1050 @end lilypond
1051
1052 @noindent
1053 In this case, the extender lines always replace existing figures.
1054
1055 The @code{FiguredBass} context doesn't pay attention to the actual
1056 bass line.  As a consequence, you may have to insert extra figures to
1057 get extender lines below all notes, and you may have to add @code{\!}
1058 to avoid getting an extender line, e.g.
1059
1060 @lilypond[relative=1]
1061 <<
1062   \new Voice
1063   \figures {
1064     \set useBassFigureExtenders = ##t
1065     <6 4->4. <6 4->16. <6 4->32 <5>8. r16 <6>8 <6\! 5->
1066   }
1067   {
1068     \clef bass
1069     f16. g32 f16. g32 f16. g32 f16. g32 f8. es16 d8 es
1070   }
1071 >>
1072 @end lilypond
1073
1074 When using continuation lines, common figures are always put in the
1075 same vertical position.  When this is unwanted, you can insert a rest
1076 with @code{r}.  The rest will clear any previous alignment.  For
1077 example, you can write
1078
1079 @example
1080 <4 6>8 r8
1081 @end example
1082
1083 @noindent
1084 instead of
1085 @example
1086 <4 6>4
1087 @end example
1088
1089 Accidentals and plus signs can appear before or after the numbers,
1090 depending on the @code{figuredBassAlterationDirection} and
1091 @code{figuredBassPlusDirection}
1092 properties
1093
1094 @lilypond
1095   \figures {
1096     <6\+> <5+> <6 4-> r
1097     \set figuredBassAlterationDirection = #1
1098     <6\+> <5+> <6 4-> r
1099     \set figuredBassPlusDirection = #1
1100     <6\+> <5+> <6 4-> r
1101     \set figuredBassAlterationDirection = #-1
1102     <6\+> <5+> <6 4-> r
1103   }
1104 @end lilypond
1105
1106
1107 Figured bass can also be added to @code{Staff} contexts
1108 directly.  In this case, their vertical position is adjusted
1109 automatically.
1110
1111 @lilypond[ragged-right,fragment,quote]
1112 <<
1113   \new Staff = someUniqueName
1114   \relative c'' {
1115     c4 c'8 r8 c,4 c'
1116   }
1117
1118   %% send to existing Staff.
1119   \context Staff = someUniqueName
1120   \figuremode {
1121     <4>4 <6 10>8 s8
1122
1123     \set Staff.useBassFigureExtenders = ##t
1124     <4 6>4 <4 6>
1125   }
1126 >>
1127 @end lilypond
1128
1129 @c @predefined
1130
1131 @c @snippets
1132
1133 @seealso
1134 @c Music Glossary:
1135 @c @rglos{}.
1136
1137 @c Learning Manual:
1138 @c @rlearning{}.
1139
1140 @c Notation Reference:
1141 @c @ruser{}.
1142
1143 @c Application Usage:
1144 @c @rprogram{}.
1145
1146 @c Installed Files:
1147 @c @file{}.
1148
1149 @c Snippets:
1150 @c @rlsr{}.
1151
1152 @c Internals Reference:
1153 @c @rinternals{}.
1154
1155 @c @knownissues
1156
1157 @node Displaying figured bass
1158 @unnumberedsubsubsec Displaying figured bass
1159
1160 Figured bass is displayed using the @code{FiguredBass} context.
1161
1162 @c @predefined
1163
1164 @c @snippets
1165
1166 @seealso
1167 @c Music Glossary:
1168 @c @rglos{}.
1169
1170 @c Learning Manual:
1171 @c @rlearning{}.
1172
1173 @c Notation Reference:
1174 @c @ruser{}.
1175
1176 @c Application Usage:
1177 @c @rprogram{}.
1178
1179 @c Installed Files:
1180 @c @file{}.
1181
1182 @c Snippets:
1183 @c @rlsr{}.
1184
1185 Internals Reference:
1186 @rinternals{NewBassFigure},
1187 @rinternals{BassFigureAlignment},
1188 @rinternals{BassFigureLine},
1189 @rinternals{BassFigureBracket},
1190 @rinternals{BassFigureContinuation},
1191 @rinternals{FiguredBass}.
1192
1193 @knownissues
1194
1195 By default, this method produces figures above the notes.  To get
1196 figures below the notes, use
1197
1198 @example
1199 \override Staff.BassFigureAlignmentPositioning #'direction = #DOWN
1200 @end example
1201
1202 When using figured bass above the staff with extender lines and
1203 @code{implicitBassFigures} the lines may become swapped around.
1204 Maintaining order consistently will be impossible when multiple figures
1205 have overlapping extender lines.  To avoid this problem, please
1206 use @code{stacking-dir} on @code{BassFigureAlignment}.
1207
1208
1209 @seealso