Revised tablature documentation

[lilypond.git] / Documentation / notation / fretted-strings.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.12.0"

@node Fretted string instruments
@section Fretted string instruments

@lilypondfile[quote]{fretted-headword.ly}

This section discusses several aspects of music notation that are unique
to fretted string instruments.

@cindex tablature
@cindex tablature, guitar
@cindex tablature, banjo
@cindex guitar tablature
@cindex banjo tablature

@menu
* Common notation for fretted strings::
* Guitar::
* Banjo::
@end menu

@node Common notation for fretted strings
@subsection Common notation for fretted strings

This section discusses common notation that is unique
to fretted string instruments.

@menu
* References for fretted strings::
* String number indications::
* Default tablatures::
* Custom tablatures::
* Fret diagram markups::
* Predefined fret diagrams::
* Automatic fret diagrams::
* Right-hand fingerings::
@end menu

@node References for fretted strings
@unnumberedsubsubsec References for fretted strings

Music for fretted string instruments is normally notated on
a single staff, either in traditional music notation or in
tablature.  Sometimes the two types are combined, and it is
especially common in popular music to use chord diagrams above
a staff of traditional notation.  The guitar and the banjo are
transposing instruments, sounding an octave lower than written.
Scores for these instruments should use the @code{"treble_8"} clef.
Some other elements pertinent to fretted string instruments
are covered elsewhere:

@itemize
@item Fingerings are indicated as shown in @ref{Fingering instructions}.

@item Instructions for @notation{Laissez vibrer} ties
as well as ties on arpeggios and tremolos can be found in
@ref{Ties}.

@item Instructions for handling multiple voices can be found
in @ref{Collision resolution}.

@item Instructions for indicating harmonics can be found in
@ref{Harmonics}.

@end itemize


@seealso
Notation Reference:
@ref{Fingering instructions},
@ref{Ties},
@ref{Collision resolution},
@ref{Instrument names},
@ref{Writing music in parallel},
@ref{Arpeggio},
@ref{List of articulations},
@ref{Clef}.


@node String number indications
@unnumberedsubsubsec String number indications

@cindex string numbers
@cindex string vs. fingering numbers
@cindex fingering vs. string numbers

The string on which a note should be played may be indicated by
appending @code{\@var{number}} to a note inside a chord construct
@code{<>}.

@warning{String numbers @strong{must} be defined inside a chord
construct even if there is only a single note.}

@lilypond[verbatim,quote,relative=0]
\clef "treble_8"
<c\5>4 <e\4> <g\3>2
<c,\5 e\4 g\3>1
@end lilypond

When fingerings and string indications are used together, their
placement is controlled by the order in which the two items appear
in the code:

@lilypond[verbatim,quote,relative=1]
\clef "treble_8"
<g\3-0>2
<g-0\3>
@end lilypond

@snippets

@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
{controlling-the-placement-of-chord-fingerings.ly}

@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
{allowing-fingerings-to-be-printed-inside-the-staff.ly}


@seealso
Notation Reference:
@ref{Fingering instructions}.

Snippets:
@rlsr{Fretted strings}.

Internals Reference:
@rinternals{StringNumber},
@rinternals{Fingering}.


@node Default tablatures
@unnumberedsubsubsec Default tablatures

@cindex tablatures, basic
@cindex tablatures, default

@funindex TabStaff
@funindex TabVoice

Music for plucked string instruments is frequently notated using a
finger/touch notation or tablature. In contrast to traditional
notation pitches are not denoted with note heads, but by numbers (or
letterlike symbols in historical intavolatura). The numbers
indicate on which string and fret a note must be played. The numbers
are printed on top of each other if they are to be played
simultaneously.


By default, string 1 is the highest,
and the tuning defaults to the standard guitar tuning (with 6 strings).
The notes are printed as tablature, by using @code{TabStaff} and
@code{TabVoice} contexts

@lilypond[quote,ragged-right,fragment,verbatim]
\new TabStaff \relative c' {
        a,8 a' <c e> a
        d, a' <d f> a
}
@end lilypond

Default tablatures do not contain any symbols for tone duration nor any
other musical symbols such as e.g. expressive marks.

@lilypond[quote,ragged-right,verbatim]
symbols = {
  \time 3/4
  c4-.^"Allegro" d( e)
  f4-.\f g a^\fermata
  \mark \default
  c8_.\<\( c16 c ~ c2\!
  c'2.\prall\)
}

\score {
  <<
    \new Staff { \clef "G_8" \symbols }
    \new TabStaff   { \symbols }
  >>
}
@end lilypond

@funindex \tabFullNotation

If all musical symbols used in traditional notation should also show up
in tablature one has to apply the command @code{\tabFullNotation} in a
@code{TabStaff}-context. Please bear in mind that half notes are
double-stemmed in tablature in order to distinguish them from quarter
notes.

@lilypond[quote,ragged-right,verbatim]
symbols = {
  \time 3/4
  c4-.^"Allegro" d( e)
  f4-.\f g a^\fermata
  \mark \default
  c8_.\<\( c16 c ~ c2\!
  c'2.\prall\)
}

\score {
  \new TabStaff {
    \tabFullNotation
    \symbols
  }
}
@end lilypond

@funindex minimumFret

@cindex fret

By default pitches are assigned to the lowest playing position on the
fret-board (first position). Open strings are automatically preferred.
If you would like a certain pitch to be played on a specific string
you can add a string number indication to the pitch name. If you
define pitch names and string numbers without a chord construct
(@code{<>}) the string number indications do not appear in traditional
notation. It is much more comfortable to define the playing position
by using the value of @code{minimumFret}. The default value for
minimumFret is 0.


@lilypond[quote,ragged-right,verbatim]
\new StaffGroup <<
   \new Staff \relative c {
     \clef "treble_8"
     \time 2/4
     c16 d e f g4
     c,16\5 d\5 e\4 f\4 g4\4
     c,16 d e f g4
   }
   \new TabStaff \relative c {
     c16 d e f g4
     c,16\5 d\5 e\4 f\4 g4\4
     \set TabStaff.minimumFret = #5
     c,16 d e f g4
   }
>>
@end lilypond


Ties over a line break are parenthesized by default. The same holds for
the second alternative of a repeat.

@lilypond[quote,ragged-right,verbatim]
ties = \relative c' {
        \repeat volta 2 {
        e2. f4~
        f2 g2~ }
        \alternative {
                { g4 f2. }
                { g4\repeatTie c,2. }
        }
        b1~\break
        b1  \bar "|."
}

\score {
  <<
    \new StaffGroup  <<
    \context Staff  {
        \clef "treble_8"
        \ties
    }
      \context TabStaff  {
        \ties
      }
    >>
  >>
  \layout {
  indent = #0
  ragged-right = ##t
  }
}
@end lilypond

@funindex \hideSplitTiedTabNotes

The command @code{\hideSplitTiedTabNotes} cancels the behavior of
engraving fret numbers in parentheses:

@lilypond[quote,ragged-right,verbatim]
ties = \relative c' {
        \repeat volta 2 {
        e2. f4~
        f2 g2~ }
        \alternative {
                { g4 f2. }
                { g4\repeatTie c,2. }
        }
        b1~\break
        b1  \bar "|."
}

\score {
  <<
    \new StaffGroup  <<
    \context Staff  {
        \clef "treble_8"
        \ties
    }
      \context TabStaff  {
      \hideSplitTiedTabNotes
        \ties
      }
    >>
  >>
  \layout {
  indent = #0
  ragged-right = ##t
  }
}
@end lilypond

@cindex harmonic indications in tablature notation
@cindex tablature and harmonic indications
@cindex slides in tablature notation
@cindex tablature and slides

Harmonic indications and slides can be added to tablature
notation.

@lilypond[verbatim, quote, relative=1]
\new TabStaff {
  \new TabVoice {
    <c g'\harmonic> d\2\glissando e\2
  }
}
@end lilypond


@snippets

@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
{stem-and-beam-behavior-in-tablature.ly}

@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
{polyphony-in-tablature.ly}


@seealso
Notation Reference:
@ref{Stems}.

Snippets:
@rlsr{Fretted strings}.

Internals Reference:
@rinternals{TabNoteHead},
@rinternals{TabStaff},
@rinternals{TabVoice},
@rinternals{Beam}.


@knownissues

Chords are not handled in a special way, and hence the automatic
string selector may easily select the same string for two notes in
a chord.

In order to handle @code{\partcombine}, a @code{TabStaff} must use
specially-created voices:

@lilypond[quote,ragged-right,verbatim]
melodia = \partcombine { e4 g g g }{ e4 e e e }
<<
  \new TabStaff <<
    \new TabVoice = "one" s1
    \new TabVoice = "two" s1
    \new TabVoice = "shared" s1
    \new TabVoice = "solo" s1
    { \melodia }
  >>
>>
@end lilypond

Guitar special effects are limited to harmonics and slides.

@node Custom tablatures
@unnumberedsubsubsec Custom tablatures

@cindex tablatures, custom
@cindex tablature, banjo
@cindex tablature, mandolin
@cindex tablature, bass guitar
@cindex tablature, predefined string tunings
@cindex fretted instruments, predefined string tunings
@cindex predefined string tunings for fretted instruments

@funindex StringTunings

LilyPond tabulature automatically calculates the fret for
a note based on the string to which the note is assigned.
In order to do this, the tuning of the strings must be
specified.  The tuning of the strings is given in the
@code{StringTunings} property.

LilyPond comes with predefined string tunings for banjo, mandolin,
guitar and bass guitar.  LilyPond automatically sets the correct
transposition for predefined tunings.  The following example is
for bass guitar, which sounds an octave lower than written.

@lilypond[quote,ragged-right,verbatim]
<<
  \new Staff {
    \clef "bass_8"
    \relative c, {
      c4 d e f
    }
  }
  \new TabStaff {
    \set TabStaff.stringTunings = #bass-tuning
    \relative c, {
      c4 d e f
    }
  }
>>
@end lilypond

The default string tuning is @code{guitar-tuning}, which
is the standard EADGBE tuning.  Some other predefined tunings are
@code{guitar-open-g-tuning}, @code{mandolin-tuning} and
@code{banjo-open-g-tuning}.  The predefined string tunings
are found in @code{scm/output-lib.scm}.

A string tuning is a Scheme list of string pitches,
one for each string, ordered by string number from 1 to N,
where string 1 is at the top of the tablature staff and
string N is at the bottom.  This ordinarily results in ordering
from highest pitch to lowest pitch, but some instruments
(e.g. ukulele) do not have strings ordered by pitch.

A string pitch in a string tuning list is the pitch difference
of the open string from middle C measured in semitones.  The
string pitch must be an integer.  LilyPond calculates the actual
pitch of the string by adding the string tuning pitch to the
actual pitch for middle C.

LilyPond automatically calculates the number of strings in the
@code{TabStaff} as the number of elements in @code{stringTunings}.

Any desired string tuning can be created.  For example, we can
define a string tuning for a four-string instrument with pitches
of @code{a''},  @code{d''},  @code{g'}, and @code{c'}:


@lilypond[quote,verbatim]
mynotes = {
    c'4 e' g' c'' |
    e'' g'' b'' c'''
}

<<
  \new Staff {
    \clef treble
    \mynotes
  }
  \new TabStaff {
    \set TabStaff.stringTunings = #'(21 14 7 0)
    \mynotes
  }
>>
@end lilypond


@seealso
Installed Files:
@file{scm/@/output@/-lib@/.scm}.

Snippets:
@rlsr{Fretted strings}.

Internals Reference:
@rinternals{Tab_note_heads_engraver}.


@node Fret diagram markups
@unnumberedsubsubsec Fret diagram markups

@cindex fret diagrams
@cindex chord diagrams
@cindex diagrams, fret
@cindex diagrams, chord for fretted instruments
@cindex fret diagrams, custom
@cindex custom fret diagrams

Fret diagrams can be added to music as a markup to the desired
note.  The markup contains information about the desired fret
diagram.  There are three different fret-diagram markup
interfaces: standard, terse, and verbose.  The three interfaces
produce equivalent markups, but have varying amounts of
information in the markup string.  Details about the markup
interfaces are found at @ref{Text markup commands}.

The standard fret diagram markup string indicates the string
number and the fret number for each dot to be placed on the string.
In addition, open and unplayed (muted) strings can be indicated.

@lilypond[quote, verbatim]
<<
  \context ChordNames {
     \chordmode {
       c1 d:m
     }
  }
  \context Staff {
    \clef "treble_8"
    < c e g c' e' > 1 ^\markup
      \fret-diagram #"6-x;5-3;4-2;3-o;2-1;1-o;"
    < d a d' f'> ^\markup
      \fret-diagram #"6-x;5-x;4-o;3-2;2-3;1-1;"
  }
>>
@end lilypond

@cindex barre indications

Barre indications can be added to the diagram from
the fret-diagram markup string.

@lilypond[quote, verbatim]
<<
  \context ChordNames {
     \chordmode {
       f1 g
     }
  }
  \context Staff {
    \clef "treble_8"
    < f, c f a c' f'>1 ^\markup
      \fret-diagram #"c:6-1-1;6-1;5-3;4-3;3-2;2-1;1-1;"
    < g, d g b d' g'> ^\markup
      \fret-diagram #"c:6-1-3;6-3;5-5;4-5;3-4;2-3;1-3;"
  }
>>
@end lilypond

@cindex fret-diagram markup

@funindex fret-diagram
@funindex \fret-diagram

The size of the fret diagram, and the number of frets in the diagram
can be changed in the fret-diagram markup string.

@lilypond[quote, verbatim]
<<
  \context ChordNames {
     \chordmode {
       f1 g
     }
  }
  \context Staff {
    \clef "treble_8"
    < f, c f a c' f'>1 ^\markup
      \fret-diagram #"s:1.5;c:6-1-1;6-1;5-3;4-3;3-2;2-1;1-1;"
    < g, b, d g b g'> ^\markup
      \fret-diagram #"h:6;6-3;5-2;4-o;3-o;2-o;1-3;"
  }
>>
@end lilypond

The number of strings in a fret diagram can be changed to accomodate
different instruments such as banjos and ukeleles with the fret-diagram
markup string.

@lilypond[quote, verbatim]
<<
  \context ChordNames {
     \chordmode {
       a1
     }
  }
  \context Staff {
        %% A chord for ukelele
    a'1 ^\markup \fret-diagram #"w:4;4-2-2;3-1-1;2-o;1-o;"
  }
>>
@end lilypond

Fingering indications can be added, and the location of fingering labels
can be controlled by the fret-diagram markup string.

@lilypond[quote, verbatim]
<<
  \context ChordNames {
     \chordmode {
       c1 d:m
     }
  }
  \context Staff {
    \clef "treble_8"
    < c e g c' e' > 1 ^\markup
      \fret-diagram #"f:1;6-x;5-3-3;4-2-2;3-o;2-1-1;1-o;"
    < d a d' f'> ^\markup
      \fret-diagram #"f:2;6-x;5-x;4-o;3-2-2;2-3-3;1-1-1;"
  }
>>
@end lilypond

Dot radius and dot position can be controlled with the fret-diagram
markup string.

@lilypond[quote, verbatim]
<<
  \context ChordNames {
     \chordmode {
       c1 d:m
     }
  }
  \context Staff {
    \clef "treble_8"
    < c e g c' e' > 1 ^\markup
      \fret-diagram #"d:0.35;6-x;5-3;4-2;3-o;2-1;1-o;"
    < d a d' f'> ^\markup
      \fret-diagram #"p:0.2;6-x;5-x;4-o;3-2;2-3;1-1;"
  }
>>
@end lilypond

@cindex fret-diagram-terse markup

@funindex fret-diagram-terse
@funindex \fret-diagram-terse

The fret-diagram-terse markup string omits string numbers; the string
number is implied by the presence of semicolons.  There is one semicolon
for each string in the diagram.  The first semicolon corresponds to the
highest string number and the last semicolon corresponds to the first string.
Mute strings, open strings, and fret numbers can be indicated.

@lilypond[quote, verbatim]
<<
  \context ChordNames {
     \chordmode {
       c1 d:m
     }
  }
  \context Staff {
    \clef "treble_8"
    < c e g c' e' > 1 ^\markup
      \fret-diagram-terse #"x;3;2;o;1;o;"
    < d a d' f'> ^\markup
      \fret-diagram-terse #"x;x;o;2;3;1;"
  }
>>
@end lilypond

Barre indicators can be included in the fret-diagram-terse markup string.

@lilypond[quote, verbatim]
<<
  \context ChordNames {
     \chordmode {
       f1 g
     }
  }
  \context Staff {
    \clef "treble_8"
    < f, c f a c' f'>1 ^\markup
      \fret-diagram-terse #"1-(;3;3;2;1;1-);"
    < g, d g b d' g'> ^\markup
      \fret-diagram-terse #"3-(;5;5;4;3;3-);"
  }
>>
@end lilypond

Fingering indications can be included in the fret-diagram-terse markup string.

@c Need to use override to enable fingerings to show this -- can we do so?
@lilypond[quote, verbatim]
<<
  \context ChordNames {
     \chordmode {
       c1 d:m
     }
  }
  \context Staff {
    \override Voice.TextScript
      #'(fret-diagram-details finger-code) = #'below-string
    \clef "treble_8"
    < c e g c' e' > 1 ^\markup
      \fret-diagram-terse #"x;3-3;2-2;o;1-1;o;"
    < d a d' f'> ^\markup
      \fret-diagram-terse #"x;x;o;2-2;3-3;1-1;"
  }
>>
@end lilypond

Other fret diagram properties must be adjusted using @code{\override} when using
the fret-diagram-terse markup.

@cindex fret-diagram-verbose markup

@funindex fret-diagram-verbose
@funindex \fret-diagram-verbose

The fret-diagram-verbose markup string is in the format of a Scheme list.  Each
element of the list indicates an item to be placed on the fret diagram.

@lilypond[quote, verbatim]
<<  \context ChordNames {
     \chordmode {
       c1 d:m
     }
  }
  \context Staff {
    \clef "treble_8"
    < c e g c' e' > 1 ^\markup
      \fret-diagram-verbose #'(
        (mute 6)
        (place-fret 5 3)
        (place-fret 4 2)
        (open 3)
        (place-fret 2 1)
        (open 1)
      )
    < d a d' f'> ^\markup
      \fret-diagram-verbose #'(
        (mute 6)
        (mute 5)
        (open 4)
        (place-fret 3 2)
        (place-fret 2 3)
        (place-fret 1 1)
      )
  }
>>
@end lilypond

Fingering indications and barres can be included in a
fret-diagram-verbose markup string.  Unique to the
fret-diagram-verbose interface is a capo indication that
can be placed on the fret diagram.  The capo indication is
a thick bar that covers all strings.  The fret with the
capo will be the lowest fret in the fret diagram.

@c \override is necessary to make fingering visible
@lilypond[quote, verbatim]
<<
  \context ChordNames {
     \chordmode {
       f1 g c
     }
  }
  \context Staff {
    \clef "treble_8"
    \override Voice.TextScript
      #'(fret-diagram-details finger-code) = #'below-string

    < f, c f a c' f'>1 ^\markup
      \fret-diagram-verbose #'(
        (place-fret 6 1)
        (place-fret 5 3)
        (place-fret 4 3)
        (place-fret 3 2)
        (place-fret 2 1)
        (place-fret 1 1)
        (barre 6 1 1)
      )
    < g, b, d g b g'> ^\markup
      \fret-diagram-verbose #'(
        (place-fret 6 3 2)
        (place-fret 5 2 1)
        (open 4)
        (open 3)
        (open 2)
        (place-fret 1 3 3)
      )
    < c e g c' e'> ^\markup
      \fret-diagram-verbose #'(
        (capo 3)
        (mute 6)
        (place-fret 4 5 1)
        (place-fret 3 5 2)
        (place-fret 2 5 3)
      )
   }
>>
@end lilypond

All other fret diagram properties must be adjusted using @code{\override}
when using the fret-diagram-verbose markup.

@ignore
The following example shows the three fret-diagram markup
interfaces, along with examples of common tweaks.  For example,
the size of the verbose fret diagram is reduced to 0.75, and the
finger indications are specified to appear below the diagram.  The
terse diagram includes tweaks to specify placement of finger code
and color of dots.

@lilypond[verbatim,ragged-right,quote]
\new Voice {
  \clef "treble_8"
  d^\markup \fret-diagram #"6-x;5-x;4-o;3-2;2-3;1-2;"
  d d d
  fis^\markup \override #'(size . 0.75) {
    \override #'(finger-code . below-string) {
      \fret-diagram-verbose #'((place-fret 6 2 1) (barre 6 1 2)
                               (place-fret 5 4 3)
                               (place-fret 4 4 4)
                               (place-fret 3 3 2)
                               (place-fret 2 2 1)
                               (place-fret 1 2 1))
    }
  }
  fis fis fis
  c^\markup \override #'(dot-radius . 0.35) {
    \override #'(finger-code . in-dot) {
      \override #'(dot-color . white) {
        \fret-diagram-terse #"x;3-1-(;5-2;5-3;5-4;3-1-);"
      }
    }
  }
  c c c
}
@end lilypond
@end ignore

@cindex customized fret diagram
@cindex fret diagram, customized
@cindex diagram, fret, customized

@funindex fret-diagram-interface

The graphical layout of a fret diagram can be customized according to
user preference through the properties of the @code{fret-diagram-interface}.
Details are found at @rinternals{fret-diagram-interface}.  For a fret diagram
markup, the interface properties belong to @code{Voice.TextScript}.

@snippets

@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
{customizing-markup-fret-diagrams.ly}


@seealso
Notation Reference:
@ref{Text markup commands}.

Snippets:
@rlsr{Fretted strings}.

Internals Reference:
@rinternals{fret-diagram-interface}.


@node Predefined fret diagrams
@unnumberedsubsubsec Predefined fret diagrams


@cindex fret diagrams
@cindex chord diagrams

@funindex FretBoards
@funindex stringTunings

Fret diagrams can be displayed using the @code{FretBoards} context.  By
default, the @code{FretBoards} context will display fret diagrams that
are stored in a lookup table:

@lilypond[verbatim, ragged-right, quote]
\include "predefined-guitar-fretboards.ly"
\context FretBoards {
  \chordmode {
    c1 d
  }
}
@end lilypond

The default predefined fret diagrams are contained in the file
@code{predefined-guitar-fretboards.ly}.  Fret diagrams are
stored based on the pitches of a chord and the value of
@code{stringTunings} that is currently in use.
@code{predefined-guitar-fretboards.ly} contains predefined
fret diagrams only for @code{guitar-tuning}.  Predefined fret
diagrams can be added for other instruments or other tunings
by following the examples found in
@code{predefined-guitar-fretboards.ly}.

Chord pitches can be entered
either as simultaneous music or using chord mode (see
@ref{Chord mode overview}).

@lilypond[verbatim, ragged-right,quote]
\include "predefined-guitar-fretboards.ly"
\context FretBoards {
  \chordmode {c1}
  <c' e' g'>1
}
@end lilypond

@cindex chord names with fret diagrams
@cindex fret diagrams with chord names

@funindex ChordNames
@funindex chordmode
@funindex \chordmode

It is common that both chord names and fret diagrams are displayed together.
This is achieved by putting a @code{ChordNames} context in parallel with
a @code{FretBoards} context and giving both contexts the same music.

@lilypond[verbatim, ragged-right, quote]
\include "predefined-guitar-fretboards.ly"
mychords = \chordmode{
  c1 f g
}

<<
  \context ChordNames {
    \mychords
  }
  \context FretBoards {
    \mychords
  }
>>
@end lilypond

@cindex transposing fret diagrams
@cindex fret diagrams, transposing
@cindex diagrams, fret, transposing

Predefined fret diagrams are transposable, as long as a diagram for the
transposed chord is stored in the fret diagram table.

@lilypond[verbatim, ragged-right, quote]
\include "predefined-guitar-fretboards.ly"
mychords = \chordmode{
  c1 f g
}

mychordlist = {
  \mychords
  \transpose c e { \mychords}
}
<<
  \context ChordNames {
    \mychordlist
  }
  \context FretBoards {
    \mychordlist
  }
>>
@end lilypond


The predefined fret diagram table contains seven chords (major, minor,
augmented, diminished, dominant seventh, major seventh, minor seventh)
for each of 17 keys.  A complete list of the predefined fret diagrams is
shown in @ref{Predefined fretboard diagrams}.  If there is no entry in
the table for a chord, the FretBoards engraver will calculate a
fret-diagram using the automatic fret diagram functionality described in
@ref{Automatic fret diagrams}.

@lilypond[verbatim, ragged-right, quote]
\include "predefined-guitar-fretboards.ly"
mychords = \chordmode{
  c1 c:9
}

<<
  \context ChordNames {
    \mychords
  }
  \context FretBoards {
    \mychords
  }
>>
@end lilypond

@cindex fret diagrams, adding custom
@cindex custom fret diagrams, adding
@cindex adding custom fret diagrams

Fret diagrams can be added to the fret diagram table.  To add a diagram,
you must specify the chord for the diagram, the tuning to be used, and
a definition for the diagram.  The diagram definition can be either a
fret-diagram-terse definition string or a fret-diagram-verbose
marking list.

@lilypond[verbatim, ragged-right, quote]
\include "predefined-guitar-fretboards.ly"

\storePredefinedDiagram \chordmode {c:9}
                        #guitar-tuning
                        #"x;3-2;2-1;3-3;3-4;x;"

mychords = \chordmode{
  c1 c:9
}

<<
  \context ChordNames {
    \mychords
  }
  \context FretBoards {
    \mychords
  }
>>
@end lilypond

Different fret diagrams for the same chord name can be stored using different
octaves of pitches.  The different octave should be at least two octaves
above or below the default octave, because the octaves above and  below the
default octave are used for transposing fretboards.

@lilypond[verbatim, ragged-right, quote]
\include "predefined-guitar-fretboards.ly"

\storePredefinedDiagram \chordmode {c''}
                        #guitar-tuning
                        #(offset-fret 2 (chord-shape 'bes guitar-tuning))

mychords = \chordmode{
  c1 c''
}

<<
  \context ChordNames {
    \mychords
  }
  \context FretBoards {
    \mychords
  }
>>
@end lilypond

@cindex fretted instruments, chord shapes
@cindex chord shapes for fretted instruments

@funindex \addChordShape
@funindex add ChordShape
@funindex storePredefinedDiagram
@funindex \storePredefinedDiagram

In addition to fret diagrams, LilyPond stores an internal list of chord
shapes.  The chord shapes are fret diagrams that can be shifted along
the neck to different posistions to provide different chords.  Chord
shapes can be added to the internal list and then used to define
predefined fret diagrams.  Because they can be moved to various
positions on the neck, chord shapes will normally not contain
any open strings.  Like fret diagrams, chord shapes can be
entered as either fret-diagram-terse strings or fret-diagram-verbose
marking lists.

@lilypond[verbatim, ragged-right, quote]
\include "predefined-guitar-fretboards.ly"

% add a new chord shape

\addChordShape #'powerf #guitar-tuning #"1-1;3-3;3-4;x;x;x;"

% add some new chords based on the power chord shape

\storePredefinedDiagram \chordmode {f''}
                        #guitar-tuning
                        #(chord-shape 'powerf guitar-tuning)
\storePredefinedDiagram \chordmode {g''}
                        #guitar-tuning
                        #(offset-fret 2 (chord-shape 'powerf guitar-tuning))

mychords = \chordmode{
  f1 f'' g g''
}

<<
  \context ChordNames {
    \mychords
  }
  \context FretBoards {
    \mychords
  }
>>
@end lilypond

The graphical layout of a fret diagram can be customized according to
user preference through the properties of the @code{fret-diagram-interface}.
Details are found at @rinternals{fret-diagram-interface}.  For a
predefined fret diagram, the interface properties belong to
@code{FretBoards.FretBoard}.

@snippets

@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
{customizing-fretboard-fret-diagrams.ly}

@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
{defining-predefined-fretboards-for-other-instruments.ly}

@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
{chordchanges-for-fretboards.ly}


@seealso
Notation Reference:
@ref{Custom tablatures},
@ref{Automatic fret diagrams},
@ref{Chord mode overview},
@ref{Predefined fretboard diagrams}.

Installed Files:
@file{ly/@/predefined@/-guitar@/-fretboards@/.ly},
@file{ly/@/predefined@/-guitar@/-ninth@/-fretboards@/.ly}.

Snippets:
@rlsr{Fretted strings}.

Internals Reference:
@rinternals {fret-diagram-interface}.


@node Automatic fret diagrams
@unnumberedsubsubsec Automatic fret diagrams

@cindex fret diagrams, automatic
@cindex chord diagrams, automatic
@cindex automatic fret diagrams
@cindex automatic chord diagrams

Fret diagrams can be automatically created from entered notes using the
@code{FretBoards} context.  If no predefined diagram is available for
the entered notes in the active @code{stringTunings}, this context
calculates strings and frets that can be used to play the notes.

@lilypond[quote,ragged-right,verbatim]
<<
  \context ChordNames {
     \chordmode {
       f1 g
     }
  }
  \context FretBoards {
    < f, c f a c' f'>1
    < g,\6 b, d g b g'>
  }
  \context Staff {
    \clef "treble_8"
    < f, c f a c' f'>1
    < g, b, d g b' g'>
  }
>>
@end lilypond

@funindex predefinedFretboardsOff
@funindex \predefinedFretboardsOff
@funindex predefinedFretboardsOn
@funindex \predefinedFretboardsOn

As no predefined diagrams are loaded by default, automatic calculation
of fret diagrams is the default behavior.  Once default diagrams are
loaded, automatic calculation can be enabled and disabled with predefined
commands:

@lilypond[quote,ragged-right,verbatim]

\storePredefinedDiagram <c e g c' e'>
                        #guitar-tuning
                        #"x;3-1-(;5-2;5-3;5-4;3-1-1);"
<<
  \context ChordNames {
     \chordmode {
       c1 c c
     }
  }
  \context FretBoards {
    <c e g c' e'>1
    \predefinedFretboardsOff
    <c e g c' e'>
    \predefinedFretboardsOn
    <c e g c' e'>
  }
  \context Staff {
    \clef "treble_8"
    <c e g c' e'>1
    <c e g c' e'>
    <c e g c' e'>
  }
>>
@end lilypond



Sometimes the fretboard calculator will be unable to find
an acceptable diagram.  This can often be remedied by
manually assigning a note to a string.  In many cases, only one
note need be manually placed on a string; the rest of
the notes will then be placed appropriately by the @code{FretBoards}
context.

@cindex fret diagrams, adding fingerings
@cindex fingerings, adding to fret diagrams

Fingerings can be added to FretBoard fret diagrams.

@lilypond[quote, verbatim]
<<
  \context ChordNames {
     \chordmode {
       c1 d:m
     }
  }
  \context FretBoards {
    < c-3 e-2 g c'-1 e' > 1
    < d a-2 d'-3 f'-1>
  }
  \context Staff {
    \clef "treble_8"
    < c e g c' e' > 1
    < d a d' f'>
  }
>>
@end lilypond

The minimum fret to be used in calculating strings and frets for
the FretBoard context can be set with the @code{minimumFret}
property.

@lilypond[quote, verbatim]
<<
  \context ChordNames {
     \chordmode {
       d1:m d:m
     }
  }
  \context FretBoards {
    < d a d' f'>
    \set FretBoards.minimumFret = #5
    < d a d' f'>
  }
  \context Staff {
    \clef "treble_8"
    < d a d' f'>
    < d a d' f'>
  }
>>
@end lilypond

The strings and frets for the @code{FretBoards} context depend
on the @code{stringTunings} property, which has the same meaning
as in the TabStaff context.  See @ref{Custom tablatures} for
information on the @code{stringTunings} property.

The graphical layout of a fret diagram can be customized according to
user preference through the properties of the @code{fret-diagram-interface}.
Details are found at @rinternals{fret-diagram-interface}.  For a
@code{FretBoards} fret diagram, the interface properties belong to
@code{FretBoards.FretBoard}.


@predefined
@code{\predefinedFretboardsOff},
@code{\predefinedFretboardsOn}.
@endpredefined


@seealso
Notation Reference:
@ref{Custom tablatures}.

Snippets:
@rlsr{Fretted strings}.

Internals Reference:
@rinternals {fret-diagram-interface}.


@node Right-hand fingerings
@unnumberedsubsubsec Right-hand fingerings

@cindex fretted instruments, right hand fingerings
@cindex fingerings, right hand for fretted instruments
@cindex right hand fingerings for fretted instruments

@funindex rightHandFinger
@funindex \rightHandFinger

Right-hand fingerings @var{p-i-m-a} must be entered within a
chord construct @code{<>} for them to be printed in the score,
even when applied to a single note.

@warning{There @strong{must} be a hyphen after the note and a space
before the closing @code{>}.}

@lilypond[quote,verbatim,relative=0]
\clef "treble_8"
<c-\rightHandFinger #1 >4
<e-\rightHandFinger #2 >
<g-\rightHandFinger #3 >
<c-\rightHandFinger #4 >
<c,-\rightHandFinger #1 e-\rightHandFinger #2
  g-\rightHandFinger #3 c-\rightHandFinger #4 >1
@end lilypond

For convenience, you can abbreviate @code{\rightHandFinger} to something
short, for example @code{RH},

@example
#(define RH rightHandFinger)
@end example


@snippets

@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
{placement-of-right-hand-fingerings.ly}

@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
{fingerings,-string-indications,-and-right-hand-fingerings.ly}


@seealso
Snippets:
@rlsr{Fretted strings}.

Internals Reference:
@rinternals{StrokeFinger}.


@node Guitar
@subsection Guitar

Most of the notational issues associated with guitar music are
covered sufficiently in the general fretted strings section, but there
are a few more worth covering here.  Occasionally users want to
create songbook-type documents having only lyrics with chord
indications above them.  Since LilyPond is a music typesetter,
it is not recommended for documents that have no music notation
in them.  A better alternative is a word processor, text editor,
or, for experienced users, a typesetter like GuitarTeX.

@menu
* Indicating position and barring::
* Indicating harmonics and dampened notes::
@end menu

@node Indicating position and barring
@unnumberedsubsubsec Indicating position and barring

@cindex indicating position and barring for fretted instruments
@cindex fretted instruments, indicating position and barring

This example demonstrates how to include guitar position and
barring indications.

@lilypond[quote,ragged-right,fragment,verbatim,relative=0]
\clef "treble_8"
b16 d g b e
\textSpannerDown
\override TextSpanner #'(bound-details left text) = #"XII "
  g16\startTextSpan
  b16 e g e b g\stopTextSpan
e16 b g d
@end lilypond


@seealso
Notation Reference:
@ref{Text spanners}.

Snippets:
@rlsr{Fretted strings},
@rlsr{Expressive marks}.


@node Indicating harmonics and dampened notes
@unnumberedsubsubsec Indicating harmonics and dampened notes

@cindex fretted instruments, dampened notes
@cindex fretted instruments, harmonics
@cindex dampened notes on fretted instruments
@cindex harmonics on fretted instruments

Special note heads can be used to indicate dampened notes or
harmonics.  Harmonics are normally further explained with a
text markup.

@lilypond[quote,ragged-right,verbatim]
\relative c' {
  \clef "treble_8"
  \override Staff.NoteHead #'style = #'cross
  g8 a b c b4
  \override Staff.NoteHead #'style = #'harmonic-mixed
  d^\markup { \italic { \fontsize #-2 { "harm. 12" }}} <g b>1
}
@end lilypond


@seealso
Snippets:
@rlsr{Fretted strings}.

Notation Reference:
@ref{Special note heads},
@ref{Note head styles}.


@node Banjo
@subsection Banjo

@menu
* Banjo tablatures::
@end menu

@node Banjo tablatures
@unnumberedsubsubsec Banjo tablatures

@cindex banjo tablatures
@cindex tablature, banjo

LilyPond has basic support for the five-string banjo.  When making tablatures
for five-string banjo, use the banjo tablature format function to get
correct fret numbers for the fifth string:

@c due to crazy intervals of banjo music, absolute pitch is recommended

@lilypond[quote,ragged-right,fragment,verbatim]
\new TabStaff <<
  \set TabStaff.tablatureFormat = #fret-number-tablature-format-banjo
  \set TabStaff.stringTunings = #banjo-open-g-tuning
  {
    \stemDown
    g8 d' g'\5 a b g e d' |
    g4 d''8\5 b' a'\2 g'\5 e'\2 d' |
    g4
  }
>>
@end lilypond

@cindex banjo tunings
@cindex tunings, banjo

@funindex banjo-c-tuning
@funindex banjo-modal-tuning
@funindex banjo-open-d-tuning
@funindex banjo-open-dm-tuning
@funindex four-string-banjo

A number of common tunings for banjo are predefined in LilyPond:
@code{banjo-c-tuning} (gCGBD), @code{banjo-modal-tuning} (gDGCD),
@code{banjo-open-d-tuning} (aDF#AD) and @code{banjo-open-dm-tuning}
(aDFAD).

These tunings may be converted to four-string banjo tunings using the
@code{four-string-banjo} function:

@example
\set TabStaff.stringTunings = #(four-string-banjo banjo-c-tuning)
@end example


@seealso
Snippets:
@rlsr{Fretted strings}.

Installed Files:
@file{scm/@/output@/-lib@/.scm} contains predefined banjo tunings.