@end menu
@node References for fretted strings
-@subsubsection 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
@seealso
Notation Reference:
-@ref{Instrument names},
-@ref{Writing music in parallel},
@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
-@subsubsection String number indications
+@unnumberedsubsubsec String number indications
@cindex String numbers
@node Default tablatures
-@subsubsection Default tablatures
+@unnumberedsubsubsec Default tablatures
@cindex Tablatures, basic
@cindex Tablatures, default
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.
+greater than or equal to the value of @code{minimumFret}.
+The default value for @code{minimumFret} is 0.
@lilypond[quote,ragged-right,verbatim]
>>
@end lilypond
+Harmonic indications and slides can be added to tablature
+notation.
+
+@lilypond[fragment, verbatim, quote, relative=1]
+\new TabStaff {
+ \new TabVoice {
+ <c g'\harmonic> d\2\glissando e\2
+ }
+}
+@end lilypond
+
+
@snippets
@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
>>
@end lilypond
+Guitar special effects are limited to harmonics and slides.
@node Custom tablatures
-@subsubsection Custom tablatures
+@unnumberedsubsubsec 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 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
@lilypond[quote,ragged-right,verbatim]
<<
- \new Staff <<
+ \new Staff {
\clef "bass_8"
\relative c, {
- c4 d e f
+ c4 d e f
}
- >>
- \new TabStaff <<
+ }
+ \new TabStaff {
\set TabStaff.stringTunings = #bass-tuning
\relative c, {
- c4 d e f
+ c4 d e f
}
- >>
+ }
>>
@end lilypond
-The default string tuning is @code{guitar-tuning} (the standard
-EADGBE tuning). Some other predefined tunings are
+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}.
+@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}.
-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 diagram markups
-@subsubsection Fret diagram markups
+@unnumberedsubsubsec Fret diagram markups
@cindex fret diagrams
@cindex chord diagrams
markup , the interface properties belong to @code{Voice.TextScript}.
@snippets
-TODO create snippets for changing properties. Use regression test?
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{customizing-markup-fret-diagrams.ly}
+
@seealso
@rinternals{fret-diagram-interface}.
@node Predefined fret diagrams
-@subsubsection Predefined fret diagrams
+@unnumberedsubsubsec Predefined fret diagrams
@cindex fret diagrams
@cindex chord diagrams
are stored in a lookup table:
@lilypond[verbatim, ragged-right, quote]
+\include "predefined-guitar-fretboards.ly"
\context FretBoards {
\chordmode {
c1 d
}
@end lilypond
-Fret diagrams are stored based on the pitches of a chord and the value of
-@code{StringTunings} that is currently in use. Currently, predefined chords
-are available only for @code{guitar-tuning}. Chord pitches can be entered
-either as simultaneous music or using chord mode (see
+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
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
}
@end lilypond
Predefined fret diagrams are transposable, as long as a diagram for the
-transposed chord is stored in the fret diagram table.
+transposed chord is stored in the fret diagram table.
@lilypond[verbatim, ragged-right, quote]
+\include "predefined-guitar-fretboards.ly"
mychords = \chordmode{
c1 f g
}
The predefined fret diagram table contains seven chords (major, minor,
augmented, diminished, dominant seventh, major seventh, minor seventh)
-for each of 17 keys (C, C\sharp?, D\flat, D, D\sharp, E\flat, E, F,
-F\sharp, G\flat, G, G\sharp, A\flat, A, A\sharp, B\flat, and B). 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}.
-
-TODO -- example of existing chord, non-existing chord
-
-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 the
+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
+
+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 the
fret-diagram-terse definition string for the diagram.
-TODO -- add a few diagrams to the table and display it
+@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.
-TODO -- show the use of different fret diagrams
+@lilypond[verbatim, ragged-right, quote]
+\include "predefined-guitar-fretboards.ly"
+
+\storePredefinedDiagram \chordmode {c'}
+ #guitar-tuning
+ #(offset-fret 2 (chord-shape 'bes))
+
+mychords = \chordmode{
+ c1 c'
+}
+
+<<
+ \context ChordNames {
+ \mychords
+ }
+ \context FretBoards {
+ \mychords
+ }
+>>
+@end lilypond
In addition to fret diagrams, LilyPond stores an internal list of chord
shapes. The chord shapes are fret diagrams that can be shifted along
shapes can be added to the internal list and then used to define
predefined fret diagrams.
-TODO -- snippet with power chords
+@lilypond[verbatim, ragged-right, quote]
+\include "predefined-guitar-fretboards.ly"
+
+% add a new chord shape
+
+\addChordShape #'powerf #"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)
+\storePredefinedDiagram \chordmode {g'}
+ #guitar-tuning
+ #(offset-fret 2 (chord-shape 'powerf))
+
+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}
+
+
+@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}.
+
+Snippets:
+@rlsr{Fretted strings}.
+
+Internals Reference:
+@rinternals {fret-diagram-interface}.
-The appearance of the fret diagrams is controlled using the
-@code{fret-diagram-interface}, which is explained in TODO add ref.
@node Automatic fret diagrams
-@subsubsection Automatic fret diagrams
+@unnumberedsubsubsec 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.
+@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 FretBoards {
- \predefinedDiagramsOff
< f, c f a c' f'>1
< g,\6 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
+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 accceptable 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.
<<
\context ChordNames {
\chordmode {
- c1 c d:m d:m
+ c1 c
}
}
\context FretBoards {
- \predefinedDiagramsOff
- < c e g c' e' > 1
- < c\5 e g c' e' > 1
- < d a d' f'>
- < d\4 a d' f'>
+ < c g c' e' g'> 1
+ < c g\4 c' e' g'> 1
}
\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'>
+ < c g c' e' g'> 1
+ < c g c' e' g'> 1
}
>>
@end lilypond
}
}
\context FretBoards {
- \predefinedDiagramsOff
- < c\5-3 e-2 g c'-1 e' > 1
- < d\4 a-2 d'-3 f'-1>
+ < c-3 e-2 g c'-1 e' > 1
+ < d a-2 d'-3 f'-1>
}
\context Staff {
\clef "treble_8"
>>
@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
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.
+@code{FretBoards.FretBoard}.
-@c TODO -- snippet for using StringTunings
+@predefined
+@code{\predefinedFretboardsOff},
+@code{\predefinedFretboardsOn}.
@seealso
Notation Reference:
-@ref{Custom tablatures}
+@ref{Custom tablatures}.
Snippets:
@rlsr{Fretted strings}.
@node Right-hand fingerings
-@subsubsection Right-hand fingerings
+@unnumberedsubsubsec 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,
@end menu
@node Indicating position and barring
-@subsubsection Indicating position and barring
+@unnumberedsubsubsec Indicating position and barring
This example demonstrates how to include guitar position and
barring indications.
@rlsr{Expressive marks}.
@node Indicating harmonics and dampened notes
-@subsubsection Indicating harmonics and dampened notes
+@unnumberedsubsubsec Indicating harmonics and dampened notes
Special note heads can be used to indicate dampened notes or
harmonics. Harmonics are normally further explained with a
@end menu
@node Banjo tablatures
-@subsubsection Banjo tablatures
+@unnumberedsubsubsec Banjo tablatures
@cindex Banjo tablatures
LilyPond has basic support for the five-string banjo. When making tablatures