* String number indications::
* Default tablatures::
* Custom tablatures::
-* Automatic fret diagrams::
* Fret diagram markups::
+* Predefined fret diagrams::
+* Automatic fret diagrams::
* Right-hand fingerings::
@end menu
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]
@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 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}.
-@seealso
+A string tuning is a Scheme list of string pitches,
+one for each string, ordered from the bottom to the
+top of the tablature staff.
+This ordinarily results in ordering from lowest pitch to highest
+pitch, but some instruments (e.g. ukulele) do not have strings
+ordered by pitch.
-Snippets:
-@rlsr{Fretted strings}.
+A string pitch in a string tuning list is the pitch difference of
+middle C from the open string measured in semitones. The 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.
-The file @file{scm/@/output@/-lib@/.scm} contains the predefined string
-tunings.
+LilyPond automatically calculates the number of strings in the
+@code{TabStaff} as the number of elements in @code{stringTunings}.
-Internals Reference:
-@rinternals{Tab_note_heads_engraver}.
+Any desired string tuning can be created. For example, we can
+define a string tuning for a four-string instrument with pitches
+of e, a, d', and g':
-@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>
+@lilypond[quote,ragged-right,fragment,verbatim]
+\new TabStaff {
+ \set TabStaff.stringTunings = #'(-5 -10 -15 -20)
+ {
+ a,4 c' a e' e c' a e'
}
- \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}
+Installed Files:
+@file{scm/output-lib.scm}.
Snippets:
@rlsr{Fretted strings}.
-Internals Reference:
-@rinternals {fret-diagram-interface}.
+Internals Reference:
+@rinternals{Tab_note_heads_engraver}.
+@knownissues
+
+No guitar special effects have been implemented.
@node Fret diagram markups
@subsubsection Fret diagram markups
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
Internals Reference:
@rinternals{fret-diagram-interface}.
+@node Predefined fret diagrams
+@subsubsection Predefined fret diagrams
+@cindex fret diagrams
+@cindex chord diagrams
+
+Fret diagrams can be displayed using the @code{FretBoards} context. By
+default, the @code{FretBoards} context will display fret diagrams that
+are stored in a lookup table:
+
+@lilypond[verbatim, ragged-right, quote]
+\include "predefined-guitar-fretboards.ly"
+\context FretBoards {
+ \chordmode {
+ c1 d
+ }
+}
+@end lilypond
+
+The default predefined fret diagrams are contained in the file
+@code{predefined-guitar-fretboards.ly}. Fret diagrams are
+stored based on the pitches of a chord and the value of
+@code{stringTunings} that is currently in use.
+@code{predefined-guitar-fretboards.ly} contains predefined
+fret diagrams only for @code{guitar-tuning}. Predefined fret
+diagrams can be added for other instruments or other tunings
+by following the examples found in
+@code{predefined-guitar-fretboards.ly}.
+
+Chord pitches can be entered
+either as simultaneous music or using chord mode (see
+@ref{Chord mode overview}).
+
+@lilypond[verbatim, ragged-right,quote]
+\include "predefined-guitar-fretboards.ly"
+\context FretBoards {
+ \chordmode {c1}
+ <c' e' g'>1
+}
+@end lilypond
+
+It is common that both chord names and fret diagrams are displayed together.
+This is achieved by putting a @code{ChordNames} context in parallel with
+a @code{FretBoards} context and giving both contexts the same music.
+
+@lilypond[verbatim, ragged-right, quote]
+\include "predefined-guitar-fretboards.ly"
+mychords = \chordmode{
+ c1 f g
+}
+
+<<
+ \context ChordNames {
+ \mychords
+ }
+ \context FretBoards {
+ \mychords
+ }
+>>
+@end lilypond
+
+Predefined fret diagrams are transposable, as long as a diagram for the
+transposed chord is stored in the fret diagram table.
+
+@lilypond[verbatim, ragged-right, quote]
+\include "predefined-guitar-fretboards.ly"
+mychords = \chordmode{
+ c1 f g
+}
+
+mychordlist = {
+ \mychords
+ \transpose c e { \mychords}
+}
+<<
+ \context ChordNames {
+ \mychordlist
+ }
+ \context FretBoards {
+ \mychordlist
+ }
+>>
+@end lilypond
+
+
+The predefined fret diagram table contains seven chords (major, minor,
+augmented, diminished, dominant seventh, major seventh, minor seventh)
+for each of 17 keys. A complete list of the predefined fret diagrams is
+shown in @ref{Predefined fretboard diagrams}. If there is no entry in
+the table for a chord, the FretBoards engraver will calculate a
+fret-diagram using the automatic fret diagram functionality described in
+@ref{Automatic fret diagrams}.
+
+@lilypond[verbatim, ragged-right, quote]
+\include "predefined-guitar-fretboards.ly"
+mychords = \chordmode{
+ c1 c:9
+}
+
+<<
+ \context ChordNames {
+ \mychords
+ }
+ \context FretBoards {
+ \mychords
+ }
+>>
+@end lilypond
+
+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.
+
+@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.
+
+@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
+the neck to different posistions to provide different chords. Chord
+shapes can be added to the internal list and then used to define
+predefined fret diagrams.
+
+@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}.
+
+
+@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. If no predefined diagram is available for
+the entered notes in the active @code{stringTunings}, this context
+calculates strings and frets that can be used to play the notes.
+
+@lilypond[quote,ragged-right,verbatim]
+<<
+ \context ChordNames {
+ \chordmode {
+ f1 g
+ }
+ }
+ \context FretBoards {
+ < f, c f a c' f'>1
+ < g,\6 b, d g b g'>
+ }
+ \context Staff {
+ \clef "treble_8"
+ < f, c f a c' f'>1
+ < g, b, d g b' g'>
+ }
+>>
+@end lilypond
+
+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.
+
+@lilypond[quote,ragged-right,verbatim]
+<<
+ \context ChordNames {
+ \chordmode {
+ c1 c
+ }
+ }
+ \context FretBoards {
+ < c g c' e' g'> 1
+ < c g\4 c' e' g'> 1
+ }
+ \context Staff {
+ \clef "treble_8"
+ < c g c' e' g'> 1
+ < c g c' e' g'> 1
+ }
+>>
+@end lilypond
+
+Fingerings can be added to FretBoard fret diagrams.
+
+@lilypond[quote, verbatim]
+<<
+ \context ChordNames {
+ \chordmode {
+ c1 d:m
+ }
+ }
+ \context FretBoards {
+ < c-3 e-2 g c'-1 e' > 1
+ < d a-2 d'-3 f'-1>
+ }
+ \context Staff {
+ \clef "treble_8"
+ < c e g c' e' > 1
+ < d a d' f'>
+ }
+>>
+@end lilypond
+
+The minimum fret to be used in calculating strings and frets for
+the FretBoard context can be set with the @code{minimumFret}
+property.
+
+@lilypond[quote, verbatim]
+<<
+ \context ChordNames {
+ \chordmode {
+ d1:m d:m
+ }
+ }
+ \context FretBoards {
+ < d a d' f'>
+ \set FretBoards.minimumFret = #5
+ < d a d' f'>
+ }
+ \context Staff {
+ \clef "treble_8"
+ < d a d' f'>
+ < d a d' f'>
+ }
+>>
+@end lilypond
+
+The strings and frets for the @code{FretBoards} context depend
+on the @code{stringTunings} property, which has the same meaning
+as in the TabStaff context. See @ref{Custom tablatures} for
+information on the @code{stringTunings} property.
+
+The graphical layout of a fret diagram can be customized according to
+user preference through the properties of the @code{fret-diagram-interface}.
+Details are found at @rinternals{fret-diagram-interface}. For a
+@code{FretBoards} fret diagram, the interface properties belong to
+@code{FretBoards.FretBoard}.
+
+@predefined
+\predefinedFretboardsOff,
+\predefinedFretboardsOn.
+
+@seealso
+
+Notation Reference:
+@ref{Custom tablatures}.
+
+Snippets:
+@rlsr{Fretted strings}.
+
+Internals Reference:
+@rinternals {fret-diagram-interface}.
+
+
@node Right-hand fingerings
@subsubsection Right-hand fingerings
projects / lilypond.git / blobdiff