1 @c -*- coding: utf-8; mode: texinfo; -*-
3 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
5 When revising a translation, copy the HEAD committish of the
6 version that you are working on. See TRANSLATION for details.
13 @lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
16 This section discusses how to specify the pitch of notes. There
17 are three steps to this process: input, modifying, and output.
21 * Changing multiple pitches::
22 * Displaying pitches::
28 @subsection Writing pitches
30 This section discusses how to input pitches.
33 * Absolute octave entry::
34 * Relative octave entry::
36 * Note names in other languages::
40 @node Absolute octave entry
41 @unnumberedsubsubsec Absolute octave entry
46 @c don't use @samp here because that might get confused with
48 A pitch name is specified using lowercase letters@tie{}@code{a}
49 through@tie{}@code{g}. An ascending C-major scale is engraved
52 @lilypond[verbatim,quote,ragged-right,fragment]
57 There are two different ways to enter these note names with regard
58 to octave placement: absolute and relative. The relative mode
59 will in most cases be the most convenient, but the absolute mode
60 is more fundamental and will be presented first.
63 @cindex absolute octave specification
65 In absolute mode, every note is placed explicitly in a specific
66 octave. The note names @code{c} to @code{b} are engraved in the
67 octave below middle C, as in the previous example.
69 @lilypond[verbatim,quote,ragged-right,fragment]
79 If a note should be in another octave than this, an octave
80 specification must be given. It takes the form of a series of
81 single quote@tie{}(@code{'}) or comma@tie{}(@code{,}) characters.
82 Each@tie{}@code{'} raises the pitch by one octave;
83 each@tie{}@code{,} lowers the pitch by an octave.
85 @lilypond[verbatim,quote,ragged-right,fragment]
87 c' c'' e' g d'' d' d c
89 c, c,, e, g d,, d, d c
94 Snippets: @lsrdir{pitches}.
96 Internals reference: @internalsref{LedgerLineSpanner},
97 @internalsref{NoteHead}.
100 @node Relative octave entry
101 @unnumberedsubsubsec Relative octave entry
104 @cindex relative octave specification
107 The absolute mode requires a lot of octave specifications, which
108 not only becomes tedious but also easily leads to errors.
109 Therefore, it is usually more convenient to let notes be entered
110 relative to the previous note. This is done with the relative
114 \relative @var{startpitch} @var{musicexpr}
117 In relative mode, each note is assumed to be as close to the
118 previous note as possible. This means that the octave of notes
119 that appear in @var{musicexpr} are calculated as follows:
123 The pitch of the first note is relative to @code{\relative
127 If no octave changing marks are used, the basic interval between a
128 note and the one that precedes it is always taken to be a fourth
132 This distance is determined without regarding alterations or the
133 actual sounding pitches; a @code{fisis} following a @code{ceses}
134 will be put above the @code{ceses}. In other words, a
135 doubly-augmented fourth is considered a smaller interval than a
136 diminished fifth, even though the doubly-augmented fourth spans
137 seven semitones while the diminished fifth only spans six
141 The octave changing marks@tie{}@code{'} and@tie{}@code{,} can be
142 added to raise or lower the pitch by an extra octave from the
146 Multiple octave changing marks can be used. @code{''}@tie{}will
147 raise the pitch by two octaves.
151 Here is the relative mode shown in action:
153 @lilypond[verbatim,quote,ragged-right,fragment]
159 Octave changing marks are used for intervals greater than a
162 @lilypond[verbatim,quote,ragged-right,fragment]
168 A note sequence without a single octave mark can nevertheless span
171 @lilypond[verbatim,quote,ragged-right,fragment]
177 If the preceding item is a chord, the first note of the chord is
178 used as the reference point for the octave placement of a
179 following note or chord:
181 @lilypond[verbatim,quote,ragged-right,fragment]
189 The @var{startpitch} (after @code{\relative}) is a note name in
190 absolute mode. In principle it can be any note name, but common
191 practice is to use@tie{}@code{c} in various octave positions.
193 When octaves are specified as above by adding@tie{}@code{'}
194 and@tie{}@code{,} to pitch names, it is easy to accidentally put a
195 pitch in the wrong octave. The relative octave mode prevents
196 these errors since most of the time it is not necessary to
197 indicate any octaves at all. Furthermore, in absolute mode, a
198 single mistake may be difficult to spot; in relative mode, a
199 single error puts the rest of the piece off by one octave.
201 LilyPond examines pitches based on the note names -- in other
202 words, an augmented fourth is @emph{not} treated the same as a
203 diminished fifth. If we begin at a C, then an F-sharp will be
204 placed higher than the C, while a G-flat will be placed lower than
207 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
214 Snippets: @lsrdir{pitches}.
219 The relative conversion will not affect @code{\transpose},
220 @code{\chordmode} or @code{\relative} sections in its argument.
221 To use relative within transposed music, an additional
222 @code{\relative} must be placed inside @code{\transpose}.
225 If no @var{startpitch} is specified for @code{\relative},
226 then@tie{}@code{c'} is assumed. However, this is a deprecated
227 option and may disappear in future versions, so its use is
233 @unnumberedsubsubsec Accidentals
235 @warning{New users are sometimes confused about accidentals and
236 key signatures. In LilyPond, note names are the raw input; key
237 signatures and clefs determine how this raw input is displayed.
238 An unaltered note like@tie{}@code{c} means @q{C natural},
239 regardless of the key signature or clef. For more information,
240 see @rlearning{Accidentals and key signatures}.}
242 @cindex note names, Dutch
243 @cindex note names, default
245 A @notation{sharp} pitch is made by adding @code{is} to the name,
246 and a @notation{flat} pitch by adding @code{es}. As you might
247 expect, a @notation{double sharp} or @notation{double flat} is
248 made by adding @code{isis} or @code{eses}. This syntax derived
249 from note naming conventions in Nordic and Germanic languages,
250 like German and Dutch. To use other names for accidentals, see
251 @ref{Note names in other languages}.
253 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
259 These are the Dutch note names. In Dutch, @code{aes} is
260 contracted to @code{as}, but both forms are accepted. Similarly,
261 both @code{es} and @code{ees} are accepted:
263 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
267 A natural will cancel the effect of an accidental or key
268 signature. However, naturals are not encoded into the note name
269 syntax with a suffix; a natural pitch is shown as a simple note
272 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
277 @cindex accidental, reminder
278 @cindex accidental, cautionary
279 @cindex accidental, parenthesized
280 @cindex reminder accidental
282 @cindex cautionary accidental
283 @cindex parenthesized accidental
286 Normally accidentals are printed automatically, but you may also
287 print them manually. A reminder accidental can be forced by
288 adding an exclamation mark@tie{}@code{!} after the pitch. A
289 cautionary accidental (i.e., an accidental within parentheses) can
290 be obtained by adding the question mark@tie{}@code{?} after the
291 pitch. These extra accidentals can be used to produce natural
294 @lilypond[verbatim,quote,ragged-right,fragment,relative=1]
295 cis cis cis! cis? c c? c! c
299 @cindex quarter tones
300 @cindex semi-flats, semi-sharps
302 Half-flats and half-sharps are formed by adding @code{eh} and
303 @code{ih}; the following is a series of Cs with increasing
306 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
307 \set Staff.extraNatural = ##f
311 Micro tones are also exported to the MIDI file.
316 @lsr{pitches,preventing-extra-naturals-from-being-automatically-added.ly}
320 In accordance with standard typesetting rules, a natural sign is
321 printed before a sharp or flat if a previous accidental needs to
322 be canceled. To change this behavior, use
324 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
326 \set Staff.extraNatural = ##f
333 Music Glossary: @rglos{sharp}, @rglos{flat}, @rglos{double sharp},
336 Learning Manual: @rlearning{Accidentals and key signatures}.
338 Notation Reference: @ref{Automatic accidentals},
339 @ref{Musica ficta accidentals},
340 @ref{Note names in other languages}.
342 Snippets: @lsrdir{pitches}.
347 There are no generally accepted standards for denoting
348 three-quarter flats, so LilyPond's symbol does not conform to any
353 @node Note names in other languages
354 @unnumberedsubsubsec Note names in other languages
356 There are predefined sets of note names for various other
357 languages. To use them, include the language specific init file.
358 For example, add @code{\include "english.ly"} to the top of the
359 input file. The available language files and the note names they
362 @cindex note names, other languages
365 @multitable @columnfractions .2 .6 .05 .05 .05 .05
368 @tab sharp @tab flat @tab double sharp @tab double flat
370 @tab c d e f g a bes b
371 @tab -is @tab -es @tab -isis @tab -eses
373 @tab c d e f g a bf b
374 @tab -s/-sharp @tab -f/-flat @tab -ss/-x/-sharpsharp
378 @tab -is @tab -es @tab -isis @tab -eses
381 @tab -iss/-is @tab -ess/-es @tab -ississ/-isis
385 @tab -iss @tab -ess @tab -ississ @tab -essess
388 @tab -is @tab -es @tab -isis @tab -eses
390 @tab do re mi fa sol la sib si
391 @tab -d @tab -b @tab -dd @tab -bb
393 @tab do re mi fa sol la sib si
394 @tab -d/-s @tab -b @tab -dd/-ss @tab -bb
396 @tab do re mi fa sol la sib si
397 @tab -s @tab -b @tab -ss @tab -bb
399 @tab do re mi fa sol la sib si
400 @tab -s @tab -b @tab -ss @tab -bb
402 @tab do re mi fa sol la sib si
403 @tab -k @tab -b @tab -kk @tab -bb
408 Note that in Dutch, German, Norwegian, and Swedish, the flat
409 alterations of@tie{}@code{a} like for example @code{aes} and
410 @code{aeses} are usually contracted to @code{as} and @code{ases}
411 (or more commonly @code{asas}). Sometimes only these contracted
412 names are defined in the corresponding language files (this also
413 applies to the suffixes for quartertones below).
416 Some music uses microtones whose alterations are fractions of a
417 @q{normal} sharp or flat. The note names for quartertones defined
418 in the various language files are listed in the following table.
419 Here the prefixes @q{semi-} and @q{sesqui-} mean @q{half} and
420 @q{one and a half}, respectively. For the other languages no
421 special names have been defined yet.
424 @c What about Turkish Maquam music and similar microtonal systems?
426 @c Note that the term "three-quarter-sharp/-flat" used in
427 @c lilypond's source code is actually misleading since the
428 @c alteration is in fact one and a half of a regular sharp/flat.
429 @c Whence the naming "sesqui-sharp/-flat" used below.
432 @multitable @columnfractions .2 .6 .05 .05 .05 .05
435 @tab semi- @tab semi- @tab sesqui- @tab sesqui-
438 @tab c d e f g a bes b
439 @tab -ih @tab -eh @tab -isih @tab -eseh
441 @tab c d e f g a bf b
442 @tab -qs @tab -qf @tab -tqs @tab -tqf
445 @tab -ih @tab -eh @tab -isih @tab -eseh
447 @c @tab c d e f g a b h
449 @c @tab c d e f g a b h
451 @tab do re mi fa sol la sib si
452 @tab -sd @tab -sb @tab -dsd @tab -bsb
454 @c @tab do re mi fa sol la sib si
456 @c @tab do re mi fa sol la sib si
458 @tab do re mi fa sol la sib si
459 @tab -sqt @tab -bqt @tab -stqt @tab -btqt
465 Snippets: @lsrdir{pitches}.
468 @node Changing multiple pitches
469 @subsection Changing multiple pitches
471 This section discusses how to modify pitches.
479 @unnumberedsubsubsec Octave check
483 In relative mode, it is easy to forget an octave changing mark.
484 Octave checks make such errors easier to correct. A note may be
485 followed by @code{=}@var{quotes} to indicate what its absolute
486 octave should be. In the following example,
489 \relative c'' @{ c g d='' @}
493 the@tie{}@code{d} will generate a warning, because
494 a@tie{}@code{d''} is expected, as indicated by the octave check
495 @code{=''}, but a @code{d'} is found, since both @code{c}-@code{g}
496 and @code{g}-@code{d} without octavation marks are descending
497 fourths. In the output, the octave is corrected to be
498 a@tie{}@code{d''} and the next note is calculated relative
499 to@tie{}@code{d''} instead of@tie{}@code{d'}.
501 There is also an octave check that produces no visible output.
505 @var{pitch} \octave @var{controlpitch}
509 where @var{pitch} is a regular note within a music expression in
510 relative mode and @var{controlpitch} is a pitch in absolute mode.
511 This checks that @var{pitch} lies within the octave surrounding
512 @var{controlpitch}, i.e. not more than a fourth above or below it.
513 If this is not the case, a warning is printed and the octave is
514 corrected. The @var{controlpitch} is not printed as a note.
516 In the example below, the first check passes without incident,
517 since the@tie{}@code{e} (in @code{relative} mode) is within the
518 octave range of@tie{}@code{a'}. However, the second check
519 produces a warning, since the@tie{}@code{e} is not within the
520 octave range of@tie{}@code{b'}. The warning message is printed,
521 and the octave is adjusted so that the following notes are in the
522 correct octave once again.
533 The octave of a note following an @code{\octave} check is
534 determined with respect to the note preceding it, as modified by
535 the outcome of the octave check. In the next fragment, the first
536 note, an@tie{}@code{e'}, lies within the octave of@tie{}@code{b},
537 and the @code{\octave} check passes successfully. The second note
538 is then calculated relative to (absolute)@tie{}@code{e'}, which
539 yields an@tie{}@code{a'}, above middle@tie{}C. In this case, the
540 check had no influence on the output of the piece.
542 The second @code{\octave} check fails: @code{a'}@tie{}is not
543 within the range of@tie{}@code{b}. A warning is issued, and the
544 last note is calculated relative to@tie{}@code{a}, not
545 to@tie{}@code{a'}, and we get a@tie{}@code{d'}. Without the last
546 @code{\octave} check, the last note would have been
549 @lilypond[verbatim,quote,ragged-right,fragment]
561 Snippets: @lsrdir{pitches}.
565 @unnumberedsubsubsec Transpose
568 @cindex transposition of pitches
571 A music expression can be transposed with @code{\transpose}. The
575 \transpose @var{from} @var{to} @var{musicexpr}
578 This means that @var{musicexpr} is transposed by the interval
579 between the pitches @var{from} and @var{to}: any note with pitch
580 @var{from} is changed to @var{to} and any other note is transposed
581 by the same interval.
583 Consider a piece written in the key of D-major. If this piece is
584 a little too low for its performer, it can be transposed up to
588 \transpose d e @dots{}
591 Consider a part written for violin (a C instrument). If this part
592 is to be played on the A clarinet (for which an A is notated as a
593 C, and thus sounds a minor third lower than notated), the
594 following transposition will produce the appropriate part:
597 \transpose a c @dots{}
600 @code{\transpose} will also transpose key signatures:
602 @lilypond[verbatim,quote,ragged-right]
603 mus = { \key d \major cis d fis g }
612 @code{\transpose} distinguishes between enharmonic pitches: both
613 @code{\transpose c cis} or @code{\transpose c des} will transpose
614 up half a tone. The first version will print sharps and the notes
615 will remain on the same scale step, the second version will print
616 flats on the scale step above.
618 @lilypond[verbatim,quote,ragged-right]
621 \transpose c cis { \relative c' \mus }
622 \transpose c des { \relative c' \mus }
626 @code{\transpose} may also be used to input written notes for a
627 transposing instrument. The previous examples show how to enter
628 pitches in C (or @notation{concert pitch}) and typeset them for a
629 transposing instrument, but the opposite is also possible if you
630 for example have a set of instrumental parts and want to print a
631 conductor's score. For example, when entering music for a B-flat
632 trumpet which begins on a notated E (concert D), one would write:
635 musicInBflat = @{ e4 @dots{} @}
636 \transpose c bes \musicInBflat
639 To print this music in F (e.g., rearranging to a french horn) you
640 would wrap the existing music with another @code{\transpose}
643 musicInBflat = @{ e4 @dots{} @}
644 \transpose f c @{ \transpose c bes \musicInBflat @}
649 Snippets: @lsrdir{pitches}, @lsr{scheme,
650 transpose-pitches-with-minimum-accidentals.ly}.
652 Internals reference: @internalsref{TransposedMusic}.
656 If you want to use both @code{\transpose} and @code{\relative},
657 you must put @code{\transpose} outside of @code{\relative}, since
658 @code{\relative} will have no effect on music that appears inside
659 a @code{\transpose}. See the previous example.
662 @node Displaying pitches
663 @subsection Displaying pitches
665 This section discusses how to alter the output of pitches.
671 * Instrument transpositions::
672 * Automatic accidentals::
677 @unnumberedsubsubsec Clef
691 @cindex mezzosoprano clef
692 @cindex baritone clef
693 @cindex varbaritone clef
696 The clef is set with the @code{\clef} @var{clefname}
699 @lilypond[verbatim,quote,ragged-right,fragment]
702 % treble clef by default
716 The clef can also be changed inside the staff:
718 @lilypond[verbatim,quote,ragged-right,fragment]
736 These same clef symbols are used in different positions on the
737 staff to change the range of notes shown by that staff. The
738 treble (alto, bass) clef is always positioned to show the line on
739 which a@tie{}@code{g'} (@code{c'}, @code{f}) note is printed.
741 Supported clefs include
743 @multitable @columnfractions .4 .6
744 @headitem Clef @tab Position
745 @item @code{treble, violin, G, G2} @tab
746 G clef (g') on 2nd line
747 @item @code{alto, C} @tab
748 C clef (c') on 3rd line
749 @item @code{tenor} @tab
750 C clef (c') on 4th line
751 @item @code{bass, F} @tab
752 F clef (f) on 4th line
753 @item @code{french} @tab
754 G clef (g') on 1st line, so-called French violin clef
755 @item @code{soprano} @tab
756 C clef (c') on 1st line
757 @item @code{mezzosoprano} @tab
758 C clef (c') on 2nd line
759 @item @code{baritone} @tab
760 C clef (c') on 5th line
761 @item @code{varbaritone} @tab
762 F clef (f) on 3rd line
763 @item @code{subbass} @tab
764 F clef (f) on 5th line
765 @item @code{percussion} @tab
767 @item @code{tab} @tab
771 Further supported clefs are described under @ref{Ancient clefs}.
773 By adding @code{_8} or @code{^8} to the clef name, the clef is
774 transposed one octave down or up, respectively, and @code{_15} and
775 @code{^15} transposes by two octaves. The argument @var{clefname}
776 must be enclosed in quotes when it contains underscores or digits.
779 @cindex choral tenor clef
781 @lilypond[verbatim,quote,ragged-right,fragment,relative=1]
787 When a clef change takes place at a line break the new clef symbol
788 is printed at both the end of the previous line and the beginning
789 of the new line by default. If the warning clef at the end of the
790 previous line in not required it can be suppressed by setting the
791 @code{explicitClefVisibility} Staff property to the value
792 @var{end-of-line-invisible}: @code{\set
793 Staff.explicitClefVisibility = #end-of-line-invisible} The default
794 behaviour can be recovered with @code{\unset
795 Staff.explicitClefVisibility}
797 The command @code{\clef "treble_8"} is equivalent to setting
798 @code{clefGlyph}, @code{clefPosition} (which controls the Y
799 position of the clef), @code{middleCPosition} and
800 @code{clefOctavation}. A clef is printed when either the
801 @code{clefGlyph}, @code{clefPosition} or @code{clefOctavation}
802 properties are changed. Note that changing the glyph, the
803 position of the clef, or the octavation, does not in itself change
804 the position of subsequent notes on the staff: the position of
805 middle C must also be specified to do this. The positional
806 parameters are relative to the staff centre line, positive numbers
807 displacing upwards, counting 1 for each line and space. The
808 clefOctavation value would normally be set to 7, -7, 15 or -15,
809 but other values are not invalid.
811 The following examples show the possibilities when setting these
812 properties manually. First some manual changes which preserve the
813 standard relative positioning of clefs and notes:
815 @lilypond[verbatim,quote,ragged-right]
817 % The default treble clef
819 % The standard bass clef
820 \set Staff.clefGlyph = #"clefs.F"
821 \set Staff.clefPosition = #2
822 \set Staff.middleCPosition = #6
825 \set Staff.clefGlyph = #"clefs.C"
826 \set Staff.clefPosition = #4
827 \set Staff.middleCPosition = #4
829 % The standard choral tenor clef
830 \set Staff.clefGlyph = #"clefs.G"
831 \set Staff.clefPosition = #-2
832 \set Staff.clefOctavation = #-7
833 \set Staff.middleCPosition = #1
835 % A non-standard clef
836 \set Staff.clefPosition = #0
837 \set Staff.clefOctavation = #0
838 \set Staff.middleCPosition = #-4
843 and some which do not:
845 @lilypond[verbatim,quote,ragged-right]
847 \set Staff.clefGlyph = #"clefs.F"
848 \set Staff.clefPosition = #2
850 \set Staff.clefGlyph = #"clefs.G"
852 \set Staff.clefGlyph = #"clefs.C"
854 \set Staff.clefOctavation = #7
856 \set Staff.clefOctavation = #0
857 \set Staff.clefPosition = #0
859 \set Staff.middleCPosition = #4
866 Notation Reference: @ref{Ancient clefs}.
868 Snippets: @lsrdir{pitches}.
870 Internals reference: @internalsref{Clef}.
874 @unnumberedsubsubsec Key signature
876 @cindex key signature
879 @warning{New users are sometimes confused about accidentals and
880 key signatures. In LilyPond, note names are the raw input; key
881 signatures and clefs determine how this raw input is displayed.
882 An unaltered note like@tie{}@code{c} means @q{C natural},
883 regardless of the key signature or clef. For more information,
884 see @rlearning{Accidentals and key signatures}.}
886 The key signature indicates the tonality in which a piece is
887 played. It is denoted by a set of alterations (flats or sharps)
888 at the start of the staff.
890 Setting or changing the key signature is done with the @code{\key}
894 \key @var{pitch} @var{type}
903 @funindex \mixolydian
909 Here, @var{type} should be @code{\major} or @code{\minor} to get
910 @var{pitch}-major or @var{pitch}-minor, respectively. You may
911 also use the standard mode names (also called @q{church modes}):
912 @code{\ionian}, @code{\locrian}, @code{\aeolian},
913 @code{\mixolydian}, @code{\lydian}, @code{\phrygian}, and
916 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
925 @lsr{pitches,preventing-natural-signs-from-being-printed-when-the-key-signature-changes.ly}
929 A natural sign is printed to cancel any previous accidentals.
932 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
937 \set Staff.printKeyCancellation = ##f
945 The @code{\key} command sets the context property
946 @code{Staff.keySignature}. Non-standard key signatures can be
947 specified by setting this property directly. The format of this
951 \set Staff.keySignature =
952 #'((@var{octave} . @var{step}) . @var{alter})
956 where, for each element in the list, @var{octave} specifies the
957 octave (0 being the octave from middle C to the B above),
958 @var{step} specifies the note within the octave (0 means C and 6
959 means B), and @var{alter} is @code{,SHARP} @code{,FLAT}
960 @code{,DOUBLE-SHARP} etc. (Note the leading comma.) Here is an
961 example of a possible key signature for generating a whole-tone
964 @lilypond[verbatim,quote,ragged-right]
967 \set Staff.keySignature =
968 #`(((0 . 3) . ,SHARP) ((0 . 5) . ,FLAT) ((0 . 6) . ,FLAT))
976 Music Glossary: @rglos{church mode}, @rglos{scordatura}.
978 Learning Manual: @rlearning{Accidentals and key signatures}.
980 Snippets: @lsrdir{pitches},
981 FIXME link to snippet 248,
982 FIXME link to a snippet about scordatura.
984 Internals reference: @internalsref{KeyCancellation},
985 @internalsref{KeySignature}, @internalsref{Key_engraver}.
988 @node Ottava brackets
989 @unnumberedsubsubsec Ottava brackets
997 @notation{Ottava brackets} introduce an extra transposition of an
998 octave for the staff:
1000 @lilypond[verbatim,quote,ragged-right,fragment]
1010 The @code{set-octavation} function also takes -1 (for 8va bassa),
1011 2@tie{}(for 15ma), and -2 (for 15ma bassa) as arguments.
1012 Internally the function sets the properties @code{ottavation}
1013 (e.g., to @code{"8va"} or @code{"8vb"}) and
1014 @code{middleCPosition}. To override the text of the bracket, set
1015 @code{ottavation} after invoking @code{set-octavation}, i.e.,
1017 @lilypond[verbatim,quote,ragged-right]
1020 \set Staff.ottavation = #"8"
1028 Music Glossary: @c FIXME add link once it's in the glossary @c @rgloss{ottava}.
1030 Snippets: @lsrdir{pitches}.
1032 Internals reference: @internalsref{OttavaBracket}.
1037 @code{set-octavation} will get confused when clef changes happen
1038 during an octavation bracket.
1041 @node Instrument transpositions
1042 @unnumberedsubsubsec Instrument transpositions
1044 @cindex transposition, MIDI
1045 @cindex transposition, instrument
1047 The key of a @notation{transposing instrument} can be specified.
1048 This applies to many wind instruments, for example, clarinets
1049 (B-flat, A, and E-flat), horn (F) and trumpet (B-flat, C, D, and
1052 The transposition is entered with the command
1055 \transposition @var{pitch}
1059 where @var{pitch} specifies the key in which the instrument plays.
1060 For example, a part for B-flat clarinet would include
1066 This command sets the property @code{instrumentTransposition}.
1067 The value of this property is used for MIDI output and quotations.
1068 MIDI output is transposed to play at concert pitch, and cue notes
1069 and quotations are automatically transposed to the key of the
1070 instrument in which they are quoted. For more information about
1071 quotations, see @ref{Quoting other voices}.
1073 The pitch to use for @code{\transposition} should correspond to
1074 the real sound heard when a@tie{}@code{c'} written on the staff is
1075 played by the transposing instrument. @code{\transposition}
1076 should be used when the music is entered from an orchestral part
1077 written for the instrument. For example, in classical horn parts,
1078 the tuning of the instrument is often changed during a piece.
1079 Here are a few notes for a violin and a B-flat clarinet where the
1080 parts have been entered using the notes and key as they appear in
1081 each part or the conductor's score:
1083 @lilypond[verbatim,quote,ragged-right]
1085 \new Staff = "Violin I" {
1086 \set Staff.instrumentName = "Vln"
1087 \set Staff.midiInstrument="violin"
1090 g'4( c''8) r c'' r c''4
1092 \new Staff = "Clarinet" {
1093 \set Staff.instrumentName = "Cl"
1094 \set Staff.midiInstrument="clarinet"
1097 a'4( d''8) r d'' r d''4
1102 Without the @code{\transposition} command the MIDI output of this
1103 music would play the notes a tone apart; with it the notes are
1104 played correctly in unison.
1106 However, when entering the notes of a score in concert pitch, when
1107 all voices are entered in C, they may be prefaced by (the default)
1108 @code{\transposition c'}:
1122 to serve as a reminder that these parts are written in C.
1127 Music Glossary: @c FIXME add link once it's in the glossary @c @rgloss{instrument transposition}.
1129 Notation Reference: @ref{Quoting other voices}, @ref{Transpose}.
1131 Snippets: @lsrdir{pitches}.
1134 @node Automatic accidentals
1135 @unnumberedsubsubsec Automatic accidentals
1136 @cindex automatic accidentals
1138 Common rules for typesetting accidentals have been placed in a
1139 function. This function is called as follows
1141 @funindex set-accidental-style
1145 #(set-accidental-style 'voice)
1150 @c TODO: check the context stuff below
1151 @c -does it *really* work?
1152 @c -the default contexts as specified in
1153 @c scm/music-function.scm seem to be different -vv
1155 If no context name is supplied, the accidental style applies to
1156 the @code{Staff} by default. Optionally, the function can take
1157 the context for which the style should be changed as a second
1161 #(set-accidental-style 'STYLE #('CONTEXT))
1164 The following accidental styles are supported. To demonstrate
1165 each style, we use the following example:
1167 @lilypond[verbatim,quote,ragged-right]
1171 cis'8 fis, d'4 <a cis>8 f bis4 |
1185 \voiceTwo \relative c' {
1189 \change Staff = down
1193 \change Staff = down
1194 <fis, a cis>4 gis <f a d>2 |
1201 \context Staff = "up" {
1202 %%% change the next line as desired:
1203 %#(set-accidental-style 'default)
1206 \context Staff = "down" {
1207 %%% change the next line as desired:
1208 %#(set-accidental-style 'default)
1215 @c don't use verbatim in this table.
1218 This is the default typesetting behavior. It corresponds to
1219 eighteenth-century common practice: Accidentals are remembered to
1220 the end of the measure in which they occur and only on their own
1221 octave. Thus, in the example below, no natural signs are printed
1222 before the@tie{}@code{b} in the second measure or the
1225 @lilypond[quote,ragged-right]
1229 cis'8 fis, d'4 <a cis>8 f bis4 |
1243 \voiceTwo \relative c' {
1247 \change Staff = down
1251 \change Staff = down
1252 <fis, a cis>4 gis <f a d>2 |
1259 \context Staff = "up" {
1260 %#(set-accidental-style 'default)
1263 \context Staff = "down" {
1264 %#(set-accidental-style 'default)
1272 The normal behavior is to remember the accidentals on
1273 Staff-level. This variable, however, typesets accidentals
1274 individually for each voice. Apart from that, the rule is similar
1277 As a result, accidentals from one voice do not get canceled in
1278 other voices, which is often an unwanted result: in the following
1279 example, it is hard to determine whether the second@tie{}@code{a}
1280 should be played natural or sharp. The @code{voice} option should
1281 therefore be used only if the voices are to be read solely by
1282 individual musicians. If the staff is to be used by one musician
1283 (e.g., a conductor or in a piano score) then @code{modern} or
1284 @code{modern-cautionary} should be used instead.
1287 @lilypond[quote,ragged-right]
1291 cis'8 fis, d'4 <a cis>8 f bis4 |
1305 \voiceTwo \relative c' {
1309 \change Staff = down
1313 \change Staff = down
1314 <fis, a cis>4 gis <f a d>2 |
1321 \context Staff = "up" {
1322 #(set-accidental-style 'voice)
1325 \context Staff = "down" {
1326 #(set-accidental-style 'voice)
1334 @funindex modern style accidentals
1336 This rule corresponds to the common practice in the twentieth
1337 century. It prints the same accidentals as @code{default}, with
1338 two exceptions which serve to avoid ambiguity: after temporary
1339 accidentals, cancellation marks are printed also in the following
1340 measure (for notes in the same octave) and, in the same measure,
1341 for notes in other octaves. Hence the naturals before
1342 the@tie{}@code{b} and the@tie{}@code{c} in the second measure of
1345 @lilypond[quote,ragged-right]
1349 cis'8 fis, d'4 <a cis>8 f bis4 |
1363 \voiceTwo \relative c' {
1367 \change Staff = down
1371 \change Staff = down
1372 <fis, a cis>4 gis <f a d>2 |
1379 \context Staff = "up" {
1380 #(set-accidental-style 'modern)
1383 \context Staff = "down" {
1384 #(set-accidental-style 'modern)
1391 @item modern-cautionary
1392 @funindex modern-cautionary
1394 This rule is similar to @code{modern}, but the @q{extra}
1395 accidentals (the ones not typeset by @code{default}) are typeset
1396 as cautionary accidentals. They are by default printed with
1397 parentheses, but they can also be printed in reduced size by
1398 defining the @code{cautionary-style} property of
1399 @code{AccidentalSuggestion}.
1402 @lilypond[quote,ragged-right]
1406 cis'8 fis, d'4 <a cis>8 f bis4 |
1420 \voiceTwo \relative c' {
1424 \change Staff = down
1428 \change Staff = down
1429 <fis, a cis>4 gis <f a d>2 |
1436 \context Staff = "up" {
1437 #(set-accidental-style 'modern-cautionary)
1440 \context Staff = "down" {
1441 #(set-accidental-style 'modern-cautionary)
1449 @funindex modern-voice
1451 This rule is used for multivoice accidentals to be read both by
1452 musicians playing one voice and musicians playing all voices.
1453 Accidentals are typeset for each voice, but they @emph{are}
1454 canceled across voices in the same @internalsref{Staff}. Hence,
1455 the@tie{}@code{a} in the last measure is canceled because the
1456 previous cancellation was in a different voice, and
1457 the@tie{}@code{d} in the lower staff is canceled because of the
1458 accidental in a different voice in the previous measure:
1461 @lilypond[quote,ragged-right]
1465 cis'8 fis, d'4 <a cis>8 f bis4 |
1479 \voiceTwo \relative c' {
1483 \change Staff = down
1487 \change Staff = down
1488 <fis, a cis>4 gis <f a d>2 |
1495 \context Staff = "up" {
1496 #(set-accidental-style 'modern-voice)
1499 \context Staff = "down" {
1500 #(set-accidental-style 'modern-voice)
1507 @funindex modern-voice-cautionary
1508 @item modern-voice-cautionary
1510 This rule is the same as @code{modern-voice}, but with the extra
1511 accidentals (the ones not typeset by @code{voice}) typeset
1512 as cautionaries. Even though all accidentals typeset by
1513 @code{default} @emph{are} typeset by this variable,
1514 some of them are typeset as cautionaries.
1516 @lilypond[quote,ragged-right]
1520 cis'8 fis, d'4 <a cis>8 f bis4 |
1534 \voiceTwo \relative c' {
1538 \change Staff = down
1542 \change Staff = down
1543 <fis, a cis>4 gis <f a d>2 |
1550 \context Staff = "up" {
1551 #(set-accidental-style 'modern-voice-cautionary)
1554 \context Staff = "down" {
1555 #(set-accidental-style 'modern-voice-cautionary)
1563 @funindex piano accidentals
1565 This rule reflects twentieth-century practice for piano notation.
1566 Its behavior is very similar to @code{modern} style, but here
1567 accidentals also get canceled across the staves in the same
1568 GrandStaff or PianoStaff, hence all the cancellations of the final
1571 This accidental style takes place in a GrandStaff context.
1572 However, you have to explicitly set it for @emph{each} individual
1573 Staff of the GrandStaff:
1577 \new GrandStaff @{ <<
1578 \new Staff = "up" @{ <<
1579 #(set-accidental-style 'piano)
1582 \new Staff = "down" @{ <<
1583 #(set-accidental-style 'piano)
1589 @lilypond[quote,ragged-right]
1593 cis'8 fis, d'4 <a cis>8 f bis4 |
1607 \voiceTwo \relative c' {
1611 \change Staff = down
1615 \change Staff = down
1616 <fis, a cis>4 gis <f a d>2 |
1623 \context Staff = "up" {
1624 #(set-accidental-style 'piano)
1627 \context Staff = "down" {
1628 #(set-accidental-style 'piano)
1635 @item piano-cautionary
1636 @funindex #(set-accidental-style 'piano-cautionary)
1638 Same as @code{#(set-accidental-style 'piano)} but with the extra
1639 accidentals typeset as cautionaries.
1641 @lilypond[quote,ragged-right]
1645 cis'8 fis, d'4 <a cis>8 f bis4 |
1659 \voiceTwo \relative c' {
1663 \change Staff = down
1667 \change Staff = down
1668 <fis, a cis>4 gis <f a d>2 |
1675 \context Staff = "up" {
1676 #(set-accidental-style 'piano-cautionary)
1679 \context Staff = "down" {
1680 #(set-accidental-style 'piano-cautionary)
1688 @funindex no-reset accidental style
1690 This is the same as @code{default} but with accidentals lasting
1691 @q{forever} and not only within the same measure:
1693 @lilypond[quote,ragged-right]
1697 cis'8 fis, d'4 <a cis>8 f bis4 |
1711 \voiceTwo \relative c' {
1715 \change Staff = down
1719 \change Staff = down
1720 <fis, a cis>4 gis <f a d>2 |
1727 \context Staff = "up" {
1728 #(set-accidental-style 'no-reset)
1731 \context Staff = "down" {
1732 #(set-accidental-style 'no-reset)
1740 @funindex forget accidental style
1742 This is the opposite of @code{no-reset}: Accidentals are not
1743 remembered at all -- and hence all accidentals are typeset
1744 relative to the key signature, regardless of what was before in
1747 @lilypond[quote,ragged-right]
1751 cis'8 fis, d'4 <a cis>8 f bis4 |
1765 \voiceTwo \relative c' {
1769 \change Staff = down
1773 \change Staff = down
1774 <fis, a cis>4 gis <f a d>2 |
1781 \context Staff = "up" {
1782 #(set-accidental-style 'forget)
1785 \context Staff = "down" {
1786 #(set-accidental-style 'forget)
1797 Snippets: @lsrdir{pitches}.
1799 Internals reference: @internalsref{Accidental_engraver},
1800 @internalsref{Accidental}, @internalsref{AccidentalSuggestion},
1801 @internalsref{AccidentalPlacement}, @internalsref{GrandStaff} and
1802 @internalsref{PianoStaff}, @internalsref{Staff}.
1807 Simultaneous notes are considered to be entered in sequential
1808 mode. This means that in a chord the accidentals are typeset as
1809 if the notes in the chord happen one at a time, in the order in
1810 which they appear in the input file. This is a problem when
1811 accidentals in a chord depend on each other, which does not happen
1812 for the default accidental style. The problem can be solved by
1813 manually inserting@tie{}@code{!} and@tie{}@code{?} for the
1818 @unnumberedsubsubsec Ambitus
1821 The term @notation{ambitus} or @notation{ambit} denotes a range of
1822 pitches for a given voice in a part of music. It may also denote
1823 the pitch range that a musical instrument is capable of playing.
1824 Ambits are printed on vocal parts, so performers can easily
1825 determine if it matches their capabilities.
1827 Ambits are denoted at the beginning of a piece near the initial
1828 clef. The range is graphically specified by two note heads that
1829 represent the minimum and maximum pitch. To print such ambits,
1830 add the @code{Ambitus_engraver} to the @code{Voice} context, for
1833 @lilypond[verbatim,quote,ragged-right]
1837 \consists Ambitus_engraver
1841 \relative \new Staff {
1846 If you have multiple voices in a single staff and you want a
1847 single ambitus per staff rather than per voice, add the
1848 @code{Ambitus_engraver} to the @code{Staff} context rather than to
1849 the @code{Voice} context:
1851 @lilypond[verbatim,quote,ragged-right]
1853 \consists "Ambitus_engraver"
1857 \remove "Ambitus_engraver"
1859 \override Ambitus #'X-offset = #-1.0
1864 \remove "Ambitus_engraver"
1873 This example uses one advanced feature,
1876 \override Ambitus #'X-offset = #-1.0
1880 This code moves the ambitus to the left. The same effect could
1881 have been achieved with @code{extra-offset}, but then the
1882 formatting system would not reserve space for the moved object.
1886 Snippets: @lsrdir{pitches}.
1887 @c FIXME: lsr stuff.
1888 @c @lsr{vocal,ambitus@/.ly}.
1890 Internals reference: @internalsref{Ambitus},
1891 @internalsref{AmbitusLine}, @internalsref{AmbitusNoteHead},
1892 @internalsref{AmbitusAccidental}, @internalsref{Ambitus_engraver},
1893 @internalsref{Staff} and @internalsref{Voice}.
1898 There is no collision handling in the case of multiple per-voice
1903 @subsection Note heads
1906 * Easy notation note heads::
1907 * Shape note heads::
1909 * Special noteheads::
1912 @node Easy notation note heads
1913 @unnumberedsubsubsec Easy notation note heads
1915 @cindex note heads, practice
1916 @cindex note heads, easy notation
1917 @cindex easy notation
1920 The @q{easy play} note head includes a note name inside the head.
1921 It is used in music for beginners
1923 @lilypond[verbatim,quote,ragged-right,fragment,staffsize=26]
1929 The command @code{\setEasyHeads} overrides settings for the
1930 @code{NoteHead} object. To make the letters readable, it
1931 has to be printed in a large font size. To print with a larger
1932 font, see @ref{Setting the staff size}.
1936 @funindex \setEasyHeads
1937 @code{\setEasyHeads}
1941 Notation Reference: @ref{Setting the staff size}.
1943 Snippets: @lsrdir{pitches},
1945 Internals reference: @internalsref{NoteHead}.
1948 @node Shape note heads
1949 @unnumberedsubsubsec Shape note heads
1951 @cindex note heads, shape
1953 In shape note head notation, the shape of the note head
1954 corresponds to the harmonic function of a note in the scale. This
1955 notation was popular in nineteenth-century American song books.
1957 Shape note heads can be produced by setting @code{\aikenHeads} or
1958 @code{\sacredHarpHeads}, depending on the style desired.
1960 @lilypond[verbatim,fragment,relative=1]
1967 Shapes are typeset according to the step in the scale, where
1968 the base of the scale is determined by the @code{\key} command.
1971 @funindex shapeNoteStyles
1972 @funindex \aikenHeads
1973 @funindex \sacredHarpHeads
1975 Shape note heads are implemented through the
1976 @code{shapeNoteStyles} property. Its value is a vector of
1977 symbols. The k-th element indicates the style to use for the k-th
1978 step of the scale. Arbitrary combinations are possible, e.g.:
1980 @lilypond[verbatim,fragment,relative=1]
1981 \set shapeNoteStyles =
1982 ##(cross triangle fa #f mensural xcircle diamond)
1988 Snippets: @lsrdir{pitches}.
1992 @unnumberedsubsubsec Improvisation
1994 Improvisation is sometimes denoted with slashed note heads. Such
1995 note heads can be created by adding a @code{Pitch_squash_engraver}
1996 to the @code{Voice} context. Then, the following command
1999 \set squashedPosition = #0
2000 \override NoteHead #'style = #'slash
2004 switches on the slashes.
2006 There are shortcuts @code{\improvisationOn} (and an accompanying
2007 @code{\improvisationOff}) for this command sequence. They are
2008 used in the following example:
2010 @lilypond[verbatim,quote,ragged-right]
2012 \consists Pitch_squash_engraver
2014 e8 e g a a16(bes)(a8) g
2026 Snippets: @lsrdir{pitches}.
2028 Internals reference: @internalsref{Pitch_squash_engraver} and
2029 @internalsref{Voice}.
2031 @node Special noteheads
2032 @unnumberedsubsubsec Special noteheads
2034 @cindex note heads, special
2036 Different noteheads are used by various instruments for various
2037 meanings -- crosses are used for @q{parlato} with vocalists,
2038 stopped notes on guitar; diamonds are used for harmonics on string
2039 instruments, etc. There is a shorthand (@code{\harmonic}) for
2040 diamond shapes; the other notehead styles are produced by tweaking
2043 @lilypond[verbatim,quote,ragged-right,fragment,relative=1]
2045 \override NoteHead #'style = #'cross
2047 \revert NoteHead #'style
2048 e d <c f\harmonic> <d a'\harmonic>
2052 To see all notehead styles, please see @ref{Note head styles}.
2057 Snippets: @lsrdir{pitches}.
2059 Notation Reference: @ref{Note head styles}.
2061 Internals reference: @internalsref{NoteHead}.