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