Documentation/user/pitches.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.12.0"
  10
  11
  12 @node Pitches
  13 @section Pitches
  14
  15 @lilypondfile[quote]{pitches-headword.ly}
  16
  17 This section discusses how to specify the pitch of notes.  There
  18 are three steps to this process: input, modification, and output.
  19
  20 @menu
  21 * Writing pitches::
  22 * Changing multiple pitches::
  23 * Displaying pitches::
  24 * Note heads::
  25 @end menu
  26
  27
  28 @node Writing pitches
  29 @subsection Writing pitches
  30
  31 This section discusses how to input pitches.  There are two
  32 different ways to place notes in octaves: absolute and relative
  33 mode.  In most cases, relative mode will be more convenient.
  34
  35 @menu
  36 * Absolute octave entry::
  37 * Relative octave entry::
  38 * Accidentals::
  39 * Note names in other languages::
  40 @end menu
  41
  42
  43 @node Absolute octave entry
  44 @unnumberedsubsubsec Absolute octave entry
  45
  46 @cindex pitch names
  47 @cindex pitches
  48 @cindex absolute
  49 @cindex absolute octave specification
  50 @cindex octave specification, absolute
  51 @cindex absolute octave entry
  52 @cindex octave entry, absolute
  53
  54 A pitch name is specified using lowercase letters@tie{}@code{a}
  55 through@tie{}@code{g}.  The note names @code{c} to @code{b} are
  56 engraved in the octave below middle C.
  57
  58 @c don't use c' here.
  59 @lilypond[verbatim,quote,fragment]
  60 \clef bass
  61 c d e f
  62 g a b c
  63 d e f g
  64 @end lilypond
  65
  66 @cindex octave changing mark
  67
  68 @funindex '
  69 @funindex ,
  70
  71 Other octaves may be specified with a single quote@tie{}(@code{'})
  72 or comma@tie{}(@code{,}) character.  Each@tie{}@code{'} raises the
  73 pitch by one octave; each@tie{}@code{,} lowers the pitch by an
  74 octave.
  75
  76 @lilypond[verbatim,quote,fragment]
  77 \clef treble
  78 c' c'' e' g
  79 d'' d' d c
  80 \clef bass
  81 c, c,, e, g
  82 d,, d, d c
  83 @end lilypond
  84
  85
  86 @seealso
  87 Music Glossary:
  88 @rglos{Pitch names}.
  89
  90 Snippets:
  91 @rlsr{Pitches}.
  92
  93
  94 @node Relative octave entry
  95 @unnumberedsubsubsec Relative octave entry
  96
  97 @cindex relative
  98 @cindex relative octave entry
  99 @cindex octave entry, relative
 100 @cindex relative octave specification
 101 @cindex ocatve specification, relative
 102
 103 @funindex relative
 104 @funindex \relative
 105
 106 When octaves are specified in absolute mode it is easy to
 107 accidentally put a pitch in the wrong octave.  Relative octave
 108 mode reduces these errors since most of the time it is not
 109 necessary to indicate any octaves at all.  Furthermore, in
 110 absolute mode a single mistake may be difficult to spot, while in
 111 relative mode a single error puts the rest of the piece off by one
 112 octave.
 113
 114 @example
 115 \relative @var{startpitch} @var{musicexpr}
 116 @end example
 117
 118 In relative mode, each note is assumed to be as close to the
 119 previous note as possible.  This means that the octave of each
 120 pitch inside @var{musicexpr} is calculated as follows:
 121
 122 @itemize
 123 @item
 124 If no octave changing mark is used on a pitch, its octave is
 125 calculated so that the interval with the previous note is less
 126 than a fifth.  This interval is determined without considering
 127 accidentals.
 128
 129 @item
 130 An octave changing mark@tie{}@code{'} or@tie{}@code{,} can be
 131 added to respectively raise or lower a pitch by an extra octave,
 132 relative to the pitch calculated without an octave mark.
 133
 134 @item
 135 Multiple octave changing marks can be used.  For example,
 136 @code{''}@tie{}and@tie{}@code{,,} will alter the pitch by two
 137 octaves.
 138
 139 @item
 140 The pitch of the first note is relative to
 141 @code{@var{startpitch}}.  @var{startpitch} is specified in
 142 absolute octave mode, and it is recommended that it be a octave of
 143 @code{c}.
 144
 145 @end itemize
 146
 147 Here is the relative mode shown in action:
 148
 149 @lilypond[verbatim,quote]
 150 \relative c {
 151   \clef bass
 152   c d e f
 153   g a b c
 154   d e f g
 155 }
 156 @end lilypond
 157
 158 Octave changing marks are used for intervals greater than a
 159 fourth:
 160
 161 @lilypond[verbatim,quote]
 162 \relative c'' {
 163   c g c f,
 164   c' a, e'' c
 165 }
 166 @end lilypond
 167
 168 A note sequence without a single octave mark can nevertheless span
 169 large intervals:
 170
 171 @lilypond[verbatim,quote]
 172 \relative c {
 173   c f b e
 174   a d g c
 175 }
 176 @end lilypond
 177
 178 @cindex chords and relative octave entry
 179 @cindex relative octave entry and chords
 180
 181 If the preceding item is a chord, the first note of the chord is
 182 used as the reference point for the octave placement of a
 183 following note or chord.  Inside chords, the next note is always
 184 relative to the preceding one.  Examine the next example
 185 carefully, paying attention to the @code{c} notes.
 186
 187 @lilypond[verbatim,quote]
 188 \relative c' {
 189   c
 190   <c e g>
 191   <c' e g'>
 192   <c, e, g''>
 193 }
 194 @end lilypond
 195
 196 As explained above, the octave of pitches is calculated only with
 197 the note names, regardless of any alterations.  Therefore, an
 198 E-double-sharp following a B will be placed higher, while an
 199 F-double-flat will be placed lower.  In other words, a
 200 double-augmented fourth is considered a smaller interval than a
 201 double-diminished fifth, regardless of the number of semitones
 202 that each interval contains.
 203
 204 @lilypond[verbatim,quote]
 205 \relative c'' {
 206   c2 fis
 207   c2 ges
 208   b2 eisis
 209   b2 feses
 210 }
 211 @end lilypond
 212
 213
 214 @seealso
 215 Music Glossary:
 216 @rglos{fifth},
 217 @rglos{interval},
 218 @rglos{Pitch names}.
 219
 220 Notation Reference:
 221 @ref{Octave checks}.
 222
 223 Snippets:
 224 @rlsr{Pitches}.
 225
 226 Internals Reference:
 227 @rinternals{RelativeOctaveMusic}.
 228
 229
 230 @cindex relative octave entry and transposition
 231 @cindex transposition and relative octave entry
 232
 233 @funindex \transpose
 234 @funindex transpose
 235 @funindex \chordmode
 236 @funindex chordmode
 237 @funindex \relative
 238 @funindex relative
 239
 240
 241 @knownissues
 242
 243 The relative conversion will not affect @code{\transpose},
 244 @code{\chordmode} or @code{\relative} sections in its argument.
 245 To use relative mode within transposed music, an additional
 246 @code{\relative} must be placed inside @code{\transpose}.
 247
 248 @c DEPRECATED
 249 If no @var{startpitch} is specified for @code{\relative},
 250 then@tie{}@code{c'} is assumed.  However, this is a deprecated
 251 option and may disappear in future versions, so its use is
 252 discouraged.
 253
 254
 255
 256 @node Accidentals
 257 @unnumberedsubsubsec Accidentals
 258
 259 @cindex accidental
 260 @cindex key signature
 261 @cindex clef
 262
 263 @c duplicated in Key signature and Accidentals
 264 @warning{New users are sometimes confused about accidentals and
 265 key signatures.  In LilyPond, note names are the raw input; key
 266 signatures and clefs determine how this raw input is displayed.
 267 An unaltered note like@tie{}@code{c} means @q{C natural},
 268 regardless of the key signature or clef.  For more information,
 269 see @rlearning{Accidentals and key signatures}.}
 270
 271 @cindex note names, Dutch
 272 @cindex note names, default
 273 @cindex default note names
 274 @cindex sharp
 275 @cindex flat
 276 @cindex double sharp
 277 @cindex sharp, double
 278 @cindex double flat
 279 @cindex flat, double
 280 @cindex natural sign
 281 @cindex natural pitch
 282
 283 A @notation{sharp} pitch is made by adding @code{is} to the note
 284 name, and a @notation{flat} pitch by adding @code{es}.  As you
 285 might expect, a @notation{double sharp} or @notation{double flat}
 286 is made by adding @code{isis} or @code{eses}.  This syntax is
 287 derived from Dutch note naming conventions.  To use other names
 288 for accidentals, see @ref{Note names in other languages}.
 289
 290 @lilypond[verbatim,quote,relative=2]
 291 ais1 aes aisis aeses
 292 @end lilypond
 293
 294 A natural will cancel the effect of an accidental or key
 295 signature.  However, naturals are not encoded into the note name
 296 syntax with a suffix; a natural pitch is shown as a simple note
 297 name:
 298
 299 @lilypond[verbatim,quote,relative=2]
 300 a4 aes a2
 301 @end lilypond
 302
 303 @cindex quarter tones
 304 @cindex semi-flats
 305 @cindex semi-sharps
 306
 307 Quarter tones may be added; the following is a series of Cs with
 308 increasing pitches:
 309
 310 @lilypond[verbatim,quote,relative=2]
 311 ceseh1 ces ceh c cih cis cisih
 312 @end lilypond
 313
 314
 315
 316 @cindex accidental, reminder
 317 @cindex accidental, cautionary
 318 @cindex accidental, parenthesized
 319 @cindex reminder accidental
 320 @cindex cautionary accidental
 321 @cindex parenthesized accidental
 322
 323 @funindex ?
 324 @funindex !
 325
 326
 327 Normally accidentals are printed automatically, but you may also
 328 print them manually.  A reminder accidental can be forced by
 329 adding an exclamation mark@tie{}@code{!} after the pitch.  A
 330 cautionary accidental (i.e., an accidental within parentheses) can
 331 be obtained by adding the question mark@tie{}@code{?} after the
 332 pitch.  These extra accidentals can also be used to produce
 333 natural signs.
 334
 335 @lilypond[verbatim,quote,relative=2]
 336 cis cis cis! cis? c c c! c?
 337 @end lilypond
 338
 339 @cindex accidental on tied note
 340 @cindex tied note, accidental
 341
 342 Accidentals on tied notes are only printed at the beginning of a
 343 new system:
 344
 345 @lilypond[verbatim,quote,relative=2]
 346 cis1 ~ cis ~
 347 \break
 348 cis
 349 @end lilypond
 350
 351
 352 @snippets
 353
 354 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 355 {preventing-extra-naturals-from-being-automatically-added.ly}
 356
 357 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 358 {makam-example.ly}
 359
 360
 361 @seealso
 362 Music Glossary:
 363 @rglos{sharp},
 364 @rglos{flat},
 365 @rglos{double sharp},
 366 @rglos{double flat},
 367 @rglos{Pitch names},
 368 @rglos{quarter tone}.
 369
 370 Learning Manual:
 371 @rlearning{Accidentals and key signatures}.
 372
 373 Notation Reference:
 374 @ref{Automatic accidentals},
 375 @ref{Annotational accidentals (musica ficta)},
 376 @ref{Note names in other languages}.
 377
 378 Snippets:
 379 @rlsr{Pitches}.
 380
 381 Internals Reference:
 382 @rinternals{Accidental_engraver},
 383 @rinternals{Accidental},
 384 @rinternals{AccidentalCautionary},
 385 @rinternals{accidental-interface}.
 386
 387
 388 @cindex accidental, quarter-tone
 389 @cindex quarter-tone accidental
 390
 391 @knownissues
 392
 393 There are no generally accepted standards for denoting
 394 quarter-tone accidentals, so LilyPond's symbol does not conform to
 395 any standard.
 396
 397
 398
 399 @node Note names in other languages
 400 @unnumberedsubsubsec Note names in other languages
 401
 402 @cindex note names, other languages
 403 @cindex pitch names, other languages
 404 @cindex language, note names in other
 405 @cindex language, pitch names in other
 406
 407 There are predefined sets of note and accidental names for various
 408 other languages.  To use them, include the language-specific init
 409 file listed below.  For example, to use English note names, add
 410 @code{@w{\include "english.ly"}} to the input file.
 411
 412 @warning{Because some other include files (such as @code{@w{predefined-fretboards.ly}})
 413 use default (Nederlands) note names, the @code{@bs{}include}
 414 command for the language file should be placed after all other
 415 LilyPond distribution files.}
 416
 417 The available language files and the note names they define are:
 418
 419 @quotation
 420 @multitable {@file{nederlands.ly}} {do re mi fa sol la sib si}
 421 @headitem Language File
 422   @tab Note Names
 423 @item @file{nederlands.ly}
 424   @tab c d e f g a bes b
 425 @item @file{arabic.ly}
 426   @tab do re mi fa sol la sib si
 427 @item @file{catalan.ly}
 428   @tab do re mi fa sol la sib si
 429 @item @file{deutsch.ly}
 430   @tab c d e f g a b h
 431 @item @file{english.ly}
 432   @tab c d e f g a bf b
 433 @item @file{espanol.ly}
 434   @tab do re mi fa sol la sib si
 435 @item @file{italiano.ly}
 436   @tab do re mi fa sol la sib si
 437 @item @file{norsk.ly}
 438   @tab c d e f g a b h
 439 @item @file{portugues.ly}
 440   @tab do re mi fa sol la sib si
 441 @item @file{suomi.ly}
 442   @tab c d e f g a b h
 443 @item @file{svenska.ly}
 444   @tab c d e f g a b h
 445 @item @file{vlaams.ly}
 446   @tab do re mi fa sol la sib si
 447 @end multitable
 448 @end quotation
 449
 450 @noindent
 451 and the accidental suffixes they define are:
 452
 453 @quotation
 454 @multitable {@file{nederlands.ly}} {-s/-sharp} {-ess/-es} {-ss/-x/-sharpsharp} {-essess/-eses}
 455 @headitem Language File
 456   @tab sharp @tab flat @tab double sharp @tab double flat
 457 @item @file{nederlands.ly}
 458   @tab -is @tab -es @tab -isis @tab -eses
 459 @item @file{arabic.ly}
 460   @tab -d @tab -b @tab -dd @tab -bb
 461 @item @file{catalan.ly}
 462   @tab -d/-s @tab -b @tab -dd/-ss @tab -bb
 463 @item @file{deutsch.ly}
 464   @tab -is @tab -es @tab -isis @tab -eses
 465 @item @file{english.ly}
 466   @tab -s/-sharp @tab -f/-flat @tab -ss/-x/-sharpsharp
 467     @tab -ff/-flatflat
 468 @item @file{espanol.ly}
 469   @tab -s @tab -b @tab -ss @tab -bb
 470 @item @file{italiano.ly}
 471   @tab -d @tab -b @tab -dd @tab -bb
 472 @item @file{norsk.ly}
 473   @tab -iss/-is @tab -ess/-es @tab -ississ/-isis
 474     @tab -essess/-eses
 475 @item @file{portugues.ly}
 476   @tab -s @tab -b @tab -ss @tab -bb
 477 @item @file{suomi.ly}
 478   @tab -is @tab -es @tab -isis @tab -eses
 479 @item @file{svenska.ly}
 480   @tab -iss @tab -ess @tab -ississ @tab -essess
 481 @item @file{vlaams.ly}
 482   @tab -k @tab -b @tab -kk @tab -bb
 483 @end multitable
 484 @end quotation
 485
 486 In Dutch, @code{aes} is contracted to @code{as}, but both forms
 487 are accepted in LilyPond.  Similarly, both @code{es} and
 488 @code{ees} are accepted.  This also applies to
 489 @code{aeses}@tie{}/@tie{}@code{ases} and
 490 @code{eeses}@tie{}/@tie{}@code{eses}.  Sometimes only these
 491 contracted names are defined in the corresponding language files.
 492
 493 @lilypond[verbatim,quote,relative=2]
 494 a2 as e es a ases e eses
 495 @end lilypond
 496
 497
 498 @cindex microtones
 499 @cindex semi-sharp
 500 @cindex semi-flat
 501 @cindex sesqui-sharp
 502 @cindex sesqui-flat
 503
 504 Some music uses microtones whose alterations are fractions of a
 505 @q{normal} sharp or flat.  The note names for quarter-tones
 506 defined in the various language files are listed in the following
 507 table.  Here the prefixes @notation{semi-} and @notation{sesqui-}
 508 mean @q{half} and @q{one and a half}, respectively.  For the other
 509 languages, no special names have been defined yet.
 510
 511 @quotation
 512 @multitable {@file{nederlands.ly}} {@b{semi-sharp}} {@b{semi-flat}} {@b{sesqui-sharp}} {@b{sesqui-flat}}
 513 @headitem Language File
 514   @tab semi-sharp @tab semi-flat @tab sesqui-sharp @tab sesqui-flat
 515
 516 @item @file{nederlands.ly}
 517   @tab -ih @tab -eh @tab -isih @tab -eseh
 518 @item @file{arabic.ly}
 519   @tab -sd @tab -sb @tab -dsd @tab -bsb
 520 @item @file{deutsch.ly}
 521   @tab -ih @tab -eh @tab -isih @tab -eseh
 522 @item @file{english.ly}
 523   @tab -qs @tab -qf @tab -tqs @tab -tqf
 524 @item @file{italiano.ly}
 525   @tab -sd @tab -sb @tab -dsd @tab -bsb
 526 @item @file{portugues.ly}
 527   @tab -sqt @tab -bqt @tab -stqt @tab -btqt
 528 @end multitable
 529 @end quotation
 530
 531
 532 @seealso
 533 Music Glossary:
 534 @rglos{Pitch names}.
 535
 536 Snippets:
 537 @rlsr{Pitches}.
 538
 539
 540 @node Changing multiple pitches
 541 @subsection Changing multiple pitches
 542
 543 This section discusses how to modify pitches.
 544
 545 @menu
 546 * Octave checks::
 547 * Transpose::
 548 @end menu
 549
 550 @node Octave checks
 551 @unnumberedsubsubsec Octave checks
 552
 553 @cindex octave correction
 554 @cindex octave check
 555 @cindex control pitch
 556
 557 @funindex =
 558 @funindex \octaveCheck
 559 @funindex octaveCheck
 560 @funindex controlpitch
 561
 562 In relative mode, it is easy to forget an octave changing mark.
 563 Octave checks make such errors easier to find by displaying a
 564 warning and correcting the octave if a note is found in an
 565 unexpected octave.
 566
 567 To check the octave of a note, specify the absolute octave after
 568 the @code{=}@tie{}symbol.  This example will generate a warning
 569 (and change the pitch) because the second note is the absolute
 570 octave @code{d''} instead of @code{d'} as indicated by the octave
 571 correction.
 572
 573 @lilypond[verbatim,quote]
 574 \relative c'' {
 575   c2 d='4 d
 576   e2 f
 577 }
 578 @end lilypond
 579
 580 The octave of notes may also be checked with the
 581 @code{\octaveCheck}@tie{}@var{controlpitch} command.
 582 @var{controlpitch} is specified in absolute mode.  This checks
 583 that the interval between the previous note and the
 584 @var{controlpitch} is within a fourth (i.e., the normal
 585 calculation of relative mode).  If this check fails, a warning is
 586 printed, but the previous note is not changed.  Future notes are
 587 relative to the @var{controlpitch}.
 588
 589 @lilypond[verbatim,quote]
 590 \relative c'' {
 591   c2 d
 592   \octaveCheck c'
 593   e2 f
 594 }
 595 @end lilypond
 596
 597 Compare the two bars below.  The first and third @code{\octaveCheck}
 598 checks fail, but the second one does not fail.
 599
 600 @lilypond[verbatim,quote]
 601 \relative c'' {
 602   c4 f g f
 603
 604   c4
 605   \octaveCheck c'
 606   f
 607   \octaveCheck c'
 608   g
 609   \octaveCheck c'
 610   f
 611 }
 612 @end lilypond
 613
 614
 615 @seealso
 616 Snippets:
 617 @rlsr{Pitches}.
 618
 619 Internals Reference:
 620 @rinternals{RelativeOctaveCheck}.
 621
 622
 623 @node Transpose
 624 @unnumberedsubsubsec Transpose
 625
 626 @cindex transpose
 627 @cindex transposing
 628 @cindex transposition
 629 @cindex transposition of pitches
 630 @cindex transposition of notes
 631 @cindex pitches, transposition of
 632 @cindex notes, transposition of
 633
 634 @funindex \transpose
 635 @funindex transpose
 636
 637 A music expression can be transposed with @code{\transpose}.  The
 638 syntax is
 639
 640 @example
 641 \transpose @var{frompitch} @var{topitch} @var{musicexpr}
 642 @end example
 643
 644 @noindent
 645 This means that @var{musicexpr} is transposed by the interval
 646 between the pitches @var{frompitch} and @var{topitch}: any note
 647 with pitch @var{frompitch} is changed to @var{topitch} and any
 648 other note is transposed by the same interval.  Both pitches are
 649 entered in absolute mode.
 650
 651 Consider a piece written in the key of D-major.  It can be
 652 transposed up to E-major; note that the key signature is
 653 automatically transposed as well.
 654
 655 @lilypond[verbatim,quote]
 656 \transpose d e {
 657   \relative c' {
 658     \key d \major
 659     d4 fis a d
 660   }
 661 }
 662 @end lilypond
 663
 664 @cindex transposing instruments
 665 @cindex instruments, transposing
 666
 667 If a part written in C (normal @notation{concert pitch}) is to be
 668 played on the A clarinet (for which an A is notated as a C and
 669 thus sounds a minor third lower than notated), the appropriate
 670 part will be produced with:
 671
 672 @lilypond[verbatim,quote]
 673 \transpose a c' {
 674   \relative c' {
 675     \key c \major
 676     c4 d e g
 677   }
 678 }
 679 @end lilypond
 680
 681 @noindent
 682 Note that we specify @w{@code{\key c \major}} explicitly.  If we
 683 do not specify a key signature, the notes will be transposed but
 684 no key signature will be printed.
 685
 686 @code{\transpose} distinguishes between enharmonic pitches: both
 687 @w{@code{\transpose c cis}} or @w{@code{\transpose c des}} will
 688 transpose up a semitone.  The first version will print sharps and
 689 the notes will remain on the same scale step, the second version
 690 will print flats on the scale step above.
 691
 692 @lilypond[verbatim,quote]
 693 music = \relative c' { c d e f }
 694 \new Staff {
 695   \transpose c cis { \music }
 696   \transpose c des { \music }
 697 }
 698 @end lilypond
 699
 700
 701 @code{\transpose} may also be used in a different way, to input
 702 written notes for a transposing instrument.  The previous examples
 703 show how to enter pitches in C (or @notation{concert pitch}) and
 704 typeset them for a transposing instrument, but the opposite is
 705 also possible if you for example have a set of instrumental parts
 706 and want to print a conductor's score.  For example, when entering
 707 music for a B-flat trumpet that begins on a notated E (concert D),
 708 one would write:
 709
 710 @example
 711 musicInBflat = @{ e4 @dots{} @}
 712 \transpose c bes, \musicInBflat
 713 @end example
 714
 715 @noindent
 716 To print this music in F (e.g., rearranging to a French horn) you
 717 could wrap the existing music with another @code{\transpose}:
 718
 719 @example
 720 musicInBflat = @{ e4 @dots{} @}
 721 \transpose f c' @{ \transpose c bes, \musicInBflat @}
 722 @end example
 723
 724 @noindent
 725 For more information about transposing instruments,
 726 see @ref{Instrument transpositions}.
 727
 728
 729 @snippets
 730
 731 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 732 {transposing-pitches-with-minimum-accidentals-smart-transpose.ly}
 733
 734
 735 @seealso
 736 Notation Reference:
 737 @ref{Instrument transpositions}.
 738
 739 Snippets:
 740 @rlsr{Pitches}.
 741
 742 Internals Reference:
 743 @rinternals{TransposedMusic}.
 744
 745
 746 @funindex \transpose
 747 @funindex transpose
 748 @funindex \chordmode
 749 @funindex chordmode
 750 @funindex \relative
 751 @funindex relative
 752
 753 @knownissues
 754
 755 The relative conversion will not affect @code{\transpose},
 756 @code{\chordmode} or @code{\relative} sections in its argument.
 757 To use relative mode within transposed music, an additional
 758 @code{\relative} must be placed inside @code{\transpose}.
 759
 760
 761 @node Displaying pitches
 762 @subsection Displaying pitches
 763
 764 This section discusses how to alter the output of pitches.
 765
 766 @menu
 767 * Clef::
 768 * Key signature::
 769 * Ottava brackets::
 770 * Instrument transpositions::
 771 * Automatic accidentals::
 772 * Ambitus::
 773 @end menu
 774
 775
 776 @node Clef
 777 @unnumberedsubsubsec Clef
 778
 779 @cindex G clef
 780 @cindex C clef
 781 @cindex F clef
 782 @cindex treble clef
 783 @cindex violin clef
 784 @cindex alto clef
 785 @cindex tenor clef
 786 @cindex bass clef
 787 @cindex french clef
 788 @cindex soprano clef
 789 @cindex mezzosoprano clef
 790 @cindex baritone clef
 791 @cindex varbaritone clef
 792 @cindex subbass clef
 793 @cindex clef
 794 @cindex ancient clef
 795 @cindex clef, ancient
 796 @cindex clef, G
 797 @cindex clef, C
 798 @cindex clef, F
 799 @cindex clef, treble
 800 @cindex clef, violin
 801 @cindex clef, alto
 802 @cindex clef, tenor
 803 @cindex clef, bass
 804 @cindex clef, french
 805 @cindex clef, soprano
 806 @cindex clef, mezzosoprano
 807 @cindex clef, baritone
 808 @cindex clef, varbaritone
 809 @cindex subbass clef, subbass
 810
 811 @funindex \clef
 812 @funindex clef
 813
 814 The clef may be altered.  Middle C is shown in every example.
 815
 816 @lilypond[verbatim,quote,relative=1]
 817 \clef treble
 818 c2 c
 819 \clef alto
 820 c2 c
 821 \clef tenor
 822 c2 c
 823 \clef bass
 824 c2 c
 825 @end lilypond
 826
 827 Other clefs include:
 828
 829 @lilypond[verbatim,quote,relative=1]
 830 \clef french
 831 c2 c
 832 \clef soprano
 833 c2 c
 834 \clef mezzosoprano
 835 c2 c
 836 \clef baritone
 837 c2 c
 838
 839 \break
 840
 841 \clef varbaritone
 842 c2 c
 843 \clef subbass
 844 c2 c
 845 \clef percussion
 846 c2 c
 847 \clef tab
 848 c2 c
 849 @end lilypond
 850
 851 Further supported clefs are described under @ref{Mensural clefs}
 852 and @ref{Gregorian clefs}.
 853
 854 @cindex transposing clefs
 855 @cindex clef, transposing
 856 @cindex octave transposition
 857 @cindex choral tenor clef
 858 @cindex tenor clef, choral
 859
 860 By adding@tie{}@code{_8} or@tie{}@code{^8} to the clef name, the
 861 clef is transposed one octave down or up, respectively,
 862 and@tie{}@code{_15} and@tie{}@code{^15} transpose by two octaves.
 863 The clef name must be enclosed in quotes when it contains
 864 underscores or digits.
 865
 866 @lilypond[verbatim,quote,relative=2]
 867 \clef treble
 868 c2 c
 869 \clef "treble_8"
 870 c2 c
 871 \clef "bass^15"
 872 c2 c
 873 @end lilypond
 874
 875
 876 @snippets
 877
 878 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 879 {tweaking-clef-properties.ly}
 880
 881
 882 @seealso
 883 Notation Reference:
 884 @ref{Mensural clefs}, @ref{Gregorian clefs}.
 885
 886 Snippets:
 887 @rlsr{Pitches}.
 888
 889 Internals Reference:
 890 @rinternals{Clef_engraver},
 891 @rinternals{Clef},
 892 @rinternals{OctavateEight},
 893 @rinternals{clef-interface}.
 894
 895
 896 @node Key signature
 897 @unnumberedsubsubsec Key signature
 898
 899 @cindex key signature
 900
 901 @funindex \key
 902 @funindex key
 903
 904 @c duplicated in Key signature and Accidentals
 905 @warning{New users are sometimes confused about accidentals and
 906 key signatures.  In LilyPond, note names are the raw input; key
 907 signatures and clefs determine how this raw input is displayed.
 908 An unaltered note like@tie{}@code{c} means @q{C natural},
 909 regardless of the key signature or clef.  For more information,
 910 see @rlearning{Accidentals and key signatures}.}
 911
 912 The key signature indicates the tonality in which a piece is
 913 played.  It is denoted by a set of alterations (flats or sharps)
 914 at the start of the staff.  The key signature may be altered:
 915
 916 @example
 917 \key @var{pitch} @var{mode}
 918 @end example
 919
 920 @funindex \major
 921 @funindex major
 922 @funindex \minor
 923 @funindex minor
 924 @funindex \ionian
 925 @funindex ionian
 926 @funindex \locrian
 927 @funindex locrian
 928 @funindex \aeolian
 929 @funindex aeolian
 930 @funindex \mixolydian
 931 @funindex mixolydian
 932 @funindex \lydian
 933 @funindex lydian
 934 @funindex \phrygian
 935 @funindex phrygian
 936 @funindex \dorian
 937 @funindex dorian
 938
 939 @cindex church modes
 940 @cindex modes
 941 @cindex major
 942 @cindex minor
 943 @cindex ionian
 944 @cindex locrian
 945 @cindex aeolian
 946 @cindex mixolydian
 947 @cindex lydian
 948 @cindex phrygian
 949 @cindex dorian
 950
 951 Here, @var{mode} should be @code{\major} or @code{\minor} to get a
 952 key signature of @var{pitch}-major or @var{pitch}-minor,
 953 respectively.  You may also use the standard mode names, also
 954 called @notation{church modes}: @code{\ionian}, @code{\dorian},
 955 @code{\phrygian}, @code{\lydian}, @code{\mixolydian},
 956 @code{\aeolian}, and @code{\locrian}.
 957
 958 @lilypond[verbatim,quote,relative=2]
 959 \key g \major
 960 fis1
 961 f
 962 fis
 963 @end lilypond
 964
 965
 966 @snippets
 967
 968 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 969 {preventing-natural-signs-from-being-printed-when-the-key-signature-changes.ly}
 970
 971 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 972 {non-traditional-key-signatures.ly}
 973
 974
 975 @seealso
 976 Music Glossary:
 977 @rglos{church mode},
 978 @rglos{scordatura}.
 979
 980 Learning Manual:
 981 @rlearning{Accidentals and key signatures}.
 982
 983 Snippets:
 984 @rlsr{Pitches}.
 985
 986 Internals Reference:
 987 @rinternals{KeyChangeEvent},
 988 @rinternals{Key_engraver},
 989 @rinternals{Key_performer},
 990 @rinternals{KeyCancellation},
 991 @rinternals{KeySignature},
 992 @rinternals{key-cancellation-interface},
 993 @rinternals{key-signature-interface}.
 994
 995
 996 @node Ottava brackets
 997 @unnumberedsubsubsec Ottava brackets
 998
 999 @cindex ottava
1000 @cindex 15ma
1001 @cindex 8va
1002 @cindex 8ve
1003 @cindex octavation
1004
1005 @funindex set-octavation
1006 @funindex \ottava
1007 @funindex ottava
1008
1009 @notation{Ottava brackets} introduce an extra transposition of an
1010 octave for the staff:
1011
1012 @lilypond[verbatim,quote,relative=2]
1013 a'2 b
1014 \ottava #1
1015 a b
1016 \ottava #0
1017 a b
1018 @end lilypond
1019
1020 The @code{ottava} function also takes -1 (for 8va bassa),
1021 2@tie{}(for 15ma), and -2 (for 15ma bassa) as arguments.
1022
1023
1024 @snippets
1025
1026 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
1027 {ottava-text.ly}
1028
1029
1030 @seealso
1031 Music Glossary:
1032 @rglos{octavation}.
1033
1034 Snippets:
1035 @rlsr{Pitches}.
1036
1037 Internals Reference:
1038 @rinternals{Ottava_spanner_engraver},
1039 @rinternals{OttavaBracket},
1040 @rinternals{ottava-bracket-interface}.
1041
1042
1043 @node Instrument transpositions
1044 @unnumberedsubsubsec Instrument transpositions
1045
1046 @cindex transposition, MIDI
1047 @cindex transposition, instrument
1048 @cindex transposing instrument
1049 @cindex MIDI
1050 @cindex MIDI transposition
1051
1052 @funindex \transposition
1053 @funindex transposition
1054
1055 When typesetting scores that involve transposing instruments, some
1056 parts can be typeset in a different pitch than the
1057 @notation{concert pitch}.  In these cases, the key of the
1058 @notation{transposing instrument} should be specified; otherwise
1059 the MIDI output and cues in other parts will produce incorrect
1060 pitches.  For more information about quotations, see
1061 @ref{Quoting other voices}.
1062
1063 @example
1064 \transposition @var{pitch}
1065 @end example
1066
1067 The pitch to use for @code{\transposition} should correspond to
1068 the real sound heard when a@tie{}@code{c'} written on the staff is
1069 played by the transposing instrument.  This pitch is entered in
1070 absolute mode, so an instrument that produces a real sound which
1071 is one tone higher than the printed music should use
1072 @w{@code{\transposition d'}}.  @code{\transposition} should
1073 @emph{only} be used if the pitches are @emph{not} being entered in
1074 concert pitch.
1075
1076 Here are a few notes for violin and B-flat clarinet where the
1077 parts have been entered using the notes and key as they appear in
1078 each part of the conductor's score.  The two instruments are
1079 playing in unison.
1080
1081 @lilypond[verbatim,quote]
1082 \new GrandStaff <<
1083   \new Staff = "violin" {
1084     \relative c'' {
1085       \set Staff.instrumentName = #"Vln"
1086       \set Staff.midiInstrument = #"violin"
1087       % not strictly necessary, but a good reminder
1088       \transposition c'
1089
1090       \key c \major
1091       g4( c8) r c r c4
1092     }
1093   }
1094   \new Staff = "clarinet" {
1095     \relative c'' {
1096       \set Staff.instrumentName = \markup { Cl (B\flat) }
1097       \set Staff.midiInstrument = #"clarinet"
1098       \transposition bes
1099
1100       \key d \major
1101       a4( d8) r d r d4
1102     }
1103   }
1104 >>
1105 @end lilypond
1106
1107 The @code{\transposition} may be changed during a piece.  For
1108 example, a clarinetist may switch from an A clarinet to a B-flat
1109 clarinet.
1110
1111 @lilypond[verbatim,quote,relative=2]
1112 \set Staff.instrumentName = #"Cl (A)"
1113 \key a \major
1114 \transposition a
1115 c d e f
1116 \textLengthOn
1117 s1*0^\markup { Switch to B\flat clarinet }
1118 R1
1119
1120 \key bes \major
1121 \transposition bes
1122 c2 g
1123 @end lilypond
1124
1125
1126 @seealso
1127 Music Glossary:
1128 @rglos{concert pitch},
1129 @rglos{transposing instrument}.
1130
1131 Notation Reference:
1132 @ref{Quoting other voices}, @ref{Transpose}.
1133
1134 Snippets:
1135 @rlsr{Pitches}.
1136
1137
1138 @node Automatic accidentals
1139 @unnumberedsubsubsec Automatic accidentals
1140
1141 @cindex accidental style
1142 @cindex accidental style, default
1143 @cindex accidentals
1144 @cindex accidentals, automatic
1145 @cindex automatic accidentals
1146 @cindex default accidental style
1147
1148 @funindex set-accidental-style
1149 @funindex voice
1150 @funindex default
1151
1152 There are many different conventions on how to typeset
1153 accidentals.  LilyPond provides a function to specify which
1154 accidental style to use.  This function is called as follows:
1155
1156 @example
1157 \new Staff <<
1158   #(set-accidental-style 'voice)
1159   @{ @dots{} @}
1160 >>
1161 @end example
1162
1163 The accidental style applies to the current @code{Staff} by
1164 default (with the exception of the styles @code{piano} and
1165 @code{piano-cautionary}, which are explained below).  Optionally,
1166 the function can take a second argument that determines in which
1167 scope the style should be changed.  For example, to use the same
1168 style in all staves of the current @code{StaffGroup}, use:
1169
1170 @example
1171 #(set-accidental-style 'voice 'StaffGroup)
1172 @end example
1173
1174 The following accidental styles are supported.  To demonstrate
1175 each style, we use the following example:
1176
1177
1178 @lilypond[verbatim,quote]
1179 musicA = {
1180   <<
1181     \relative c' {
1182       cis'8 fis, d'4 <a cis>8 f bis4 |
1183       cis2. <c, g'>4 |
1184     }
1185     \\
1186     \relative c' {
1187       ais'2 cis, |
1188       fis8 b a4 cis2 |
1189     }
1190   >>
1191 }
1192
1193 musicB = {
1194   \clef bass
1195   \new Voice {
1196     \voiceTwo \relative c' {
1197       <fis, a cis>4
1198       \change Staff = up
1199       cis'
1200       \change Staff = down
1201       <fis, a>
1202       \change Staff = up
1203       dis' |
1204       \change Staff = down
1205       <fis, a cis>4 gis <f a d>2 |
1206     }
1207   }
1208 }
1209
1210 \new PianoStaff {
1211   <<
1212     \context Staff = "up" {
1213       #(set-accidental-style 'default)
1214       \musicA
1215     }
1216     \context Staff = "down" {
1217       #(set-accidental-style 'default)
1218       \musicB
1219     }
1220   >>
1221 }
1222 @end lilypond
1223
1224 Note that the last lines of this example can be replaced by the
1225 following, as long as the same accidental style should be used in
1226 both staves.
1227
1228 @example
1229 \new PianoStaff @{
1230   <<
1231     \context Staff = "up" @{
1232       %%% change the next line as desired:
1233       #(set-accidental-style 'default 'Score)
1234       \musicA
1235     @}
1236     \context Staff = "down" @{
1237       \musicB
1238     @}
1239   >>
1240 @}
1241 @end example
1242
1243
1244 @c don't use verbatim in this table.
1245 @table @code
1246 @item default
1247
1248 @cindex default accidental style
1249 @cindex accidental style, default
1250
1251 @funindex default
1252
1253 This is the default typesetting behavior.  It corresponds to
1254 eighteenth-century common practice: accidentals are remembered to
1255 the end of the measure in which they occur and only in their own
1256 octave.  Thus, in the example below, no natural signs are printed
1257 before the@tie{}@code{b} in the second measure or the
1258 last@tie{}@code{c}:
1259
1260 @lilypond[quote]
1261 musicA = {
1262   <<
1263     \relative c' {
1264       cis'8 fis, d'4 <a cis>8 f bis4 |
1265       cis2. <c, g'>4 |
1266     }
1267     \\
1268     \relative c' {
1269       ais'2 cis, |
1270       fis8 b a4 cis2 |
1271     }
1272   >>
1273 }
1274
1275 musicB = {
1276   \clef bass
1277   \new Voice {
1278     \voiceTwo \relative c' {
1279       <fis, a cis>4
1280       \change Staff = up
1281       cis'
1282       \change Staff = down
1283       <fis, a>
1284       \change Staff = up
1285       dis' |
1286       \change Staff = down
1287       <fis, a cis>4 gis <f a d>2 |
1288     }
1289   }
1290 }
1291
1292 \new PianoStaff {
1293   <<
1294     \context Staff = "up" {
1295       #(set-accidental-style 'default)
1296       \musicA
1297     }
1298     \context Staff = "down" {
1299       #(set-accidental-style 'default)
1300       \musicB
1301     }
1302   >>
1303 }
1304 @end lilypond
1305
1306 @item voice
1307
1308 @cindex accidental style, voice
1309 @cindex voice accidental style
1310 @cindex accidental style, modern
1311 @cindex modern accidental style
1312 @cindex accidental style, modern-cautionary
1313 @cindex modern-cautionary accidental style
1314
1315 @funindex voice
1316
1317 The normal behavior is to remember the accidentals at
1318 @code{Staff}-level.  In this style, however, accidentals are
1319 typeset individually for each voice.  Apart from that, the rule is
1320 similar to @code{default}.
1321
1322 As a result, accidentals from one voice do not get canceled in
1323 other voices, which is often an unwanted result: in the following
1324 example, it is hard to determine whether the second@tie{}@code{a}
1325 should be played natural or sharp.  The @code{voice} option should
1326 therefore be used only if the voices are to be read solely by
1327 individual musicians.  If the staff is to be used by one musician
1328 (e.g., a conductor or in a piano score) then @code{modern} or
1329 @code{modern-cautionary} should be used instead.
1330
1331
1332 @lilypond[quote]
1333 musicA = {
1334   <<
1335     \relative c' {
1336       cis'8 fis, d'4 <a cis>8 f bis4 |
1337       cis2. <c, g'>4 |
1338     }
1339     \\
1340     \relative c' {
1341       ais'2 cis, |
1342       fis8 b a4 cis2 |
1343     }
1344   >>
1345 }
1346
1347 musicB = {
1348   \clef bass
1349   \new Voice {
1350     \voiceTwo \relative c' {
1351       <fis, a cis>4
1352       \change Staff = up
1353       cis'
1354       \change Staff = down
1355       <fis, a>
1356       \change Staff = up
1357       dis' |
1358       \change Staff = down
1359       <fis, a cis>4 gis <f a d>2 |
1360     }
1361   }
1362 }
1363
1364 \new PianoStaff {
1365   <<
1366     \context Staff = "up" {
1367       #(set-accidental-style 'voice)
1368       \musicA
1369     }
1370     \context Staff = "down" {
1371       #(set-accidental-style 'voice)
1372       \musicB
1373     }
1374   >>
1375 }
1376 @end lilypond
1377
1378 @item modern
1379
1380 @cindex accidentals, modern style
1381 @cindex modern style accidentals
1382
1383 @funindex modern
1384
1385 This rule corresponds to the common practice in the twentieth
1386 century.  It prints the same accidentals as @code{default}, with
1387 two exceptions that serve to avoid ambiguity: after temporary
1388 accidentals, cancellation marks are printed also in the following
1389 measure (for notes in the same octave) and, in the same measure,
1390 for notes in other octaves.  Hence the naturals before
1391 the@tie{}@code{b} and the@tie{}@code{c} in the second measure of
1392 the upper staff:
1393
1394 @lilypond[quote]
1395 musicA = {
1396   <<
1397     \relative c' {
1398       cis'8 fis, d'4 <a cis>8 f bis4 |
1399       cis2. <c, g'>4 |
1400     }
1401     \\
1402     \relative c' {
1403       ais'2 cis, |
1404       fis8 b a4 cis2 |
1405     }
1406   >>
1407 }
1408
1409 musicB = {
1410   \clef bass
1411   \new Voice {
1412     \voiceTwo \relative c' {
1413       <fis, a cis>4
1414       \change Staff = up
1415       cis'
1416       \change Staff = down
1417       <fis, a>
1418       \change Staff = up
1419       dis' |
1420       \change Staff = down
1421       <fis, a cis>4 gis <f a d>2 |
1422     }
1423   }
1424 }
1425
1426 \new PianoStaff {
1427   <<
1428     \context Staff = "up" {
1429       #(set-accidental-style 'modern)
1430       \musicA
1431     }
1432     \context Staff = "down" {
1433       #(set-accidental-style 'modern)
1434       \musicB
1435     }
1436   >>
1437 }
1438 @end lilypond
1439
1440 @item modern-cautionary
1441
1442 @cindex accidentals, modern cautionary style
1443 @cindex modern accidental style
1444 @cindex modern cautionary accidental style
1445 @cindex modern style accidentals
1446 @cindex modern style cautionary accidentals
1447
1448 @funindex modern-cautionary
1449
1450 This rule is similar to @code{modern}, but the @q{extra}
1451 accidentals (the ones not typeset by @code{default}) are typeset
1452 as cautionary accidentals.  They are by default printed with
1453 parentheses, but they can also be printed in reduced size by
1454 defining the @code{cautionary-style} property of
1455 @code{AccidentalSuggestion}.
1456
1457 @lilypond[quote]
1458 musicA = {
1459   <<
1460     \relative c' {
1461       cis'8 fis, d'4 <a cis>8 f bis4 |
1462       cis2. <c, g'>4 |
1463     }
1464     \\
1465     \relative c' {
1466       ais'2 cis, |
1467       fis8 b a4 cis2 |
1468     }
1469   >>
1470 }
1471
1472 musicB = {
1473   \clef bass
1474   \new Voice {
1475     \voiceTwo \relative c' {
1476       <fis, a cis>4
1477       \change Staff = up
1478       cis'
1479       \change Staff = down
1480       <fis, a>
1481       \change Staff = up
1482       dis' |
1483       \change Staff = down
1484       <fis, a cis>4 gis <f a d>2 |
1485     }
1486   }
1487 }
1488
1489 \new PianoStaff {
1490   <<
1491     \context Staff = "up" {
1492       #(set-accidental-style 'modern-cautionary)
1493       \musicA
1494     }
1495     \context Staff = "down" {
1496       #(set-accidental-style 'modern-cautionary)
1497       \musicB
1498     }
1499   >>
1500 }
1501 @end lilypond
1502
1503 @item modern-voice
1504
1505 @cindex accidental style, modern
1506 @cindex accidentals, modern
1507 @cindex accidentals, multivoice
1508 @cindex modern accidental style
1509 @cindex modern accidentals
1510 @cindex multivoice accidentals
1511
1512 @funindex modern-voice
1513
1514 This rule is used for multivoice accidentals to be read both by
1515 musicians playing one voice and musicians playing all voices.
1516 Accidentals are typeset for each voice, but they @emph{are}
1517 canceled across voices in the same @code{Staff}.  Hence,
1518 the@tie{}@code{a} in the last measure is canceled because the
1519 previous cancellation was in a different voice, and
1520 the@tie{}@code{d} in the lower staff is canceled because of the
1521 accidental in a different voice in the previous measure:
1522
1523 @lilypond[quote]
1524 musicA = {
1525   <<
1526     \relative c' {
1527       cis'8 fis, d'4 <a cis>8 f bis4 |
1528       cis2. <c, g'>4 |
1529     }
1530     \\
1531     \relative c' {
1532       ais'2 cis, |
1533       fis8 b a4 cis2 |
1534     }
1535   >>
1536 }
1537
1538 musicB = {
1539   \clef bass
1540   \new Voice {
1541     \voiceTwo \relative c' {
1542       <fis, a cis>4
1543       \change Staff = up
1544       cis'
1545       \change Staff = down
1546       <fis, a>
1547       \change Staff = up
1548       dis' |
1549       \change Staff = down
1550       <fis, a cis>4 gis <f a d>2 |
1551     }
1552   }
1553 }
1554
1555 \new PianoStaff {
1556   <<
1557     \context Staff = "up" {
1558       #(set-accidental-style 'modern-voice)
1559       \musicA
1560     }
1561     \context Staff = "down" {
1562       #(set-accidental-style 'modern-voice)
1563       \musicB
1564     }
1565   >>
1566 }
1567 @end lilypond
1568
1569 @cindex accidental style, cautionary, modern voice
1570 @cindex accidental style, modern voice cautionary
1571 @cindex accidental style, voice, modern cautionary
1572
1573 @funindex modern-voice-cautionary
1574
1575 @item modern-voice-cautionary
1576
1577 This rule is the same as @code{modern-voice}, but with the extra
1578 accidentals (the ones not typeset by @code{voice}) typeset as
1579 cautionaries.  Even though all accidentals typeset by
1580 @code{default} @emph{are} typeset with this rule, some of them are
1581 typeset as cautionaries.
1582
1583 @lilypond[quote]
1584 musicA = {
1585   <<
1586     \relative c' {
1587       cis'8 fis, d'4 <a cis>8 f bis4 |
1588       cis2. <c, g'>4 |
1589     }
1590     \\
1591     \relative c' {
1592       ais'2 cis, |
1593       fis8 b a4 cis2 |
1594     }
1595   >>
1596 }
1597
1598 musicB = {
1599   \clef bass
1600   \new Voice {
1601     \voiceTwo \relative c' {
1602       <fis, a cis>4
1603       \change Staff = up
1604       cis'
1605       \change Staff = down
1606       <fis, a>
1607       \change Staff = up
1608       dis' |
1609       \change Staff = down
1610       <fis, a cis>4 gis <f a d>2 |
1611     }
1612   }
1613 }
1614
1615 \new PianoStaff {
1616   <<
1617     \context Staff = "up" {
1618       #(set-accidental-style 'modern-voice-cautionary)
1619       \musicA
1620     }
1621     \context Staff = "down" {
1622       #(set-accidental-style 'modern-voice-cautionary)
1623       \musicB
1624     }
1625   >>
1626 }
1627 @end lilypond
1628
1629 @item piano
1630
1631 @cindex accidental style, piano
1632 @cindex accidentals, piano
1633 @cindex piano accidental style
1634 @cindex piano accidentals
1635
1636 @funindex piano
1637
1638 This rule reflects twentieth-century practice for piano notation.
1639 Its behavior is very similar to @code{modern} style, but here
1640 accidentals also get canceled across the staves in the same
1641 @code{GrandStaff} or @code{PianoStaff}, hence all the
1642 cancellations of the final notes.
1643
1644 This accidental style applies to the current @code{GrandStaff} or
1645 @code{PianoStaff} by default.
1646
1647 @lilypond[quote]
1648 musicA = {
1649   <<
1650     \relative c' {
1651       cis'8 fis, d'4 <a cis>8 f bis4 |
1652       cis2. <c, g'>4 |
1653     }
1654     \\
1655     \relative c' {
1656       ais'2 cis, |
1657       fis8 b a4 cis2 |
1658     }
1659   >>
1660 }
1661
1662 musicB = {
1663   \clef bass
1664   \new Voice {
1665     \voiceTwo \relative c' {
1666       <fis, a cis>4
1667       \change Staff = up
1668       cis'
1669       \change Staff = down
1670       <fis, a>
1671       \change Staff = up
1672       dis' |
1673       \change Staff = down
1674       <fis, a cis>4 gis <f a d>2 |
1675     }
1676   }
1677 }
1678
1679 \new PianoStaff {
1680   <<
1681     \context Staff = "up" {
1682       #(set-accidental-style 'piano)
1683       \musicA
1684     }
1685     \context Staff = "down" {
1686       \musicB
1687     }
1688   >>
1689 }
1690 @end lilypond
1691
1692 @item piano-cautionary
1693
1694 @cindex accidentals, piano cautionary
1695 @cindex cautionary accidentals, piano
1696 @cindex piano cautionary accidentals
1697 @cindex accidental style, piano cautionary
1698 @cindex cautionary accidental style, piano
1699 @cindex piano cautionary accidental style
1700
1701 @funindex piano-cautionary
1702
1703 This is the same as @code{piano} but with the extra accidentals
1704 typeset as cautionaries.
1705
1706 @lilypond[quote]
1707 musicA = {
1708   <<
1709     \relative c' {
1710       cis'8 fis, d'4 <a cis>8 f bis4 |
1711       cis2. <c, g'>4 |
1712     }
1713     \\
1714     \relative c' {
1715       ais'2 cis, |
1716       fis8 b a4 cis2 |
1717     }
1718   >>
1719 }
1720
1721 musicB = {
1722   \clef bass
1723   \new Voice {
1724     \voiceTwo \relative c' {
1725       <fis, a cis>4
1726       \change Staff = up
1727       cis'
1728       \change Staff = down
1729       <fis, a>
1730       \change Staff = up
1731       dis' |
1732       \change Staff = down
1733       <fis, a cis>4 gis <f a d>2 |
1734     }
1735   }
1736 }
1737
1738 \new PianoStaff {
1739   <<
1740     \context Staff = "up" {
1741       #(set-accidental-style 'piano-cautionary)
1742       \musicA
1743     }
1744     \context Staff = "down" {
1745       \musicB
1746     }
1747   >>
1748 }
1749 @end lilypond
1750
1751
1752 @item neo-modern
1753
1754 @cindex neo-modern accidental style
1755 @cindex accidental style, neo-modern
1756
1757 @funindex neo-modern
1758
1759 This rule reproduces a common practice in contemporary music:
1760 accidentals are printed like with @code{modern}, but they are printed
1761 again if the same note appears later in the same measure -- except
1762 if the note is immediately repeated.
1763
1764 @lilypond[quote]
1765 musicA = {
1766   <<
1767     \relative c' {
1768       cis'8 fis, d'4 <a cis>8 f bis4 |
1769       cis2. <c, g'>4 |
1770     }
1771     \\
1772     \relative c' {
1773       ais'2 cis, |
1774       fis8 b a4 cis2 |
1775     }
1776   >>
1777 }
1778
1779 musicB = {
1780   \clef bass
1781   \new Voice {
1782     \voiceTwo \relative c' {
1783       <fis, a cis>4
1784       \change Staff = up
1785       cis'
1786       \change Staff = down
1787       <fis, a>
1788       \change Staff = up
1789       dis' |
1790       \change Staff = down
1791       <fis, a cis>4 gis <f a d>2 |
1792     }
1793   }
1794 }
1795
1796 \new PianoStaff {
1797   <<
1798     \context Staff = "up" {
1799       #(set-accidental-style 'neo-modern)
1800       \musicA
1801     }
1802     \context Staff = "down" {
1803       #(set-accidental-style 'neo-modern)
1804       \musicB
1805     }
1806   >>
1807 }
1808 @end lilypond
1809
1810 @item neo-modern-cautionary
1811
1812 @cindex neo-modern-cautionary accidental style
1813 @cindex accidental style, neo-modern-cautionary
1814
1815 @funindex neo-modern-cautionary
1816
1817 This rule is similar to @code{neo-modern}, but the extra
1818 accidentals are printed as cautionary accidentals.
1819
1820 @lilypond[quote]
1821 musicA = {
1822   <<
1823     \relative c' {
1824       cis'8 fis, d'4 <a cis>8 f bis4 |
1825       cis2. <c, g'>4 |
1826     }
1827     \\
1828     \relative c' {
1829       ais'2 cis, |
1830       fis8 b a4 cis2 |
1831     }
1832   >>
1833 }
1834
1835 musicB = {
1836   \clef bass
1837   \new Voice {
1838     \voiceTwo \relative c' {
1839       <fis, a cis>4
1840       \change Staff = up
1841       cis'
1842       \change Staff = down
1843       <fis, a>
1844       \change Staff = up
1845       dis' |
1846       \change Staff = down
1847       <fis, a cis>4 gis <f a d>2 |
1848     }
1849   }
1850 }
1851
1852 \new PianoStaff {
1853   <<
1854     \context Staff = "up" {
1855       #(set-accidental-style 'neo-modern-cautionary)
1856       \musicA
1857     }
1858     \context Staff = "down" {
1859       #(set-accidental-style 'neo-modern-cautionary)
1860       \musicB
1861     }
1862   >>
1863 }
1864 @end lilypond
1865
1866
1867 @item dodecaphonic
1868
1869 @cindex dodecaphonic accidental style
1870 @cindex dodecaphonic style, neo-modern
1871
1872 @funindex dodecaphonic
1873
1874 This rule reflects a practice introduced by composers at
1875 the beginning of the 20th century, in an attempt to
1876 abolish the hierarchy between natural and non-natural notes.
1877 With this style, @emph{every} note gets an accidental sign,
1878 including natural signs.
1879
1880 @lilypond[quote]
1881 musicA = {
1882   <<
1883     \relative c' {
1884       cis'8 fis, d'4 <a cis>8 f bis4 |
1885       cis2. <c, g'>4 |
1886     }
1887     \\
1888     \relative c' {
1889       ais'2 cis, |
1890       fis8 b a4 cis2 |
1891     }
1892   >>
1893 }
1894
1895 musicB = {
1896   \clef bass
1897   \new Voice {
1898     \voiceTwo \relative c' {
1899       <fis, a cis>4
1900       \change Staff = up
1901       cis'
1902       \change Staff = down
1903       <fis, a>
1904       \change Staff = up
1905       dis' |
1906       \change Staff = down
1907       <fis, a cis>4 gis <f a d>2 |
1908     }
1909   }
1910 }
1911
1912 \new PianoStaff {
1913   <<
1914     \context Staff = "up" {
1915       #(set-accidental-style 'dodecaphonic)
1916       \musicA
1917     }
1918     \context Staff = "down" {
1919       #(set-accidental-style 'dodecaphonic)
1920       \musicB
1921     }
1922   >>
1923 }
1924 @end lilypond
1925
1926
1927 @item teaching
1928
1929 @cindex teaching accidental style
1930 @cindex accidental style, teaching
1931
1932 @funindex teaching
1933
1934 This rule is intended for students, and makes it easy to create
1935 scale sheets with automagically created cautionary accidentals.
1936 Accidentals are printed like with @code{modern}, but cautionary
1937 accidentals are added for all sharp or flat tones specified by the
1938 key signature, except if the note is immediately repeated.
1939
1940 @lilypond[quote]
1941 musicA = {
1942   <<
1943     \relative c' {
1944       cis'8 fis, d'4 <a cis>8 f bis4 |
1945       cis2. <c, g'>4 |
1946     }
1947     \\
1948     \relative c' {
1949       ais'2 cis, |
1950       fis8 b a4 cis2 |
1951     }
1952   >>
1953 }
1954
1955 musicB = {
1956   \clef bass
1957   \new Voice {
1958     \voiceTwo \relative c' {
1959       <fis, a cis>4
1960       \change Staff = up
1961       cis'
1962       \change Staff = down
1963       <fis, a>
1964       \change Staff = up
1965       dis' |
1966       \change Staff = down
1967       <fis, a cis>4 gis <f a d>2 |
1968     }
1969   }
1970 }
1971
1972 \new PianoStaff {
1973   <<
1974     \context Staff = "up" {
1975       \key fis \minor
1976       #(set-accidental-style 'teaching)
1977       \musicA
1978     }
1979     \context Staff = "down" {
1980       \key fis \minor
1981       #(set-accidental-style 'teaching)
1982       \musicB
1983     }
1984   >>
1985 }
1986 @end lilypond
1987
1988
1989
1990 @item no-reset
1991
1992 @cindex accidental style, no reset
1993 @cindex no reset accidental style
1994
1995 @funindex no-reset
1996
1997 This is the same as @code{default} but with accidentals lasting
1998 @q{forever} and not only within the same measure:
1999
2000 @lilypond[quote]
2001 musicA = {
2002   <<
2003     \relative c' {
2004       cis'8 fis, d'4 <a cis>8 f bis4 |
2005       cis2. <c, g'>4 |
2006     }
2007     \\
2008     \relative c' {
2009       ais'2 cis, |
2010       fis8 b a4 cis2 |
2011     }
2012   >>
2013 }
2014
2015 musicB = {
2016   \clef bass
2017   \new Voice {
2018     \voiceTwo \relative c' {
2019       <fis, a cis>4
2020       \change Staff = up
2021       cis'
2022       \change Staff = down
2023       <fis, a>
2024       \change Staff = up
2025       dis' |
2026       \change Staff = down
2027       <fis, a cis>4 gis <f a d>2 |
2028     }
2029   }
2030 }
2031
2032 \new PianoStaff {
2033   <<
2034     \context Staff = "up" {
2035       #(set-accidental-style 'no-reset)
2036       \musicA
2037     }
2038     \context Staff = "down" {
2039       #(set-accidental-style 'no-reset)
2040       \musicB
2041     }
2042   >>
2043 }
2044 @end lilypond
2045
2046 @item forget
2047
2048 @cindex forget accidental style
2049 @cindex accidental style, forget
2050
2051 @funindex forget
2052
2053 This is the opposite of @code{no-reset}: Accidentals are not
2054 remembered at all -- and hence all accidentals are typeset
2055 relative to the key signature, regardless of what came before in
2056 the music.  Unlike @code{dodecaphonic}, this rule never prints
2057 any naturals.
2058
2059 @lilypond[quote]
2060 musicA = {
2061   <<
2062     \relative c' {
2063       cis'8 fis, d'4 <a cis>8 f bis4 |
2064       cis2. <c, g'>4 |
2065     }
2066     \\
2067     \relative c' {
2068       ais'2 cis, |
2069       fis8 b a4 cis2 |
2070     }
2071   >>
2072 }
2073
2074 musicB = {
2075   \clef bass
2076   \new Voice {
2077     \voiceTwo \relative c' {
2078       <fis, a cis>4
2079       \change Staff = up
2080       cis'
2081       \change Staff = down
2082       <fis, a>
2083       \change Staff = up
2084       dis' |
2085       \change Staff = down
2086       <fis, a cis>4 gis <f a d>2 |
2087     }
2088   }
2089 }
2090
2091 \new PianoStaff {
2092   <<
2093     \context Staff = "up" {
2094       #(set-accidental-style 'forget)
2095       \musicA
2096     }
2097     \context Staff = "down" {
2098       #(set-accidental-style 'forget)
2099       \musicB
2100     }
2101   >>
2102 }
2103 @end lilypond
2104 @end table
2105
2106 @snippets
2107
2108 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
2109 {dodecaphonic-style-accidentals-for-each-note-including-naturals.ly}
2110
2111
2112 @seealso
2113 Snippets:
2114 @rlsr{Pitches}.
2115
2116 Internals Reference:
2117 @rinternals{Accidental},
2118 @rinternals{Accidental_engraver},
2119 @rinternals{GrandStaff} and
2120 @rinternals{PianoStaff},
2121 @rinternals{Staff},
2122 @rinternals{AccidentalSuggestion},
2123 @rinternals{AccidentalPlacement},
2124 @rinternals{accidental-suggestion-interface}.
2125
2126
2127 @cindex accidentals and simultaneous notes
2128 @cindex simultaneous notes and accidentals
2129 @cindex accidentals in chords
2130 @cindex chords, accidentals in
2131
2132 @knownissues
2133
2134 Simultaneous notes are considered to be entered in sequential
2135 mode.  This means that in a chord the accidentals are typeset as
2136 if the notes in the chord happen one at a time, in the order in
2137 which they appear in the input file.  This is a problem when
2138 accidentals in a chord depend on each other, which does not happen
2139 for the default accidental style.  The problem can be solved by
2140 manually inserting@tie{}@code{!} and@tie{}@code{?} for the
2141 problematic notes.
2142
2143
2144 @node Ambitus
2145 @unnumberedsubsubsec Ambitus
2146
2147 @cindex ambitus
2148 @cindex range of pitches
2149 @cindex pitch range
2150
2151 The term @notation{ambitus} (pl. ambitus) denotes a range of
2152 pitches for a given voice in a part of music.  It may also denote
2153 the pitch range that a musical instrument is capable of playing.
2154 Ambitus are printed on vocal parts so that performers can easily
2155 determine if it matches their capabilities.
2156
2157 Ambitus are denoted at the beginning of a piece near the initial
2158 clef.  The range is graphically specified by two note heads that
2159 represent the lowest and highest pitches.  Accidentals are only
2160 printed if they are not part of the key signature.
2161
2162 @lilypond[verbatim,quote]
2163 \layout {
2164   \context {
2165     \Voice
2166     \consists "Ambitus_engraver"
2167   }
2168 }
2169
2170 \relative c'' {
2171   aes c e2
2172   cis,1
2173 }
2174 @end lilypond
2175
2176
2177 @snippets
2178
2179 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
2180 {adding-ambitus-per-voice.ly}
2181
2182 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
2183 {ambitus-with-multiple-voices.ly}
2184
2185
2186 @seealso
2187 Music Glossary:
2188 @rglos{ambitus}.
2189
2190 Snippets:
2191 @rlsr{Pitches}.
2192
2193 Internals Reference:
2194 @rinternals{Ambitus_engraver},
2195 @rinternals{Voice},
2196 @rinternals{Staff},
2197 @rinternals{Ambitus},
2198 @rinternals{AmbitusAccidental},
2199 @rinternals{AmbitusLine},
2200 @rinternals{AmbitusNoteHead},
2201 @rinternals{ambitus-interface}.
2202
2203
2204 @knownissues
2205
2206 There is no collision handling in the case of multiple per-voice
2207 ambitus.
2208
2209
2210 @node Note heads
2211 @subsection Note heads
2212
2213 This section suggests ways of altering note heads.
2214
2215 @menu
2216 * Special note heads::
2217 * Easy notation note heads::
2218 * Shape note heads::
2219 * Improvisation::
2220 @end menu
2221
2222 @node Special note heads
2223 @unnumberedsubsubsec Special note heads
2224
2225 @cindex note heads, special
2226 @cindex note heads, cross
2227 @cindex note heads, diamond
2228 @cindex note heads, parlato
2229 @cindex note heads, harmonic
2230 @cindex note heads, guitar
2231 @cindex special note heads
2232 @cindex cross note heads
2233 @cindex diamond note heads
2234 @cindex parlato note heads
2235 @cindex harmonic note heads
2236 @cindex guitar note heads
2237 @cindex note head styles
2238 @cindex styles, note heads
2239
2240 @funindex cross
2241
2242 Note heads may be altered:
2243
2244 @lilypond[verbatim,quote,relative=2]
2245 c4 b a b
2246 \override NoteHead #'style = #'cross
2247 c4 b a b
2248 \revert NoteHead #'style
2249 c4 d e f
2250 @end lilypond
2251
2252 There is a shorthand for diamond shapes which can only be used
2253 inside chords:
2254
2255 @lilypond[verbatim,quote,relative=2]
2256 <c f\harmonic>2 <d a'\harmonic>4 <c g'\harmonic>
2257 @end lilypond
2258
2259 @noindent
2260 To see all note head styles, see @ref{Note head styles}.
2261
2262
2263 @seealso
2264 Snippets:
2265 @rlsr{Pitches}.
2266
2267 Notation Reference:
2268 @ref{Note head styles},
2269 @ref{Chorded notes}.
2270
2271 Internals Reference:
2272 @rinternals{note-event},
2273 @rinternals{Note_heads_engraver},
2274 @rinternals{Ledger_line_engraver},
2275 @rinternals{NoteHead},
2276 @rinternals{LedgerLineSpanner},
2277 @rinternals{note-head-interface},
2278 @rinternals{ledger-line-spanner-interface}.
2279
2280
2281 @node Easy notation note heads
2282 @unnumberedsubsubsec Easy notation note heads
2283
2284 @cindex note heads, practice
2285 @cindex practice note heads
2286 @cindex note heads, easy notation
2287 @cindex easy notation
2288 @cindex Hal Leonard
2289 @cindex beginners' music
2290 @cindex music, beginners'
2291 @cindex easy play note heads
2292 @cindex note heads, easy play
2293
2294 @funindex \easyHeadsOn
2295 @funindex easyHeadsOn
2296 @funindex \easyHeadsOff
2297 @funindex easyHeadsOff
2298
2299 The @q{easy play} note head includes a note name inside the head.
2300 It is used in music for beginners.  To make the letters readable,
2301 it should be printed in a large font size.  To print with a larger
2302 font, see @ref{Setting the staff size}.
2303
2304 @lilypond[verbatim,quote]
2305 #(set-global-staff-size 26)
2306 \relative c' {
2307   \easyHeadsOn
2308   c2 e4 f
2309   g1
2310   \easyHeadsOff
2311   c,1
2312 }
2313 @end lilypond
2314
2315
2316 @predefined
2317 @code{\easyHeadsOn},
2318 @code{\easyHeadsOff}.
2319 @endpredefined
2320
2321
2322 @seealso
2323 Notation Reference:
2324 @ref{Setting the staff size}.
2325
2326 Snippets:
2327 @rlsr{Pitches}.
2328
2329 Internals Reference:
2330 @rinternals{note-event},
2331 @rinternals{Note_heads_engraver},
2332 @rinternals{NoteHead},
2333 @rinternals{note-head-interface}.
2334
2335
2336 @node Shape note heads
2337 @unnumberedsubsubsec Shape note heads
2338
2339 @cindex note heads, shape
2340 @cindex note heads, Aiken
2341 @cindex note heads, sacred harp
2342 @cindex shape notes
2343 @cindex Aiken shape note heads
2344 @cindex sacred harp note heads
2345
2346 @funindex \key
2347 @funindex key
2348 @funindex \aikenHeads
2349 @funindex aikenHeads
2350 @funindex \sacredHarpHeads
2351 @funindex sacredHarpHeads
2352
2353 In shape note head notation, the shape of the note head
2354 corresponds to the harmonic function of a note in the scale.  This
2355 notation was popular in nineteenth-century American song books.
2356 Shape note heads can be produced:
2357
2358 @lilypond[verbatim,quote,relative=2]
2359 \aikenHeads
2360 c, d e f g a b c
2361 \sacredHarpHeads
2362 c, d e f g a b c
2363 @end lilypond
2364
2365 Shapes are typeset according to the step in the scale, where the
2366 base of the scale is determined by the @code{\key} command.
2367
2368
2369 @predefined
2370 @code{\aikenHeads},
2371 @code{\sacredHarpHeads}.
2372 @endpredefined
2373
2374
2375 @snippets
2376
2377 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
2378 {applying-note-head-styles-depending-on-the-step-of-the-scale.ly}
2379
2380 @noindent
2381 To see all note head styles, see @ref{Note head styles}.
2382
2383
2384 @seealso
2385 Snippets:
2386 @rlsr{Pitches}.
2387
2388 Notation Reference:
2389 @ref{Note head styles}.
2390
2391 Internals Reference:
2392 @rinternals{note-event},
2393 @rinternals{Note_heads_engraver},
2394 @rinternals{NoteHead},
2395 @rinternals{note-head-interface}.
2396
2397
2398 @node Improvisation
2399 @unnumberedsubsubsec Improvisation
2400
2401 @cindex improvisation
2402 @cindex slashed note heads
2403 @cindex note heads, improvisation
2404 @cindex note heads, slashed
2405
2406 @funindex \improvisationOn
2407 @funindex improvisationOn
2408 @funindex \improvisationOff
2409 @funindex improvisationOff
2410
2411 Improvisation is sometimes denoted with slashed note heads, where
2412 the performer may choose any pitch but should play the specified
2413 rhythm.  Such note heads can be created:
2414
2415 @lilypond[verbatim,quote,relative=2]
2416 \new Voice \with {
2417   \consists "Pitch_squash_engraver"
2418 } {
2419   e8 e g a a16( bes) a8 g
2420   \improvisationOn
2421   e8 ~
2422   e2 ~ e8 f4 f8 ~
2423   f2
2424   \improvisationOff
2425   a16( bes) a8 g e
2426 }
2427 @end lilypond
2428
2429
2430 @predefined
2431 @code{\improvisationOn},
2432 @code{\improvisationOff}.
2433 @endpredefined
2434
2435
2436 @seealso
2437 Snippets:
2438 @rlsr{Pitches}.
2439
2440 Internals Reference:
2441 @rinternals{Pitch_squash_engraver},
2442 @rinternals{Voice},
2443 @rinternals{RhythmicStaff}.
2444
2445