]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/user/fretted-strings.itely
Update documentation for fret diagrams
[lilypond.git] / Documentation / user / fretted-strings.itely
1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @ignore
3     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
4
5     When revising a translation, copy the HEAD committish of the
6     version that you are working on.  See TRANSLATION for details.
7 @end ignore
8
9 @c \version "2.11.53"
10
11 @node Fretted string instruments
12 @section Fretted string instruments
13
14 @lilypondfile[quote]{fretted-headword.ly}
15
16 This section discusses several aspects of music notation that are unique
17 to fretted string instruments.
18
19 @cindex tablature
20 @cindex guitar tablature
21
22 @menu
23 * Common notation for fretted strings::  
24 * Guitar::                      
25 * Banjo::                       
26 @end menu
27
28 @node Common notation for fretted strings
29 @subsection Common notation for fretted strings
30
31 This section discusses common notation that is unique
32 to fretted string instruments.
33
34 @menu
35 * References for fretted strings::  
36 * String number indications::   
37 * Default tablatures::          
38 * Custom tablatures::           
39 * Fret diagram markups::
40 * Predefined fret diagrams::
41 * Automatic fret diagrams::               
42 * Right-hand fingerings::       
43 @end menu
44
45 @node References for fretted strings
46 @subsubsection References for fretted strings
47
48 Music for fretted string instruments is normally notated on
49 a single staff, either in traditional music notation or in
50 tablature.  Sometimes the two types are combined, and it is
51 especially common in popular music to use chord diagrams above
52 a staff of traditional notation.  The guitar and the banjo are
53 transposing instruments, sounding an octave lower than written. 
54 Scores for these instruments should use the @code{"treble_8"} clef. 
55 Some other elements pertinent to fretted string instruments 
56 are covered elsewhere:
57
58 @itemize
59 @item Fingerings are indicated with @ref{Fingering instructions}.
60
61 @item Instructions for @notation{Laissez vibrer} ties
62 as well as ties on arpeggios and tremolos is described in
63 @ref{Ties}.
64
65 @item Instructions on handling multiple voices is described 
66 in @ref{Collision resolution}. 
67
68 @end itemize
69
70 @seealso
71
72 Notation Reference:
73 @ref{Instrument names},
74 @ref{Writing music in parallel},
75 @ref{Fingering instructions},
76 @ref{Ties},
77 @ref{Arpeggio},
78 @ref{List of articulations},
79 @ref{Clef}.
80
81 @node String number indications
82 @subsubsection String number indications
83
84 @cindex String numbers
85
86 The string on which a note should be played may be indicated by
87 appending @code{\@var{number}} to a note inside a chord construct
88 @code{<>}.
89
90 @warning{String numbers @strong{must} be defined inside a chord
91 construct even if there is only a single note.}
92
93 @lilypond[verbatim,quote,relative=0]
94 \clef "treble_8"
95 <c\5>4 <e\4> <g\3>2
96 <c,\5 e\4 g\3>1
97 @end lilypond
98
99 When fingerings and string indications are used together, their
100 placement is controlled by the order in which the two items appear
101 in the code:
102
103 @lilypond[verbatim,quote,relative=1]
104 \clef "treble_8"
105 <g\3-0>2
106 <g-0\3>
107 @end lilypond
108
109 @snippets
110
111 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
112 {controlling-the-placement-of-chord-fingerings.ly}
113
114 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
115 {allowing-fingerings-to-be-printed-inside-the-staff.ly}
116
117 @seealso
118
119 Notation Reference:
120 @ref{Fingering instructions}.
121
122 Snippets:
123 @rlsr{Fretted strings}.
124
125 Internals Reference:
126 @rinternals{StringNumber},
127 @rinternals{Fingering}.
128
129
130 @node Default tablatures
131 @subsubsection Default tablatures
132 @cindex Tablatures, basic
133 @cindex Tablatures, default
134
135 Tablature notation is used for notating music for plucked string
136 instruments.  Pitches are not denoted with note heads, but by
137 numbers indicating on which string and fret a note must be played.  
138 LilyPond offers limited support for tablature.
139
140 The string number associated with a note is given as a backslash
141 followed by a number.  By default, string 1 is the highest, 
142 and the tuning defaults to the standard guitar tuning (with 6 strings).  
143 The notes are printed as tablature, by using @code{TabStaff} and
144 @code{TabVoice} contexts
145
146 @lilypond[quote,ragged-right,fragment,verbatim]
147 \new TabStaff {
148   a,4\5 c'\2 a\3 e'\1
149   e\4 c'\2 a\3 e'\1
150 }
151 @end lilypond
152
153 @funindex minimumFret
154 @cindex fret
155
156
157 When no string is specified for a note, the note is assigned to
158 the lowest string that can generate the note with a fret number
159 greater than or equal to the value of @code{minimumFret}.
160 The default value for @code{minimumFret} is 0.
161
162
163 @lilypond[quote,ragged-right,verbatim]
164 \new StaffGroup <<
165    \new Staff \relative c {
166      \clef "treble_8"
167      c16 d e f g4
168      c,16 d e f g4
169    }
170    \new TabStaff \relative c {
171      c16 d e f g4
172      \set TabStaff.minimumFret = #5
173      c,16 d e f g4
174    }
175 >>
176 @end lilypond
177
178 @snippets
179
180 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
181 {stem-and-beam-behavior-in-tablature.ly}
182
183 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
184 {polyphony-in-tablature.ly}
185
186 @seealso
187
188 Notation Reference:
189 @ref{Stems}.
190
191 Snippets:
192 @rlsr{Fretted strings}.
193
194 Internals Reference: 
195 @rinternals{TabNoteHead},
196 @rinternals{TabStaff},
197 @rinternals{TabVoice},
198 @rinternals{Beam}.
199
200 @knownissues
201
202 Chords are not handled in a special way, and hence the automatic
203 string selector may easily select the same string for two notes in
204 a chord.
205
206 In order to handle @code{\partcombine}, a @code{TabStaff} must use
207 specially-created voices:
208
209 @lilypond[quote,ragged-right,verbatim]
210 melodia = \partcombine { e4 g g g }{ e4 e e e }
211 <<
212   \new TabStaff <<
213     \new TabVoice = "one" s1
214     \new TabVoice = "two" s1
215     \new TabVoice = "shared" s1
216     \new TabVoice = "solo" s1
217     { \melodia }
218   >>
219 >>
220 @end lilypond
221
222
223 @node Custom tablatures
224 @subsubsection Custom tablatures
225 @cindex Tablatures, custom
226
227 You can change the tuning of the strings.  A string tuning is
228 given as a Scheme list with one integer number for each string,
229 the number being the pitch (measured in semitones relative to
230 middle C) of an open string.  The numbers specified for
231 @code{stringTunings} are the numbers of semitones to subtract or
232 add, starting the specified pitch by default middle C, in string
233 order.  LilyPond automatically calculates the number of strings by
234 looking at @code{stringTunings}.
235
236 In the next example, @code{stringTunings} is set for the pitches
237 e, a, d, and g.
238
239 @lilypond[quote,ragged-right,fragment,verbatim]
240 \new TabStaff <<
241   \set TabStaff.stringTunings = #'(-5 -10 -15 -20)
242   {
243     a,4 c' a e' e c' a e'
244   }
245 >>
246 @end lilypond
247
248 LilyPond comes with predefined string tunings for banjo, mandolin,
249 guitar and bass guitar.  Lilypond automatically sets the correct 
250 transposition for predefined tunings.  The following example is
251 for bass guitar, which sounds an octave lower than written.
252
253 @lilypond[quote,ragged-right,verbatim]
254 <<
255   \new Staff <<
256     \clef "bass_8"
257     \relative c, {
258     c4 d e f
259     }
260   >>
261   \new TabStaff <<
262     \set TabStaff.stringTunings = #bass-tuning
263     \relative c, {
264     c4 d e f
265     }
266   >>
267 >>
268 @end lilypond
269
270 The default string tuning is @code{guitar-tuning} (the standard
271 EADGBE tuning).  Some other predefined tunings are
272 @code{guitar-open-g-tuning}, @code{mandolin-tuning} and
273 @code{banjo-open-g-tuning}.
274
275 @seealso
276
277 Snippets:
278 @rlsr{Fretted strings}.
279
280 The file @file{scm/@/output@/-lib@/.scm} contains the predefined string
281 tunings.
282
283 Internals Reference: 
284 @rinternals{Tab_note_heads_engraver}.
285
286 @knownissues
287
288 No guitar special effects have been implemented.
289
290 @node Fret diagram markups
291 @subsubsection Fret diagram markups
292 @cindex fret diagrams
293 @cindex chord diagrams
294
295 Fret diagrams can be added to music as a markup to the desired
296 note.  The markup contains information about the desired fret
297 diagram.  There are three different fret-diagram markup
298 interfaces: standard, terse, and verbose.  The three interfaces
299 produce equivalent markups, but have varying amounts of
300 information in the markup string.  Details about the markup
301 interfaces are found at @ref{Text markup commands}.
302
303 The standard fret diagram markup string indicates the string
304 number and the fret number for each dot to be placed on the string.
305 In addition, open and unplayed (muted) strings can be indicated.
306
307 @lilypond[quote, verbatim]
308 <<
309   \context ChordNames {
310      \chordmode { 
311        c1 d:m          
312      }
313   }
314   \context Staff {
315     \clef "treble_8"
316     < c e g c' e' > 1 ^\markup 
317       \fret-diagram #"6-x;5-3;4-2;3-o;2-1;1-o;"
318     < d a d' f'> ^\markup
319       \fret-diagram #"6-x;5-x;4-o;3-2;2-3;1-1;"
320   }  
321 >>
322 @end lilypond
323
324 Barre indications can be added to the diagram from
325 the fret-diagram markup string.
326
327 @lilypond[quote, verbatim]
328 <<
329   \context ChordNames {
330      \chordmode {
331        f1 g
332      }
333   }
334   \context Staff {
335     \clef "treble_8"
336     < f, c f a c' f'>1 ^\markup
337       \fret-diagram #"c:6-1-1;6-1;5-3;4-3;3-2;2-1;1-1;"
338     < g, b, d g b' g'> ^\markup
339       \fret-diagram #"c:6-1-3;6-3;5-5;4-5;3-4;2-3;1-3;"
340   }
341 >>
342 @end lilypond
343
344 The size of the fret diagram, and the number of frets in the diagram
345 can be changed in the fret-diagram markup string.
346
347 @lilypond[quote, verbatim]
348 <<
349   \context ChordNames {
350      \chordmode {
351        f1 g
352      }
353   }
354   \context Staff {
355     \clef "treble_8"
356     < f, c f a c' f'>1 ^\markup
357       \fret-diagram #"s:1.5;c:6-1-1;6-1;5-3;4-3;3-2;2-1;1-1;"
358     < g, b, d g b' g'> ^\markup
359       \fret-diagram #"h:6;6-3;5-2;4-o;3-o;2-o;1-3;"
360   }
361 >>
362 @end lilypond
363
364 The number of strings in a fret diagram can be changed to accomodate
365 different instruments such as banjos and ukeleles with the fret-diagram
366 markup string.
367
368 @lilypond[quote, verbatim]
369 <<
370   \context ChordNames {
371      \chordmode {
372        a1
373      }
374   }
375   \context Staff {
376         %% A chord for ukelele
377     a'1 ^\markup \fret-diagram #"w:4;4-2-2;3-1-1;2-o;1-o;"
378   }
379 >>
380 @end lilypond
381
382 Fingering indications can be added, and the location of fingering labels
383 can be controlled by the fret-diagram markup string.
384
385 @lilypond[quote, verbatim]
386 <<
387   \context ChordNames {
388      \chordmode { 
389        c1 d:m          
390      }
391   }
392   \context Staff {
393     \clef "treble_8"
394     < c e g c' e' > 1 ^\markup 
395       \fret-diagram #"f:1;6-x;5-3-3;4-2-2;3-o;2-1-1;1-o;"
396     < d a d' f'> ^\markup
397       \fret-diagram #"f:2;6-x;5-x;4-o;3-2-2;2-3-3;1-1-1;"
398   }  
399 >>
400 @end lilypond
401
402 Dot radius and dot position can be controlled with the fret-diagram
403 markup string.
404
405 @lilypond[quote, verbatim]
406 <<
407   \context ChordNames {
408      \chordmode { 
409        c1 d:m          
410      }
411   }
412   \context Staff {
413     \clef "treble_8"
414     < c e g c' e' > 1 ^\markup 
415       \fret-diagram #"d:0.35;6-x;5-3;4-2;3-o;2-1;1-o;"
416     < d a d' f'> ^\markup
417       \fret-diagram #"p:0.2;6-x;5-x;4-o;3-2;2-3;1-1;"
418   }  
419 >>
420 @end lilypond
421
422 The fret-diagram-terse markup string omits string numbers; the string
423 number is implied by the presence of semicolons.  There is one semicolon 
424 for each string in the diagram.  The first semicolon corresponds to the
425 highest string number and the last semicolon corresponds to the first string.
426 Mute strings, open strings, and fret numbers can be indicated.
427
428 @lilypond[quote, verbatim]
429 <<
430   \context ChordNames {
431      \chordmode {
432        c1 d:m
433      }
434   }
435   \context Staff {
436     \clef "treble_8"
437     < c e g c' e' > 1 ^\markup
438       \fret-diagram-terse #"x;3;2;o;1;o;"
439     < d a d' f'> ^\markup
440       \fret-diagram-terse #"x;x;o;2;3;1;"
441   }
442 >>
443 @end lilypond
444
445 Barre indicators can be included in the fret-diagram-terse markup string.
446
447 @lilypond[quote, verbatim]
448 <<
449   \context ChordNames {
450      \chordmode {
451        f1 g
452      }
453   }
454   \context Staff {
455     \clef "treble_8"
456     < f, c f a c' f'>1 ^\markup
457       \fret-diagram-terse #"1-(;3;3;2;1;1-);"
458     < g, b, d g b' g'> ^\markup
459       \fret-diagram-terse #"3-(;5;5;4;3;3-);"
460   }
461 >>
462 @end lilypond      
463
464 Fingering indications can be included in the fret-diagram-terse markup string.
465
466 @c Need to use override to enable fingerings to show this -- can we do so?
467 @lilypond[quote, verbatim]
468 <<    
469   \context ChordNames {
470      \chordmode {
471        c1 d:m
472      }
473   }
474   \context Staff {
475     \override Voice.TextScript 
476       #'fret-diagram-details #'finger-code = #'below-string
477     \clef "treble_8"
478     < c e g c' e' > 1 ^\markup
479       \fret-diagram-terse #"x;3-3;2-2;o;1-1;o;"
480     < d a d' f'> ^\markup
481       \fret-diagram-terse #"x;x;o;2-2;3-3;1-1;"
482   }
483 >>
484 @end lilypond
485
486 Other fret diagram properties must be adjusted using @code{\override} when using
487 the fret-diagram-terse markup.
488
489 The fret-diagram-verbose markup string is in the format of a Scheme list.  Each
490 element of the list indicates an item to be placed on the fret diagram.
491
492 @lilypond[quote, verbatim]
493 <<  \context ChordNames {
494      \chordmode {
495        c1 d:m
496      }
497   }
498   \context Staff {
499     \clef "treble_8"
500     < c e g c' e' > 1 ^\markup
501       \fret-diagram-verbose #'(
502         (mute 6)
503         (place-fret 5 3)
504         (place-fret 4 2)
505         (open 3)
506         (place-fret 2 1)
507         (open 1)
508       )
509     < d a d' f'> ^\markup
510       \fret-diagram-verbose #'(
511         (mute 6)
512         (mute 5)
513         (open 4)
514         (place-fret 3 2)
515         (place-fret 2 3)
516         (place-fret 1 1)
517       )
518   }
519 >>
520 @end lilypond
521
522 Fingering indications and barres can be included in a 
523 fret-diagram-verbose markup string.
524
525 @c \override is necessary to make fingering visible
526 @lilypond[quote, verbatim]
527 <<
528   \context ChordNames {
529      \chordmode {
530        f1 g
531      }
532   }
533   \context Staff {
534     \clef "treble_8"
535     \override Voice.TextScript
536       #'fret-diagram-details #'finger-code = #'below-string
537
538     < f, c f a c' f'>1 ^\markup
539       \fret-diagram-verbose #'(
540         (place-fret 6 1)
541         (place-fret 5 3)
542         (place-fret 4 3)
543         (place-fret 3 2)
544         (place-fret 2 1)
545         (place-fret 1 1)
546         (barre 6 1 1)
547       )
548     < g, b, d g b' g'> ^\markup
549       \fret-diagram-verbose #'(
550         (place-fret 6 3 2)
551         (place-fret 5 2 1)
552         (open 4)
553         (open 3)
554         (open 2)
555         (place-fret 1 3 3)
556       )
557   }
558 >>
559 @end lilypond
560
561 All other fret diagram properties must be adjusted using @code{\override} 
562 when using the fret-diagram-verbose markup.
563
564 @ignore
565 The following example shows the three fret-diagram markup
566 interfaces, along with examples of common tweaks.  For example,
567 the size of the verbose fret diagram is reduced to 0.75, and the
568 finger indications are specified to appear below the diagram.  The
569 terse diagram includes tweaks to specify placement of finger code
570 and color of dots.
571
572 @lilypond[verbatim,ragged-right,quote]
573 \new Voice {
574   \clef "treble_8"
575   d^\markup \fret-diagram #"6-x;5-x;4-o;3-2;2-3;1-2;"
576   d d d
577   fis^\markup \override #'(size . 0.75) {
578     \override #'(finger-code . below-string) {
579       \fret-diagram-verbose #'((place-fret 6 2 1) (barre 6 1 2)
580                                (place-fret 5 4 3) 
581                                (place-fret 4 4 4)
582                                (place-fret 3 3 2) 
583                                (place-fret 2 2 1)
584                                (place-fret 1 2 1))
585     }
586   }
587   fis fis fis
588   c^\markup \override #'(dot-radius . 0.35) {
589     \override #'(finger-code . in-dot) {
590       \override #'(dot-color . white) {
591         \fret-diagram-terse #"x;3-1-(;5-2;5-3;5-4;3-1-);"
592       }
593     }
594   }
595   c c c
596 }
597 @end lilypond
598 @end ignore
599
600 The graphical layout of a fret diagram can be customized according to
601 user preference through the properties of the @code{fret-diagram-interface}.
602 Details are found at @rinternals{fret-diagram-interface}.  For a fret diagram
603 markup , the interface properties belong to @code{Voice.TextScript}.
604
605 @snippets
606
607 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
608 {customizing-markup-fret-diagrams.ly}
609
610
611 @seealso
612
613 Notation Reference:
614 @ref{Text markup commands}.
615
616 Snippets:
617 @rlsr{Fretted strings}.
618
619 Internals Reference:
620 @rinternals{fret-diagram-interface}.
621
622 @node Predefined fret diagrams
623 @subsubsection Predefined fret diagrams
624 @cindex fret diagrams
625 @cindex chord diagrams
626
627 Fret diagrams can be displayed using the @code{FretBoards} context.  By
628 default, the @code{FretBoards} context will display fret diagrams that
629 are stored in a lookup table:
630
631 @lilypond[verbatim, ragged-right, quote]
632 \include "predefined-guitar-fretboards.ly"
633 \context FretBoards {
634   \chordmode {
635     c1 d
636   }
637 }
638 @end lilypond
639
640 The default predefined fret diagrams are contained in the file
641 @code{predefined-guitar-fretboards.ly}.  Fret diagrams are 
642 stored based on the pitches of a chord and the value of
643 @code{stringTunings} that is currently in use.  
644 @code{predefined-guitar-fretboards.ly} contains predefined 
645 fret diagrams only for @code{guitar-tuning}.  Predefined fret
646 diagrams can be added for other instruments or other tunings
647 by following the examples found in 
648 @code{predefined-guitar-fretboards.ly}.  
649
650 Chord pitches can be entered
651 either as simultaneous music or using chord mode (see
652 @ref{Chord mode overview}).
653
654 @lilypond[verbatim, ragged-right,quote]
655 \include "predefined-guitar-fretboards.ly"
656 \context FretBoards {
657   \chordmode {c1}
658   <c' e' g'>1
659 }
660 @end lilypond
661
662 It is common that both chord names and fret diagrams are displayed together.
663 This is achieved by putting a @code{ChordNames} context in parallel with
664 a @code{FretBoards} context and giving both contexts the same music.
665
666 @lilypond[verbatim, ragged-right, quote]
667 \include "predefined-guitar-fretboards.ly"
668 mychords = \chordmode{
669   c1 f g
670 }
671
672 <<
673   \context ChordNames {
674     \mychords
675   }
676   \context FretBoards {
677     \mychords
678   }
679 >>
680 @end lilypond
681
682 Predefined fret diagrams are transposable, as long as a diagram for the
683 transposed chord is stored in the fret diagram table.
684
685 @lilypond[verbatim, ragged-right, quote]
686 \include "predefined-guitar-fretboards.ly"
687 mychords = \chordmode{
688   c1 f g
689 }
690
691 mychordlist = {
692   \mychords
693   \transpose c e { \mychords}
694 }
695 <<
696   \context ChordNames {
697     \mychordlist
698   }
699   \context FretBoards {
700     \mychordlist
701   }
702 >>
703 @end lilypond
704
705
706 The predefined fret diagram table contains seven chords (major, minor,
707 augmented, diminished, dominant seventh, major seventh, minor seventh)
708 for each of 17 keys.  A complete list of the predefined fret diagrams is
709 shown in @ref{Predefined fretboard diagrams}.  If there is no entry in
710 the table for a chord, the FretBoards engraver will calculate a
711 fret-diagram using the automatic fret diagram functionality described in
712 @ref{Automatic fret diagrams}.
713
714 @lilypond[verbatim, ragged-right, quote]
715 \include "predefined-guitar-fretboards.ly"
716 mychords = \chordmode{
717   c1 c:9
718 }
719
720 <<
721   \context ChordNames {
722     \mychords
723   }
724   \context FretBoards {
725     \mychords
726   }
727 >>
728 @end lilypond
729
730 Fret diagrams can be added to the fret diagram table.  To add a diagram,
731 you must specify the chord for the diagram, the tuning to be used, and the
732 fret-diagram-terse definition string for the diagram.
733
734 @lilypond[verbatim, ragged-right, quote]
735 \include "predefined-guitar-fretboards.ly"
736
737 \storePredefinedDiagram \chordmode {c:9} 
738                         #guitar-tuning
739                         #"x;3-2;2-1;3-3;3-4;x;"
740
741 mychords = \chordmode{
742   c1 c:9
743 }
744
745 <<
746   \context ChordNames {
747     \mychords
748   }
749   \context FretBoards {
750     \mychords
751   }
752 >>
753 @end lilypond
754
755 Different fret diagrams for the same chord name can be stored using different
756 octaves of pitches.
757
758 @lilypond[verbatim, ragged-right, quote]
759 \include "predefined-guitar-fretboards.ly"
760
761 \storePredefinedDiagram \chordmode {c'} 
762                         #guitar-tuning
763                         #(offset-fret 2 (chord-shape 'bes))
764
765 mychords = \chordmode{
766   c1 c'
767 }
768
769 <<
770   \context ChordNames {
771     \mychords
772   }
773   \context FretBoards {
774     \mychords
775   }
776 >>
777 @end lilypond
778
779 In addition to fret diagrams, LilyPond stores an internal list of chord
780 shapes.  The chord shapes are fret diagrams that can be shifted along
781 the neck to different posistions to provide different chords.  Chord
782 shapes can be added to the internal list and then used to define
783 predefined fret diagrams.
784
785 @lilypond[verbatim, ragged-right, quote]
786 \include "predefined-guitar-fretboards.ly"
787
788 % add a new chord shape
789
790 \addChordShape #'powerf #"1-1;3-3;3-4;x;x;x;"
791
792 % add some new chords based on the power chord shape
793
794 \storePredefinedDiagram \chordmode {f'} 
795                         #guitar-tuning 
796                         #(chord-shape 'powerf)
797 \storePredefinedDiagram \chordmode {g'} 
798                         #guitar-tuning
799                         #(offset-fret 2 (chord-shape 'powerf))
800
801 mychords = \chordmode{
802   f1 f' g g' 
803 }
804
805 <<
806   \context ChordNames {
807     \mychords
808   }
809   \context FretBoards {
810     \mychords
811   }
812 >>
813 @end lilypond
814
815 The graphical layout of a fret diagram can be customized according to
816 user preference through the properties of the @code{fret-diagram-interface}.
817 Details are found at @rinternals{fret-diagram-interface}.  For a 
818 predefined fret diagram, the interface properties belong to 
819 @code{FretBoards.FretBoard}.
820
821 @snippets
822
823 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
824 {customizing-fretboard-fret-diagrams.ly}
825
826
827 @seealso
828
829 Notation Reference:
830 @ref{Custom tablatures},
831 @ref{Automatic fret diagrams},
832 @ref{Chord mode overview},
833 @ref{Predefined fretboard diagrams}.
834
835 Installed Files:
836 @file{ly/predefined-guitar-fretboards.ly}.
837
838 Snippets:
839 @rlsr{Fretted strings}.
840
841 Internals Reference:
842 @rinternals {fret-diagram-interface}.
843
844
845 @node Automatic fret diagrams
846 @subsubsection Automatic fret diagrams
847 @cindex fret diagrams
848 @cindex chord diagrams
849
850 Fret diagrams can be automatically created from entered notes using the 
851 @code{FretBoards} context.  If no predefined diagram is available for
852 the entered notes in the active @code{stringTunings}, this context
853 calculates strings and frets that can be used to play the notes.
854
855 @lilypond[quote,ragged-right,verbatim]
856 <<
857   \context ChordNames {
858      \chordmode { 
859        f1 g  
860      }
861   }
862   \context FretBoards {
863     < f, c f a c' f'>1
864     < g,\6 b, d g b g'>
865   }
866   \context Staff {
867     \clef "treble_8"
868     < f, c f a c' f'>1
869     < g, b, d g b' g'>
870   }  
871 >>
872 @end lilypond
873
874 As no predefined diagrams are loaded by default, automatic calculation 
875 of fret diagrams is the default behavior.  Once default diagrams are
876 loaded, automatic calculation can be enabled and disabled with predefined
877 commands:
878
879 @lilypond[quote,ragged-right,verbatim]
880
881 \storePredefinedDiagram <c\5 e g c' e'>
882                         #guitar-tuning
883                         #"x;3-1-(;5-2;5-3;5-4;3-1-1);"
884 <<
885   \context ChordNames {
886      \chordmode { 
887        c1 c c 
888      }
889   }
890   \context FretBoards {
891     <c\5 e g c' e'>1
892     \predefinedFretboardsOff
893     <c\5 e g c' e'>
894     \predefinedFretboardsOn
895     <c\5 e g c' e'>
896   }
897   \context Staff {
898     \clef "treble_8"
899     <c\5 e g c' e'>1
900     <c\5 e g c' e'>
901     <c\5 e g c' e'>
902   }  
903 >>
904 @end lilypond
905
906   
907
908 Notes can be explicitly placed on a string.  It is often enough
909 to place only the lowest note on an explicit string; the rest of 
910 the notes will then be placed appropriately by the @code{FretBoards}
911 context.
912
913 @lilypond[quote,ragged-right,verbatim]
914 <<
915   \context ChordNames {
916      \chordmode { 
917        c1 c d:m d:m    
918      }
919   }
920   \context FretBoards {
921     < c e g c' e' > 1
922     < c\5 e g c' e' > 1
923     < d a d' f'>
924     < d\4 a d' f'>
925   }
926   \context Staff {
927     \clef "treble_8"
928     < c e g c' e' > 1
929     < c e g c' e' > 1
930     < d a d' f'>
931     < d a d' f'>
932   }  
933 >>
934 @end lilypond
935
936 Fingerings can be added to FretBoard fret diagrams.
937
938 @lilypond[quote, verbatim]
939 <<
940   \context ChordNames {
941      \chordmode { 
942        c1 d:m          
943      }
944   }
945   \context FretBoards {
946     < c\5-3 e-2 g c'-1 e' > 1
947     < d\4 a-2 d'-3 f'-1>
948   }
949   \context Staff {
950     \clef "treble_8"
951     < c e g c' e' > 1
952     < d a d' f'>
953   }  
954 >>
955 @end lilypond
956
957 The strings and frets for the @code{FretBoards} context depend
958 on the @code{stringTunings} property, which has the same meaning
959 as in the TabStaff context.  See @ref{Custom tablatures} for 
960 information on the @code{stringTunings} property. 
961
962 The graphical layout of a fret diagram can be customized according to
963 user preference through the properties of the @code{fret-diagram-interface}.
964 Details are found at @rinternals{fret-diagram-interface}.  For a 
965 @code{FretBoards} fret diagram, the interface properties belong to 
966 @code{FretBoards.FretBoard}.
967
968 @snippets
969 The minimum fret to be used in calculating strings and frets for
970 the FretBoard context can be set with the @code{minimumFret}
971 property.
972
973 @c TODO -- snippet showing minimum fret.
974
975 @c TODO -- snippet for using StringTunings
976
977 @predefined
978 \predefinedFretboardsOff,
979 \predefinedFretboardsOn.
980
981 @seealso
982
983 Notation Reference:
984 @ref{Custom tablatures}.
985
986 Snippets:
987 @rlsr{Fretted strings}.
988
989 Internals Reference:
990 @rinternals {fret-diagram-interface}.
991
992
993 @node Right-hand fingerings
994 @subsubsection Right-hand fingerings
995
996 Right-hand fingerings @var{p-i-m-a} must be entered within a  
997 chord construct @code{<>} for them to be printed in the score, 
998 even when applied to a single note. 
999
1000 @warning{There @strong{must} be a hyphen after the note and a space 
1001 before the closing @code{>}.}
1002
1003 @lilypond[quote,verbatim,relative=0]
1004 \clef "treble_8"
1005 <c-\rightHandFinger #1 >4 
1006 <e-\rightHandFinger #2 > 
1007 <g-\rightHandFinger #3 > 
1008 <c-\rightHandFinger #4 >
1009 <c,-\rightHandFinger #1 e-\rightHandFinger #2 g-\rightHandFinger #3 c-\rightHandFinger #4 >1
1010 @end lilypond
1011
1012 For convenience, you can abbreviate @code{\rightHandFinger} to something
1013 short, for example @code{RH},
1014
1015 @example
1016 #(define RH rightHandFinger)
1017 @end example
1018
1019 @cindex fingerings, right hand, for guitar
1020 @cindex right hand fingerings for guitar
1021
1022 @snippets
1023
1024 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
1025 {placement-of-right-hand-fingerings.ly}
1026
1027 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
1028 {fingerings,-string-indications,-and-right-hand-fingerings.ly}
1029
1030 @seealso
1031
1032 Snippets:
1033 @rlsr{Fretted strings}.
1034
1035 Internals Reference: 
1036 @rinternals{StrokeFinger}.
1037
1038
1039 @node Guitar
1040 @subsection Guitar
1041
1042 Most of the notational issues associated with guitar music are
1043 covered sufficiently in the general fretted strings section, but there
1044 are a few more worth covering here.  Occasionally users want to 
1045 create songbook-type documents having only lyrics with chord
1046 indications above them.  Since Lilypond is a music typesetter,
1047 it is not recommended for documents that have no music notation
1048 in them.  A better alternative is a word processor, text editor, 
1049 or, for experienced users, a typesetter like GuitarTeX.
1050
1051 @menu
1052 * Indicating position and barring::  
1053 * Indicating harmonics and dampened notes::  
1054 @end menu
1055
1056 @node Indicating position and barring
1057 @subsubsection Indicating position and barring
1058
1059 This example demonstrates how to include guitar position and
1060 barring indications.
1061
1062 @lilypond[quote,ragged-right,fragment,verbatim,relative=0]
1063 \clef "treble_8"
1064 b16 d g b e
1065 \textSpannerDown
1066 \override TextSpanner #'bound-details #'left #'text = #"XII "
1067   g16\startTextSpan
1068   b16 e g e b g\stopTextSpan
1069 e16 b g d
1070 @end lilypond
1071
1072 @seealso
1073
1074 Notation Reference:
1075 @ref{Text spanners}.
1076
1077 Snippets:
1078 @rlsr{Fretted strings},
1079 @rlsr{Expressive marks}.
1080
1081 @node Indicating harmonics and dampened notes
1082 @subsubsection Indicating harmonics and dampened notes
1083
1084 Special note heads can be used to indicate dampened notes or 
1085 harmonics.  Harmonics are normally further explained with a 
1086 text markup.
1087
1088 @lilypond[quote,ragged-right,fragment,verbatim]
1089 \relative c' {
1090   \clef "treble_8"
1091   \override Staff.NoteHead #'style = #'cross
1092   g8 a b c b4
1093   \override Staff.NoteHead #'style = #'harmonic-mixed
1094   d^\markup { \italic { \fontsize #-2 { "harm. 12" }}} <g b>1
1095 }
1096 @end lilypond
1097
1098 @seealso
1099
1100 Snippets:
1101 @rlsr{Fretted strings}.
1102
1103 Notation Reference:
1104 @ref{Special note heads},
1105 @ref{Note head styles}.
1106
1107 @node Banjo
1108 @subsection Banjo
1109
1110 @menu
1111 * Banjo tablatures::            
1112 @end menu
1113
1114 @node Banjo tablatures
1115 @subsubsection Banjo tablatures
1116 @cindex Banjo tablatures
1117
1118 LilyPond has basic support for the five-string banjo.  When making tablatures
1119 for five-string banjo, use the banjo tablature format function to get
1120 correct fret numbers for the fifth string:
1121
1122 @c due to crazy intervals of banjo music, absolute pitch is recommended
1123
1124 @lilypond[quote,ragged-right,fragment,verbatim]
1125 \new TabStaff <<
1126   \set TabStaff.tablatureFormat = #fret-number-tablature-format-banjo
1127   \set TabStaff.stringTunings = #banjo-open-g-tuning
1128   {
1129     \stemDown
1130     g8 d' g'\5 a b g e d' |
1131     g4 d''8\5 b' a'\2 g'\5 e'\2 d' |
1132     g4
1133   }
1134 >>
1135 @end lilypond
1136
1137 A number of common tunings for banjo are predefined in LilyPond:
1138 @code{banjo-c-tuning} (gCGBD), @code{banjo-modal-tuning} (gDGCD),
1139 @code{banjo-open-d-tuning} (aDF#AD) and @code{banjo-open-dm-tuning}
1140 (aDFAD).
1141
1142 These tunings may be converted to four-string banjo tunings using the
1143 @code{four-string-banjo} function:
1144
1145 @example
1146 \set TabStaff.stringTunings = #(four-string-banjo banjo-c-tuning)
1147 @end example
1148
1149 @seealso
1150
1151 Snippets:
1152 @rlsr{Fretted strings}.
1153
1154 The file @file{scm/@/output@/-lib@/.scm} contains predefined banjo tunings.
1155
1156
1157
1158
1159