Update from Jonathan.

[lilypond.git] / Documentation / user / 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.11.38"

@node Fretted string instruments
@section 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

@menu
* References for fretted strings::
* String number indications::
* Default tablatures::
* Custom tablatures::
* Fret diagrams::
* Right hand fingerings::
@end menu

@node References for fretted strings
@subsubsection References for fretted strings

@c TODO Add refs
TBC

@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{\}@tie{}@var{number} to a note inside a chord.

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

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


@ignore
In notation for fretted stringed instruments, the string on which
a note should be played is indicated by a circled number, and this
is added with @code{\}@var{number} inside a chord construct.  The 
string indication must occur within a @code{<>} chord construct for it to
be printed in the score, even if it is a single note.  If the 
@code{\}@var{number} is placed outside the @code{<>}, it will not generate
errors but also will not print the string indication.  

@warning{rhythmic durations must be specified outside of the
chords.}
example, @code{<c\5>4} will produce a quarter-note C on the fifth
string.
@end ignore

Although fingering is covered in detail elsewhere, it is worth noting
here how fingerings and string indications behave together, since
guitar music often incorporates both at once.  The usual convention
is to place the fingering closest to the note, then the string 
indication outside the fingering.  This is controlled by the order in 
which the two items appear:

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

@snippets

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

@seealso

Internals Reference: @rinternals{StringNumber},
@c @lsr{guitar/,string-number.ly}.


@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 to a note is given as a backslash
followed by a number, e.g., @code{c4\3} for a C quarter on the third
string.  By default, string 1 is the highest one, and the tuning
defaults to the standard guitar tuning (with 6 strings).  The notes
are printed as tablature, by using @rinternals{TabStaff} and
@rinternals{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, the first string that does not give a
fret number less than @code{minimumFret} is selected.  The default
value for @code{minimumFret} is 0


@example
e16 fis gis a b4
\set TabStaff.minimumFret = #8
e16 fis gis a b4
@end example
@lilypond[quote,ragged-right]
frag = {
  \key e \major
  e16 fis gis a b4
  \set TabStaff.minimumFret = #8
  e16 fis gis a b4
}
  \new StaffGroup <<
    \new Staff { \clef "G_8" \frag }
    \new TabStaff { \frag }
  >>
@end lilypond


@snippets

To print tablatures with stems down and horizontal beams,
initialize the @code{TabStaff} with this code:

@example
\stemDown
\override Beam #'damping = #100000
@end example

@seealso

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

@knownissues

Chords are not handled in a special way, and hence the automatic
string selector may easily select the same string to 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.

@example
\set TabStaff.stringTunings = #bass-tuning
@end example

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

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 Fret diagrams
@subsubsection Fret diagrams
@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 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 {
  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

You can set a number of graphical properties according to your preference.
Details about the property interface to fret diagrams are found at
@rinternals{fret-diagram-interface}.


@seealso



@node Right hand fingerings
@subsubsection Right hand fingerings

Right-hand fingerings @var{p-i-m-a} can be entered using 
@code{<@var{note}-\rightHandFinger @var{finger} >}.
The right-hand fingering indication must occur within a @code{<>} chord 
construct for it to be printed in the score, even if it is a single note.  
There must be a hyphen after the note and the space
before the closing @code{>}.


@lilypond[quote,ragged-right,fragment,verbatim]
\relative c' {
  <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 brevity, 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

You may exercise greater control over the placement of right-hand 
fingerings by setting @code{strokeFingerOrientations},

@lilypond[quote,verbatim,ragged-right,fragment,relative=1]
#(define RH rightHandFinger)
{
  \set strokeFingerOrientations = #'(up down)
  <c-\RH #1 es-\RH #2 g-\RH #4 > 4
  \set strokeFingerOrientations = #'(up right down)
  <c-\RH #1 es-\RH #2 g-\RH #4 > 4
}
@end lilypond

The letters used for the fingerings are contained in the property
@code{digit-names}, but they can also be set individually by supplying
@code{\rightHandFinger} with a string argument, as in the following example


@lilypond[quote,verbatim,ragged-right,fragment,relative=1]
#(define RH rightHandFinger)
{
  \set strokeFingerOrientations = #'(right)
  \override StrokeFinger #'digit-names = ##("x" "y" "z" "!" "@")
  <c-\RH #5 >4
  <c-\RH "@">4
  <c-\RH #2 >4
  <c-\RH "z">4
}
@end lilypond

This example combines left-hand fingering, string indication, and 
right-hand fingering

@lilypond[quote,ragged-right,fragment,verbatim]
#(define RH rightHandFinger)
\relative c' {
  <c-3\5-\RH #1 >4 
  <e-2\4-\RH #2 > 
  <g-0\3-\RH #3 > 
  <c-1\2-\RH #4 >
}
@end lilypond

@seealso

Internals Reference: @rinternals{StrokeFinger}


@node Guitar
@subsection Guitar

@c TODO Make a snippet based on
@c http://www.nabble.com/Creating-a-nice-formatted-Chords-%2B-Lyrics-layout-for-guitar-players-to13829430.html
@c and include it somewhere -td

@menu
* Guitar tablatures::
* Indicating position and barring::
@end menu

@node Guitar tablatures
@subsubsection Guitar tablatures

@c TODO Add text
TBC

@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 "G_8"
b16 d16 g16 b16 e16
\textSpannerDown
\override TextSpanner #'bound-details #'left #'text = #"XII "
  g16\startTextSpan
  b16 e16 g16 e16 b16 g16\stopTextSpan
e16 b16 g16 d16
@end lilypond


Stopped (X) note heads are used in guitar music to signal a place where the
guitarist must play a certain note or chord, with its fingers just
touching the strings instead of fully pressing them.  This gives the sound a
percussive noise-like sound that still maintains part of the original
pitch.  It is notated with cross note heads; this is
demonstrated in @ref{Special note heads}.


@node Banjo
@subsection Banjo

@menu Banjo tablatures
* Banjo tablatures::
@end menu

@node Banjo tablatures
@subsubsection Banjo tablatures
@cindex Banjo tablatures

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

@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

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