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 This section discusses how to specify the pitch of notes.
15 @lilypondfile[ragged-right,line-width=16\cm,staffsize=16,quote]
20 * Changing multiple pitches::
21 * Displaying pitches::
26 @subsection Writing pitches
31 * Absolute octave entry::
32 * Relative octave entry::
34 * Note names in other languages::
38 @node Absolute octave entry
39 @unnumberedsubsubsec Absolute octave entry
44 A pitch name is specified using lowercase letters @code{a} through
45 @code{g}. An ascending C-major scale is engraved with
47 @lilypond[quote,fragment,verbatim,ragged-right]
52 There are two different ways to enter these note names with regard
53 to octave placement: absolute and relative. The relative mode
54 will in most cases be the most convenient, but the absolute mode
55 is more fundamental and will be presented first.
58 @cindex Absolute octave specification
60 In absolute mode, every note is placed explicitly in a certain
61 octave. The note names @code{c} to @code{b} are engraved in the
62 octave below middle C, as in the previous example.
64 @lilypond[quote,fragment,verbatim,ragged-right]
74 If a note should be in another octave than this, an octave
75 specification must be given. It takes the form of a series of
76 single quote (@samp{'}) or comma (@samp{,}) characters. Each
77 @samp{'} raises the pitch by one octave; each @samp{,} lowers the
80 @lilypond[quote,ragged-right,fragment,verbatim]
82 c' c'' e' g d'' d' d c
84 c, c,, e, g d,, d, d c
88 @node Relative octave entry
89 @unnumberedsubsubsec Relative octaves entry
92 @cindex Relative octave specification
95 The absolute mode requires a lot of octave specifications, which
96 not only becomes tedious but also easily leads to errors.
97 Therefore, it is usually more convenient to let notes be entered
98 relative to the previous note. This is done with the relative
102 \relative @var{startpitch} @var{musicexpr}
105 In relative mode, each note is assumed to be as close to the
106 previous note as possible. This means that the octave of notes
107 that appear in @var{musicexpr} are calculated as follows:
111 The pitch of the first note is relative to @code{\relative
115 If no octave changing marks are used, the basic interval between a
116 note and the one that precedes it is always taken to be a fourth
120 This distance is determined without regarding alterations or the
121 actual sounding pitches; a @code{fisis} following a @code{ceses}
122 will be put above the @code{ceses}. In other words, a
123 doubly-augmented fourth is considered a smaller interval than a
124 diminished fifth, even though the doubly-augmented fourth spans
125 seven semitones while the diminished fifth only spans six
129 The octave changing marks @code{'} and @code{,} can be added to
130 raise or lower the pitch by an extra octave from the basic
134 Multiple octave changing marks can be used. @code{''} will raise
135 the pitch by two octaves.
139 Here is the relative mode shown in action:
141 @lilypond[quote,fragment,ragged-right,verbatim]
147 Octave changing marks are used for intervals greater than a
150 @lilypond[quote,ragged-right,fragment,verbatim]
156 A note sequence without a single octave mark can nevertheless span
159 @lilypond[quote,ragged-right,fragment,verbatim]
165 If the preceding item is a chord, the first note of the chord is
166 used as the reference point for the octave placement of a
167 following note or chord:
169 @lilypond[quote,ragged-right,fragment,verbatim]
177 The @var{startpitch} (after @code{\relative}) is a note name in
178 absolute mode. In principle it can be any note name, but common
179 practice is to use @code{c} in various octave positions.
181 When octaves are specified as above by adding @code{'} and
182 @code{,} to pitch names, it is easy to accidentally put a pitch in
183 the wrong octave. The relative octave mode prevents these errors
184 since most of the time it is not necessary to indicate any octaves
185 at all. Furthermore, in absolute mode, a single mistake may be
186 difficult to spot; in relative mode, a single error puts the rest
187 of the piece off by one octave.
191 Snippets: @lsrdir{pitch}
196 The relative conversion will not affect @code{\transpose},
197 @code{\chordmode} or @code{\relative} sections in its argument.
198 To use relative within transposed music, an additional
199 @code{\relative} must be placed inside @code{\transpose}.
202 If no @var{startpitch} is specified for @code{\relative}, then
203 @code{c'} is assumed. However, this is a deprecated option and
204 may disappear in future versions, so its use is discouraged.
210 @unnumberedsubsubsec Accidentals
212 @cindex note names, Dutch
213 @cindex note names, default
215 @c following paragraph changed to match Tutorial and Accidental
216 @c and Key Signature pages.
218 A @rglos{sharp} pitch is made by adding @samp{is} to the name, and
219 a @rglos{flat} pitch by adding @samp{es}. As you might expect,
220 a @rglos{double sharp} or @rglos{double flat} is made by adding
221 @samp{isis} or @samp{eses}. This syntax derived from note naming
222 conventions in Nordic and Germanic languages, like German and
223 Dutch. To use other names for accidentals, see @ref{Note names
226 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
232 These are the Dutch note names. In Dutch, @code{aes} is
233 contracted to @code{as}, but both forms are accepted. Similarly,
234 both @code{es} and @code{ees} are accepted:
236 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
240 A natural will cancel the effect of an accidental or key
241 signature. However, naturals are not encoded into the note name
242 syntax with a suffix; a natural pitch is shown as a simple note
245 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
249 The input @code{d e f} is interpreted as @q{print a D-natural,
250 E-natural, and an F-natural,} regardless of the key signature.
251 For more information about the distinction between musical content
252 and the presentation of that content, see @rlearning{Accidentals
255 @lilypond[fragment,quote,ragged-right,verbatim,relative]
263 @cindex accidental, reminder
264 @cindex accidental, cautionary
265 @cindex accidental, parenthesized
266 @cindex reminder accidental
268 @cindex cautionary accidental
269 @cindex parenthesized accidental
272 Normally accidentals are printed automatically, but you may also
273 print them manually. A reminder accidental can be forced by
274 adding an exclamation mark @code{!} after the pitch. A cautionary
275 accidental (i.e., an accidental within parentheses) can be
276 obtained by adding the question mark @samp{?} after the pitch.
277 These extra accidentals can be used to produce natural signs, too.
279 @lilypond[quote,ragged-right,fragment,verbatim,relative=1]
280 cis cis cis! cis? c c? c! c
284 @cindex quarter tones
285 @cindex semi-flats, semi-sharps
287 Half-flats and half-sharps are formed by adding @code{-eh} and
288 @code{-ih}; the following is a series of Cs with increasing
291 @lilypond[verbatim,ragged-right,quote,relative=2,fragment]
292 \set Staff.extraNatural = ##f
296 Micro tones are also exported to the MIDI file.
301 In accordance with standard typesetting rules, a natural sign is
302 printed before a sharp or flat if a previous accidental needs to
303 be cancelled. To change this behavior, use @code{\set
304 Staff.extraNatural = ##f}
306 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
308 \set Staff.extraNatural = ##f
315 The automatic production of accidentals can be tuned in many ways
316 concerning for how long an accidental is considered to last. For
317 more information, see @ref{Automatic accidentals}.
319 For @emph{musica ficta}, editorial accidentals placed above the
320 staff commonly used in editions of early music, see @ref{Musica
323 Program reference: @internalsref{LedgerLineSpanner},
324 @internalsref{NoteHead}.
329 There are no generally accepted standards for denoting
330 three-quarter flats, so LilyPond's symbol does not conform to any
335 @node Note names in other languages
336 @unnumberedsubsubsec Note names in other languages
338 There are predefined sets of note names for various other
339 languages. To use them, include the language specific init file.
340 For example, add @code{\include "english.ly"} to the top of the
341 input file. The available language files and the note names they
344 @cindex note names, other languages
347 @multitable @columnfractions .2 .6 .05 .05 .05 .05
350 @tab sharp @tab flat @tab double sharp @tab double flat
352 @tab c d e f g a bes b
353 @tab -is @tab -es @tab -isis @tab -eses
355 @tab c d e f g a bf b
356 @tab -s/-sharp @tab -f/-flat @tab -ss/-x/-sharpsharp
360 @tab -is @tab -es @tab -isis @tab -eses
363 @tab -iss/-is @tab -ess/-es @tab -ississ/-isis
367 @tab -iss @tab -ess @tab -ississ @tab -essess
369 @tab do re mi fa sol la sib si
370 @tab -d @tab -b @tab -dd @tab -bb
372 @tab do re mi fa sol la sib si
373 @tab -d/-s @tab -b @tab -dd/-ss @tab -bb
375 @tab do re mi fa sol la sib si
376 @tab -s @tab -b @tab -ss @tab -bb
381 Note that in Dutch, German, Norwegian, and Swedish, the flat
382 alterations of @samp{a} like for example @code{aes} and
383 @code{aeses} are usually contracted to @code{as} and @code{ases}
384 (or more commonly @code{asas}). Sometimes only these contracted
385 names are defined in the corresponding language files (this also
386 applies to the suffixes for quartertones below).
389 Some music uses microtones whose alterations are fractions of a
390 @q{regular} sharp or flat. The note names for quartertones
391 defined in the various language files are listed in the following
392 table. Here the prefixes @q{semi-} and @q{sesqui-} mean @q{half}
393 and @q{one and a half}, respectively. For Norwegian, Swedish,
394 Catalan and Spanish no special names have been defined yet.
397 @c What about Turkish Maquam music and similar microtonal systems?
399 @c Note that the term "three-quarter-sharp/-flat" used in lilypond's source code
400 @c is actually misleading since the alteration is in fact one and a half
401 @c of a regular sharp/flat. Whence the naming "sesqui-sharp/-flat" used below.
404 @multitable @columnfractions .2 .6 .05 .05 .05 .05
407 @tab semi- @tab semi- @tab sesqui- @tab sesqui-
410 @tab c d e f g a bes b
411 @tab -ih @tab -eh @tab -isih @tab -eseh
413 @tab c d e f g a bf b
414 @tab -qs @tab -qf @tab -tqs @tab -tqf
417 @tab -ih @tab -eh @tab -isih @tab -eseh
419 @c @tab c d e f g a b h
421 @c @tab c d e f g a b h
423 @tab do re mi fa sol la sib si
424 @tab -sd @tab -sb @tab -dsd @tab -bsb
426 @c @tab do re mi fa sol la sib si
428 @c @tab do re mi fa sol la sib si
432 @node Changing multiple pitches
433 @subsection Changing multiple pitches
441 @unnumberedsubsubsec Octave check
445 Octave checks make octave errors easier to correct: a note may be
446 followed by @code{=}@var{quotes} which indicates what its absolute
447 octave should be. In the following example,
450 \relative c'' @{ c='' b=' d,='' @}
454 the @code{d} will generate a warning, because a @code{d''} is
455 expected (because @code{b'} to @code{d''} is only a third), but a
456 @code{d'} is found. In the output, the octave is corrected to be
457 a @code{d''} and the next note is calculated relative to
458 @code{d''} instead of @code{d'}.
460 There is also an octave check that produces no visible output.
467 This checks that @var{pitch} (without quotes) yields @var{pitch}
468 (with quotes) in @code{\relative} mode compared to the note given
469 in the @code{\relative} command. If not, a warning is printed,
470 and the octave is corrected. The @var{pitch} is not printed as a
473 In the example below, the first check passes without incident,
474 since the @code{e} (in @code{relative} mode) is within a fifth of
475 @code{a'}. However, the second check produces a warning, since
476 the @code{e} is not within a fifth of @code{b'}. The warning
477 message is printed, and the octave is adjusted so that the
478 following notes are in the correct octave once again.
489 The octave of a note following an octave check is determined with
490 respect to the note preceding it. In the next fragment, the last
491 note is an @code{a'}, above middle C. That means that the
492 @code{\octave} check passes successfully, so the check could be
493 deleted without changing the output of the piece.
495 @lilypond[quote,ragged-right,verbatim,fragment]
505 @unnumberedsubsubsec Transpose
508 @cindex Transposition of pitches
511 A music expression can be transposed with @code{\transpose}. The
515 \transpose @var{from} @var{to} @var{musicexpr}
518 This means that @var{musicexpr} is transposed by the interval
519 between the pitches @var{from} and @var{to}: any note with pitch
520 @code{from} is changed to @code{to} and any other note is
521 transposed by the same interval.
523 Consider a piece written in the key of D-major. If this piece is
524 a little too low for its performer, it can be transposed up to
528 \transpose d e @dots{}
531 Consider a part written for violin (a C instrument). If this part
532 is to be played on the A clarinet (for which an A is notated as a
533 C, and which sounds a minor third lower than notated), the
534 following transposition will produce the appropriate part:
537 \transpose a c @dots{}
540 @code{\transpose} will also transpose key signatures:
542 @lilypond[quote,ragged-right,verbatim]
543 mus = { \key d \major cis d fis g }
552 @code{\transpose} distinguishes between enharmonic pitches: both
553 @code{\transpose c cis} or @code{\transpose c des} will transpose
554 up half a tone. The first version will print sharps and the notes
555 will remain on the same scale step, the second version will print
556 flats on the scale step above.
558 @lilypond[quote,ragged-right,verbatim]
561 \transpose c cis { \relative c' \mus }
562 \transpose c des { \relative c' \mus }
568 @code{\transpose} may also be used to input written notes for a
569 transposing instrument. Pitches are normally entered into
570 LilyPond in C (or @q{concert pitch}), but they may be entered in
571 another key. For example, when entering music for a B-flat
572 trumpet which begins on concert D, one would write
575 \transpose c bes @{ e4 @dots{} @}
578 To print this music in B-flat again (i.e., producing a trumpet
579 part, instead of a concert pitch conductor's score) you would wrap
580 the existing music with another @code{transpose}
583 \transpose bes c @{ \transpose c bes @{ e4 @dots{} @} @}
589 Program reference: @internalsref{TransposedMusic}.
592 @lsr{scheme,transpose-pitches-with-minimum-accidentals.ly}.
597 If you want to use both @code{\transpose} and @code{\relative},
598 you must put @code{\transpose} outside of @code{\relative}, since
599 @code{\relative} will have no effect on music that appears inside
603 @node Displaying pitches
604 @subsection Displaying pitches
610 * Instrument transpositions::
614 @unnumberedsubsubsec Clef
618 The clef indicates which lines of the staff correspond to which
619 pitches. The clef is set with the @code{\clef} command
621 @lilypond[quote,ragged-right,fragment,verbatim]
622 { c''2 \clef alto g'2 }
632 @cindex mezzosoprano clef
633 @cindex baritone clef
634 @cindex varbaritone clef
637 Supported clefs include
639 @multitable @columnfractions .33 .66
640 @headitem Clef @tab Position
641 @item @code{treble}, violin, G, G2 @tab
643 @item @code{alto, C} @tab
645 @item @code{tenor} @tab
647 @item @code{bass, F} @tab
649 @item @code{french} @tab
650 G clef on 1st line, so-called French violin clef
651 @item @code{soprano} @tab
653 @item @code{mezzosoprano} @tab
655 @item @code{baritone} @tab
657 @item @code{varbaritone} @tab
659 @item @code{subbass} @tab
661 @item @code{percussion} @tab
663 @item @code{tab} @tab
667 By adding @code{_8} or @code{^8} to the clef name, the clef is
668 transposed one octave down or up, respectively, and @code{_15} and
669 @code{^15} transposes by two octaves. The argument @var{clefname}
670 must be enclosed in quotes when it contains underscores or digits.
673 @cindex choral tenor clef
674 @lilypond[quote,ragged-right,verbatim,fragment,relative=1]
681 The command @code{\clef "treble_8"} is equivalent to setting
682 @code{clefGlyph}, @code{clefPosition} (which controls the Y
683 position of the clef), @code{middleCPosition} and
684 @code{clefOctavation}. A clef is printed when any of these
685 properties are changed. The following example shows possibilities
686 when setting properties manually.
688 @lilypond[quote,ragged-right,verbatim]
690 \set Staff.clefGlyph = #"clefs.F"
691 \set Staff.clefPosition = #2
693 \set Staff.clefGlyph = #"clefs.G"
695 \set Staff.clefGlyph = #"clefs.C"
697 \set Staff.clefOctavation = #7
699 \set Staff.clefOctavation = #0
700 \set Staff.clefPosition = #0
704 \set Staff.middleCPosition = #4
712 Program reference: @internalsref{Clef}.
714 This manual: @ref{Ancient clefs}.
718 @unnumberedsubsubsec Key signature
720 @cindex Key signature
723 The key signature indicates the tonality in which a piece is
724 played. It is denoted by a set of alterations (flats or sharps)
725 at the start of the staff.
727 Setting or changing the key signature is done with the @code{\key}
731 @code{\key} @var{pitch} @var{type}
740 @funindex \mixolydian
746 Here, @var{type} should be @code{\major} or @code{\minor} to get
747 @var{pitch}-major or @var{pitch}-minor, respectively. You may
748 also use the standard mode names (also called @q{church modes}):
749 @code{\ionian}, @code{\locrian}, @code{\aeolian},
750 @code{\mixolydian}, @code{\lydian}, @code{\phrygian}, and
753 This command sets the context property @code{Staff.keySignature}.
754 Non-standard key signatures can be specified by setting this
755 property directly. See @internalsref{Key_engraver}, and for an
757 @c TODO: LSR snippet 248. leave this here for now -gp
759 @warning{The relationship between accidentals and key signatures can
760 be confusing to new users who think of the note letters as scale
761 steps and not as absolute pitches. The note names that are
762 entered in a music expression are the raw material; key signatures
763 and clefs decide how this raw material is displayed. Thus,
764 unaltered notes may get natural signs depending on the key
765 signature. For more information, see @ref{Accidentals} and
766 @rlearning{Accidentals and key signatures}.}
768 @lilypond[quote,ragged-right,verbatim,relative=2,fragment]
777 A natural sign is printed to cancel any previous accidentals.
778 This can be suppressed by setting the
779 @code{Staff.printKeyCancellation} property.
781 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
786 \set Staff.printKeyCancellation = ##f
796 Program reference: @internalsref{KeyCancellation},
797 @internalsref{KeySignature}.
800 @node Ottava brackets
801 @unnumberedsubsubsec Ottava brackets
803 @q{Ottava} brackets introduce an extra transposition of an octave
804 for the staff. They are created by invoking the function
805 @code{set-octavation}
813 @lilypond[quote,ragged-right,verbatim,fragment]
823 The @code{set-octavation} function also takes -1 (for 8va bassa),
824 2@tie{}(for 15ma), and -2 (for 15ma bassa) as arguments.
825 Internally the function sets the properties @code{ottavation}
826 (e.g., to @code{"8va"} or @code{"8vb"}) and
827 @code{centralCPosition}. To override the text of the bracket, set
828 @code{ottavation} after invoking @code{set-octavation}, i.e.,
830 @lilypond[quote,ragged-right,verbatim]
833 \set Staff.ottavation = #"8"
841 Program reference: @internalsref{OttavaBracket}.
846 @code{set-octavation} will get confused when clef changes happen
847 during an octavation bracket.
850 @node Instrument transpositions
851 @unnumberedsubsubsec Instrument transpositions
853 @cindex transposition, MIDI
854 @cindex transposition, instrument
856 The key of a transposing instrument can also be specified. This
857 applies to many wind instruments, for example, clarinets (B-flat,
858 A, and E-flat), horn (F) and trumpet (B-flat, C, D, and E-flat).
860 The transposition is entered after the keyword
861 @code{\transposition}
864 \transposition bes %% B-flat clarinet
868 This command sets the property @code{instrumentTransposition}.
869 The value of this property is used for MIDI output and quotations.
870 It does not affect how notes are printed in the current staff. To
871 change the printed output, see @ref{Transpose}.
873 The pitch to use for @code{\transposition} should correspond to
874 the real sound heard when a @code{c'} written on the staff is
875 played by the transposing instrument. For example, when entering
876 a score in concert pitch, typically all voices are entered in C,
877 so they should be entered as
890 The command @code{\transposition} should be used when the music is
891 entered from a (transposed) orchestral part. For example, in
892 classical horn parts, the tuning of the instrument is often
893 changed during a piece. When copying the notes from the part, use
894 @code{\transposition}, e.g.,
905 TODO: also mention that it affects cue voices. Or make a link.