@c -*- coding: utf-8; mode: texinfo; -*-
@ignore
    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  See TRANSLATION for details.
@end ignore

@c \version "2.11.53"

@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 guitar 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::           
* Automatic fret diagrams::               
* Fret diagram markups::
* Right-hand fingerings::       
@end menu

@node References for fretted strings
@subsubsection 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 with @ref{Fingering instructions}.

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

@item Instructions on handling multiple voices is described 
in @ref{Collision resolution}. 

@end itemize

@seealso

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

@node String number indications
@subsubsection String number indications

@cindex 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
@subsubsection Default tablatures
@cindex Tablatures, basic
@cindex Tablatures, default

Tablature notation is used for notating music for plucked string
instruments.  Pitches are not denoted with note heads, but by
numbers indicating on which string and fret a note must be played.  
LilyPond offers limited support for tablature.

The string number associated with a note is given as a backslash
followed by a number.  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 {
  a,4\5 c'\2 a\3 e'\1
  e\4 c'\2 a\3 e'\1
}
@end lilypond

@funindex minimumFret
@cindex fret


When no string is specified for a note, the note is assigned to
the lowest string that can generate the note with a fret number
greater than or equal to @code{minimumFret} is selected.  The
default value for @code{minimumFret} is 0.


@lilypond[quote,ragged-right,verbatim]
\new StaffGroup <<
   \new Staff \relative c {
     \clef "treble_8"
     c16 d e f g4
     c,16 d e f g4
   }
   \new TabStaff \relative c {
     c16 d e f g4
     \set TabStaff.minimumFret = #5
     c,16 d e f g4
   }
>>
@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


@node Custom tablatures
@subsubsection Custom tablatures
@cindex Tablatures, custom

You can change the tuning of the strings.  A string tuning is
given as a Scheme list with one integer number for each string,
the number being the pitch (measured in semitones relative to
middle C) of an open string.  The numbers specified for
@code{stringTunings} are the numbers of semitones to subtract or
add, starting the specified pitch by default middle C, in string
order.  LilyPond automatically calculates the number of strings by
looking at @code{stringTunings}.

In the next example, @code{stringTunings} is set for the pitches
e, a, d, and g.

@lilypond[quote,ragged-right,fragment,verbatim]
\new TabStaff <<
  \set TabStaff.stringTunings = #'(-5 -10 -15 -20)
  {
    a,4 c' a e' e c' a e'
  }
>>
@end lilypond

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} (the standard
EADGBE tuning).  Some other predefined tunings are
@code{guitar-open-g-tuning}, @code{mandolin-tuning} and
@code{banjo-open-g-tuning}.

@seealso

Snippets:
@rlsr{Fretted strings}.

The file @file{scm/@/output@/-lib@/.scm} contains the predefined string
tunings.

Internals Reference: 
@rinternals{Tab_note_heads_engraver}.

@knownissues

No guitar special effects have been implemented.

@node Automatic fret diagrams
@subsubsection Automatic fret diagrams
@cindex fret diagrams
@cindex chord diagrams

Fret diagrams can be automatically created from entered notes using the 
@code{FretBoards} context.  This context calculates strings and frets
which 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

Notes can be explicitly placed on a string.  It is often enough
to place only the lowest note on an explicit string; the rest of 
the notes will then be placed appropriately by the @code{FretBoards}
context.

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

Fingerings can be added to FretBoard fret diagrams.

@lilypond[quote, verbatim]
<<
  \context ChordNames {
     \chordmode { 
       c1 d:m          
     }
  }
  \context FretBoards {
    < c\5-3 e-2 g c'-1 e' > 1
    < d\4 a-2 d'-3 f'-1>
  }
  \context Staff {
    \clef "treble_8"
    < c e g c' e' > 1
    < 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}.

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

@c TODO -- snippet showing minimum fret.

@c TODO -- snippet for using StringTunings

@seealso

Notation Reference:
@ref{Custom tablatures}

Snippets:
@rlsr{Fretted strings}.

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


@node Fret diagram markups
@subsubsection Fret diagram markups
@cindex fret diagrams
@cindex chord 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

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, b, d g b' g'> ^\markup
      \fret-diagram #"c:6-1-3;6-3;5-5;4-5;3-4;2-3;1-3;"
  }
>>
@end lilypond

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

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, b, d g b' 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.

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.

@c \override is necessary to make fingering visible
@lilypond[quote, verbatim]
<<
  \context ChordNames {
     \chordmode {
       f1 g
     }
  }
  \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)
      )
  }
>>
@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

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
TODO create snippets for changing properties.  Use regression test?

@seealso

Notation Reference:
@ref{Text markup commands}.

Snippets:
@rlsr{Fretted strings}.

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

@node Right-hand fingerings
@subsubsection Right-hand fingerings

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

@cindex fingerings, right hand, for guitar
@cindex right hand fingerings for guitar

@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
@subsubsection 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
@subsubsection Indicating harmonics and dampened notes

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,fragment,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
@subsubsection Banjo tablatures
@cindex Banjo tablatures

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

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

The file @file{scm/@/output@/-lib@/.scm} contains predefined banjo tunings.