Documentation/notation/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.  For details, see the Contributors'
   7     Guide, node Updating translation committishes..
   8 @end ignore
   9
  10 @c \version "2.19.2"
  11
  12
  13 @node Pitches
  14 @section Pitches
  15
  16 @lilypondfile[quote]{pitches-headword.ly}
  17
  18 This section discusses how to specify the pitch of notes.  There
  19 are three steps to this process: input, modification, and output.
  20
  21 @menu
  22 * Writing pitches::
  23 * Changing multiple pitches::
  24 * Displaying pitches::
  25 * Note heads::
  26 @end menu
  27
  28
  29 @node Writing pitches
  30 @subsection Writing pitches
  31
  32 This section discusses how to input pitches.  There are two
  33 different ways to place notes in octaves: absolute and relative
  34 mode.  In most cases, relative mode will be more convenient.
  35
  36 @menu
  37 * Absolute octave entry::
  38 * Relative octave entry::
  39 * Accidentals::
  40 * Note names in other languages::
  41 @end menu
  42
  43
  44 @node Absolute octave entry
  45 @unnumberedsubsubsec Absolute octave entry
  46
  47 @cindex pitch names
  48 @cindex pitches
  49 @cindex absolute
  50 @cindex absolute octave specification
  51 @cindex octave specification, absolute
  52 @cindex absolute octave entry
  53 @cindex octave entry, absolute
  54
  55 A pitch name is specified using lowercase letters@tie{}@code{a}
  56 through@tie{}@code{g}.  The note names @code{c} to @code{b} are
  57 engraved in the octave below middle C.
  58
  59 @c don't use c' here.
  60 @lilypond[verbatim,quote]
  61 {
  62   \clef bass
  63   c4 d e f
  64   g4 a b c
  65   d4 e f g
  66 }
  67 @end lilypond
  68
  69 @cindex octave changing mark
  70
  71 @funindex '
  72 @funindex ,
  73
  74 Other octaves may be specified with a single quote@tie{}(@code{'})
  75 or comma@tie{}(@code{,}) character.  Each@tie{}@code{'} raises the
  76 pitch by one octave; each@tie{}@code{,} lowers the pitch by an
  77 octave.
  78
  79 @lilypond[verbatim,quote]
  80 {
  81   \clef treble
  82   c'4 c'' e' g
  83   d''4 d' d c
  84   \clef bass
  85   c,4 c,, e, g
  86   d,,4 d, d c
  87 }
  88 @end lilypond
  89
  90 @funindex absolute
  91 @funindex \absolute
  92 Music can be marked explicitly as being in absolute octave
  93 notation by preceding it with @code{\absolute}:
  94
  95 @example
  96 \absolute @var{musicexpr}
  97 @end example
  98
  99 will be interpreted in absolute octave entry mode regardless of
 100 the context it appears in.
 101
 102 @seealso
 103 Music Glossary:
 104 @rglos{Pitch names}.
 105
 106 Snippets:
 107 @rlsr{Pitches}.
 108
 109
 110 @node Relative octave entry
 111 @unnumberedsubsubsec Relative octave entry
 112
 113 @cindex relative
 114 @cindex relative octave entry
 115 @cindex octave entry, relative
 116 @cindex relative octave specification
 117 @cindex octave specification, relative
 118
 119 @funindex relative
 120 @funindex \relative
 121
 122 Absolute octave entry requires specifying the octave for every
 123 single note.  Relative octave entry, in contrast, specifies each
 124 octave in relation to the last note: changing one note's octave
 125 will affect all of the following notes.
 126
 127 Relative note mode has to be entered explicitly using the
 128 @code{\relative} command:
 129
 130 @example
 131 \relative @var{startpitch} @var{musicexpr}
 132 @end example
 133
 134 In relative mode, each note is assumed to be as close to the
 135 previous note as possible.  This means that the octave of each
 136 pitch inside @code{@var{musicexpr}} is calculated as follows:
 137
 138 @itemize
 139 @item
 140 If no octave changing mark is used on a pitch, its octave is
 141 calculated so that the interval with the previous note is less
 142 than a fifth.  This interval is determined without considering
 143 accidentals.
 144
 145 @item
 146 An octave changing mark@tie{}@code{'} or@tie{}@code{,} can be
 147 added to respectively raise or lower a pitch by an extra octave,
 148 relative to the pitch calculated without an octave mark.
 149
 150 @item
 151 Multiple octave changing marks can be used.  For example,
 152 @code{''}@tie{}and@tie{}@code{,,} will alter the pitch by two
 153 octaves.
 154
 155 @item
 156 The pitch of the first note is relative to
 157 @code{@var{startpitch}}.  @code{@var{startpitch}} is specified in
 158 absolute octave mode.  Which choices are meaningful?
 159
 160 @table @asis
 161 @item an octave of @code{c}
 162 Identifying middle C with @code{c'} is quite basic, so finding
 163 octaves of @code{c} tends to be straightforward.  If your music
 164 starts with @code{gis} above @code{c'''}, you'd write something
 165 like @code{\relative c''' @{ gis' @dots{} @}}
 166
 167 @item an octave of the first note inside
 168 Writing @code{\relative gis''' @{ gis @dots{} @}} makes it easy to
 169 determine the absolute pitch of the first note inside.
 170
 171 @item no explicit starting pitch
 172 This (namely writing @code{\relative @{ gis''' @dots{} @}}) can be
 173 viewed as a compact version of the previous option: the first note
 174 inside is written in absolute pitch itself.  This happens to be
 175 equivalent to choosing @code{f} as the reference pitch.
 176 @end table
 177
 178 The documentation will usually employ the first option.
 179 @end itemize
 180
 181 Here is the relative mode shown in action:
 182
 183 @lilypond[verbatim,quote]
 184 \relative c {
 185   \clef bass
 186   c d e f
 187   g a b c
 188   d e f g
 189 }
 190 @end lilypond
 191
 192 Octave changing marks are used for intervals greater than a
 193 fourth:
 194
 195 @lilypond[verbatim,quote]
 196 \relative c'' {
 197   c g c f,
 198   c' a, e'' c
 199 }
 200 @end lilypond
 201
 202 A note sequence without a single octave mark can nevertheless span
 203 large intervals:
 204
 205 @lilypond[verbatim,quote]
 206 \relative c {
 207   c f b e
 208   a d g c
 209 }
 210 @end lilypond
 211
 212 When @code{\relative} blocks are nested, the innermost
 213 @code{\relative} block applies.
 214
 215 @lilypond[verbatim,quote]
 216 \relative c' {
 217   c d e f
 218   \relative c'' {
 219     c d e f
 220   }
 221 }
 222 @end lilypond
 223
 224 @code{\relative} has no effect on @code{\chordmode} blocks.
 225
 226 @lilypond[verbatim,quote]
 227 \new Staff {
 228   \relative c''' {
 229     \chordmode { c1 }
 230   }
 231   \chordmode { c1 }
 232 }
 233 @end lilypond
 234
 235 @code{\relative} is not allowed inside of @code{\chordmode} blocks.
 236
 237 Music inside a @code{\transpose} block is absolute unless a
 238 @code{\relative} is included.
 239
 240 @lilypond[verbatim,quote]
 241 \relative c' {
 242   d e
 243   \transpose f g {
 244     d e
 245     \relative c' {
 246       d e
 247     }
 248   }
 249 }
 250 @end lilypond
 251
 252
 253 @cindex chords and relative octave entry
 254 @cindex relative octave entry and chords
 255
 256 If the preceding item is a chord, the first note of the chord is
 257 used as the reference point for the octave placement of a
 258 following note or chord.  Inside chords, the next note is always
 259 relative to the preceding one.  Examine the next example
 260 carefully, paying attention to the @code{c} notes.
 261
 262 @lilypond[verbatim,quote]
 263 \relative c' {
 264   c
 265   <c e g>
 266   <c' e g'>
 267   <c, e, g''>
 268 }
 269 @end lilypond
 270
 271 As explained above, the octave of pitches is calculated only with
 272 the note names, regardless of any alterations.  Therefore, an
 273 E-double-sharp following a B will be placed higher, while an
 274 F-double-flat will be placed lower.  In other words, a
 275 double-augmented fourth is considered a smaller interval than a
 276 double-diminished fifth, regardless of the number of semitones
 277 that each interval contains.
 278
 279 @lilypond[verbatim,quote]
 280 \relative c'' {
 281   c2 fis
 282   c2 ges
 283   b2 eisis
 284   b2 feses
 285 }
 286 @end lilypond
 287
 288 One consequence of these rules is that the first note inside
 289 @code{@w{\relative f}} music is interpreted just the same as
 290 if it was written in absolute pitch mode.
 291
 292 @seealso
 293 Music Glossary:
 294 @rglos{fifth},
 295 @rglos{interval},
 296 @rglos{Pitch names}.
 297
 298 Notation Reference:
 299 @ref{Octave checks}.
 300
 301 Snippets:
 302 @rlsr{Pitches}.
 303
 304 Internals Reference:
 305 @rinternals{RelativeOctaveMusic}.
 306
 307 @cindex relative octave entry and transposition
 308 @cindex transposition and relative octave entry
 309
 310 @funindex \transpose
 311 @funindex transpose
 312 @funindex \chordmode
 313 @funindex chordmode
 314 @funindex \relative
 315 @funindex relative
 316
 317
 318 @node Accidentals
 319 @unnumberedsubsubsec Accidentals
 320
 321 @cindex accidental
 322 @cindex key signature
 323 @cindex clef
 324
 325 @c duplicated in Key signature and Accidentals
 326 @warning{New users are sometimes confused about accidentals and
 327 key signatures.  In LilyPond, note names are the raw input; key
 328 signatures and clefs determine how this raw input is displayed.
 329 An unaltered note like@tie{}@code{c} means @q{C natural},
 330 regardless of the key signature or clef.  For more information,
 331 see @rlearning{Accidentals and key signatures}.}
 332
 333 @cindex note names, Dutch
 334 @cindex note names, default
 335 @cindex default note names
 336 @cindex sharp
 337 @cindex flat
 338 @cindex double sharp
 339 @cindex sharp, double
 340 @cindex double flat
 341 @cindex flat, double
 342 @cindex natural sign
 343 @cindex natural pitch
 344
 345 A @notation{sharp} pitch is made by adding @code{is} to the note
 346 name, and a @notation{flat} pitch by adding @code{es}.  As you
 347 might expect, a @notation{double sharp} or @notation{double flat}
 348 is made by adding @code{isis} or @code{eses}.  This syntax is
 349 derived from Dutch note naming conventions.  To use other names
 350 for accidentals, see @ref{Note names in other languages}.
 351
 352 @lilypond[verbatim,quote,relative=2]
 353 ais1 aes aisis aeses
 354 @end lilypond
 355
 356 A natural will cancel the effect of an accidental or key
 357 signature.  However, naturals are not encoded into the note name
 358 syntax with a suffix; a natural pitch is shown as a simple note
 359 name:
 360
 361 @lilypond[verbatim,quote,relative=2]
 362 a4 aes a2
 363 @end lilypond
 364
 365 @cindex quarter tones
 366 @cindex semi-flats
 367 @cindex semi-sharps
 368
 369 Quarter tones may be added; the following is a series of Cs with
 370 increasing pitches:
 371
 372 @lilypond[verbatim,quote,relative=2]
 373 ceseh1 ces ceh c cih cis cisih
 374 @end lilypond
 375
 376
 377
 378 @cindex accidental, reminder
 379 @cindex accidental, cautionary
 380 @cindex accidental, parenthesized
 381 @cindex reminder accidental
 382 @cindex cautionary accidental
 383 @cindex parenthesized accidental
 384
 385 @funindex ?
 386 @funindex !
 387
 388
 389 Normally accidentals are printed automatically, but you may also
 390 print them manually.  A reminder accidental can be forced by
 391 adding an exclamation mark@tie{}@code{!} after the pitch.  A
 392 cautionary accidental (i.e., an accidental within parentheses) can
 393 be obtained by adding the question mark@tie{}@code{?} after the
 394 pitch.  These extra accidentals can also be used to produce
 395 natural signs.
 396
 397 @lilypond[verbatim,quote,relative=2]
 398 cis cis cis! cis? c c c! c?
 399 @end lilypond
 400
 401 @cindex accidental on tied note
 402 @cindex tied note, accidental
 403
 404 Accidentals on tied notes are only printed at the beginning of a
 405 new system:
 406
 407 @lilypond[verbatim,quote,relative=2,ragged-right]
 408 cis1~ 1~
 409 \break
 410 cis
 411 @end lilypond
 412
 413
 414 @snippets
 415
 416 @lilypondfile[verbatim,quote,texidoc,doctitle,ragged-right]
 417 {hiding-accidentals-on-tied-notes-at-the-start-of-a-new-system.ly}
 418
 419 @lilypondfile[verbatim,quote,texidoc,doctitle]
 420 {preventing-extra-naturals-from-being-automatically-added.ly}
 421
 422 @seealso
 423 Music Glossary:
 424 @rglos{sharp},
 425 @rglos{flat},
 426 @rglos{double sharp},
 427 @rglos{double flat},
 428 @rglos{Pitch names},
 429 @rglos{quarter tone}.
 430
 431 Learning Manual:
 432 @rlearning{Accidentals and key signatures}.
 433
 434 Notation Reference:
 435 @ref{Automatic accidentals},
 436 @ref{Annotational accidentals (musica ficta)},
 437 @ref{Note names in other languages}.
 438
 439 Snippets:
 440 @rlsr{Pitches}.
 441
 442 Internals Reference:
 443 @rinternals{Accidental_engraver},
 444 @rinternals{Accidental},
 445 @rinternals{AccidentalCautionary},
 446 @rinternals{accidental-interface}.
 447
 448 @cindex accidental, quarter-tone
 449 @cindex quarter-tone accidental
 450
 451 @knownissues
 452 There are no generally accepted standards for denoting
 453 quarter-tone accidentals, so LilyPond's symbol does not conform to
 454 any standard.
 455
 456
 457 @node Note names in other languages
 458 @unnumberedsubsubsec Note names in other languages
 459
 460 @cindex note names, other languages
 461 @cindex pitch names, other languages
 462 @cindex language, note names in other
 463 @cindex language, pitch names in other
 464
 465 There are predefined sets of note and accidental names for various
 466 other languages.  Selecting the note name language is usually done
 467 at the beginning of the file; the following example is written
 468 using Italian note names:
 469
 470 @lilypond[quote,verbatim]
 471 \language "italiano"
 472
 473 \relative do' {
 474   do re mi sib
 475 }
 476 @end lilypond
 477
 478 The available languages and the note names they define are:
 479
 480 @quotation
 481 @multitable {@code{nederlands}} {do re mi fa sol la sib si}
 482 @headitem Language
 483   @tab Note Names
 484 @item @code{nederlands}
 485   @tab c d e f g a bes b
 486 @item @code{catalan}
 487   @tab do re mi fa sol la sib si
 488 @item @code{deutsch}
 489   @tab c d e f g a b h
 490 @item @code{english}
 491   @tab c d e f g a bf b
 492 @item @code{espanol} or @code{español}
 493   @tab do re mi fa sol la sib si
 494 @item @code{italiano} or @code{français}
 495   @tab do re mi fa sol la sib si
 496 @item @code{norsk}
 497   @tab c d e f g a b h
 498 @item @code{portugues}
 499   @tab do re mi fa sol la sib si
 500 @item @code{suomi}
 501   @tab c d e f g a b h
 502 @item @code{svenska}
 503   @tab c d e f g a b h
 504 @item @code{vlaams}
 505   @tab do re mi fa sol la sib si
 506 @end multitable
 507 @end quotation
 508
 509 In addition to note names, accidental suffixes may
 510 also vary depending on the language:
 511
 512 @quotation
 513 @multitable {@code{nederlands}} {-s/-sharp} {-ess/-es} {-ss/-x/-sharpsharp} {-essess/-eses}
 514 @headitem Language
 515   @tab sharp @tab flat @tab double sharp @tab double flat
 516 @item @code{nederlands}
 517   @tab -is @tab -es @tab -isis @tab -eses
 518 @item @code{catalan}
 519   @tab -d/-s @tab -b @tab -dd/-ss @tab -bb
 520 @item @code{deutsch}
 521   @tab -is @tab -es @tab -isis @tab -eses
 522 @item @code{english}
 523   @tab -s/-sharp @tab -f/-flat @tab -ss/-x/-sharpsharp
 524     @tab -ff/-flatflat
 525 @item @code{espanol} or @code{español}
 526   @tab -s @tab -b @tab -ss/-x @tab -bb
 527 @item @code{italiano} or @code{français}
 528   @tab -d @tab -b @tab -dd @tab -bb
 529 @item @code{norsk}
 530   @tab -iss/-is @tab -ess/-es @tab -ississ/-isis
 531     @tab -essess/-eses
 532 @item @code{portugues}
 533   @tab -s @tab -b @tab -ss @tab -bb
 534 @item @code{suomi}
 535   @tab -is @tab -es @tab -isis @tab -eses
 536 @item @code{svenska}
 537   @tab -iss @tab -ess @tab -ississ @tab -essess
 538 @item @code{vlaams}
 539   @tab -k @tab -b @tab -kk @tab -bb
 540 @end multitable
 541 @end quotation
 542
 543 In Dutch, @code{aes} is contracted to @code{as}, but both forms
 544 are accepted in LilyPond.  Similarly, both @code{es} and
 545 @code{ees} are accepted.  This also applies to
 546 @code{aeses}@tie{}/@tie{}@code{ases} and
 547 @code{eeses}@tie{}/@tie{}@code{eses}.  Sometimes only these
 548 contracted names are defined in the corresponding language files.
 549
 550 @lilypond[verbatim,quote,relative=2]
 551 a2 as e es a ases e eses
 552 @end lilypond
 553
 554
 555 @cindex microtones
 556 @cindex semi-sharp
 557 @cindex semi-flat
 558 @cindex sesqui-sharp
 559 @cindex sesqui-flat
 560
 561 Some music uses microtones whose alterations are fractions of a
 562 @q{normal} sharp or flat.  The following table lists note names
 563 for quarter-tone accidentals in various languages; here the prefixes
 564 @notation{semi-} and @notation{sesqui-} respectively
 565 mean @q{half} and @q{one and a half}.  Languages that do not
 566 appear in this table do not provide special note names yet.
 567
 568 @quotation
 569 @multitable {@code{nederlands}} {@b{semi-sharp}} {@b{semi-flat}} {@b{sesqui-sharp}} {@b{sesqui-flat}}
 570 @headitem Language
 571   @tab semi-sharp @tab semi-flat @tab sesqui-sharp @tab sesqui-flat
 572
 573 @item @code{nederlands}
 574   @tab -ih @tab -eh @tab -isih @tab -eseh
 575 @item @code{deutsch}
 576   @tab -ih @tab -eh @tab -isih @tab -eseh
 577 @item @code{english}
 578   @tab -qs @tab -qf @tab -tqs @tab -tqf
 579 @item @code{espanol} or @code{español}
 580   @tab -cs @tab -cb @tab -tcs @tab -tcb
 581 @item @code{italiano} or @code{français}
 582   @tab -sd @tab -sb @tab -dsd @tab -bsb
 583 @item @code{portugues}
 584   @tab -sqt @tab -bqt @tab -stqt @tab -btqt
 585 @end multitable
 586 @end quotation
 587
 588 Most languages presented here are commonly associated with
 589 Western classical music, also referred to as
 590 @notation{Common Practice Period}.  However, alternate
 591 pitches and tuning systems are also supported: see
 592 @ref{Common notation for non-Western music}.
 593
 594 @seealso
 595 Music Glossary:
 596 @rglos{Pitch names},
 597 @rglos{Common Practice Period}.
 598
 599 Notation Reference:
 600 @ref{Common notation for non-Western music}.
 601
 602 Installed Files:
 603 @file{scm/define-note-names.scm}.
 604
 605 Snippets:
 606 @rlsr{Pitches}.
 607
 608
 609 @node Changing multiple pitches
 610 @subsection Changing multiple pitches
 611
 612 This section discusses how to modify pitches.
 613
 614 @menu
 615 * Octave checks::
 616 * Transpose::
 617 * Inversion::
 618 * Retrograde::
 619 * Modal transformations::
 620 @end menu
 621
 622 @node Octave checks
 623 @unnumberedsubsubsec Octave checks
 624
 625 @cindex octave correction
 626 @cindex octave check
 627 @cindex control pitch
 628
 629 @funindex =
 630 @funindex \octaveCheck
 631 @funindex octaveCheck
 632 @funindex controlpitch
 633
 634 In relative mode, it is easy to forget an octave changing mark.
 635 Octave checks make such errors easier to find by displaying a
 636 warning and correcting the octave if a note is found in an
 637 unexpected octave.
 638
 639 To check the octave of a note, specify the absolute octave after
 640 the @code{=}@tie{}symbol.  This example will generate a warning
 641 (and change the pitch) because the second note is the absolute
 642 octave @code{d''} instead of @code{d'} as indicated by the octave
 643 correction.
 644
 645 @lilypond[verbatim,quote]
 646 \relative c'' {
 647   c2 d='4 d
 648   e2 f
 649 }
 650 @end lilypond
 651
 652 The octave of notes may also be checked with the
 653 @code{\octaveCheck@tie{}@var{controlpitch}} command.
 654 @code{@var{controlpitch}} is specified in absolute mode.  This
 655 checks that the interval between the previous note and the
 656 @code{@var{controlpitch}} is within a fourth (i.e., the normal
 657 calculation of relative mode).  If this check fails, a warning is
 658 printed, but the previous note is not changed.  Future notes are
 659 relative to the @code{@var{controlpitch}}.
 660
 661 @lilypond[verbatim,quote]
 662 \relative c'' {
 663   c2 d
 664   \octaveCheck c'
 665   e2 f
 666 }
 667 @end lilypond
 668
 669 Compare the two bars below.  The first and third @code{\octaveCheck}
 670 checks fail, but the second one does not fail.
 671
 672 @lilypond[verbatim,quote]
 673 \relative c'' {
 674   c4 f g f
 675
 676   c4
 677   \octaveCheck c'
 678   f
 679   \octaveCheck c'
 680   g
 681   \octaveCheck c'
 682   f
 683 }
 684 @end lilypond
 685
 686 @seealso
 687 Snippets:
 688 @rlsr{Pitches}.
 689
 690 Internals Reference:
 691 @rinternals{RelativeOctaveCheck}.
 692
 693
 694 @node Transpose
 695 @unnumberedsubsubsec Transpose
 696
 697 @cindex transpose
 698 @cindex transposing
 699 @cindex transposition
 700 @cindex transposition of pitches
 701 @cindex transposition of notes
 702 @cindex pitches, transposition of
 703 @cindex notes, transposition of
 704
 705 @funindex \transpose
 706 @funindex transpose
 707
 708 A music expression can be transposed with @code{\transpose}.  The
 709 syntax is
 710
 711 @example
 712 \transpose @var{frompitch} @var{topitch} @var{musicexpr}
 713 @end example
 714
 715 @noindent
 716 This means that @code{@var{musicexpr}} is transposed by the
 717 interval between the pitches @code{@var{frompitch}} and
 718 @code{@var{topitch}}: any note with pitch @code{@var{frompitch}}
 719 is changed to @code{@var{topitch}} and any other note is
 720 transposed by the same interval.  Both pitches are entered in
 721 absolute mode.
 722
 723 @warning{Music inside a @code{@bs{}transpose} block is absolute
 724 unless a @code{@bs{}relative} is included in the block.}
 725
 726 Consider a piece written in the key of D-major.  It can be
 727 transposed up to E-major; note that the key signature is
 728 automatically transposed as well.
 729
 730 @lilypond[verbatim,quote]
 731 \transpose d e {
 732   \relative c' {
 733     \key d \major
 734     d4 fis a d
 735   }
 736 }
 737 @end lilypond
 738
 739 @cindex transposing instruments
 740 @cindex instruments, transposing
 741
 742 If a part written in C (normal @notation{concert pitch}) is to be
 743 played on the A clarinet (for which an A is notated as a C and
 744 thus sounds a minor third lower than notated), the appropriate
 745 part will be produced with:
 746
 747 @lilypond[verbatim,quote]
 748 \transpose a c' {
 749   \relative c' {
 750     \key c \major
 751     c4 d e g
 752   }
 753 }
 754 @end lilypond
 755
 756 @noindent
 757 Note that we specify @w{@code{\key c \major}} explicitly.  If we
 758 do not specify a key signature, the notes will be transposed but
 759 no key signature will be printed.
 760
 761 @code{\transpose} distinguishes between enharmonic pitches: both
 762 @w{@code{\transpose c cis}} or @w{@code{\transpose c des}} will
 763 transpose up a semitone.  The first version will print sharps and
 764 the notes will remain on the same scale step, the second version
 765 will print flats on the scale step above.
 766
 767 @lilypond[verbatim,quote]
 768 music = \relative c' { c d e f }
 769 \new Staff {
 770   \transpose c cis { \music }
 771   \transpose c des { \music }
 772 }
 773 @end lilypond
 774
 775
 776 @code{\transpose} may also be used in a different way, to input
 777 written notes for a transposing instrument.  The previous examples
 778 show how to enter pitches in C (or @notation{concert pitch}) and
 779 typeset them for a transposing instrument, but the opposite is
 780 also possible if you for example have a set of instrumental parts
 781 and want to print a conductor's score.  For example, when entering
 782 music for a B-flat trumpet that begins on a notated E (concert D),
 783 one would write:
 784
 785 @example
 786 musicInBflat = @{ e4 @dots{} @}
 787 \transpose c bes, \musicInBflat
 788 @end example
 789
 790 @noindent
 791 To print this music in F (e.g., rearranging to a French horn) you
 792 could wrap the existing music with another @code{\transpose}:
 793
 794 @example
 795 musicInBflat = @{ e4 @dots{} @}
 796 \transpose f c' @{ \transpose c bes, \musicInBflat @}
 797 @end example
 798
 799 @noindent
 800 For more information about transposing instruments,
 801 see @ref{Instrument transpositions}.
 802
 803
 804 @snippets
 805
 806 @lilypondfile[verbatim,quote,texidoc,doctitle]
 807 {transposing-pitches-with-minimum-accidentals-smart-transpose.ly}
 808
 809 @seealso
 810 Notation Reference:
 811 @ref{Instrument transpositions},
 812 @ref{Inversion},
 813 @ref{Modal transformations},
 814 @ref{Relative octave entry},
 815 @ref{Retrograde}.
 816
 817 Snippets:
 818 @rlsr{Pitches}.
 819
 820 Internals Reference:
 821 @rinternals{TransposedMusic}.
 822
 823 @funindex \transpose
 824 @funindex transpose
 825 @funindex \chordmode
 826 @funindex chordmode
 827 @funindex \relative
 828 @funindex relative
 829
 830 @knownissues
 831 The relative conversion will not affect @code{\transpose},
 832 @code{\chordmode} or @code{\relative} sections in its argument.  To use
 833 relative mode within transposed music, an additional @code{\relative}
 834 must be placed inside @code{\transpose}.
 835
 836 Triple accidentals will not be printed if using @code{\transpose}. An
 837 @q{enharmonically equivalent} pitch will be used instead (e.g. d-flat
 838 rather than e-triple-flat).
 839
 840
 841 @node Inversion
 842 @unnumberedsubsubsec Inversion
 843
 844 @cindex inversion
 845 @cindex operation, inversion
 846 @funindex \inversion
 847
 848 A music expression can be inverted and transposed in a single
 849 operation with:
 850
 851 @example
 852 \inversion @var{around-pitch} @var{to-pitch} @var{musicexpr}
 853 @end example
 854
 855 The @code{@var{musicexpr}} is inverted interval-by-interval around
 856 @code{@var{around-pitch}}, and then transposed so that
 857 @code{@var{around-pitch}} is mapped to @code{@var{to-pitch}}.
 858
 859 @lilypond[verbatim,quote]
 860 music = \relative c' { c d e f }
 861 \new Staff {
 862   \music
 863   \inversion d' d' \music
 864   \inversion d' ees' \music
 865 }
 866 @end lilypond
 867
 868 @warning{Motifs to be inverted should be expressed in absolute form
 869 or be first converted to absolute form by enclosing them in a
 870 @code{\relative} block.}
 871
 872 @seealso
 873 Notation Reference:
 874 @ref{Modal transformations},
 875 @ref{Retrograde},
 876 @ref{Transpose}.
 877
 878
 879 @node Retrograde
 880 @unnumberedsubsubsec Retrograde
 881
 882 @cindex retrograde transformation
 883 @cindex transformation, retrograde
 884 @cindex operation, retrograde
 885 @funindex \retrograde
 886 @funindex retrograde
 887
 888 A music expression can be reversed to produce its retrograde:
 889
 890 @lilypond[verbatim,quote]
 891 music = \relative c' { c8. ees16( fis8. a16 b8.) gis16 f8. d16 }
 892
 893 \new Staff {
 894   \music
 895   \retrograde \music
 896 }
 897 @end lilypond
 898
 899 @knownissues
 900 Manual ties inside @code{\retrograde} will be broken and
 901 generate warnings.  Some ties can be generated automatically
 902 by enabling @ref{Automatic note splitting}.
 903
 904 @seealso
 905 Notation Reference:
 906 @ref{Inversion},
 907 @ref{Modal transformations},
 908 @ref{Transpose}.
 909
 910
 911 @node Modal transformations
 912 @unnumberedsubsubsec Modal transformations
 913
 914 @cindex modal transformations
 915 @cindex transformations, modal
 916 @cindex operations, modal
 917
 918 In a musical composition that is based on a scale, a motif is
 919 frequently transformed in various ways.  It may be
 920 @notation{transposed} to start at different places in the scale or
 921 it may be @notation{inverted} around a pivot point in the scale.
 922 It may also be reversed to produce its @notation{retrograde}, see
 923 @ref{Retrograde}.
 924
 925 @warning{Any note that does not lie within the given scale will be
 926 left untransformed.}
 927
 928 @subsubsubheading Modal transposition
 929
 930 @cindex modal transposition
 931 @cindex transposition, modal
 932 @cindex operation, transposition
 933 @funindex \modalTranspose
 934 @funindex modalTranspose
 935
 936 A motif can be transposed within a given scale with:
 937
 938 @example
 939 \modalTranspose @var{from-pitch} @var{to-pitch} @var{scale} @var{motif}
 940 @end example
 941
 942 The notes of @var{motif} are shifted within the @var{scale} by the
 943 number of scale degrees given by the interval between @var{to-pitch}
 944 and @var{from-pitch}:
 945
 946 @lilypond[verbatim,quote]
 947 diatonicScale = \relative c' { c d e f g a b }
 948 motif = \relative c' { c8 d e f g a b c }
 949
 950 \new Staff {
 951   \motif
 952   \modalTranspose c f \diatonicScale \motif
 953   \modalTranspose c b, \diatonicScale \motif
 954 }
 955 @end lilypond
 956
 957 An ascending scale of any length and with any intervals may be
 958 specified:
 959
 960 @lilypond[verbatim,quote]
 961 pentatonicScale = \relative c' { ges aes bes des ees }
 962 motif = \relative c' { ees8 des ges,4 <ges' bes,> <ges bes,> }
 963
 964 \new Staff {
 965   \motif
 966   \modalTranspose ges ees' \pentatonicScale \motif
 967 }
 968 @end lilypond
 969
 970 When used with a chromatic scale @code{\modalTranspose} has a
 971 similar effect to @code{\transpose}, but with the ability to
 972 specify the names of the notes to be used:
 973
 974 @lilypond[verbatim,quote]
 975 chromaticScale = \relative c' { c cis d dis e f fis g gis a ais b }
 976 motif = \relative c' { c8 d e f g a b c }
 977
 978 \new Staff {
 979   \motif
 980   \transpose c f \motif
 981   \modalTranspose c f \chromaticScale \motif
 982 }
 983 @end lilypond
 984
 985 @subsubsubheading Modal inversion
 986
 987 @cindex modal inversion
 988 @cindex inversion, modal
 989 @cindex operation, modal inversion
 990 @funindex \modalInversion
 991 @funindex modalInversion
 992
 993 A motif can be inverted within a given scale around a given pivot
 994 note and transposed in a single operation with:
 995
 996 @example
 997 \modalInversion @var{around-pitch} @var{to-pitch} @var{scale} @var{motif}
 998 @end example
 999
1000 The notes of @var{motif} are placed the same number of scale degrees
1001 from the @var{around-pitch} note within the @var{scale}, but in the
1002 opposite direction, and the result is then shifted within the
1003 @var{scale} by the number of scale degrees given by the interval between
1004 @var{to-pitch} and @var{around-pitch}.
1005
1006 So to simply invert around a note in the scale use the same value for
1007 @var{around-pitch} and @var{to-pitch}:
1008
1009 @lilypond[verbatim,quote]
1010 octatonicScale = \relative c' { ees f fis gis a b c d }
1011 motif = \relative c' { c8. ees16 fis8. a16 b8. gis16 f8. d16 }
1012
1013 \new Staff {
1014   \motif
1015   \modalInversion fis' fis' \octatonicScale \motif
1016 }
1017 @end lilypond
1018
1019 To invert around a pivot between two notes in the scale, invert around
1020 one of the notes and then transpose by one scale degree.  The two notes
1021 specified can be interpreted as bracketing the pivot point:
1022
1023 @lilypond[verbatim,quote]
1024 scale = \relative c' { c g' }
1025 motive = \relative c' { c c g' c, }
1026
1027 \new Staff {
1028   \motive
1029   \modalInversion c' g' \scale \motive
1030 }
1031 @end lilypond
1032
1033 The combined operation of inversion and retrograde produce the
1034 retrograde-inversion:
1035
1036 @lilypond[verbatim,quote]
1037 octatonicScale = \relative c' { ees f fis gis a b c d }
1038 motif = \relative c' { c8. ees16 fis8. a16 b8. gis16 f8. d16 }
1039
1040 \new Staff {
1041   \motif
1042   \retrograde \modalInversion c' c' \octatonicScale \motif
1043 }
1044 @end lilypond
1045
1046 @seealso
1047 Notation Reference:
1048 @ref{Inversion},
1049 @ref{Retrograde},
1050 @ref{Transpose}.
1051
1052
1053 @node Displaying pitches
1054 @subsection Displaying pitches
1055
1056 This section discusses how to alter the output of pitches.
1057
1058 @menu
1059 * Clef::
1060 * Key signature::
1061 * Ottava brackets::
1062 * Instrument transpositions::
1063 * Automatic accidentals::
1064 * Ambitus::
1065 @end menu
1066
1067
1068 @node Clef
1069 @unnumberedsubsubsec Clef
1070
1071 @cindex G clef
1072 @cindex C clef
1073 @cindex F clef
1074 @cindex treble clef
1075 @cindex violin clef
1076 @cindex alto clef
1077 @cindex tenor clef
1078 @cindex bass clef
1079 @cindex french clef
1080 @cindex soprano clef
1081 @cindex mezzosoprano clef
1082 @cindex baritone clef
1083 @cindex varbaritone clef
1084 @cindex subbass clef
1085 @cindex clef
1086 @cindex ancient clef
1087 @cindex clef, ancient
1088 @cindex clef, G
1089 @cindex clef, C
1090 @cindex clef, F
1091 @cindex clef, treble
1092 @cindex clef, violin
1093 @cindex clef, alto
1094 @cindex clef, tenor
1095 @cindex clef, bass
1096 @cindex clef, french
1097 @cindex clef, soprano
1098 @cindex clef, mezzosoprano
1099 @cindex clef, baritone
1100 @cindex clef, varbaritone
1101 @cindex clef, subbass
1102
1103
1104 @funindex \clef
1105 @funindex clef
1106
1107 The clef may be altered.  Middle C is shown in every example.  The
1108 following clef names can (but do not need to) be enclosed in quotes.
1109
1110 @lilypond[verbatim,quote,relative=1]
1111 \clef treble
1112 c2 c
1113 \clef alto
1114 c2 c
1115 \clef tenor
1116 c2 c
1117 \clef bass
1118 c2 c
1119 @end lilypond
1120
1121 Other clefs include:
1122
1123 @lilypond[verbatim,quote,relative=1]
1124 \clef french
1125 c2 c
1126 \clef soprano
1127 c2 c
1128 \clef mezzosoprano
1129 c2 c
1130 \clef baritone
1131 c2 c
1132
1133 \break
1134
1135 \clef varbaritone
1136 c2 c
1137 \clef subbass
1138 c2 c
1139 \clef percussion
1140 c2 c
1141
1142 \break
1143
1144 \clef G   % synonym for treble
1145 c2 c
1146 \clef F   % synonym for bass
1147 c2 c
1148 \clef C   % synonym for alto
1149 c2 c
1150 @end lilypond
1151
1152 @cindex transposing clef
1153 @cindex clef, transposing
1154 @cindex octave transposition
1155 @cindex optional octave transposition
1156 @cindex octave transposition, optional
1157 @cindex choral tenor clef
1158 @cindex tenor clef, choral
1159
1160 By adding@tie{}@code{_8} or@tie{}@code{^8} to the clef name, the
1161 clef is transposed one octave down or up respectively,
1162 and@tie{}@code{_15} and@tie{}@code{^15} transpose by two octaves.
1163 Other integers can be used if required.  Clef names containing
1164 non-alphabetic characters must be enclosed in quotes
1165
1166 @lilypond[verbatim,quote,relative=1]
1167 \clef treble
1168 c2 c
1169 \clef "treble_8"
1170 c2 c
1171 \clef "bass^15"
1172 c2 c
1173 \clef "alto_2"
1174 c2 c
1175 \clef "G_8"
1176 c2 c
1177 \clef "F^5"
1178 c2 c
1179 @end lilypond
1180
1181 Optional octavation can be obtained by enclosing the numeric
1182 argument in parentheses or brackets:
1183
1184 @lilypond[verbatim,quote,relative=1]
1185 \clef "treble_(8)"
1186 c2 c
1187 \clef "bass^[15]"
1188 c2 c
1189 @end lilypond
1190
1191 The pitches are displayed as if the numeric argument were
1192 given without parentheses/brackets.
1193
1194 Some special purpose clefs are described in @ref{Mensural clefs},
1195 @ref{Gregorian clefs}, @ref{Default tablatures}, and @ref{Custom
1196 tablatures}.  For mixing different clefs when using cue notes within a
1197 score, see the @code{\cueClef} and @code{\cueDuringWithClef} functions
1198 in @ref{Formatting cue notes}.
1199
1200 @snippets
1201
1202 @lilypondfile[verbatim,quote,texidoc,doctitle]
1203 {tweaking-clef-properties.ly}
1204
1205 @seealso
1206 Notation Reference:
1207 @ref{Mensural clefs},
1208 @ref{Gregorian clefs},
1209 @ref{Default tablatures},
1210 @ref{Custom tablatures},
1211 @ref{Formatting cue notes}.
1212
1213 Snippets:
1214 @rlsr{Pitches}.
1215
1216 Internals Reference:
1217 @rinternals{Clef_engraver},
1218 @rinternals{Clef},
1219 @rinternals{ClefModifier},
1220 @rinternals{clef-interface}.
1221
1222 @knownissues
1223 Ottavation numbers attached to clefs are treated as separate grobs.  So
1224 any @code{\override} done to the @var{Clef} will also need to be
1225 applied, as a separate @code{\override}, to the @var{ClefModifier}
1226 grob.
1227
1228 @lilypond[fragment,quote,verbatim,relative=1]
1229 \new Staff \with {
1230   \override Clef.color = #blue
1231   \override ClefModifier.color = #red
1232 }
1233
1234 \clef "treble_8" c4
1235 @end lilypond
1236
1237
1238 @node Key signature
1239 @unnumberedsubsubsec Key signature
1240
1241 @cindex key signature
1242
1243 @funindex \key
1244 @funindex key
1245
1246 @c duplicated in Key signature and Accidentals
1247 @warning{New users are sometimes confused about accidentals and
1248 key signatures.  In LilyPond, note names are the raw input; key
1249 signatures and clefs determine how this raw input is displayed.
1250 An unaltered note like@tie{}@code{c} means @q{C natural},
1251 regardless of the key signature or clef.  For more information,
1252 see @rlearning{Accidentals and key signatures}.}
1253
1254 The key signature indicates the tonality in which a piece is
1255 played.  It is denoted by a set of alterations (flats or sharps)
1256 at the start of the staff.  The key signature may be altered:
1257
1258 @example
1259 \key @var{pitch} @var{mode}
1260 @end example
1261
1262 @funindex \major
1263 @funindex major
1264 @funindex \minor
1265 @funindex minor
1266 @funindex \ionian
1267 @funindex ionian
1268 @funindex \locrian
1269 @funindex locrian
1270 @funindex \aeolian
1271 @funindex aeolian
1272 @funindex \mixolydian
1273 @funindex mixolydian
1274 @funindex \lydian
1275 @funindex lydian
1276 @funindex \phrygian
1277 @funindex phrygian
1278 @funindex \dorian
1279 @funindex dorian
1280
1281 @cindex church modes
1282 @cindex modes
1283 @cindex major
1284 @cindex minor
1285 @cindex ionian
1286 @cindex locrian
1287 @cindex aeolian
1288 @cindex mixolydian
1289 @cindex lydian
1290 @cindex phrygian
1291 @cindex dorian
1292
1293 @noindent
1294 Here, @code{@var{mode}} should be @code{\major} or @code{\minor}
1295 to get a key signature of @code{@var{pitch}}-major or
1296 @code{@var{pitch}}-minor, respectively.  You may also use the
1297 standard mode names, also called @notation{church modes}:
1298 @code{\ionian}, @code{\dorian}, @code{\phrygian}, @code{\lydian},
1299 @code{\mixolydian}, @code{\aeolian}, and @code{\locrian}.
1300
1301 @lilypond[verbatim,quote,relative=2]
1302 \key g \major
1303 fis1
1304 f
1305 fis
1306 @end lilypond
1307
1308 Additional modes can be defined, by listing the alterations
1309 for each scale step when the mode starts on C.
1310
1311 @lilypond[verbatim,quote]
1312 freygish = #`((0 . ,NATURAL) (1 . ,FLAT) (2 . ,NATURAL)
1313     (3 . ,NATURAL) (4 . ,NATURAL) (5 . ,FLAT) (6 . ,FLAT))
1314
1315 \relative c' {
1316   \key c \freygish c4 des e f
1317   \bar "||" \key d \freygish d es fis g
1318 }
1319 @end lilypond
1320
1321 Accidentals in the key signature may be printed in octaves other
1322 than their traditional positions, or in multiple octaves, by
1323 using the @code{flat-positions} and @code{sharp-positions}
1324 properties of @code{KeySignature}.  Entries in these properties
1325 specify the range of staff-positions where accidentals will be
1326 printed.  If a single position is specified in an entry, the
1327 accidentals are placed within the octave ending at that staff
1328 position.
1329
1330 @lilypond[verbatim, quote,relative=0]
1331 \override Staff.KeySignature.flat-positions = #'((-5 . 5))
1332 \override Staff.KeyCancellation.flat-positions = #'((-5 . 5))
1333 \clef bass \key es \major es g bes d
1334 \clef treble \bar "||" \key es \major es g bes d
1335
1336 \override Staff.KeySignature.sharp-positions = #'(2)
1337 \bar "||" \key b \major b fis b2
1338 @end lilypond
1339
1340 @snippets
1341
1342 @lilypondfile[verbatim,quote,texidoc,doctitle]
1343 {preventing-natural-signs-from-being-printed-when-the-key-signature-changes.ly}
1344
1345 @lilypondfile[verbatim,quote,texidoc,doctitle]
1346 {non-traditional-key-signatures.ly}
1347
1348 @seealso
1349 Music Glossary:
1350 @rglos{church mode},
1351 @rglos{scordatura}.
1352
1353 Learning Manual:
1354 @rlearning{Accidentals and key signatures}.
1355
1356 Snippets:
1357 @rlsr{Pitches}.
1358
1359 Internals Reference:
1360 @rinternals{KeyChangeEvent},
1361 @rinternals{Key_engraver},
1362 @rinternals{Key_performer},
1363 @rinternals{KeyCancellation},
1364 @rinternals{KeySignature},
1365 @rinternals{key-signature-interface}.
1366
1367
1368 @node Ottava brackets
1369 @unnumberedsubsubsec Ottava brackets
1370
1371 @cindex ottava
1372 @cindex 15ma
1373 @cindex 8va
1374 @cindex 8ve
1375 @cindex octavation
1376
1377 @funindex set-octavation
1378 @funindex \ottava
1379 @funindex ottava
1380
1381 @notation{Ottava brackets} introduce an extra transposition of an
1382 octave for the staff:
1383
1384 @lilypond[verbatim,quote,relative=2]
1385 a2 b
1386 \ottava #-2
1387 a2 b
1388 \ottava #-1
1389 a2 b
1390 \ottava #0
1391 a2 b
1392 \ottava #1
1393 a2 b
1394 \ottava #2
1395 a2 b
1396 @end lilypond
1397
1398 @snippets
1399
1400 @lilypondfile[verbatim,quote,texidoc,doctitle]
1401 {ottava-text.ly}
1402
1403 @lilypondfile[verbatim,quote,texidoc,doctitle]
1404 {adding-an-ottava-marking-to-a-single-voice.ly}
1405
1406 @seealso
1407 Music Glossary:
1408 @rglos{octavation}.
1409
1410 Snippets:
1411 @rlsr{Pitches}.
1412
1413 Internals Reference:
1414 @rinternals{Ottava_spanner_engraver},
1415 @rinternals{OttavaBracket},
1416 @rinternals{ottava-bracket-interface}.
1417
1418
1419 @node Instrument transpositions
1420 @unnumberedsubsubsec Instrument transpositions
1421
1422 @cindex transposition, MIDI
1423 @cindex transposition, instrument
1424 @cindex transposing instrument
1425 @cindex MIDI
1426 @cindex MIDI transposition
1427
1428 @funindex \transposition
1429 @funindex transposition
1430
1431 When typesetting scores that involve transposing instruments, some
1432 parts can be typeset in a different pitch than the
1433 @notation{concert pitch}.  In these cases, the key of the
1434 @notation{transposing instrument} should be specified; otherwise
1435 the MIDI output and cues in other parts will produce incorrect
1436 pitches.  For more information about quotations, see
1437 @ref{Quoting other voices}.
1438
1439 @example
1440 \transposition @var{pitch}
1441 @end example
1442
1443 The pitch to use for @code{\transposition} should correspond to
1444 the real sound heard when a@tie{}@code{c'} written on the staff is
1445 played by the transposing instrument.  This pitch is entered in
1446 absolute mode, so an instrument that produces a real sound which
1447 is one tone higher than the printed music should use
1448 @w{@code{\transposition d'}}.  @code{\transposition} should
1449 @emph{only} be used if the pitches are @emph{not} being entered in
1450 concert pitch.
1451
1452 Here are a few notes for violin and B-flat clarinet where the
1453 parts have been entered using the notes and key as they appear in
1454 each part of the conductor's score.  The two instruments are
1455 playing in unison.
1456
1457 @lilypond[verbatim,quote]
1458 \new GrandStaff <<
1459   \new Staff = "violin" {
1460     \relative c'' {
1461       \set Staff.instrumentName = #"Vln"
1462       \set Staff.midiInstrument = #"violin"
1463       % not strictly necessary, but a good reminder
1464       \transposition c'
1465
1466       \key c \major
1467       g4( c8) r c r c4
1468     }
1469   }
1470   \new Staff = "clarinet" {
1471     \relative c'' {
1472       \set Staff.instrumentName = \markup { Cl (B\flat) }
1473       \set Staff.midiInstrument = #"clarinet"
1474       \transposition bes
1475
1476       \key d \major
1477       a4( d8) r d r d4
1478     }
1479   }
1480 >>
1481 @end lilypond
1482
1483 The @code{\transposition} may be changed during a piece.  For
1484 example, a clarinetist may be required to switch from an A clarinet
1485 to a B-flat clarinet.
1486
1487 @lilypond[verbatim,quote]
1488 flute = \relative c'' {
1489   \key f \major
1490   \cueDuring #"clarinet" #DOWN {
1491     R1 _\markup\tiny "clarinet"
1492     c4 f e d
1493     R1 _\markup\tiny "clarinet"
1494   }
1495 }
1496 clarinet = \relative c'' {
1497   \key aes \major
1498   \transposition a
1499   aes4 bes c des
1500   R1^\markup { muta in B\flat }
1501   \key g \major
1502   \transposition bes
1503   d2 g,
1504 }
1505 \addQuote "clarinet" \clarinet
1506 <<
1507   \new Staff \with { instrumentName = #"Flute" }
1508     \flute
1509   \new Staff \with { instrumentName = #"Cl (A)" }
1510     \clarinet
1511 >>
1512 @end lilypond
1513
1514 @seealso
1515 Music Glossary:
1516 @rglos{concert pitch},
1517 @rglos{transposing instrument}.
1518
1519 Notation Reference:
1520 @ref{Quoting other voices},
1521 @ref{Transpose}.
1522
1523 Snippets:
1524 @rlsr{Pitches}.
1525
1526
1527 @node Automatic accidentals
1528 @unnumberedsubsubsec Automatic accidentals
1529
1530 @cindex accidental style
1531 @cindex accidental style, default
1532 @cindex accidentals
1533 @cindex accidentals, automatic
1534 @cindex automatic accidentals
1535 @cindex default accidental style
1536
1537 @funindex \accidentalStyle
1538 @funindex voice
1539 @funindex default
1540
1541 There are many different conventions on how to typeset
1542 accidentals.  LilyPond provides a function to specify which
1543 accidental style to use.  This function is called as follows:
1544
1545 @example
1546 \new Staff <<
1547   \accidentalStyle voice
1548   @{ @dots{} @}
1549 >>
1550 @end example
1551
1552 The accidental style applies to the current @code{Staff} by
1553 default (with the exception of the styles @code{piano} and
1554 @code{piano-cautionary}, which are explained below).  Optionally,
1555 the function can take a second argument that determines in which
1556 scope the style should be changed.  For example, to use the same
1557 style in all staves of the current @code{StaffGroup}, use:
1558
1559 @example
1560 \accidentalStyle StaffGroup.voice
1561 @end example
1562
1563 The following accidental styles are supported.  To demonstrate
1564 each style, we use the following example:
1565
1566
1567 @lilypond[verbatim,quote]
1568 musicA = {
1569   <<
1570     \relative c' {
1571       cis'8 fis, bes4 <a cis>8 f bis4 |
1572       cis2. <c, g'>4 |
1573     }
1574     \\
1575     \relative c' {
1576       ais'2 cis, |
1577       fis8 b a4 cis2 |
1578     }
1579   >>
1580 }
1581
1582 musicB = {
1583   \clef bass
1584   \new Voice {
1585     \voiceTwo \relative c' {
1586       <fis, a cis>8[ <fis a cis>
1587       \change Staff = up
1588       cis' cis
1589       \change Staff = down
1590       <fis, a> <fis a>]
1591       \showStaffSwitch
1592       \change Staff = up
1593       dis'4 |
1594       \change Staff = down
1595       <fis, a cis>4 gis <f a d>2 |
1596     }
1597   }
1598 }
1599
1600 \new PianoStaff {
1601   <<
1602     \context Staff = "up" {
1603       \accidentalStyle default
1604       \musicA
1605     }
1606     \context Staff = "down" {
1607       \accidentalStyle default
1608       \musicB
1609     }
1610   >>
1611 }
1612 @end lilypond
1613
1614 Note that the last lines of this example can be replaced by the
1615 following, as long as the same accidental style should be used in
1616 both staves.
1617
1618 @example
1619 \new PianoStaff @{
1620   <<
1621     \context Staff = "up" @{
1622       %%% change the next line as desired:
1623       \accidentalStyle Score.default
1624       \musicA
1625     @}
1626     \context Staff = "down" @{
1627       \musicB
1628     @}
1629   >>
1630 @}
1631 @end example
1632
1633
1634 @c don't use verbatim in this table.
1635 @table @code
1636 @item default
1637
1638 @cindex default accidental style
1639 @cindex accidental style, default
1640
1641 @funindex default
1642
1643 This is the default typesetting behavior.  It corresponds to
1644 eighteenth-century common practice: accidentals are remembered to
1645 the end of the measure in which they occur and only in their own
1646 octave.  Thus, in the example below, no natural signs are printed
1647 before the@tie{}@code{b} in the second measure or the
1648 last@tie{}@code{c}:
1649
1650 @lilypond[quote]
1651 musicA = {
1652   <<
1653     \relative c' {
1654       cis'8 fis, bes4 <a cis>8 f bis4 |
1655       cis2. <c, g'>4 |
1656     }
1657     \\
1658     \relative c' {
1659       ais'2 cis, |
1660       fis8 b a4 cis2 |
1661     }
1662   >>
1663 }
1664
1665 musicB = {
1666   \clef bass
1667   \new Voice {
1668     \voiceTwo \relative c' {
1669       <fis, a cis>8[ <fis a cis>
1670       \change Staff = up
1671       cis' cis
1672       \change Staff = down
1673       <fis, a> <fis a>]
1674       \showStaffSwitch
1675       \change Staff = up
1676       dis'4 |
1677       \change Staff = down
1678       <fis, a cis>4 gis <f a d>2 |
1679     }
1680   }
1681 }
1682
1683 \new PianoStaff {
1684   <<
1685     \context Staff = "up" {
1686       \accidentalStyle default
1687       \musicA
1688     }
1689     \context Staff = "down" {
1690       \accidentalStyle default
1691       \musicB
1692     }
1693   >>
1694 }
1695 @end lilypond
1696
1697 @item voice
1698
1699 @cindex accidental style, voice
1700 @cindex voice accidental style
1701 @cindex accidental style, modern
1702 @cindex modern accidental style
1703 @cindex accidental style, modern-cautionary
1704 @cindex modern-cautionary accidental style
1705
1706 @funindex voice
1707
1708 The normal behavior is to remember the accidentals at
1709 @code{Staff}-level.  In this style, however, accidentals are
1710 typeset individually for each voice.  Apart from that, the rule is
1711 similar to @code{default}.
1712
1713 As a result, accidentals from one voice do not get canceled in
1714 other voices, which is often an unwanted result: in the following
1715 example, it is hard to determine whether the second@tie{}@code{a}
1716 should be played natural or sharp.  The @code{voice} option should
1717 therefore be used only if the voices are to be read solely by
1718 individual musicians.  If the staff is to be used by one musician
1719 (e.g., a conductor or in a piano score) then @code{modern} or
1720 @code{modern-cautionary} should be used instead.
1721
1722
1723 @lilypond[quote]
1724 musicA = {
1725   <<
1726     \relative c' {
1727       cis'8 fis, bes4 <a cis>8 f bis4 |
1728       cis2. <c, g'>4 |
1729     }
1730     \\
1731     \relative c' {
1732       ais'2 cis, |
1733       fis8 b a4 cis2 |
1734     }
1735   >>
1736 }
1737
1738 musicB = {
1739   \clef bass
1740   \new Voice {
1741     \voiceTwo \relative c' {
1742       <fis, a cis>8[ <fis a cis>
1743       \change Staff = up
1744       cis' cis
1745       \change Staff = down
1746       <fis, a> <fis a>]
1747       \showStaffSwitch
1748       \change Staff = up
1749       dis'4 |
1750       \change Staff = down
1751       <fis, a cis>4 gis <f a d>2 |
1752     }
1753   }
1754 }
1755
1756 \new PianoStaff {
1757   <<
1758     \context Staff = "up" {
1759       \accidentalStyle voice
1760       \musicA
1761     }
1762     \context Staff = "down" {
1763       \accidentalStyle voice
1764       \musicB
1765     }
1766   >>
1767 }
1768 @end lilypond
1769
1770 @item modern
1771
1772 @cindex accidentals, modern style
1773 @cindex modern style accidentals
1774
1775 @funindex modern
1776
1777 This rule corresponds to the common practice in the twentieth
1778 century.  It omits some extra natural signs, which were
1779 traditionally prefixed to a sharp following a double sharp,
1780 or a flat following a double flat.  The @code{modern} rule
1781 prints the same accidentals as @code{default}, with
1782 two additions that serve to avoid ambiguity: after temporary
1783 accidentals, cancellation marks are printed also in the following
1784 measure (for notes in the same octave) and, in the same measure,
1785 for notes in other octaves.  Hence the naturals before
1786 the@tie{}@code{b} and the@tie{}@code{c} in the second measure of
1787 the upper staff:
1788
1789 @lilypond[quote]
1790 musicA = {
1791   <<
1792     \relative c' {
1793       cis'8 fis, bes4 <a cis>8 f bis4 |
1794       cis2. <c, g'>4 |
1795     }
1796     \\
1797     \relative c' {
1798       ais'2 cis, |
1799       fis8 b a4 cis2 |
1800     }
1801   >>
1802 }
1803
1804 musicB = {
1805   \clef bass
1806   \new Voice {
1807     \voiceTwo \relative c' {
1808       <fis, a cis>8[ <fis a cis>
1809       \change Staff = up
1810       cis' cis
1811       \change Staff = down
1812       <fis, a> <fis a>]
1813       \showStaffSwitch
1814       \change Staff = up
1815       dis'4 |
1816       \change Staff = down
1817       <fis, a cis>4 gis <f a d>2 |
1818     }
1819   }
1820 }
1821
1822 \new PianoStaff {
1823   <<
1824     \context Staff = "up" {
1825       \accidentalStyle modern
1826       \musicA
1827     }
1828     \context Staff = "down" {
1829       \accidentalStyle modern
1830       \musicB
1831     }
1832   >>
1833 }
1834 @end lilypond
1835
1836 @item modern-cautionary
1837
1838 @cindex accidentals, modern cautionary style
1839 @cindex modern accidental style
1840 @cindex modern cautionary accidental style
1841 @cindex modern style accidentals
1842 @cindex modern style cautionary accidentals
1843
1844 @funindex modern-cautionary
1845
1846 This rule is similar to @code{modern}, but the @q{extra}
1847 accidentals (the ones not typeset by @code{default}) are typeset
1848 as cautionary accidentals.  They are by default printed with
1849 parentheses, but they can also be printed in reduced size by
1850 defining the @code{cautionary-style} property of
1851 @code{AccidentalSuggestion}.
1852
1853 @lilypond[quote]
1854 musicA = {
1855   <<
1856     \relative c' {
1857       cis'8 fis, bes4 <a cis>8 f bis4 |
1858       cis2. <c, g'>4 |
1859     }
1860     \\
1861     \relative c' {
1862       ais'2 cis, |
1863       fis8 b a4 cis2 |
1864     }
1865   >>
1866 }
1867
1868 musicB = {
1869   \clef bass
1870   \new Voice {
1871     \voiceTwo \relative c' {
1872       <fis, a cis>8[ <fis a cis>
1873       \change Staff = up
1874       cis' cis
1875       \change Staff = down
1876       <fis, a> <fis a>]
1877       \showStaffSwitch
1878       \change Staff = up
1879       dis'4 |
1880       \change Staff = down
1881       <fis, a cis>4 gis <f a d>2 |
1882     }
1883   }
1884 }
1885
1886 \new PianoStaff {
1887   <<
1888     \context Staff = "up" {
1889       \accidentalStyle modern-cautionary
1890       \musicA
1891     }
1892     \context Staff = "down" {
1893       \accidentalStyle modern-cautionary
1894       \musicB
1895     }
1896   >>
1897 }
1898 @end lilypond
1899
1900 @item modern-voice
1901
1902 @cindex accidental style, modern
1903 @cindex accidentals, modern
1904 @cindex accidentals, multivoice
1905 @cindex modern accidental style
1906 @cindex modern accidentals
1907 @cindex multivoice accidentals
1908
1909 @funindex modern-voice
1910
1911 This rule is used for multivoice accidentals to be read both by
1912 musicians playing one voice and musicians playing all voices.
1913 Accidentals are typeset for each voice, but they @emph{are}
1914 canceled across voices in the same @code{Staff}.  Hence,
1915 the@tie{}@code{a} in the last measure is canceled because the
1916 previous cancellation was in a different voice, and
1917 the@tie{}@code{d} in the lower staff is canceled because of the
1918 accidental in a different voice in the previous measure:
1919
1920 @lilypond[quote]
1921 musicA = {
1922   <<
1923     \relative c' {
1924       cis'8 fis, bes4 <a cis>8 f bis4 |
1925       cis2. <c, g'>4 |
1926     }
1927     \\
1928     \relative c' {
1929       ais'2 cis, |
1930       fis8 b a4 cis2 |
1931     }
1932   >>
1933 }
1934
1935 musicB = {
1936   \clef bass
1937   \new Voice {
1938     \voiceTwo \relative c' {
1939       <fis, a cis>8[ <fis a cis>
1940       \change Staff = up
1941       cis' cis
1942       \change Staff = down
1943       <fis, a> <fis a>]
1944       \showStaffSwitch
1945       \change Staff = up
1946       dis'4 |
1947       \change Staff = down
1948       <fis, a cis>4 gis <f a d>2 |
1949     }
1950   }
1951 }
1952
1953 \new PianoStaff {
1954   <<
1955     \context Staff = "up" {
1956       \accidentalStyle modern-voice
1957       \musicA
1958     }
1959     \context Staff = "down" {
1960       \accidentalStyle modern-voice
1961       \musicB
1962     }
1963   >>
1964 }
1965 @end lilypond
1966
1967 @cindex accidental style, cautionary, modern voice
1968 @cindex accidental style, modern voice cautionary
1969 @cindex accidental style, voice, modern cautionary
1970
1971 @funindex modern-voice-cautionary
1972
1973 @item modern-voice-cautionary
1974
1975 This rule is the same as @code{modern-voice}, but with the extra
1976 accidentals (the ones not typeset by @code{voice}) typeset as
1977 cautionaries.  Even though all accidentals typeset by
1978 @code{default} @emph{are} typeset with this rule, some of them are
1979 typeset as cautionaries.
1980
1981 @lilypond[quote]
1982 musicA = {
1983   <<
1984     \relative c' {
1985       cis'8 fis, bes4 <a cis>8 f bis4 |
1986       cis2. <c, g'>4 |
1987     }
1988     \\
1989     \relative c' {
1990       ais'2 cis, |
1991       fis8 b a4 cis2 |
1992     }
1993   >>
1994 }
1995
1996 musicB = {
1997   \clef bass
1998   \new Voice {
1999     \voiceTwo \relative c' {
2000       <fis, a cis>8[ <fis a cis>
2001       \change Staff = up
2002       cis' cis
2003       \change Staff = down
2004       <fis, a> <fis a>]
2005       \showStaffSwitch
2006       \change Staff = up
2007       dis'4 |
2008       \change Staff = down
2009       <fis, a cis>4 gis <f a d>2 |
2010     }
2011   }
2012 }
2013
2014 \new PianoStaff {
2015   <<
2016     \context Staff = "up" {
2017       \accidentalStyle modern-voice-cautionary
2018       \musicA
2019     }
2020     \context Staff = "down" {
2021       \accidentalStyle modern-voice-cautionary
2022       \musicB
2023     }
2024   >>
2025 }
2026 @end lilypond
2027
2028 @item piano
2029
2030 @cindex accidental style, piano
2031 @cindex accidentals, piano
2032 @cindex piano accidental style
2033 @cindex piano accidentals
2034
2035 @funindex piano
2036
2037 This rule reflects twentieth-century practice for piano notation.
2038 Its behavior is very similar to @code{modern} style, but here
2039 accidentals also get canceled across the staves in the same
2040 @code{GrandStaff} or @code{PianoStaff}, hence all the
2041 cancellations of the final notes.
2042
2043 This accidental style applies to the current @code{GrandStaff} or
2044 @code{PianoStaff} by default.
2045
2046 @lilypond[quote]
2047 musicA = {
2048   <<
2049     \relative c' {
2050       cis'8 fis, bes4 <a cis>8 f bis4 |
2051       cis2. <c, g'>4 |
2052     }
2053     \\
2054     \relative c' {
2055       ais'2 cis, |
2056       fis8 b a4 cis2 |
2057     }
2058   >>
2059 }
2060
2061 musicB = {
2062   \clef bass
2063   \new Voice {
2064     \voiceTwo \relative c' {
2065       <fis, a cis>8[ <fis a cis>
2066       \change Staff = up
2067       cis' cis
2068       \change Staff = down
2069       <fis, a> <fis a>]
2070       \showStaffSwitch
2071       \change Staff = up
2072       dis'4 |
2073       \change Staff = down
2074       <fis, a cis>4 gis <f a d>2 |
2075     }
2076   }
2077 }
2078
2079 \new PianoStaff {
2080   <<
2081     \context Staff = "up" {
2082       \accidentalStyle piano
2083       \musicA
2084     }
2085     \context Staff = "down" {
2086       \musicB
2087     }
2088   >>
2089 }
2090 @end lilypond
2091
2092 @item piano-cautionary
2093
2094 @cindex accidentals, piano cautionary
2095 @cindex cautionary accidentals, piano
2096 @cindex piano cautionary accidentals
2097 @cindex accidental style, piano cautionary
2098 @cindex cautionary accidental style, piano
2099 @cindex piano cautionary accidental style
2100
2101 @funindex piano-cautionary
2102
2103 This is the same as @code{piano} but with the extra accidentals
2104 typeset as cautionaries.
2105
2106 @lilypond[quote]
2107 musicA = {
2108   <<
2109     \relative c' {
2110       cis'8 fis, bes4 <a cis>8 f bis4 |
2111       cis2. <c, g'>4 |
2112     }
2113     \\
2114     \relative c' {
2115       ais'2 cis, |
2116       fis8 b a4 cis2 |
2117     }
2118   >>
2119 }
2120
2121 musicB = {
2122   \clef bass
2123   \new Voice {
2124     \voiceTwo \relative c' {
2125       <fis, a cis>8[ <fis a cis>
2126       \change Staff = up
2127       cis' cis
2128       \change Staff = down
2129       <fis, a> <fis a>]
2130       \showStaffSwitch
2131       \change Staff = up
2132       dis'4 |
2133       \change Staff = down
2134       <fis, a cis>4 gis <f a d>2 |
2135     }
2136   }
2137 }
2138
2139 \new PianoStaff {
2140   <<
2141     \context Staff = "up" {
2142       \accidentalStyle piano-cautionary
2143       \musicA
2144     }
2145     \context Staff = "down" {
2146       \musicB
2147     }
2148   >>
2149 }
2150 @end lilypond
2151
2152
2153 @item neo-modern
2154
2155 @cindex neo-modern accidental style
2156 @cindex accidental style, neo-modern
2157
2158 @funindex neo-modern
2159
2160 This rule reproduces a common practice in contemporary music:
2161 accidentals are printed like with @code{modern}, but they are printed
2162 again if the same note appears later in the same measure -- except
2163 if the note is immediately repeated.
2164
2165 @lilypond[quote]
2166 musicA = {
2167   <<
2168     \relative c' {
2169       cis'8 fis, bes4 <a cis>8 f bis4 |
2170       cis2. <c, g'>4 |
2171     }
2172     \\
2173     \relative c' {
2174       ais'2 cis, |
2175       fis8 b a4 cis2 |
2176     }
2177   >>
2178 }
2179
2180 musicB = {
2181   \clef bass
2182   \new Voice {
2183     \voiceTwo \relative c' {
2184       <fis, a cis>8[ <fis a cis>
2185       \change Staff = up
2186       cis' cis
2187       \change Staff = down
2188       <fis, a> <fis a>]
2189       \showStaffSwitch
2190       \change Staff = up
2191       dis'4 |
2192       \change Staff = down
2193       <fis, a cis>4 gis <f a d>2 |
2194     }
2195   }
2196 }
2197
2198 \new PianoStaff {
2199   <<
2200     \context Staff = "up" {
2201       \accidentalStyle neo-modern
2202       \musicA
2203     }
2204     \context Staff = "down" {
2205       \accidentalStyle neo-modern
2206       \musicB
2207     }
2208   >>
2209 }
2210 @end lilypond
2211
2212 @item neo-modern-cautionary
2213
2214 @cindex neo-modern-cautionary accidental style
2215 @cindex accidental style, neo-modern-cautionary
2216
2217 @funindex neo-modern-cautionary
2218
2219 This rule is similar to @code{neo-modern}, but the extra
2220 accidentals are printed as cautionary accidentals.
2221
2222 @lilypond[quote]
2223 musicA = {
2224   <<
2225     \relative c' {
2226       cis'8 fis, bes4 <a cis>8 f bis4 |
2227       cis2. <c, g'>4 |
2228     }
2229     \\
2230     \relative c' {
2231       ais'2 cis, |
2232       fis8 b a4 cis2 |
2233     }
2234   >>
2235 }
2236
2237 musicB = {
2238   \clef bass
2239   \new Voice {
2240     \voiceTwo \relative c' {
2241       <fis, a cis>8[ <fis a cis>
2242       \change Staff = up
2243       cis' cis
2244       \change Staff = down
2245       <fis, a> <fis a>]
2246       \showStaffSwitch
2247       \change Staff = up
2248       dis'4 |
2249       \change Staff = down
2250       <fis, a cis>4 gis <f a d>2 |
2251     }
2252   }
2253 }
2254
2255 \new PianoStaff {
2256   <<
2257     \context Staff = "up" {
2258       \accidentalStyle neo-modern-cautionary
2259       \musicA
2260     }
2261     \context Staff = "down" {
2262       \accidentalStyle neo-modern-cautionary
2263       \musicB
2264     }
2265   >>
2266 }
2267 @end lilypond
2268
2269
2270 @item neo-modern-voice
2271
2272 @cindex neo-modern-voice accidental style
2273 @cindex accidental style, neo-modern-voice
2274
2275 @funindex neo-modern-voice
2276
2277 This rule is used for multivoice accidentals to be read both by
2278 musicians playing one voice and musicians playing all voices.
2279 Accidentals are typeset for each voice as with @code{neo-modern},
2280 but they are canceled across voices in the same @code{Staff}.
2281
2282 @lilypond[quote]
2283 musicA = {
2284   <<
2285     \relative c' {
2286       cis'8 fis, bes4 <a cis>8 f bis4 |
2287       cis2. <c, g'>4 |
2288     }
2289     \\
2290     \relative c' {
2291       ais'2 cis, |
2292       fis8 b a4 cis2 |
2293     }
2294   >>
2295 }
2296
2297 musicB = {
2298   \clef bass
2299   \new Voice {
2300     \voiceTwo \relative c' {
2301       <fis, a cis>8[ <fis a cis>
2302       \change Staff = up
2303       cis' cis
2304       \change Staff = down
2305       <fis, a> <fis a>]
2306       \showStaffSwitch
2307       \change Staff = up
2308       dis'4 |
2309       \change Staff = down
2310       <fis, a cis>4 gis <f a d>2 |
2311     }
2312   }
2313 }
2314
2315 \new PianoStaff {
2316   <<
2317     \context Staff = "up" {
2318       \accidentalStyle neo-modern-voice
2319       \musicA
2320     }
2321     \context Staff = "down" {
2322       \accidentalStyle neo-modern-voice
2323       \musicB
2324     }
2325   >>
2326 }
2327 @end lilypond
2328
2329 @item neo-modern-voice-cautionary
2330
2331 @cindex neo-modern-voice-cautionary accidental style
2332 @cindex accidental style, neo-modern-voice-cautionary
2333
2334 @funindex neo-modern-voice-cautionary
2335
2336 This rule is similar to @code{neo-modern-voice}, but the extra
2337 accidentals are printed as cautionary accidentals.
2338
2339 @lilypond[quote]
2340 musicA = {
2341   <<
2342     \relative c' {
2343       cis'8 fis, bes4 <a cis>8 f bis4 |
2344       cis2. <c, g'>4 |
2345     }
2346     \\
2347     \relative c' {
2348       ais'2 cis, |
2349       fis8 b a4 cis2 |
2350     }
2351   >>
2352 }
2353
2354 musicB = {
2355   \clef bass
2356   \new Voice {
2357     \voiceTwo \relative c' {
2358       <fis, a cis>8[ <fis a cis>
2359       \change Staff = up
2360       cis' cis
2361       \change Staff = down
2362       <fis, a> <fis a>]
2363       \showStaffSwitch
2364       \change Staff = up
2365       dis'4 |
2366       \change Staff = down
2367       <fis, a cis>4 gis <f a d>2 |
2368     }
2369   }
2370 }
2371
2372 \new PianoStaff {
2373   <<
2374     \context Staff = "up" {
2375       \accidentalStyle neo-modern-voice-cautionary
2376       \musicA
2377     }
2378     \context Staff = "down" {
2379       \accidentalStyle neo-modern-voice-cautionary
2380       \musicB
2381     }
2382   >>
2383 }
2384 @end lilypond
2385
2386 @item dodecaphonic
2387
2388 @cindex dodecaphonic accidental style
2389 @cindex dodecaphonic style, neo-modern
2390
2391 @funindex dodecaphonic
2392
2393 This rule reflects a practice introduced by composers at
2394 the beginning of the 20th century, in an attempt to
2395 abolish the hierarchy between natural and non-natural notes.
2396 With this style, @emph{every} note gets an accidental sign,
2397 including natural signs.
2398
2399 @lilypond[quote]
2400 musicA = {
2401   <<
2402     \relative c' {
2403       cis'8 fis, bes4 <a cis>8 f bis4 |
2404       cis2. <c, g'>4 |
2405     }
2406     \\
2407     \relative c' {
2408       ais'2 cis, |
2409       fis8 b a4 cis2 |
2410     }
2411   >>
2412 }
2413
2414 musicB = {
2415   \clef bass
2416   \new Voice {
2417     \voiceTwo \relative c' {
2418       <fis, a cis>8[ <fis a cis>
2419       \change Staff = up
2420       cis' cis
2421       \change Staff = down
2422       <fis, a> <fis a>]
2423       \showStaffSwitch
2424       \change Staff = up
2425       dis'4 |
2426       \change Staff = down
2427       <fis, a cis>4 gis <f a d>2 |
2428     }
2429   }
2430 }
2431
2432 \new PianoStaff {
2433   <<
2434     \context Staff = "up" {
2435       \accidentalStyle dodecaphonic
2436       \musicA
2437     }
2438     \context Staff = "down" {
2439       \accidentalStyle dodecaphonic
2440       \musicB
2441     }
2442   >>
2443 }
2444 @end lilypond
2445
2446
2447 @item teaching
2448
2449 @cindex teaching accidental style
2450 @cindex accidental style, teaching
2451
2452 @funindex teaching
2453
2454 This rule is intended for students, and makes it easy to create
2455 scale sheets with automatically created cautionary accidentals.
2456 Accidentals are printed like with @code{modern}, but cautionary
2457 accidentals are added for all sharp or flat tones specified by the
2458 key signature, except if the note is immediately repeated.
2459
2460 @lilypond[quote,staffsize=18]
2461 musicA = {
2462   <<
2463     \relative c' {
2464       cis'8 fis, bes4 <a cis>8 f bis4 |
2465       cis2. <c, g'>4 |
2466     }
2467     \\
2468     \relative c' {
2469       ais'2 cis, |
2470       fis8 b a4 cis2 |
2471     }
2472   >>
2473 }
2474
2475 musicB = {
2476   \clef bass
2477   \new Voice {
2478     \voiceTwo \relative c' {
2479       <fis, a cis>8[ <fis a cis>
2480       \change Staff = up
2481       cis' cis
2482       \change Staff = down
2483       <fis, a> <fis a>]
2484       \showStaffSwitch
2485       \change Staff = up
2486       dis'4 |
2487       \change Staff = down
2488       <fis, a cis>4 gis <f a d>2 |
2489     }
2490   }
2491 }
2492
2493 \new PianoStaff {
2494   <<
2495     \context Staff = "up" {
2496       \key fis \minor
2497       \accidentalStyle teaching
2498       \musicA
2499     }
2500     \context Staff = "down" {
2501       \key fis \minor
2502       \accidentalStyle teaching
2503       \musicB
2504     }
2505   >>
2506 }
2507 @end lilypond
2508
2509
2510
2511 @item no-reset
2512
2513 @cindex accidental style, no reset
2514 @cindex no reset accidental style
2515
2516 @funindex no-reset
2517
2518 This is the same as @code{default} but with accidentals lasting
2519 @q{forever} and not only within the same measure:
2520
2521 @lilypond[quote]
2522 musicA = {
2523   <<
2524     \relative c' {
2525       cis'8 fis, bes4 <a cis>8 f bis4 |
2526       cis2. <c, g'>4 |
2527     }
2528     \\
2529     \relative c' {
2530       ais'2 cis, |
2531       fis8 b a4 cis2 |
2532     }
2533   >>
2534 }
2535
2536 musicB = {
2537   \clef bass
2538   \new Voice {
2539     \voiceTwo \relative c' {
2540       <fis, a cis>8[ <fis a cis>
2541       \change Staff = up
2542       cis' cis
2543       \change Staff = down
2544       <fis, a> <fis a>]
2545       \showStaffSwitch
2546       \change Staff = up
2547       dis'4 |
2548       \change Staff = down
2549       <fis, a cis>4 gis <f a d>2 |
2550     }
2551   }
2552 }
2553
2554 \new PianoStaff {
2555   <<
2556     \context Staff = "up" {
2557       \accidentalStyle no-reset
2558       \musicA
2559     }
2560     \context Staff = "down" {
2561       \accidentalStyle no-reset
2562       \musicB
2563     }
2564   >>
2565 }
2566 @end lilypond
2567
2568 @item forget
2569
2570 @cindex forget accidental style
2571 @cindex accidental style, forget
2572
2573 @funindex forget
2574
2575 This is the opposite of @code{no-reset}: Accidentals are not
2576 remembered at all -- and hence all accidentals are typeset
2577 relative to the key signature, regardless of what came before in
2578 the music.
2579
2580 @lilypond[quote]
2581 musicA = {
2582   <<
2583     \relative c' {
2584       cis'8 fis, bes4 <a cis>8 f bis4 |
2585       cis2. <c, g'>4 |
2586     }
2587     \\
2588     \relative c' {
2589       ais'2 cis, |
2590       fis8 b a4 cis2 |
2591     }
2592   >>
2593 }
2594
2595 musicB = {
2596   \clef bass
2597   \new Voice {
2598     \voiceTwo \relative c' {
2599       <fis, a cis>8[ <fis a cis>
2600       \change Staff = up
2601       cis' cis
2602       \change Staff = down
2603       <fis, a> <fis a>]
2604       \showStaffSwitch
2605       \change Staff = up
2606       dis'4 |
2607       \change Staff = down
2608       <fis, a cis>4 gis <f a d>2 |
2609     }
2610   }
2611 }
2612
2613 \new PianoStaff {
2614   <<
2615     \context Staff = "up" {
2616       \accidentalStyle forget
2617       \musicA
2618     }
2619     \context Staff = "down" {
2620       \accidentalStyle forget
2621       \musicB
2622     }
2623   >>
2624 }
2625 @end lilypond
2626 @end table
2627
2628 @seealso
2629 Snippets:
2630 @rlsr{Pitches}.
2631
2632 Internals Reference:
2633 @rinternals{Accidental},
2634 @rinternals{Accidental_engraver},
2635 @rinternals{GrandStaff},
2636 @rinternals{PianoStaff},
2637 @rinternals{Staff},
2638 @rinternals{AccidentalSuggestion},
2639 @rinternals{AccidentalPlacement},
2640 @rinternals{accidental-suggestion-interface}.
2641
2642 @cindex accidentals and simultaneous notes
2643 @cindex simultaneous notes and accidentals
2644 @cindex accidentals in chords
2645 @cindex chords, accidentals in
2646
2647 @knownissues
2648 Simultaneous notes are not considered in the automatic
2649 determination of accidentals; only previous notes and the key
2650 signature are considered.  Forcing accidentals with@tie{}@code{!}
2651 or@tie{}@code{?} may be required when the same note name occurs
2652 simultaneously with different alterations, as in @samp{<f! fis!>}.
2653
2654 Cautionary cancellation of accidentals is done by looking at previous measure.
2655 However, in the @code{\alternative} block following a @code{\repeat volta N}
2656 section, one would expect the cancellation being calculated using the previous
2657 @emph{played} measure, not previous @emph{printed} measure.
2658 In the following example, the natural @code{c} in the second alternative does
2659 not need a natural sign:
2660
2661 @lilypond[quote]
2662 {
2663   \accidentalStyle modern
2664   \time 2/4
2665   \repeat volta 2 {
2666     c'2
2667   }
2668   \alternative {
2669      cis'
2670      c'
2671   }
2672 }
2673 @end lilypond
2674
2675 The following work-around can be used: define a function that locally changes
2676 the accidental style to @code{forget}:
2677
2678 @lilypond[verbatim,quote]
2679 forget = #(define-music-function (parser location music) (ly:music?) #{
2680   \accidentalStyle forget
2681   #music
2682   \accidentalStyle modern
2683 #})
2684 {
2685   \accidentalStyle modern
2686   \time 2/4
2687   \repeat volta 2 {
2688     c'2
2689   }
2690   \alternative {
2691      cis'
2692      \forget c'
2693   }
2694 }
2695 @end lilypond
2696
2697
2698 @node Ambitus
2699 @unnumberedsubsubsec Ambitus
2700
2701 @cindex ambitus
2702 @cindex range of pitches
2703 @cindex pitch range
2704
2705 The term @notation{ambitus} (pl. ambitus) denotes a range of
2706 pitches for a given voice in a part of music.  It may also denote
2707 the pitch range that a musical instrument is capable of playing.
2708 Ambitus are printed on vocal parts so that performers can easily
2709 determine if it matches their capabilities.
2710
2711 Ambitus are denoted at the beginning of a piece near the initial
2712 clef.  The range is graphically specified by two note heads that
2713 represent the lowest and highest pitches.  Accidentals are only
2714 printed if they are not part of the key signature.
2715
2716 @lilypond[verbatim,quote]
2717 \layout {
2718   \context {
2719     \Voice
2720     \consists "Ambitus_engraver"
2721   }
2722 }
2723
2724 \relative c'' {
2725   aes c e2
2726   cis,1
2727 }
2728 @end lilypond
2729
2730
2731 @snippets
2732
2733 @lilypondfile[verbatim,quote,texidoc,doctitle]
2734 {adding-ambitus-per-voice.ly}
2735
2736 @lilypondfile[verbatim,quote,texidoc,doctitle]
2737 {ambitus-with-multiple-voices.ly}
2738
2739 @lilypondfile[verbatim,quote,texidoc,doctitle]
2740 {changing-the-ambitus-gap.ly}
2741
2742 @seealso
2743 Music Glossary:
2744 @rglos{ambitus}.
2745
2746 Snippets:
2747 @rlsr{Pitches}.
2748
2749 Internals Reference:
2750 @rinternals{Ambitus_engraver},
2751 @rinternals{Voice},
2752 @rinternals{Staff},
2753 @rinternals{Ambitus},
2754 @rinternals{AmbitusAccidental},
2755 @rinternals{AmbitusLine},
2756 @rinternals{AmbitusNoteHead},
2757 @rinternals{ambitus-interface}.
2758
2759 @knownissues
2760 There is no collision handling in the case of multiple per-voice
2761 ambitus.
2762
2763
2764 @node Note heads
2765 @subsection Note heads
2766
2767 This section suggests ways of altering note heads.
2768
2769 @menu
2770 * Special note heads::
2771 * Easy notation note heads::
2772 * Shape note heads::
2773 * Improvisation::
2774 @end menu
2775
2776 @node Special note heads
2777 @unnumberedsubsubsec Special note heads
2778
2779 @cindex note heads, special
2780 @cindex note heads, cross
2781 @cindex note heads, diamond
2782 @cindex note heads, parlato
2783 @cindex note heads, harmonic
2784 @cindex note heads, guitar
2785 @cindex special note heads
2786 @cindex cross note heads
2787 @cindex diamond note heads
2788 @cindex parlato note heads
2789 @cindex harmonic note heads
2790 @cindex guitar note heads
2791 @cindex note head styles
2792 @cindex styles, note heads
2793
2794 @funindex cross
2795
2796 The appearance of note heads may be altered:
2797
2798 @lilypond[verbatim,quote,relative=2]
2799 c4 b
2800 \override NoteHead.style = #'cross
2801 c4 b
2802 \revert NoteHead.style
2803 a b
2804 \override NoteHead.style = #'harmonic
2805 a b
2806 \revert NoteHead.style
2807 c4 d e f
2808 @end lilypond
2809
2810 To see all note head styles, see @ref{Note head styles}.
2811
2812 The @code{cross} style is used to represent a variety of musical
2813 intentions.  The following generic predefined commands modify the
2814 note head in both staff and tablature contexts and can be used to
2815 represent any musical meaning:
2816
2817 @lilypond[verbatim,quote,relative=2]
2818 c4 b
2819 \xNotesOn
2820  a b c4 b
2821 \xNotesOff
2822 c4 d
2823 @end lilypond
2824
2825 The music function form of this predefined command may be used
2826 inside and outside chords to generate crossed note heads in both
2827 staff and tablature contexts:
2828
2829 @lilypond[verbatim,quote,relative=2]
2830 c4 b
2831 \xNote { e f }
2832 c b < g \xNote c f > b
2833 @end lilypond
2834
2835 As synonyms for @code{\xNote}, @code{\xNotesOn} and @code{\xNotesOff},
2836 @code{\deadNote}, @code{\deadNotesOn} and @code{\deadNotesOff} can
2837 be used.  The term @notation{dead note} is commonly used by guitarists.
2838
2839 There is also a similar shorthand for diamond shapes:
2840
2841 @lilypond[verbatim,quote,relative=2]
2842 <c f\harmonic>2 <d a'\harmonic>4 <c g'\harmonic> f\harmonic
2843 @end lilypond
2844
2845 @predefined
2846 @code{\harmonic},
2847 @code{\xNotesOn},
2848 @code{\xNotesOff},
2849 @code{\xNote}.
2850 @endpredefined
2851
2852 @seealso
2853 Snippets:
2854 @rlsr{Pitches}.
2855
2856 Notation Reference:
2857 @ref{Note head styles},
2858 @ref{Chorded notes},
2859 @ref{Indicating harmonics and dampened notes}.
2860
2861 Internals Reference:
2862 @rinternals{note-event},
2863 @rinternals{Note_heads_engraver},
2864 @rinternals{Ledger_line_engraver},
2865 @rinternals{NoteHead},
2866 @rinternals{LedgerLineSpanner},
2867 @rinternals{note-head-interface},
2868 @rinternals{ledger-line-spanner-interface}.
2869
2870
2871 @node Easy notation note heads
2872 @unnumberedsubsubsec Easy notation note heads
2873
2874 @cindex note heads, practice
2875 @cindex practice note heads
2876 @cindex note heads, easy notation
2877 @cindex easy notation
2878 @cindex beginners' music
2879 @cindex music, beginners'
2880 @cindex easy play note heads
2881 @cindex note heads, easy play
2882
2883 @funindex \easyHeadsOn
2884 @funindex easyHeadsOn
2885 @funindex \easyHeadsOff
2886 @funindex easyHeadsOff
2887
2888 The @q{easy play} note head includes a note name inside the head.
2889 It is used in music for beginners.  To make the letters readable,
2890 it should be printed in a large font size.  To print with a larger
2891 font, see @ref{Setting the staff size}.
2892
2893 @lilypond[verbatim,quote]
2894 #(set-global-staff-size 26)
2895 \relative c' {
2896   \easyHeadsOn
2897   c2 e4 f
2898   g1
2899   \easyHeadsOff
2900   c,1
2901 }
2902 @end lilypond
2903
2904
2905 @predefined
2906 @code{\easyHeadsOn},
2907 @code{\easyHeadsOff}.
2908 @endpredefined
2909
2910
2911 @snippets
2912
2913 @lilypondfile[verbatim,quote,texidoc,doctitle]
2914 {numbers-as-easy-note-heads.ly}
2915
2916 @seealso
2917 Notation Reference:
2918 @ref{Setting the staff size}.
2919
2920 Snippets:
2921 @rlsr{Pitches}.
2922
2923 Internals Reference:
2924 @rinternals{note-event},
2925 @rinternals{Note_heads_engraver},
2926 @rinternals{NoteHead},
2927 @rinternals{note-head-interface}.
2928
2929
2930 @node Shape note heads
2931 @unnumberedsubsubsec Shape note heads
2932
2933 @cindex note heads, shape
2934 @cindex note heads, Aiken
2935 @cindex note heads, sacred harp
2936 @cindex shape notes
2937 @cindex Aiken shape note heads
2938 @cindex sacred harp note heads
2939 @cindex note heads, Southern Harmony
2940 @cindex Southern Harmony note heads
2941 @cindex Funk shape note heads
2942 @cindex note heads, Funk
2943 @cindex note heads, Harmonica Sacra
2944 @cindex Harmonica Sacra note heads
2945 @cindex Christian Harmony note heads
2946 @cindex note heads, Christian Harmony
2947 @cindex Walker shape note heads
2948 @cindex note heads, Walker
2949
2950 @funindex \aikenHeads
2951 @funindex aikenHeads
2952 @funindex \sacredHarpHeads
2953 @funindex sacredHarpHeads
2954 @funindex \southernHarmonyHeads
2955 @funindex southernHarmonyHeads
2956 @funindex \funkHeads
2957 @funindex funkHeads
2958 @funindex \walkerHeads
2959 @funindex walkerHeads
2960
2961 In shape note head notation, the shape of the note head
2962 corresponds to the harmonic function of a note in the scale.  This
2963 notation was popular in nineteenth-century American song books.
2964 Shape note heads can be produced in Sacred Harp, Southern Harmony,
2965 Funk (Harmonica Sacra), Walker, and Aiken (Christian Harmony) styles:
2966
2967 @lilypond[verbatim,quote,relative=2]
2968 \aikenHeads
2969 c, d e f g2 a b1 c \break
2970 \sacredHarpHeads
2971 c,4 d e f g2 a b1 c \break
2972 \southernHarmonyHeads
2973 c,4 d e f g2 a b1 c \break
2974 \funkHeads
2975 c,4 d e f g2 a b1 c \break
2976 \walkerHeads
2977 c,4 d e f g2 a b1 c \break
2978 @end lilypond
2979
2980 @funindex \key
2981 @funindex key
2982 @funindex \aikenHeadsMinor
2983 @funindex aikenHeadsMinor
2984 @funindex \sacredHarpHeadsMinor
2985 @funindex sacredHarpHeadsMinor
2986 @funindex \southernHarmonyHeadsMinor
2987 @funindex southernHarmonyHeadsMinor
2988 @funindex \funkHeadsMinor
2989 @funindex funkHeadsMinor
2990 @funindex \walkerHeadsMinor
2991 @funindex walkerHeadsMinor
2992
2993 Shapes are typeset according to the step in the scale, where the base
2994 of the scale is determined by the @code{\key} command.  When writing
2995 in a minor key, the scale step can be determined from the relative
2996 major:
2997
2998 @lilypond[verbatim,quote,relative=2]
2999 \key a \minor
3000 \aikenHeads
3001 a b c d e2 f g1 a \break
3002 \aikenHeadsMinor
3003 a,4 b c d e2 f g1 a \break
3004 \sacredHarpHeadsMinor
3005 a,2 b c d \break
3006 \southernHarmonyHeadsMinor
3007 a2 b c d \break
3008 \funkHeadsMinor
3009 a2 b c d \break
3010 \walkerHeadsMinor
3011 a2 b c d \break
3012
3013 @end lilypond
3014
3015
3016 @predefined
3017 @code{\aikenHeads},
3018 @code{\aikenHeadsMinor},
3019 @code{\funkHeads},
3020 @code{\funkHeadsMinor},
3021 @code{\sacredHarpHeads},
3022 @code{\sacredHarpHeadsMinor},
3023 @code{\southernHarmonyHeads},
3024 @code{\southernHarmonyHeadsMinor},
3025 @code{\walkerHeads},
3026 @code{\walkerHeadsMinor}.
3027 @endpredefined
3028
3029
3030 @snippets
3031
3032 @lilypondfile[verbatim,quote,texidoc,doctitle]
3033 {applying-note-head-styles-depending-on-the-step-of-the-scale.ly}
3034
3035 To see all note head styles, see @ref{Note head styles}.
3036
3037 @seealso
3038 Snippets:
3039 @rlsr{Pitches}.
3040
3041 Notation Reference:
3042 @ref{Note head styles}.
3043
3044 Internals Reference:
3045 @rinternals{note-event},
3046 @rinternals{Note_heads_engraver},
3047 @rinternals{NoteHead},
3048 @rinternals{note-head-interface}.
3049
3050
3051 @node Improvisation
3052 @unnumberedsubsubsec Improvisation
3053
3054 @cindex improvisation
3055 @cindex slashed note heads
3056 @cindex note heads, improvisation
3057 @cindex note heads, slashed
3058
3059 @funindex \improvisationOn
3060 @funindex improvisationOn
3061 @funindex \improvisationOff
3062 @funindex improvisationOff
3063
3064 Improvisation is sometimes denoted with slashed note heads, where
3065 the performer may choose any pitch but should play the specified
3066 rhythm.  Such note heads can be created:
3067
3068 @lilypond[verbatim,quote,relative=2]
3069 \new Voice \with {
3070   \consists "Pitch_squash_engraver"
3071 } {
3072   e8 e g a a16( bes) a8 g
3073   \improvisationOn
3074   e8 ~
3075   2 ~ 8 f4 f8 ~
3076   2
3077   \improvisationOff
3078   a16( bes) a8 g e
3079 }
3080 @end lilypond
3081
3082 @predefined
3083 @code{\improvisationOn},
3084 @code{\improvisationOff}.
3085 @endpredefined
3086
3087 @seealso
3088 Snippets:
3089 @rlsr{Pitches}.
3090
3091 Internals Reference:
3092 @rinternals{Pitch_squash_engraver},
3093 @rinternals{Voice},
3094 @rinternals{RhythmicStaff}.