@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.  For details, see the Contributors'
    Guide, node Updating translation committishes..
@end ignore

@c \version "2.23.1"

@node Fretted string instruments
@section Fretted string instruments

@lilypondfile[quote]{snippets/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::
* Lute::
@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
(or @code{\transposition c} to get correct MIDI output).
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

@morerefs
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},
@ref{Instrument transpositions}.
@endmorerefs


@node String number indications
@unnumberedsubsubsec String number indications

@cindex string number
@cindex string vs.@: fingering number
@cindex fingering vs.@: string number

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

@lilypond[verbatim,quote,fragment]
\clef "treble_8"
c4\5 e\4 g2\3
<c\5 e\4 g\3>1
@end lilypond

When fingerings and string indications are used together, their
placement can be controlled by the order in which the two items appear
in the code @emph{only} if they appear inside of an explicit chord:
applied to whole chords or single notes @emph{outside} of chords,
fingerings are placed using a different mechanism.

@lilypond[verbatim,quote,fragment]
\clef "treble_8"
g4\3-0
g-0\3
<g\3-0>
<g-0\3>
@end lilypond

@funindex \arabicStringNumbers
@funindex \romanStringNumbers

String numbers may also, as is customary with unfretted strings,
be printed in Roman numerals and placed below the staff rather
than above.

@lilypond[verbatim,quote,fragment]
\clef "treble_8"
c'2\2
a\3
\romanStringNumbers
c'\2
\set stringNumberOrientations = #'(down)
a\3
\arabicStringNumbers
g1\4
@end lilypond

Most behaviors of string number indications (namely, the
@code{StringNumber} object), including their placement,
may be set in the same way as fingerings: see
@ref{Fingering instructions}.

@predefined
@code{\arabicStringNumbers},
@code{\romanStringNumbers}.
@endpredefined

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

Snippets:
@rlsr{Fretted strings}.

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


@node Default tablatures
@unnumberedsubsubsec Default tablatures

@cindex tablature, basic
@cindex tablature, 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
letter-like symbols in historical intavolatura).  The staff lines
in tablature indicate the string on which the note is to be played,
and a number placed on a staff line indicated the fret at which
the corresponding string is to be pressed.
Notes that are to be played simultaneously are vertically aligned.

By default, string 1 is the highest string, and corresponds to the top
line on the @code{TabStaff}.  The tuning of the @code{TabStaff}
strings defaults to the
standard guitar tuning (with 6 strings).  The notes are printed as
tablature, by using @code{TabStaff} and @code{TabVoice} contexts.  A
calligraphic tablature clef is added automatically.

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

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

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

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

@cindex fret

@funindex minimumFret
@funindex restrainOpenStrings

By default pitches are assigned to the lowest playing position on the
fretboard (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 don't want
to have string number indications appear in traditional notation, you
can override the respective stencil.  Usually it will be more
comfortable to define the playing position by using the value of
@code{minimumFret}.  The default value for minimumFret is 0.

Even when @code{minimumFret} is set, open strings are used whenever
possible.  This behavior can be changed by setting @code{restrainOpenStrings}
to @code{#t}.

@lilypond[quote,ragged-right,verbatim]
\layout { \omit Voice.StringNumber }
\new StaffGroup <<
   \new Staff \relative {
     \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 {
     c16 d e f g4
     c,16\5 d\5 e\4 f\4 g4\4
     \set TabStaff.minimumFret = #5
     \set TabStaff.restrainOpenStrings = ##t
     c,16 d e f g4
   }
>>
@end lilypond

@funindex \tabChordRepeats
@funindex \chordRepeats
@cindex chord, repetition
@cindex repetition, using @code{q}
@cindex @code{q}, chord repetition

Chord constructs can be repeated by the chord repetition symbol
@code{q}.  In combination with tabulatures, its behavior of removing
string and finger numbers alongside with other events is cumbersome, so
you'll want to run
@example
\chordRepeats #'(string-number-event fingering-event)
@end example
explicitly on music expressions in tabulature using @ref{Chord
repetition}.  This particular command is so common that it is available
as @code{\tabChordRepeats}.

@lilypond[quote,verbatim]
guitar = \relative {
  r8 <gis-2 cis-3 b-0>~ q4 q8~ 8 q4
}

\new StaffGroup <<
  \new Staff {
    \clef "treble_8"
    \guitar
  }
  \new TabStaff {
    \tabChordRepeats \guitar
  }
>>
@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 {
  \repeat volta 2 {
    e'2. f4~
    2 g2~
  }
  \alternative {
     \volta 1 { g4 f2. }
     \volta 2 { g4\repeatTie c,2. }
  }
  b1~
  \break
  b1
  \bar "|."
}

\score {
  <<
    \new StaffGroup  <<
      \new Staff {
        \clef "treble_8"
        \ties
      }
      \new 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 {
  \repeat volta 2 {
    e'2. f4~
    2 g2~ }
  \alternative {
    \volta 1 { g4 f2. }
    \volta 2 { g4\repeatTie c,2. }
  }
  b1~
  \break
  b1
  \bar "|."
}

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

@cindex harmonic indication, in tablature notation
@cindex tablature, and harmonic indications
@funindex \harmonic
@funindex \harmonicByFret
@funindex \harmonicByRatio

Harmonic indications can be added to tablature notation as sounding
pitches:

@lilypond[verbatim,quote]
\layout { \omit Voice.StringNumber }
firstHarmonic = {
  d'4\4\harmonic
  g'4\3\harmonic
  b'2\2\harmonic
}
\score {
  <<
    \new Staff {
      \clef "treble_8"
      \firstHarmonic
    }
    \new TabStaff { \firstHarmonic }
  >>
}
@end lilypond

Note that the command @code{\harmonic} must always be attached to single
notes (possibly inside of a chord) instead of whole chords.
It only makes sense for open-string harmonics
in the 12th fret. All other harmonics should be calculated by LilyPond.
This can be achieved by indicating the fret where a finger of the
fretting hand should touch a string.

@lilypond[verbatim,quote]
fretHarmonics = {
  \harmonicByFret #5 d16\4
  \harmonicByFret #4 d16\4
  \harmonicByFret #3 d8\4
  \harmonicByFret #5 <g\3 b\2>2.
}
\score {
  <<
    \new Staff {
      \clef "treble_8"
      \fretHarmonics
    }
    \new TabStaff { \fretHarmonics }
  >>
}
@end lilypond

Alternatively, harmonics can be computed by defining the ratio of
string lengths above and below the harmonic fingering.

@lilypond[verbatim,quote]
ratioHarmonics = {
  \harmonicByRatio #1/2 <g\3 b\2 e'\1>4
  \harmonicByRatio #1/3 <g\3 b\2 e'\1>4
  \harmonicByRatio #1/4 { g8\3 b8\2 e'4\1 }
}
\score {
  <<
    \new Staff {
      \clef "treble_8"
      \ratioHarmonics
    }
    \new TabStaff { \ratioHarmonics }
  >>
}
@end lilypond

@cindex string bending, in tablature notation
@cindex tablature, and string bending
@cindex bending, string, in tablature notation
@funindex \preBend
@funindex \bendHold
@funindex \preBendHold
@funindex \bendStartLevel

String bendings can be added to tablature notation.
A bending is introduced by appending @code{\^} to the note or chord to be bent;
it terminates automatically at the next note or chord.
Available are the following styles: the default prints a curve with an arrow
head up or down, @code{'hold} a dashed horizontal line, @code{'pre-bend} a
vertical line with an arrow head, and @code{'pre-bend-hold} a vertical line with
an arrow head continued by a dashed line.

@lilypond[verbatim,quote]
bend-styles = {
  <>^"default"
  f'4\^ g'4\^ f'2

  <>^"'hold"
  \grace f'4\^ g'1\bendHold \^ g'1

  <>^"'pre-bend"
  \grace f'4\preBend \^ g'1\bendHold \^ g'1

  <>^"'pre-bend-hold"
  \grace f'4\preBendHold \^ g'1\bendHold \^ g'1\^ f'

  \bar "|."
}

\score {
  \new StaffGroup
  <<
    \new Staff {
      \override TextScript.font-size = -2
      \clef "G_8"
      \bend-styles
    }
    \new TabStaff \bend-styles
  >>
  \layout {
    \context {
      \Voice
      \omit StringNumber
    }
    \context {
      \TabStaff
      minimumFret = #5
    }
    \context {
      \TabVoice
      \consists Bend_spanner_engraver
    }
  }
}
@end lilypond

Open strings are usually not bent.  To have them bent as well set the
property @code{bend-me} to @code{#t}.  To exclude other notes from being bent
set it to @code{#f}.

@lilypond[verbatim,quote]
mus = {
  <>^"default"
  <a b f'>4\^
  <ais b fis'>\^
  <a b f'>2

  <>^"bend open strings"
  <a \tweak bend-me ##t b f'>4\^
  <ais \tweak bend-me ##t bis fis'>\^
  <a b f'>2

  <>^"exclude other strings"
  <g \tweak bend-me ##f b\3 d'>4\^
  <a e'\2 >\^
  <g \tweak bend-me ##f b\3 d'>2

  \bar "|."
}

\score {
  \new StaffGroup
  <<
    \new Staff {
      \override TextScript.font-size = -2
      \clef "G_8"
      \mus
    }
    \new TabStaff \mus
  >>
  \layout {
    \context {
      \Voice
      \omit StringNumber
    }
    \context {
      \TabVoice
      \consists Bend_spanner_engraver
    }
  }
}
@end lilypond

For consecutive bendings the starting bend may need to have an appropriate
setting for @code{details.successive-level}.  For convenience there is the
function @code{bendStartLevel}, taking an integer.

@lilypond[verbatim,quote]
printNext = -\tweak details.target-visibility ##t \etc

mus = {
  c'4\3\^ cis'\3 \^ d'2\3

  \grace bes4\3\preBendHold \bendStartLevel 2 \printNext \^
  d'4\3\bendHold \^ d'2\3\^ des'4\3 \^ c'1\3

  \bar "|."
}

\score {
  \new StaffGroup
  <<
    \new Staff {
      \override TextScript.font-size = -2
      \clef "G_8"
      \mus
    }
    \new TabStaff \mus
  >>
  \layout {
    \context {
      \Voice
      \omit StringNumber
    }
    \context {
      \TabVoice
      \consists Bend_spanner_engraver
    }
  }
}
@end lilypond

Per default the @code{BendSpanner} ends at the following note or chord even
if it is tied to the starting note or chord.  A single @code{NoteColumn} may be
skipped by using @code{\skipNC}.  A group of @code{NoteColumn}s can be skipped
by using @code{\skipNCs} at the beginning and @code{\endSkipNCs} at the end.


@lilypond[verbatim,quote]
bends-with-ties-and-skips = {
  a'4~\^ \skipNC a'4~ \skipNC a'4 b'4
  a'4~ a'4~\^ \skipNC a'4 b'4
  a'4~ a'4~ a'4\^ b'4
  c'2\^ d'~ \bendHold \^ \skipNC d'~ d'\^ c'
  \grace { c'8-\preBendHold \^ }
  \skipNCs d'2~ d'2~ \endSkipNCs d'\^ c'2
  \bar "|."
}

\score {
  \new StaffGroup
  <<
    \new Staff {
      \clef "G_8"
      \bends-with-ties-and-skips
    }
    \new TabVoice \bends-with-ties-and-skips
  >>
  \layout {
    \context {
      \Voice
      \omit StringNumber
    }
    \context {
      \TabStaff
      minimumFret = #3
      restrainOpenStrings = ##t
    }
    \context {
      \TabVoice
      \consists Bend_spanner_engraver
    }
  }
}
@end lilypond

@predefined
@code{\skipNCs},
@code{\skipNC},
@code{\endSkipNCs}.
@endpredefined


@snippets

@cindex stem, in tablature
@cindex tablature, and stems
@cindex beam, in tablature
@cindex tablature, and beams
@cindex beam, horizontal
@cindex horizontal beams
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/stem-and-beam-behavior-in-tablature.ly}

@cindex polyphony, in tablatures
@cindex tablature, and polyphony
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/polyphony-in-tablature.ly}

@cindex tablature, and harmonics
@cindex harmonic, in tablatures
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/open-string-harmonics-in-tablature.ly}

@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/fretted-string-harmonics-in-tablature.ly}

@cindex slide, in tablature notation
@cindex tablature, and slides
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/slides-in-tablature.ly}

@cindex chord, glissando, in tablatures
@cindex glissando, chords in tablatures
@cindex tablature, chord glissando
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/chord-glissando-in-tablature.ly}

@cindex hammer on
@cindex pull off
@cindex tablature, hammer on
@cindex tablature, pull off
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/hammer-on-and-pull-off.ly}

@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/hammer-on-and-pull-off-using-voices.ly}

@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/hammer-on-and-pull-off-using-chords.ly}


@morerefs
Notation Reference:
@ref{Chord repetition},
@ref{Glissando},
@ref{Harmonics},
@ref{Stems},
@ref{Written-out repeats}.

Snippets:
@rlsr{Fretted strings}.

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

@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 tablature, custom
@cindex tablature, banjo
@cindex tablature, mandolin
@cindex tablature, guitar
@cindex tablature, bass guitar
@cindex tablature, ukulele
@cindex tablature, predefined string tunings
@cindex fretted instrument, predefined string tunings
@cindex predefined string tuning, for fretted instruments
@cindex tablature, violin
@cindex tablature, viola
@cindex tablature, cello
@cindex tablature, bass
@cindex tablature, double bass

@funindex stringTunings

LilyPond tablature 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, bass guitar, ukulele, violin, viola, cello, and double bass.
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 Voice \with {
    \omit StringNumber
  } {
    \clef "bass_8"
    \relative {
      c,4 d e f
    }
  }
  \new TabStaff \with {
    stringTunings = #bass-tuning
  } {
    \relative {
      c,4 d e f
    }
  }
>>
@end lilypond

The default string tuning is @code{guitar-tuning}, which
is the standard @w{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 @file{ly/string-@/tunings-@/init.ly}.

@funindex \stringTuning
@cindex tablature, custom string tunings
@cindex custom string tuning

Any desired string tuning can be created.  The
@code{\stringTuning} function can be
used to define a string tuning which can be used
to set @code{stringTunings} for the current context.

Its argument is a chord construct
defining the pitches of each string in the tuning.
The chord construct must be in absolute octave mode,
see @ref{Absolute octave entry}.  The string
with the highest number (generally the lowest string) must
come first in the chord.  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''4 g'' b'' c'''
}

<<
  \new Staff {
    \clef treble
    \mynotes
  }
  \new TabStaff {
    \set Staff.stringTunings = \stringTuning <c' g' d'' a''>
    \mynotes
  }
>>
@end lilypond

The @code{stringTunings} property is also used by
@code{FretBoards} to calculate automatic fret diagrams.

String tunings are used as part of the hash key
for predefined fret diagrams
(see @ref{Predefined fret diagrams}).

The previous example could also be written as follows:

@lilypond[quote,verbatim]
custom-tuning = \stringTuning <c' g' d'' a''>

mynotes = {
  c'4 e' g' c'' |
  e''4 g'' b'' c'''
}

<<
  \new Staff {
    \clef treble
    \mynotes
  }
  \new TabStaff {
    \set TabStaff.stringTunings = #custom-tuning
    \mynotes
  }
>>
@end lilypond

Internally, 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 a LilyPond pitch
object.  Pitch objects are created with the Scheme function
@code{ly:make-pitch} (see @rinternals{Scheme functions}).

@code{\stringTuning} creates such an object from chord input.

LilyPond automatically calculates the number of lines in the
@code{TabStaff} and the number of strings in an automatically
calculated @code{FretBoard} as the number of elements
in @code{stringTunings}.

To let all @code{TabStaff} contexts use the same custom tuning
by default, you can use

@example
\layout @{
  \context @{
    \TabStaff
    stringTunings = \stringTuning <c' g' d'' a''>
  @}
@}
@end example


@cindex moderntab clef
@cindex clef, moderntab
@cindex clef, tab
@cindex tab clef

A modern tab clef can also be used.

@lilypond[quote,ragged-right,verbatim]
\new TabStaff {
  \clef moderntab
  <a, e a>1
  \break
  \clef tab
  <a, e a>1
}
@end lilypond

The modern tab clef supports tablatures from 4 to 7 strings.

@cindex microtone, tab
@cindex quarter tone, tab
@cindex tab microtones
@cindex tab quarter tones

@code{TabStaff} may support microtones like quarter tones, which
can be played using bendings.
@code{supportNonIntegerFret = ##t} needs to be set in
@code{Score} context.  However, microtones are not supported in
@code{FretBoards}.

@lilypond[quote,ragged-right,verbatim]
\layout {
  \context {
    \Score
    supportNonIntegerFret = ##t
  }
}

custom-tuning = \stringTuning <e, a, d ges beh eeh'>

mus = \relative {
  eeses'4
  eeseh
  ees
  eeh
  e
  eih
  eis
  eisih
  eisis
}

<<
  \new Staff << \clef "G_8" \mus >>
  \new TabStaff \with { stringTunings = \custom-tuning } \mus
>>
@end lilypond

@morerefs
Notation Reference:
@ref{Absolute octave entry},
@ref{Predefined fret diagrams}.

Installed Files:
@file{ly/string-tunings-init.ly},
@file{scm/tablature.scm}.

Snippets:
@rlsr{Fretted strings}.

Internals Reference:
@rinternals{Tab_note_heads_engraver},
@rinternals{Scheme functions}.
@endmorerefs

@knownissues
Automatic tablature calculations do not work properly in most
cases for instruments where string pitches do not vary
monotonically with string number, such as ukuleles.


@node Fret diagram markups
@unnumberedsubsubsec Fret diagram markups

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

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
syntax of the different markup strings used to define
fret diagrams are found at @ref{Instrument Specific Markup}.

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]
<<
  \new ChordNames {
    \chordmode {
      c1 d:m
    }
  }
  \new 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'>1^\markup {
      \fret-diagram "6-x;5-x;4-o;3-2;2-3;1-1;"
    }
  }
>>
@end lilypond

@cindex barre indication

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

@lilypond[quote, verbatim]
<<
  \new ChordNames {
     \chordmode {
       f1 g
     }
  }
  \new 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'>1^\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
@cindex ukulele

@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]
<<
  \new ChordNames {
     \chordmode {
       f1 g
     }
  }
  \new 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'>1^\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 accommodate
different instruments such as banjos and ukuleles with the fret diagram
markup string.

@lilypond[quote, verbatim]
<<
  \new ChordNames {
    \chordmode {
      a1
    }
  }
  \new Staff {
    % An 'A' chord for ukulele
    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]
<<
  \new ChordNames {
    \chordmode {
      c1 d:m
    }
  }
  \new 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'>1^\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]
<<
  \new ChordNames {
    \chordmode {
      c1 d:m
    }
  }
  \new 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'>1^\markup {
      \fret-diagram "p:0.2;6-x;5-x;4-o;3-2;2-3;1-1;"
    }
  }
>>
@end lilypond

@cindex left-handed fret diagram
@cindex fret diagram, left-handed

Fret-diagrams may be printed left-handed

@lilypond[verbatim,quote]
\markup
  \center-column {
    "C"
    "(left-handed)"
     \override #`(fret-diagram-details . ((handedness . ,LEFT)))
     \fret-diagram "6-x;5-3-3;4-2-2;3-o;2-1;1-o;"
  }
@end lilypond

@cindex @code{\fret-diagram-terse} markup

@funindex \fret-diagram-terse

The @code{\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]
<<
  \new ChordNames {
    \chordmode {
      c1 d:m
    }
  }
  \new Staff {
    \clef "treble_8"
    <c e g c' e'>1^\markup {
      \fret-diagram-terse "x;3;2;o;1;o;"
    }
    <d a d' f'>1^\markup {
      \fret-diagram-terse "x;x;o;2;3;1;"
    }
  }
>>
@end lilypond

Barre indicators can be included in the @code{\fret-diagram-terse}
markup string.

@lilypond[quote, verbatim]
<<
  \new ChordNames {
    \chordmode {
      f1 g
    }
  }
  \new 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'>1^\markup {
      \fret-diagram-terse "3-(;5;5;4;3;3-);"
    }
  }
>>
@end lilypond

Fingering indications can be included in the @code{\fret-diagram-terse}
markup string.

@c Need to use override to enable fingerings to show this -- can we do so?
@lilypond[quote, verbatim]
<<
  \new ChordNames {
    \chordmode {
      c1 d:m
    }
  }
  \new 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'>1^\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 @code{\fret-diagram-terse} markup.

Only one indication per string can be included in a
@code{\fret-diagram-terse} markup.  To have multiple indications
per string use a fret diagram or @code{\fret-diagram-verbose}
markup.

@cindex @code{\fret-diagram-verbose} markup
@cindex capo

@funindex \fret-diagram-verbose

The @code{\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]
<<
    \new ChordNames {
      \chordmode {
        c1 d:m
      }
    }
  \new 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'>1^\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
@code{\fret-diagram-verbose} markup string.  Unique to the
@code{\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.

Fingering indication dots can be colored as well as parenthesized;
the parenthesis's color can also be altered independently.

Markups can be placed into the dots as well.

@c \override is necessary to make fingering visible
@lilypond[quote, verbatim]
<<
    \new ChordNames {
      \chordmode {
        f1 g c c b
      }
    }
  \new 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'>1^\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 g c' e' g'>1^\markup {
      \fret-diagram-verbose #'(
        (capo 3)
        (mute 6)
        (place-fret 4 5 1)
        (place-fret 3 5 2)
        (place-fret 2 5 3)
      )
    }
    \override Voice.TextScript.size = 1.4
    <c g c' e' g'>1^\markup {
      \fret-diagram-verbose #'(
        (place-fret 6 3 1 red parenthesized default-paren-color)
        (place-fret 5 3 1 inverted)
        (place-fret 4 5 2 blue parenthesized)
        (place-fret 3 5 3 blue)
        (place-fret 2 5 4 blue)
        (place-fret 1 3 1 inverted)
      )
    }
    \override Voice.TextScript.size = 1.5
    <b, fis b dis' fis'>1^\markup
      \override #'(fret-diagram-details . ((finger-code . in-dot)))
      \fret-diagram-verbose #`(
        (place-fret 5 2 1)
        (place-fret 4 4 "fis" red)
        (place-fret 3 4 "b" red)
        (place-fret
          2 4
          ,#{ \markup
                \concat {
                  \vcenter "d"
                  \fontsize #-5
                  \musicglyph "accidentals.sharp"} #}
          red)
        (place-fret 1 2 1)
      )
  }
>>
@end lilypond

All other fret diagram properties must be adjusted using
@code{\override} when using the @code{\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"
  d4^\markup {
    \fret-diagram "6-x;5-x;4-o;3-2;2-3;1-2;"
  }
  d4 d d
  fis^\markup
    \override #'((size . 0.75) (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))
  fis4 fis fis
  c^\markup
    \override #'((dot-radius . 0.35) (finger-code . in-dot)
                 (dot-color . white))
    \fret-diagram-terse "x;3-1-(;5-2;5-3;5-4;3-1-);"
  c4 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

@cindex fret diagram, changing orientation
@cindex orientation of fret diagram, changing
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/changing-fret-orientations.ly}

@cindex fret diagram, customized
@cindex custom fret diagram
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/customizing-markup-fret-diagrams.ly}

@morerefs
Notation Reference:
@ref{Instrument Specific Markup}.

Snippets:
@rlsr{Fretted strings}.

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


@node Predefined fret diagrams
@unnumberedsubsubsec Predefined fret diagrams

@cindex fret diagram
@cindex fret diagram, ukulele
@cindex fret diagram, mandolin
@cindex chord diagram

@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"
\new FretBoards {
  \chordmode {
    c1 d
  }
}
@end lilypond

The default predefined fret diagrams are contained in the file
@file{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.
@file{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
@file{predefined-@/guitar-@/fretboards.ly}.

Fret diagrams for the ukulele are contained in the file
@file{predefined-@/ukulele-@/fretboards.ly}.

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

myChords = \chordmode { a1 a:m a:aug }

\new ChordNames {
  \myChords
}

\new FretBoards {
  \set Staff.stringTunings = #ukulele-tuning
  \myChords
}
@end lilypond

Fret diagrams for the mandolin are contained in the file @*
@file{predefined-mandolin-fretboards.ly}.

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

myChords = \chordmode { c1 c:m7.5- c:aug }

\new ChordNames {
  \myChords
}

\new FretBoards {
  \set Staff.stringTunings = #mandolin-tuning
  \myChords
}
@end lilypond

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"
\new FretBoards {
  \chordmode { c1 }
  <c' e' g'>1
}
@end lilypond

@cindex chord name, with fret diagrams
@cindex fret diagram, with chord names

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

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

@cindex transposing fret diagram
@cindex fret diagram, transposing
@cindex diagram, 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 }
}
<<
  \new ChordNames {
    \mychordlist
  }
  \new FretBoards {
    \mychordlist
  }
>>
@end lilypond


The predefined fret diagram table for guitar contains eight chords
(major, minor, augmented, diminished, dominant seventh, major
seventh, minor seventh, dominant ninth) for each of 17@tie{}keys.

The predefined fret diagram table for ukulele contains these chords
plus an additional three chords (major sixth, suspended second, and
suspended fourth).

@xref{Predefined fretboard diagrams} for a complete list of the
predefined fret diagrams.  If there is no entry in the table for a
chord, the @code{FretBoards} engraver calculates a fret diagram
using the automatic fret diagram functionality, @pxref{Automatic
fret diagrams}.

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

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

@cindex fret diagram, adding custom
@cindex custom fret diagram, adding
@cindex adding custom fret diagram

Fret diagrams can be added to the fret diagram table.  To add a
diagram, you must specify the hash table for the diagram, the chord
for the diagram, the tuning to be used, and a definition for the
diagram.  Normally, the hash table will be
@var{default-fret-table}.  The diagram definition can be either a
@code{\fret-diagram-terse} definition string or a
@code{\fret-diagram-verbose} marking list.

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

\storePredefinedDiagram #default-fret-table
                        \chordmode { c:maj9 }
                        #guitar-tuning
                        "x;3-2;o;o;o;o;"

mychords = \chordmode {
  c1 c:maj9
}

<<
  \new ChordNames {
    \mychords
  }
  \new 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 #default-fret-table
                        \chordmode { c'' }
                        #guitar-tuning
                        #(offset-fret 2
                           (chord-shape 'bes guitar-tuning))

mychords = \chordmode {
  c1 c''
}

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

@cindex fretted instrument, chord shape
@cindex chord shape, for fretted instrument

@funindex \addChordShape
@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 positions 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 @code{\fret-diagram-terse} strings or
@code{\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 #default-fret-table
                        \chordmode { f'' }
                        #guitar-tuning
                        #(chord-shape 'powerf guitar-tuning)
\storePredefinedDiagram #default-fret-table
                        \chordmode { g'' }
                        #guitar-tuning
                        #(offset-fret 2
                           (chord-shape 'powerf guitar-tuning))

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

<<
  \new ChordNames {
    \mychords
  }
  \new 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

@cindex fretboard fret diagram, customized
@cindex custom fretboard fret diagram
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/customizing-fretboard-fret-diagrams.ly}

@cindex fretboard, define predefined
@cindex define predefined fretboard
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/defining-predefined-fretboards-for-other-instruments.ly}

@cindex chord, suppressing repeated
@cindex repeated chords, suppressing
@cindex suppressing repeated chords
@funindex chordChanges
@lilypondfile[verbatim,quote,texidoc,doctitle,ragged-right]
{snippets/chordchanges-for-fretboards.ly}

@cindex fretboard, alternate table
@cindex alternate fretboard table
@funindex predefinedDiagramTable
@funindex \storePredefinedDiagram
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/fretboards-alternate-tables.ly}

@morerefs
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}, @*
@file{ly/predefined-ukulele-fretboards.ly}, @*
@file{ly/predefined-mandolin-fretboards.ly}.

Snippets:
@rlsr{Fretted strings}.

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


@node Automatic fret diagrams
@unnumberedsubsubsec Automatic fret diagrams

@cindex fret diagram, automatic
@cindex chord diagram, automatic
@cindex automatic fret diagram
@cindex automatic chord diagram

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]
<<
  \new ChordNames {
    \chordmode {
      f1 g
    }
  }
  \new FretBoards {
    <f, c f a c' f'>1
    <g,\6 b, d g b g'>1
  }
  \new Staff {
    \clef "treble_8"
    <f, c f a c' f'>1
    <g, b, d g b' g'>1
  }
>>
@end lilypond

@funindex \predefinedFretboardsOff
@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 #default-fret-table
                        <c e g c' e'>
                        #guitar-tuning
                        "x;3-1-(;5-2;5-3;5-4;3-1-1-);"
<<
  \new ChordNames {
    \chordmode {
      c1 c c
    }
  }
  \new FretBoards {
    <c e g c' e'>1
    \predefinedFretboardsOff
    <c e g c' e'>1
    \predefinedFretboardsOn
    <c e g c' e'>1
  }
  \new Staff {
    \clef "treble_8"
    <c e g c' e'>1
    <c e g c' e'>1
    <c e g c' e'>1
  }
>>
@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 diagram, adding fingering
@cindex fingering, adding to fret diagram

Fingerings can be added to @code{FretBoard} fret diagrams.

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

@funindex minimumFret

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

@lilypond[quote, verbatim]
<<
  \new ChordNames {
    \chordmode {
      d1:m d:m
    }
  }
  \new FretBoards {
    <d a d' f'>1
    \set FretBoards.minimumFret = #5
    <d a d' f'>1
  }
  \new Staff {
    \clef "treble_8"
    <d a d' f'>1
    <d a d' f'>1
  }
>>
@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 @code{TabStaff} context.  @xref{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

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

Snippets:
@rlsr{Fretted strings}.

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

@knownissues
Automatic fretboard calculations do not work properly for instruments
with non-monotonic tunings.


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

@cindex fretted instrument, right-hand fingering
@cindex fingering, right-hand, for fretted instruments
@cindex right-hand fingering, for fretted instruments

@funindex \rightHandFinger

Right-hand fingerings @var{p-i-m-a} must be entered using
@code{\rightHandFinger} followed by a number.

@warning{If the number is entered in Scheme notation, remember to append
a space before following it with a closing @code{>} or similar.}

@lilypond[quote,verbatim,fragment]
\clef "treble_8"
c4\rightHandFinger #1
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, @code{\rightHandFinger} may be abbreviated to something
shorter, for example @code{\RH}, by adding the appropriate definition
at the source file's top level:

@example
RH = \rightHandFinger \etc
@end example

Most behaviors of right-hand fingerings (namely, the @code{StrokeFinger}
object) may be set in the same way as ordinary fingerings: see
@ref{Fingering instructions}.

@snippets

@cindex placement, right-hand fingering
@cindex right-hand fingering, placement
@cindex fingering, right-hand, placement
@funindex strokeFingerOrientations
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/placement-of-right-hand-fingerings.ly}

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

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

Snippets:
@rlsr{Fretted strings}.

Internals Reference:
@rinternals{StrokeFinger}.
@endmorerefs


@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::
* Indicating power chords::
@end menu

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

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

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

@lilypond[quote,ragged-right,verbatim,fragment]
\relative {
  \clef "treble_8"
  b,16 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

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

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


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

@cindex fretted instrument, dampened note
@cindex fretted instrument, harmonics
@cindex dampened note, on fretted instrument
@cindex harmonics, on fretted instrument

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 {
  \clef "treble_8"
  \override NoteHead.style = #'harmonic-mixed
  d'8^\markup { \italic \fontsize #-2 "harm. 12" } <g b>4
}
@end lilypond

Dampened notes (also called @notation{dead notes}) are supported
within normal and tablature staves:

@lilypond[quote,ragged-right,verbatim]
music = \relative {
  < a\3 \deadNote c\2 a'\1 >4
  < b\3 \deadNote d\2 b'\1 >
  < c\3 \deadNote e\2 c'\1 >
  \deadNotesOn
  \tuplet 3/2 { g8 b e }
  \deadNotesOff
  < a,\3 c\2 e\1 >1
}
\new StaffGroup <<
  \new Staff {
    \clef "treble_8"
    \music
  }
  \new TabStaff {
    \music
  }
>>
@end lilypond

Another playing technique (especially used on electric guitars) is
called @notation{palm mute}.  The string is hereby partly muted by the
palm of the striking hand (hence the name).  LilyPond supports
the notation of palm mute-style notes by changing the note head to a
triangle shape.

@lilypond[quote,ragged-right,verbatim]
\new Voice { % Warning: explicit Voice instantiation is
             %    required to have palmMuteOff work properly
             %    when palmMuteOn comes at the beginning of
             %    the piece.
  \relative c, {
    \clef "G_8"
    \palmMuteOn
    e8^\markup { \musicglyph "noteheads.s2do"  = palm mute }
    < e b' e > e
    \palmMuteOff
    e e  \palmMute e e e |
    e8 \palmMute { e e e } e e e e |
    < \palmMute e b' e >8 \palmMute { e e e } < \palmMute e b' e >2
  }
}
@end lilypond

@morerefs
Snippets:
@rlsr{Fretted strings}.

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


@node Indicating power chords
@unnumberedsubsubsec Indicating power chords

@cindex power chord
@cindex chord, power

Power chords and their symbols can be engraved in chord mode or as chord
constructs.  As an exception, the fifth is specified in these chord
names, whereas it is usually left out in other chords (e.g., major or minor triads).

@lilypond[quote,ragged-right,verbatim]
ChordsAndSymbols = {
  \chordmode {
    e,,1:5
    a,,:5.8
    \set TabStaff.restrainOpenStrings = ##t
    \set minimumFret = #8
    c,:5
    f,:5.8
  }
  \set minimumFret = #2
  \set restrainOpenStrings = ##f
  <a, e> <a cis' e'>
  <g d' g'>
}
\score {
  <<
    \new ChordNames {
    \ChordsAndSymbols
    }
    \new Staff {
      \clef "treble_8"
      \ChordsAndSymbols
    }
    \new TabStaff {
      \ChordsAndSymbols
    }
  >>
}
@end lilypond

@morerefs
Music Glossary:
@rglos{power chord}.

Notation Reference:
@ref{Extended and altered chords},
@ref{Printing chord names}.

Snippets:
@rlsr{Fretted strings}.
@endmorerefs


@node Banjo
@subsection Banjo

@menu
* Banjo tablatures::
@end menu

@node Banjo tablatures
@unnumberedsubsubsec Banjo tablatures

@cindex banjo tablature
@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,verbatim]
music = {
  g8 d' g'\5 a b g e d' |
  g4 d''8\5 b' a'\2 g'\5 e'\2 d' |
  g4
}

<<
  \new Staff \with { \omit StringNumber }
  { \clef "treble_8"  \music }
  \new TabStaff \with {
    tablatureFormat = #fret-number-tablature-format-banjo
    stringTunings = #banjo-open-g-tuning
  }
  { \music }
>>
@end lilypond

@cindex banjo tuning
@cindex tuning, banjo

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

A number of common tunings for the five-string banjo are predefined:
@code{banjo-@/open-g-@/tuning} @w{(gDGBD)}, @code{banjo-@/c-tuning}
@w{(gCGBD)}, @code{banjo-@/modal-@/tuning} @w{(gDGCD)},
@code{banjo-@/open-d-@/tuning} @w{(aDF#AD)}, @code{banjo-@/open-dm-@/tuning}
@w{(aDFAD)}, @code{banjo-@/double-c-@/tuning} @w{(gCGCD)} and
@code{banjo-@/double-d-@/tuning} @w{(aDGDE)}.

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

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

@morerefs
Installed Files:
@file{ly/string-tunings-init.ly}.

Snippets:
@rlsr{Fretted strings}.
@endmorerefs


@node Lute
@subsection Lute

@menu
* Lute tablatures::
@end menu

@node Lute tablatures
@unnumberedsubsubsec Lute tablatures

@cindex lute tablature
@cindex tablature, lute

LilyPond supports tablature for lute.

To get additional bass strings use @code{additionalBassStrings}, where the
pitches of those strings are set. They will be printed below lowest line as:
a, /a, //a, ///a, 4, 5, etc.

@code{fret-letter-tablature-format} for @code{tablatureFormat} should be used,
probably also @code{fretLabels} for further customizing.

@lilypond[quote,ragged-right,verbatim]
m = { f'4 d' a f d a, g, fis, e, d, c,  \bar "|." }

\score {
  <<
    \new Staff { \clef bass \cadenzaOn  \m }
    \new TabStaff \m
  >>
  \layout {
    \context {
      \Score
      tablatureFormat = #fret-letter-tablature-format
    }
    \context {
      \TabStaff
      stringTunings = \stringTuning <a, d f a d' f'>
      additionalBassStrings = \stringTuning <c, d, e, fis, g,>
      fretLabels = #'("a" "b" "r" "d" "e" "f" "g" "h" "i" "k")
    }
  }
}
@end lilypond

@cindex lute tuning
@cindex tuning, lute

@knownissues
Using @code{FretBoards} with @code{additionalBassStrings} is not supported and
will yield unsatisfying results.
