Documentation/user/fretted-strings.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.53"
  10
  11 @node Fretted string instruments
  12 @section Fretted string instruments
  13
  14 @lilypondfile[quote]{fretted-headword.ly}
  15
  16 This section discusses several aspects of music notation that are unique
  17 to fretted string instruments.
  18
  19 @cindex tablature
  20 @cindex guitar tablature
  21
  22 @menu
  23 * Common notation for fretted strings::
  24 * Guitar::
  25 * Banjo::
  26 @end menu
  27
  28 @node Common notation for fretted strings
  29 @subsection Common notation for fretted strings
  30
  31 This section discusses common notation that is unique
  32 to fretted string instruments.
  33
  34 @menu
  35 * References for fretted strings::
  36 * String number indications::
  37 * Default tablatures::
  38 * Custom tablatures::
  39 * Fret diagram markups::
  40 * Predefined fret diagrams::
  41 * Automatic fret diagrams::
  42 * Right-hand fingerings::
  43 @end menu
  44
  45 @node References for fretted strings
  46 @subsubsection References for fretted strings
  47
  48 Music for fretted string instruments is normally notated on
  49 a single staff, either in traditional music notation or in
  50 tablature.  Sometimes the two types are combined, and it is
  51 especially common in popular music to use chord diagrams above
  52 a staff of traditional notation.  The guitar and the banjo are
  53 transposing instruments, sounding an octave lower than written.
  54 Scores for these instruments should use the @code{"treble_8"} clef.
  55 Some other elements pertinent to fretted string instruments
  56 are covered elsewhere:
  57
  58 @itemize
  59 @item Fingerings are indicated with @ref{Fingering instructions}.
  60
  61 @item Instructions for @notation{Laissez vibrer} ties
  62 as well as ties on arpeggios and tremolos is described in
  63 @ref{Ties}.
  64
  65 @item Instructions on handling multiple voices is described
  66 in @ref{Collision resolution}.
  67
  68 @end itemize
  69
  70 @seealso
  71
  72 Notation Reference:
  73 @ref{Instrument names},
  74 @ref{Writing music in parallel},
  75 @ref{Fingering instructions},
  76 @ref{Ties},
  77 @ref{Arpeggio},
  78 @ref{List of articulations},
  79 @ref{Clef}.
  80
  81 @node String number indications
  82 @subsubsection String number indications
  83
  84 @cindex String numbers
  85
  86 The string on which a note should be played may be indicated by
  87 appending @code{\@var{number}} to a note inside a chord construct
  88 @code{<>}.
  89
  90 @warning{String numbers @strong{must} be defined inside a chord
  91 construct even if there is only a single note.}
  92
  93 @lilypond[verbatim,quote,relative=0]
  94 \clef "treble_8"
  95 <c\5>4 <e\4> <g\3>2
  96 <c,\5 e\4 g\3>1
  97 @end lilypond
  98
  99 When fingerings and string indications are used together, their
 100 placement is controlled by the order in which the two items appear
 101 in the code:
 102
 103 @lilypond[verbatim,quote,relative=1]
 104 \clef "treble_8"
 105 <g\3-0>2
 106 <g-0\3>
 107 @end lilypond
 108
 109 @snippets
 110
 111 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 112 {controlling-the-placement-of-chord-fingerings.ly}
 113
 114 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 115 {allowing-fingerings-to-be-printed-inside-the-staff.ly}
 116
 117 @seealso
 118
 119 Notation Reference:
 120 @ref{Fingering instructions}.
 121
 122 Snippets:
 123 @rlsr{Fretted strings}.
 124
 125 Internals Reference:
 126 @rinternals{StringNumber},
 127 @rinternals{Fingering}.
 128
 129
 130 @node Default tablatures
 131 @subsubsection Default tablatures
 132 @cindex Tablatures, basic
 133 @cindex Tablatures, default
 134
 135 Tablature notation is used for notating music for plucked string
 136 instruments.  Pitches are not denoted with note heads, but by
 137 numbers indicating on which string and fret a note must be played.
 138 LilyPond offers limited support for tablature.
 139
 140 The string number associated with a note is given as a backslash
 141 followed by a number.  By default, string 1 is the highest,
 142 and the tuning defaults to the standard guitar tuning (with 6 strings).
 143 The notes are printed as tablature, by using @code{TabStaff} and
 144 @code{TabVoice} contexts
 145
 146 @lilypond[quote,ragged-right,fragment,verbatim]
 147 \new TabStaff {
 148   a,4\5 c'\2 a\3 e'\1
 149   e\4 c'\2 a\3 e'\1
 150 }
 151 @end lilypond
 152
 153 @funindex minimumFret
 154 @cindex fret
 155
 156
 157 When no string is specified for a note, the note is assigned to
 158 the lowest string that can generate the note with a fret number
 159 greater than or equal to @code{minimumFret} is selected.  The
 160 default value for @code{minimumFret} is 0.
 161
 162
 163 @lilypond[quote,ragged-right,verbatim]
 164 \new StaffGroup <<
 165    \new Staff \relative c {
 166      \clef "treble_8"
 167      c16 d e f g4
 168      c,16 d e f g4
 169    }
 170    \new TabStaff \relative c {
 171      c16 d e f g4
 172      \set TabStaff.minimumFret = #5
 173      c,16 d e f g4
 174    }
 175 >>
 176 @end lilypond
 177
 178 @snippets
 179
 180 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 181 {stem-and-beam-behavior-in-tablature.ly}
 182
 183 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 184 {polyphony-in-tablature.ly}
 185
 186 @seealso
 187
 188 Notation Reference:
 189 @ref{Stems}.
 190
 191 Snippets:
 192 @rlsr{Fretted strings}.
 193
 194 Internals Reference:
 195 @rinternals{TabNoteHead},
 196 @rinternals{TabStaff},
 197 @rinternals{TabVoice},
 198 @rinternals{Beam}.
 199
 200 @knownissues
 201
 202 Chords are not handled in a special way, and hence the automatic
 203 string selector may easily select the same string for two notes in
 204 a chord.
 205
 206 In order to handle @code{\partcombine}, a @code{TabStaff} must use
 207 specially-created voices:
 208
 209 @lilypond[quote,ragged-right,verbatim]
 210 melodia = \partcombine { e4 g g g }{ e4 e e e }
 211 <<
 212   \new TabStaff <<
 213     \new TabVoice = "one" s1
 214     \new TabVoice = "two" s1
 215     \new TabVoice = "shared" s1
 216     \new TabVoice = "solo" s1
 217     { \melodia }
 218   >>
 219 >>
 220 @end lilypond
 221
 222
 223 @node Custom tablatures
 224 @subsubsection Custom tablatures
 225 @cindex Tablatures, custom
 226
 227 You can change the tuning of the strings.  A string tuning is
 228 given as a Scheme list with one integer number for each string,
 229 the number being the pitch (measured in semitones relative to
 230 middle C) of an open string.  The numbers specified for
 231 @code{stringTunings} are the numbers of semitones to subtract or
 232 add, starting the specified pitch by default middle C, in string
 233 order.  LilyPond automatically calculates the number of strings by
 234 looking at @code{stringTunings}.
 235
 236 In the next example, @code{stringTunings} is set for the pitches
 237 e, a, d, and g.
 238
 239 @lilypond[quote,ragged-right,fragment,verbatim]
 240 \new TabStaff <<
 241   \set TabStaff.stringTunings = #'(-5 -10 -15 -20)
 242   {
 243     a,4 c' a e' e c' a e'
 244   }
 245 >>
 246 @end lilypond
 247
 248 LilyPond comes with predefined string tunings for banjo, mandolin,
 249 guitar and bass guitar.  Lilypond automatically sets the correct
 250 transposition for predefined tunings.  The following example is
 251 for bass guitar, which sounds an octave lower than written.
 252
 253 @lilypond[quote,ragged-right,verbatim]
 254 <<
 255   \new Staff <<
 256     \clef "bass_8"
 257     \relative c, {
 258     c4 d e f
 259     }
 260   >>
 261   \new TabStaff <<
 262     \set TabStaff.stringTunings = #bass-tuning
 263     \relative c, {
 264     c4 d e f
 265     }
 266   >>
 267 >>
 268 @end lilypond
 269
 270 The default string tuning is @code{guitar-tuning} (the standard
 271 EADGBE tuning).  Some other predefined tunings are
 272 @code{guitar-open-g-tuning}, @code{mandolin-tuning} and
 273 @code{banjo-open-g-tuning}.
 274
 275 @seealso
 276
 277 Snippets:
 278 @rlsr{Fretted strings}.
 279
 280 The file @file{scm/@/output@/-lib@/.scm} contains the predefined string
 281 tunings.
 282
 283 Internals Reference:
 284 @rinternals{Tab_note_heads_engraver}.
 285
 286 @knownissues
 287
 288 No guitar special effects have been implemented.
 289
 290 @node Fret diagram markups
 291 @subsubsection Fret diagram markups
 292 @cindex fret diagrams
 293 @cindex chord diagrams
 294
 295 Fret diagrams can be added to music as a markup to the desired
 296 note.  The markup contains information about the desired fret
 297 diagram.  There are three different fret-diagram markup
 298 interfaces: standard, terse, and verbose.  The three interfaces
 299 produce equivalent markups, but have varying amounts of
 300 information in the markup string.  Details about the markup
 301 interfaces are found at @ref{Text markup commands}.
 302
 303 The standard fret diagram markup string indicates the string
 304 number and the fret number for each dot to be placed on the string.
 305 In addition, open and unplayed (muted) strings can be indicated.
 306
 307 @lilypond[quote, verbatim]
 308 <<
 309   \context ChordNames {
 310      \chordmode {
 311        c1 d:m
 312      }
 313   }
 314   \context Staff {
 315     \clef "treble_8"
 316     < c e g c' e' > 1 ^\markup
 317       \fret-diagram #"6-x;5-3;4-2;3-o;2-1;1-o;"
 318     < d a d' f'> ^\markup
 319       \fret-diagram #"6-x;5-x;4-o;3-2;2-3;1-1;"
 320   }
 321 >>
 322 @end lilypond
 323
 324 Barre indications can be added to the diagram from
 325 the fret-diagram markup string.
 326
 327 @lilypond[quote, verbatim]
 328 <<
 329   \context ChordNames {
 330      \chordmode {
 331        f1 g
 332      }
 333   }
 334   \context Staff {
 335     \clef "treble_8"
 336     < f, c f a c' f'>1 ^\markup
 337       \fret-diagram #"c:6-1-1;6-1;5-3;4-3;3-2;2-1;1-1;"
 338     < g, b, d g b' g'> ^\markup
 339       \fret-diagram #"c:6-1-3;6-3;5-5;4-5;3-4;2-3;1-3;"
 340   }
 341 >>
 342 @end lilypond
 343
 344 The size of the fret diagram, and the number of frets in the diagram
 345 can be changed in the fret-diagram markup string.
 346
 347 @lilypond[quote, verbatim]
 348 <<
 349   \context ChordNames {
 350      \chordmode {
 351        f1 g
 352      }
 353   }
 354   \context Staff {
 355     \clef "treble_8"
 356     < f, c f a c' f'>1 ^\markup
 357       \fret-diagram #"s:1.5;c:6-1-1;6-1;5-3;4-3;3-2;2-1;1-1;"
 358     < g, b, d g b' g'> ^\markup
 359       \fret-diagram #"h:6;6-3;5-2;4-o;3-o;2-o;1-3;"
 360   }
 361 >>
 362 @end lilypond
 363
 364 The number of strings in a fret diagram can be changed to accomodate
 365 different instruments such as banjos and ukeleles with the fret-diagram
 366 markup string.
 367
 368 @lilypond[quote, verbatim]
 369 <<
 370   \context ChordNames {
 371      \chordmode {
 372        a1
 373      }
 374   }
 375   \context Staff {
 376         %% A chord for ukelele
 377     a'1 ^\markup \fret-diagram #"w:4;4-2-2;3-1-1;2-o;1-o;"
 378   }
 379 >>
 380 @end lilypond
 381
 382 Fingering indications can be added, and the location of fingering labels
 383 can be controlled by the fret-diagram markup string.
 384
 385 @lilypond[quote, verbatim]
 386 <<
 387   \context ChordNames {
 388      \chordmode {
 389        c1 d:m
 390      }
 391   }
 392   \context Staff {
 393     \clef "treble_8"
 394     < c e g c' e' > 1 ^\markup
 395       \fret-diagram #"f:1;6-x;5-3-3;4-2-2;3-o;2-1-1;1-o;"
 396     < d a d' f'> ^\markup
 397       \fret-diagram #"f:2;6-x;5-x;4-o;3-2-2;2-3-3;1-1-1;"
 398   }
 399 >>
 400 @end lilypond
 401
 402 Dot radius and dot position can be controlled with the fret-diagram
 403 markup string.
 404
 405 @lilypond[quote, verbatim]
 406 <<
 407   \context ChordNames {
 408      \chordmode {
 409        c1 d:m
 410      }
 411   }
 412   \context Staff {
 413     \clef "treble_8"
 414     < c e g c' e' > 1 ^\markup
 415       \fret-diagram #"d:0.35;6-x;5-3;4-2;3-o;2-1;1-o;"
 416     < d a d' f'> ^\markup
 417       \fret-diagram #"p:0.2;6-x;5-x;4-o;3-2;2-3;1-1;"
 418   }
 419 >>
 420 @end lilypond
 421
 422 The fret-diagram-terse markup string omits string numbers; the string
 423 number is implied by the presence of semicolons.  There is one semicolon
 424 for each string in the diagram.  The first semicolon corresponds to the
 425 highest string number and the last semicolon corresponds to the first string.
 426 Mute strings, open strings, and fret numbers can be indicated.
 427
 428 @lilypond[quote, verbatim]
 429 <<
 430   \context ChordNames {
 431      \chordmode {
 432        c1 d:m
 433      }
 434   }
 435   \context Staff {
 436     \clef "treble_8"
 437     < c e g c' e' > 1 ^\markup
 438       \fret-diagram-terse #"x;3;2;o;1;o;"
 439     < d a d' f'> ^\markup
 440       \fret-diagram-terse #"x;x;o;2;3;1;"
 441   }
 442 >>
 443 @end lilypond
 444
 445 Barre indicators can be included in the fret-diagram-terse markup string.
 446
 447 @lilypond[quote, verbatim]
 448 <<
 449   \context ChordNames {
 450      \chordmode {
 451        f1 g
 452      }
 453   }
 454   \context Staff {
 455     \clef "treble_8"
 456     < f, c f a c' f'>1 ^\markup
 457       \fret-diagram-terse #"1-(;3;3;2;1;1-);"
 458     < g, b, d g b' g'> ^\markup
 459       \fret-diagram-terse #"3-(;5;5;4;3;3-);"
 460   }
 461 >>
 462 @end lilypond
 463
 464 Fingering indications can be included in the fret-diagram-terse markup string.
 465
 466 @c Need to use override to enable fingerings to show this -- can we do so?
 467 @lilypond[quote, verbatim]
 468 <<
 469   \context ChordNames {
 470      \chordmode {
 471        c1 d:m
 472      }
 473   }
 474   \context Staff {
 475     \override Voice.TextScript
 476       #'fret-diagram-details #'finger-code = #'below-string
 477     \clef "treble_8"
 478     < c e g c' e' > 1 ^\markup
 479       \fret-diagram-terse #"x;3-3;2-2;o;1-1;o;"
 480     < d a d' f'> ^\markup
 481       \fret-diagram-terse #"x;x;o;2-2;3-3;1-1;"
 482   }
 483 >>
 484 @end lilypond
 485
 486 Other fret diagram properties must be adjusted using @code{\override} when using
 487 the fret-diagram-terse markup.
 488
 489 The fret-diagram-verbose markup string is in the format of a Scheme list.  Each
 490 element of the list indicates an item to be placed on the fret diagram.
 491
 492 @lilypond[quote, verbatim]
 493 <<  \context ChordNames {
 494      \chordmode {
 495        c1 d:m
 496      }
 497   }
 498   \context Staff {
 499     \clef "treble_8"
 500     < c e g c' e' > 1 ^\markup
 501       \fret-diagram-verbose #'(
 502         (mute 6)
 503         (place-fret 5 3)
 504         (place-fret 4 2)
 505         (open 3)
 506         (place-fret 2 1)
 507         (open 1)
 508       )
 509     < d a d' f'> ^\markup
 510       \fret-diagram-verbose #'(
 511         (mute 6)
 512         (mute 5)
 513         (open 4)
 514         (place-fret 3 2)
 515         (place-fret 2 3)
 516         (place-fret 1 1)
 517       )
 518   }
 519 >>
 520 @end lilypond
 521
 522 Fingering indications and barres can be included in a
 523 fret-diagram-verbose markup string.
 524
 525 @c \override is necessary to make fingering visible
 526 @lilypond[quote, verbatim]
 527 <<
 528   \context ChordNames {
 529      \chordmode {
 530        f1 g
 531      }
 532   }
 533   \context Staff {
 534     \clef "treble_8"
 535     \override Voice.TextScript
 536       #'fret-diagram-details #'finger-code = #'below-string
 537
 538     < f, c f a c' f'>1 ^\markup
 539       \fret-diagram-verbose #'(
 540         (place-fret 6 1)
 541         (place-fret 5 3)
 542         (place-fret 4 3)
 543         (place-fret 3 2)
 544         (place-fret 2 1)
 545         (place-fret 1 1)
 546         (barre 6 1 1)
 547       )
 548     < g, b, d g b' g'> ^\markup
 549       \fret-diagram-verbose #'(
 550         (place-fret 6 3 2)
 551         (place-fret 5 2 1)
 552         (open 4)
 553         (open 3)
 554         (open 2)
 555         (place-fret 1 3 3)
 556       )
 557   }
 558 >>
 559 @end lilypond
 560
 561 All other fret diagram properties must be adjusted using @code{\override}
 562 when using the fret-diagram-verbose markup.
 563
 564 @ignore
 565 The following example shows the three fret-diagram markup
 566 interfaces, along with examples of common tweaks.  For example,
 567 the size of the verbose fret diagram is reduced to 0.75, and the
 568 finger indications are specified to appear below the diagram.  The
 569 terse diagram includes tweaks to specify placement of finger code
 570 and color of dots.
 571
 572 @lilypond[verbatim,ragged-right,quote]
 573 \new Voice {
 574   \clef "treble_8"
 575   d^\markup \fret-diagram #"6-x;5-x;4-o;3-2;2-3;1-2;"
 576   d d d
 577   fis^\markup \override #'(size . 0.75) {
 578     \override #'(finger-code . below-string) {
 579       \fret-diagram-verbose #'((place-fret 6 2 1) (barre 6 1 2)
 580                                (place-fret 5 4 3)
 581                                (place-fret 4 4 4)
 582                                (place-fret 3 3 2)
 583                                (place-fret 2 2 1)
 584                                (place-fret 1 2 1))
 585     }
 586   }
 587   fis fis fis
 588   c^\markup \override #'(dot-radius . 0.35) {
 589     \override #'(finger-code . in-dot) {
 590       \override #'(dot-color . white) {
 591         \fret-diagram-terse #"x;3-1-(;5-2;5-3;5-4;3-1-);"
 592       }
 593     }
 594   }
 595   c c c
 596 }
 597 @end lilypond
 598 @end ignore
 599
 600 The graphical layout of a fret diagram can be customized according to
 601 user preference through the properties of the @code{fret-diagram-interface}.
 602 Details are found at @rinternals{fret-diagram-interface}.  For a fret diagram
 603 markup , the interface properties belong to @code{Voice.TextScript}.
 604
 605 @snippets
 606 TODO create snippets for changing properties.  Use regression test?
 607
 608 @seealso
 609
 610 Notation Reference:
 611 @ref{Text markup commands}.
 612
 613 Snippets:
 614 @rlsr{Fretted strings}.
 615
 616 Internals Reference:
 617 @rinternals{fret-diagram-interface}.
 618
 619 @node Predefined fret diagrams
 620 @subsubsection Predefined fret diagrams
 621 @cindex fret diagrams
 622 @cindex chord diagrams
 623
 624 Fret diagrams can be displayed using the @code{FretBoards} context.  By
 625 default, the @code{FretBoards} context will display fret diagrams that
 626 are stored in a lookup table:
 627
 628 @lilypond[verbatim, ragged-right, quote]
 629 \include "predefined-guitar-fretboards.ly"
 630 \context FretBoards {
 631   \chordmode {
 632     c1 d
 633   }
 634 }
 635 @end lilypond
 636
 637 The default predefined fret diagrams are contained in the file
 638 @code{predefined-guitar-fretboards.ly}.  Fret diagrams are
 639 stored based on the pitches of a chord and the value of
 640 @code{stringTunings} that is currently in use.
 641 @code{predefined-guitar-fretboards.ly} contains predefined
 642 fret diagrams only for @code{guitar-tuning}.  Predefined fret
 643 diagrams can be added for other instruments or other tunings
 644 by following the examples found in
 645 @code{predefined-guitar-fretboards.ly}.
 646
 647 Chord pitches can be entered
 648 either as simultaneous music or using chord mode (see
 649 @ref{Chord mode overview}).
 650
 651 @lilypond[verbatim, ragged-right,quote]
 652 \include "predefined-guitar-fretboards.ly"
 653 \context FretBoards {
 654   \chordmode {c1}
 655   <c' e' g'>1
 656 }
 657 @end lilypond
 658
 659 It is common that both chord names and fret diagrams are displayed together.
 660 This is achieved by putting a @code{ChordNames} context in parallel with
 661 a @code{FretBoards} context and giving both contexts the same music.
 662
 663 @lilypond[verbatim, ragged-right, quote]
 664 \include "predefined-guitar-fretboards.ly"
 665 mychords = \chordmode{
 666   c1 f g
 667 }
 668
 669 <<
 670   \context ChordNames {
 671     \mychords
 672   }
 673   \context FretBoards {
 674     \mychords
 675   }
 676 >>
 677 @end lilypond
 678
 679 Predefined fret diagrams are transposable, as long as a diagram for the
 680 transposed chord is stored in the fret diagram table.
 681
 682 @lilypond[verbatim, ragged-right, quote]
 683 \include "predefined-guitar-fretboards.ly"
 684 mychords = \chordmode{
 685   c1 f g
 686 }
 687
 688 mychordlist = {
 689   \mychords
 690   \transpose c e { \mychords}
 691 }
 692 <<
 693   \context ChordNames {
 694     \mychordlist
 695   }
 696   \context FretBoards {
 697     \mychordlist
 698   }
 699 >>
 700 @end lilypond
 701
 702
 703 The predefined fret diagram table contains seven chords (major, minor,
 704 augmented, diminished, dominant seventh, major seventh, minor seventh)
 705 for each of 17 keys.  A complete list of the predefined fret diagrams is
 706 shown in @ref{Predefined fretboard diagrams}.  If there is no entry in
 707 the table for a chord, the FretBoards engraver will calculate a
 708 fret-diagram using the automatic fret diagram functionality described in
 709 @ref{Automatic fret diagrams}.
 710
 711 @lilypond[verbatim, ragged-right, quote]
 712 \include "predefined-guitar-fretboards.ly"
 713 mychords = \chordmode{
 714   c1 c:9
 715 }
 716
 717 <<
 718   \context ChordNames {
 719     \mychords
 720   }
 721   \context FretBoards {
 722     \mychords
 723   }
 724 >>
 725 @end lilypond
 726
 727 Fret diagrams can be added to the fret diagram table.  To add a diagram,
 728 you must specify the chord for the diagram, the tuning to be used, and the
 729 fret-diagram-terse definition string for the diagram.
 730
 731 @lilypond[verbatim, ragged-right, quote]
 732 \include "predefined-guitar-fretboards.ly"
 733
 734 \storePredefinedDiagram \chordmode {c:9}
 735                         #guitar-tuning
 736                         #"x;3-2;2-1;3-3;3-4;x;"
 737
 738 mychords = \chordmode{
 739   c1 c:9
 740 }
 741
 742 <<
 743   \context ChordNames {
 744     \mychords
 745   }
 746   \context FretBoards {
 747     \mychords
 748   }
 749 >>
 750 @end lilypond
 751
 752 Different fret diagrams for the same chord name can be stored using different
 753 octaves of pitches.
 754
 755 @lilypond[verbatim, ragged-right, quote]
 756 \include "predefined-guitar-fretboards.ly"
 757
 758 \storePredefinedDiagram \chordmode {c'}
 759                         #guitar-tuning
 760                         #(offset-fret 2 (chord-shape 'bes))
 761
 762 mychords = \chordmode{
 763   c1 c'
 764 }
 765
 766 <<
 767   \context ChordNames {
 768     \mychords
 769   }
 770   \context FretBoards {
 771     \mychords
 772   }
 773 >>
 774 @end lilypond
 775
 776 In addition to fret diagrams, LilyPond stores an internal list of chord
 777 shapes.  The chord shapes are fret diagrams that can be shifted along
 778 the neck to different posistions to provide different chords.  Chord
 779 shapes can be added to the internal list and then used to define
 780 predefined fret diagrams.
 781
 782 @lilypond[verbatim, ragged-right, quote]
 783 \include "predefined-guitar-fretboards.ly"
 784
 785 % add a new chord shape
 786
 787 \addChordShape #'powerf #"1-1;3-3;3-4;x;x;x;"
 788
 789 % add some new chords based on the power chord shape
 790
 791 \storePredefinedDiagram \chordmode {f'}
 792                         #guitar-tuning
 793                         #(chord-shape 'powerf)
 794 \storePredefinedDiagram \chordmode {g'}
 795                         #guitar-tuning
 796                         #(offset-fret 2 (chord-shape 'powerf))
 797
 798 mychords = \chordmode{
 799   f1 f' g g'
 800 }
 801
 802 <<
 803   \context ChordNames {
 804     \mychords
 805   }
 806   \context FretBoards {
 807     \mychords
 808   }
 809 >>
 810 @end lilypond
 811
 812 The graphical layout of a fret diagram can be customized according to
 813 user preference through the properties of the @code{fret-diagram-interface}.
 814 Details are found at @rinternals{fret-diagram-interface}.  For a
 815 predefined fret diagram, the interface properties belong to
 816 @code{FretBoards.FretBoard}.
 817
 818 @c @snippets
 819
 820 @seealso
 821
 822 Notation Reference:
 823 @ref{Custom tablatures},
 824 @ref{Automatic fret diagrams},
 825 @ref{Chord mode overview},
 826 @ref{Predefined fretboard diagrams}.
 827
 828 Installed Files:
 829 @file{ly/predefined-guitar-fretboards.ly}.
 830
 831 Snippets:
 832 @rlsr{Fretted strings}.
 833
 834 Internals Reference:
 835 @rinternals {fret-diagram-interface}.
 836
 837
 838 @node Automatic fret diagrams
 839 @subsubsection Automatic fret diagrams
 840 @cindex fret diagrams
 841 @cindex chord diagrams
 842
 843 Fret diagrams can be automatically created from entered notes using the
 844 @code{FretBoards} context.  If no predefined diagram is available for
 845 the entered notes in the active @code{stringTunings}, this context
 846 calculates strings and frets that can be used to play the notes.
 847
 848 @lilypond[quote,ragged-right,verbatim]
 849 <<
 850   \context ChordNames {
 851      \chordmode {
 852        f1 g
 853      }
 854   }
 855   \context FretBoards {
 856     < f, c f a c' f'>1
 857     < g,\6 b, d g b g'>
 858   }
 859   \context Staff {
 860     \clef "treble_8"
 861     < f, c f a c' f'>1
 862     < g, b, d g b' g'>
 863   }
 864 >>
 865 @end lilypond
 866
 867 As no predefined diagrams are loaded by default, automatic calculation
 868 of fret diagrams is the default behavior.  Once default diagrams are
 869 loaded, automatic calculation can be enabled and disabled with predefined
 870 commands:
 871
 872 @lilypond[quote,ragged-right,verbatim]
 873
 874 \storePredefinedDiagram <c\5 e g c' e'>
 875                         #guitar-tuning
 876                         #"x;3-1-(;5-2;5-3;5-4;3-1-1);"
 877 <<
 878   \context ChordNames {
 879      \chordmode {
 880        c1 c c
 881      }
 882   }
 883   \context FretBoards {
 884     <c\5 e g c' e'>1
 885     \predefinedFretboardsOff
 886     <c\5 e g c' e'>
 887     \predefinedFretboardsOn
 888     <c\5 e g c' e'>
 889   }
 890   \context Staff {
 891     \clef "treble_8"
 892     <c\5 e g c' e'>1
 893     <c\5 e g c' e'>
 894     <c\5 e g c' e'>
 895   }
 896 >>
 897 @end lilypond
 898
 899
 900
 901 Notes can be explicitly placed on a string.  It is often enough
 902 to place only the lowest note on an explicit string; the rest of
 903 the notes will then be placed appropriately by the @code{FretBoards}
 904 context.
 905
 906 @lilypond[quote,ragged-right,verbatim]
 907 <<
 908   \context ChordNames {
 909      \chordmode {
 910        c1 c d:m d:m
 911      }
 912   }
 913   \context FretBoards {
 914     < c e g c' e' > 1
 915     < c\5 e g c' e' > 1
 916     < d a d' f'>
 917     < d\4 a d' f'>
 918   }
 919   \context Staff {
 920     \clef "treble_8"
 921     < c e g c' e' > 1
 922     < c e g c' e' > 1
 923     < d a d' f'>
 924     < d a d' f'>
 925   }
 926 >>
 927 @end lilypond
 928
 929 Fingerings can be added to FretBoard fret diagrams.
 930
 931 @lilypond[quote, verbatim]
 932 <<
 933   \context ChordNames {
 934      \chordmode {
 935        c1 d:m
 936      }
 937   }
 938   \context FretBoards {
 939     < c\5-3 e-2 g c'-1 e' > 1
 940     < d\4 a-2 d'-3 f'-1>
 941   }
 942   \context Staff {
 943     \clef "treble_8"
 944     < c e g c' e' > 1
 945     < d a d' f'>
 946   }
 947 >>
 948 @end lilypond
 949
 950 The strings and frets for the @code{FretBoards} context depend
 951 on the @code{stringTunings} property, which has the same meaning
 952 as in the TabStaff context.  See @ref{Custom tablatures} for
 953 information on the @code{stringTunings} property.
 954
 955 The graphical layout of a fret diagram can be customized according to
 956 user preference through the properties of the @code{fret-diagram-interface}.
 957 Details are found at @rinternals{fret-diagram-interface}.  For a
 958 @code{FretBoards} fret diagram, the interface properties belong to
 959 @code{FretBoards.FretBoard}.
 960
 961 @snippets
 962 The minimum fret to be used in calculating strings and frets for
 963 the FretBoard context can be set with the @code{minimumFret}
 964 property.
 965
 966 @c TODO -- snippet showing minimum fret.
 967
 968 @c TODO -- snippet for using StringTunings
 969
 970 @predefined
 971 \predefinedFretboardsOff,
 972 \predefinedFretboardsOn.
 973
 974 @seealso
 975
 976 Notation Reference:
 977 @ref{Custom tablatures}.
 978
 979 Snippets:
 980 @rlsr{Fretted strings}.
 981
 982 Internals Reference:
 983 @rinternals {fret-diagram-interface}.
 984
 985
 986 @node Right-hand fingerings
 987 @subsubsection Right-hand fingerings
 988
 989 Right-hand fingerings @var{p-i-m-a} must be entered within a
 990 chord construct @code{<>} for them to be printed in the score,
 991 even when applied to a single note.
 992
 993 @warning{There @strong{must} be a hyphen after the note and a space
 994 before the closing @code{>}.}
 995
 996 @lilypond[quote,verbatim,relative=0]
 997 \clef "treble_8"
 998 <c-\rightHandFinger #1 >4
 999 <e-\rightHandFinger #2 >
1000 <g-\rightHandFinger #3 >
1001 <c-\rightHandFinger #4 >
1002 <c,-\rightHandFinger #1 e-\rightHandFinger #2 g-\rightHandFinger #3 c-\rightHandFinger #4 >1
1003 @end lilypond
1004
1005 For convenience, you can abbreviate @code{\rightHandFinger} to something
1006 short, for example @code{RH},
1007
1008 @example
1009 #(define RH rightHandFinger)
1010 @end example
1011
1012 @cindex fingerings, right hand, for guitar
1013 @cindex right hand fingerings for guitar
1014
1015 @snippets
1016
1017 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
1018 {placement-of-right-hand-fingerings.ly}
1019
1020 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
1021 {fingerings,-string-indications,-and-right-hand-fingerings.ly}
1022
1023 @seealso
1024
1025 Snippets:
1026 @rlsr{Fretted strings}.
1027
1028 Internals Reference:
1029 @rinternals{StrokeFinger}.
1030
1031
1032 @node Guitar
1033 @subsection Guitar
1034
1035 Most of the notational issues associated with guitar music are
1036 covered sufficiently in the general fretted strings section, but there
1037 are a few more worth covering here.  Occasionally users want to
1038 create songbook-type documents having only lyrics with chord
1039 indications above them.  Since Lilypond is a music typesetter,
1040 it is not recommended for documents that have no music notation
1041 in them.  A better alternative is a word processor, text editor,
1042 or, for experienced users, a typesetter like GuitarTeX.
1043
1044 @menu
1045 * Indicating position and barring::
1046 * Indicating harmonics and dampened notes::
1047 @end menu
1048
1049 @node Indicating position and barring
1050 @subsubsection Indicating position and barring
1051
1052 This example demonstrates how to include guitar position and
1053 barring indications.
1054
1055 @lilypond[quote,ragged-right,fragment,verbatim,relative=0]
1056 \clef "treble_8"
1057 b16 d g b e
1058 \textSpannerDown
1059 \override TextSpanner #'bound-details #'left #'text = #"XII "
1060   g16\startTextSpan
1061   b16 e g e b g\stopTextSpan
1062 e16 b g d
1063 @end lilypond
1064
1065 @seealso
1066
1067 Notation Reference:
1068 @ref{Text spanners}.
1069
1070 Snippets:
1071 @rlsr{Fretted strings},
1072 @rlsr{Expressive marks}.
1073
1074 @node Indicating harmonics and dampened notes
1075 @subsubsection Indicating harmonics and dampened notes
1076
1077 Special note heads can be used to indicate dampened notes or
1078 harmonics.  Harmonics are normally further explained with a
1079 text markup.
1080
1081 @lilypond[quote,ragged-right,fragment,verbatim]
1082 \relative c' {
1083   \clef "treble_8"
1084   \override Staff.NoteHead #'style = #'cross
1085   g8 a b c b4
1086   \override Staff.NoteHead #'style = #'harmonic-mixed
1087   d^\markup { \italic { \fontsize #-2 { "harm. 12" }}} <g b>1
1088 }
1089 @end lilypond
1090
1091 @seealso
1092
1093 Snippets:
1094 @rlsr{Fretted strings}.
1095
1096 Notation Reference:
1097 @ref{Special note heads},
1098 @ref{Note head styles}.
1099
1100 @node Banjo
1101 @subsection Banjo
1102
1103 @menu
1104 * Banjo tablatures::
1105 @end menu
1106
1107 @node Banjo tablatures
1108 @subsubsection Banjo tablatures
1109 @cindex Banjo tablatures
1110
1111 LilyPond has basic support for the five-string banjo.  When making tablatures
1112 for five-string banjo, use the banjo tablature format function to get
1113 correct fret numbers for the fifth string:
1114
1115 @c due to crazy intervals of banjo music, absolute pitch is recommended
1116
1117 @lilypond[quote,ragged-right,fragment,verbatim]
1118 \new TabStaff <<
1119   \set TabStaff.tablatureFormat = #fret-number-tablature-format-banjo
1120   \set TabStaff.stringTunings = #banjo-open-g-tuning
1121   {
1122     \stemDown
1123     g8 d' g'\5 a b g e d' |
1124     g4 d''8\5 b' a'\2 g'\5 e'\2 d' |
1125     g4
1126   }
1127 >>
1128 @end lilypond
1129
1130 A number of common tunings for banjo are predefined in LilyPond:
1131 @code{banjo-c-tuning} (gCGBD), @code{banjo-modal-tuning} (gDGCD),
1132 @code{banjo-open-d-tuning} (aDF#AD) and @code{banjo-open-dm-tuning}
1133 (aDFAD).
1134
1135 These tunings may be converted to four-string banjo tunings using the
1136 @code{four-string-banjo} function:
1137
1138 @example
1139 \set TabStaff.stringTunings = #(four-string-banjo banjo-c-tuning)
1140 @end example
1141
1142 @seealso
1143
1144 Snippets:
1145 @rlsr{Fretted strings}.
1146
1147 The file @file{scm/@/output@/-lib@/.scm} contains predefined banjo tunings.
1148
1149
1150
1151
1152