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 Without any explicit command, the default clef for LilyPond is the
1108 treble (or @emph{G}) clef.
1109
1110 @lilypond[verbatim,quote,relative=1,ragged-right]
1111 c2 c
1112 @end lilypond
1113
1114 However, the clef can be changed by using the @code{\clef} command and
1115 an appropriate clef name.  @emph{Middle C} is shown in each of the
1116 following examples.
1117
1118 @lilypond[verbatim,quote,relative=1]
1119 \clef treble
1120 c2 c
1121 \clef alto
1122 c2 c
1123 \clef tenor
1124 c2 c
1125 \clef bass
1126 c2 c
1127 @end lilypond
1128
1129 For the full range of possible clef names see @ref{Clef styles}.
1130
1131 Specialized clefs, such as those used in @emph{Ancient} music, are
1132 described in @ref{Mensural clefs} and @ref{Gregorian clefs}.  Music that
1133 requires tablature clefs is discussed in @ref{Default tablatures} and
1134 @ref{Custom tablatures}.
1135
1136 @cindex Cue clefs
1137 @cindex Clefs with cue notes
1138 For mixing clefs when using cue notes, see the @code{\cueClef} and
1139 @code{\cueDuringWithClef} commands in @ref{Formatting cue notes}.
1140
1141 @cindex transposing clef
1142 @cindex clef, transposing
1143 @cindex octave transposition
1144 @cindex optional octave transposition
1145 @cindex octave transposition, optional
1146 @cindex choral tenor clef
1147 @cindex tenor clef, choral
1148
1149 By adding@tie{}@code{_8} or@tie{}@code{^8} to the clef name, the
1150 clef is transposed one octave down or up respectively,
1151 and@tie{}@code{_15} and@tie{}@code{^15} transpose by two octaves.
1152 Other integers can be used if required.  Clef names containing
1153 non-alphabetic characters must be enclosed in quotes
1154
1155 @lilypond[verbatim,quote,relative=1]
1156 \clef treble
1157 c2 c
1158 \clef "treble_8"
1159 c2 c
1160 \clef "bass^15"
1161 c2 c
1162 \clef "alto_2"
1163 c2 c
1164 \clef "G_8"
1165 c2 c
1166 \clef "F^5"
1167 c2 c
1168 @end lilypond
1169
1170 Optional octavation can be obtained by enclosing the numeric
1171 argument in parentheses or brackets:
1172
1173 @lilypond[verbatim,quote,relative=1]
1174 \clef "treble_(8)"
1175 c2 c
1176 \clef "bass^[15]"
1177 c2 c
1178 @end lilypond
1179
1180 The pitches are displayed as if the numeric argument were
1181 given without parentheses/brackets.
1182
1183 @snippets
1184 @lilypondfile[verbatim,quote,texidoc,doctitle]
1185 {forcing-a-clef-symbol-to-be-displayed.ly}
1186
1187 @lilypondfile[verbatim,quote,texidoc,doctitle]
1188 {keep-change-clefs-full-sized.ly}
1189
1190 @lilypondfile[verbatim,quote,texidoc,doctitle]
1191 {tweaking-clef-properties.ly}
1192
1193 @seealso
1194 Notation Reference:
1195 @ref{Mensural clefs},
1196 @ref{Gregorian clefs},
1197 @ref{Default tablatures},
1198 @ref{Custom tablatures},
1199 @ref{Formatting cue notes}.
1200
1201 Installed Files:
1202 @file{../scm/parser-clef.scm}.
1203
1204 Snippets:
1205 @rlsr{Pitches}.
1206
1207 Internals Reference:
1208 @rinternals{Clef_engraver},
1209 @rinternals{Clef},
1210 @rinternals{ClefModifier},
1211 @rinternals{clef-interface}.
1212
1213 @knownissues
1214 Ottavation numbers attached to clefs are treated as separate grobs.  So
1215 any @code{\override} done to the @var{Clef} will also need to be
1216 applied, as a separate @code{\override}, to the @var{ClefModifier}
1217 grob.
1218
1219 @lilypond[fragment,quote,verbatim,relative=1]
1220 \new Staff \with {
1221   \override Clef.color = #blue
1222   \override ClefModifier.color = #red
1223 }
1224
1225 \clef "treble_8" c4
1226 @end lilypond
1227
1228
1229 @node Key signature
1230 @unnumberedsubsubsec Key signature
1231
1232 @cindex key signature
1233
1234 @funindex \key
1235 @funindex key
1236
1237 @c duplicated in Key signature and Accidentals
1238 @warning{New users are sometimes confused about accidentals and
1239 key signatures.  In LilyPond, note names are the raw input; key
1240 signatures and clefs determine how this raw input is displayed.
1241 An unaltered note like@tie{}@code{c} means @q{C natural},
1242 regardless of the key signature or clef.  For more information,
1243 see @rlearning{Accidentals and key signatures}.}
1244
1245 The key signature indicates the tonality in which a piece is
1246 played.  It is denoted by a set of alterations (flats or sharps)
1247 at the start of the staff.  The key signature may be altered:
1248
1249 @example
1250 \key @var{pitch} @var{mode}
1251 @end example
1252
1253 @funindex \major
1254 @funindex major
1255 @funindex \minor
1256 @funindex minor
1257 @funindex \ionian
1258 @funindex ionian
1259 @funindex \locrian
1260 @funindex locrian
1261 @funindex \aeolian
1262 @funindex aeolian
1263 @funindex \mixolydian
1264 @funindex mixolydian
1265 @funindex \lydian
1266 @funindex lydian
1267 @funindex \phrygian
1268 @funindex phrygian
1269 @funindex \dorian
1270 @funindex dorian
1271
1272 @cindex church modes
1273 @cindex modes
1274 @cindex major
1275 @cindex minor
1276 @cindex ionian
1277 @cindex locrian
1278 @cindex aeolian
1279 @cindex mixolydian
1280 @cindex lydian
1281 @cindex phrygian
1282 @cindex dorian
1283
1284 @noindent
1285 Here, @code{@var{mode}} should be @code{\major} or @code{\minor}
1286 to get a key signature of @code{@var{pitch}}-major or
1287 @code{@var{pitch}}-minor, respectively.  You may also use the
1288 standard mode names, also called @notation{church modes}:
1289 @code{\ionian}, @code{\dorian}, @code{\phrygian}, @code{\lydian},
1290 @code{\mixolydian}, @code{\aeolian}, and @code{\locrian}.
1291
1292 @lilypond[verbatim,quote,relative=2]
1293 \key g \major
1294 fis1
1295 f
1296 fis
1297 @end lilypond
1298
1299 Additional modes can be defined, by listing the alterations
1300 for each scale step when the mode starts on C.
1301
1302 @lilypond[verbatim,quote]
1303 freygish = #`((0 . ,NATURAL) (1 . ,FLAT) (2 . ,NATURAL)
1304     (3 . ,NATURAL) (4 . ,NATURAL) (5 . ,FLAT) (6 . ,FLAT))
1305
1306 \relative c' {
1307   \key c \freygish c4 des e f
1308   \bar "||" \key d \freygish d es fis g
1309 }
1310 @end lilypond
1311
1312 Accidentals in the key signature may be printed in octaves other
1313 than their traditional positions, or in multiple octaves, by
1314 using the @code{flat-positions} and @code{sharp-positions}
1315 properties of @code{KeySignature}.  Entries in these properties
1316 specify the range of staff-positions where accidentals will be
1317 printed.  If a single position is specified in an entry, the
1318 accidentals are placed within the octave ending at that staff
1319 position.
1320
1321 @lilypond[verbatim, quote,relative=0]
1322 \override Staff.KeySignature.flat-positions = #'((-5 . 5))
1323 \override Staff.KeyCancellation.flat-positions = #'((-5 . 5))
1324 \clef bass \key es \major es g bes d
1325 \clef treble \bar "||" \key es \major es g bes d
1326
1327 \override Staff.KeySignature.sharp-positions = #'(2)
1328 \bar "||" \key b \major b fis b2
1329 @end lilypond
1330
1331 @snippets
1332
1333 @lilypondfile[verbatim,quote,texidoc,doctitle]
1334 {preventing-natural-signs-from-being-printed-when-the-key-signature-changes.ly}
1335
1336 @lilypondfile[verbatim,quote,texidoc,doctitle]
1337 {non-traditional-key-signatures.ly}
1338
1339 @seealso
1340 Music Glossary:
1341 @rglos{church mode},
1342 @rglos{scordatura}.
1343
1344 Learning Manual:
1345 @rlearning{Accidentals and key signatures}.
1346
1347 Snippets:
1348 @rlsr{Pitches}.
1349
1350 Internals Reference:
1351 @rinternals{KeyChangeEvent},
1352 @rinternals{Key_engraver},
1353 @rinternals{Key_performer},
1354 @rinternals{KeyCancellation},
1355 @rinternals{KeySignature},
1356 @rinternals{key-signature-interface}.
1357
1358
1359 @node Ottava brackets
1360 @unnumberedsubsubsec Ottava brackets
1361
1362 @cindex ottava
1363 @cindex 15ma
1364 @cindex 8va
1365 @cindex 8ve
1366 @cindex octavation
1367
1368 @funindex set-octavation
1369 @funindex \ottava
1370 @funindex ottava
1371
1372 @notation{Ottava brackets} introduce an extra transposition of an
1373 octave for the staff:
1374
1375 @lilypond[verbatim,quote,relative=2]
1376 a2 b
1377 \ottava #-2
1378 a2 b
1379 \ottava #-1
1380 a2 b
1381 \ottava #0
1382 a2 b
1383 \ottava #1
1384 a2 b
1385 \ottava #2
1386 a2 b
1387 @end lilypond
1388
1389 @snippets
1390
1391 @lilypondfile[verbatim,quote,texidoc,doctitle]
1392 {ottava-text.ly}
1393
1394 @lilypondfile[verbatim,quote,texidoc,doctitle]
1395 {adding-an-ottava-marking-to-a-single-voice.ly}
1396
1397 @seealso
1398 Music Glossary:
1399 @rglos{octavation}.
1400
1401 Snippets:
1402 @rlsr{Pitches}.
1403
1404 Internals Reference:
1405 @rinternals{Ottava_spanner_engraver},
1406 @rinternals{OttavaBracket},
1407 @rinternals{ottava-bracket-interface}.
1408
1409
1410 @node Instrument transpositions
1411 @unnumberedsubsubsec Instrument transpositions
1412
1413 @cindex transposition, MIDI
1414 @cindex transposition, instrument
1415 @cindex transposing instrument
1416 @cindex MIDI
1417 @cindex MIDI transposition
1418
1419 @funindex \transposition
1420 @funindex transposition
1421
1422 When typesetting scores that involve transposing instruments, some
1423 parts can be typeset in a different pitch than the
1424 @notation{concert pitch}.  In these cases, the key of the
1425 @notation{transposing instrument} should be specified; otherwise
1426 the MIDI output and cues in other parts will produce incorrect
1427 pitches.  For more information about quotations, see
1428 @ref{Quoting other voices}.
1429
1430 @example
1431 \transposition @var{pitch}
1432 @end example
1433
1434 The pitch to use for @code{\transposition} should correspond to
1435 the real sound heard when a@tie{}@code{c'} written on the staff is
1436 played by the transposing instrument.  This pitch is entered in
1437 absolute mode, so an instrument that produces a real sound which
1438 is one tone higher than the printed music should use
1439 @w{@code{\transposition d'}}.  @code{\transposition} should
1440 @emph{only} be used if the pitches are @emph{not} being entered in
1441 concert pitch.
1442
1443 Here are a few notes for violin and B-flat clarinet where the
1444 parts have been entered using the notes and key as they appear in
1445 each part of the conductor's score.  The two instruments are
1446 playing in unison.
1447
1448 @lilypond[verbatim,quote]
1449 \new GrandStaff <<
1450   \new Staff = "violin" {
1451     \relative c'' {
1452       \set Staff.instrumentName = #"Vln"
1453       \set Staff.midiInstrument = #"violin"
1454       % not strictly necessary, but a good reminder
1455       \transposition c'
1456
1457       \key c \major
1458       g4( c8) r c r c4
1459     }
1460   }
1461   \new Staff = "clarinet" {
1462     \relative c'' {
1463       \set Staff.instrumentName = \markup { Cl (B\flat) }
1464       \set Staff.midiInstrument = #"clarinet"
1465       \transposition bes
1466
1467       \key d \major
1468       a4( d8) r d r d4
1469     }
1470   }
1471 >>
1472 @end lilypond
1473
1474 The @code{\transposition} may be changed during a piece.  For
1475 example, a clarinetist may be required to switch from an A clarinet
1476 to a B-flat clarinet.
1477
1478 @lilypond[verbatim,quote]
1479 flute = \relative c'' {
1480   \key f \major
1481   \cueDuring #"clarinet" #DOWN {
1482     R1 _\markup\tiny "clarinet"
1483     c4 f e d
1484     R1 _\markup\tiny "clarinet"
1485   }
1486 }
1487 clarinet = \relative c'' {
1488   \key aes \major
1489   \transposition a
1490   aes4 bes c des
1491   R1^\markup { muta in B\flat }
1492   \key g \major
1493   \transposition bes
1494   d2 g,
1495 }
1496 \addQuote "clarinet" \clarinet
1497 <<
1498   \new Staff \with { instrumentName = #"Flute" }
1499     \flute
1500   \new Staff \with { instrumentName = #"Cl (A)" }
1501     \clarinet
1502 >>
1503 @end lilypond
1504
1505 @seealso
1506 Music Glossary:
1507 @rglos{concert pitch},
1508 @rglos{transposing instrument}.
1509
1510 Notation Reference:
1511 @ref{Quoting other voices},
1512 @ref{Transpose}.
1513
1514 Snippets:
1515 @rlsr{Pitches}.
1516
1517
1518 @node Automatic accidentals
1519 @unnumberedsubsubsec Automatic accidentals
1520
1521 @cindex accidental style
1522 @cindex accidental style, default
1523 @cindex accidentals
1524 @cindex accidentals, automatic
1525 @cindex automatic accidentals
1526 @cindex default accidental style
1527
1528 @funindex \accidentalStyle
1529 @funindex voice
1530 @funindex default
1531
1532 There are many different conventions on how to typeset
1533 accidentals.  LilyPond provides a function to specify which
1534 accidental style to use.  This function is called as follows:
1535
1536 @example
1537 \new Staff <<
1538   \accidentalStyle voice
1539   @{ @dots{} @}
1540 >>
1541 @end example
1542
1543 The accidental style applies to the current @code{Staff} by
1544 default (with the exception of the styles @code{piano} and
1545 @code{piano-cautionary}, which are explained below).  Optionally,
1546 the function can take a second argument that determines in which
1547 scope the style should be changed.  For example, to use the same
1548 style in all staves of the current @code{StaffGroup}, use:
1549
1550 @example
1551 \accidentalStyle StaffGroup.voice
1552 @end example
1553
1554 The following accidental styles are supported.  To demonstrate
1555 each style, we use the following example:
1556
1557
1558 @lilypond[verbatim,quote]
1559 musicA = {
1560   <<
1561     \relative c' {
1562       cis'8 fis, bes4 <a cis>8 f bis4 |
1563       cis2. <c, g'>4 |
1564     }
1565     \\
1566     \relative c' {
1567       ais'2 cis, |
1568       fis8 b a4 cis2 |
1569     }
1570   >>
1571 }
1572
1573 musicB = {
1574   \clef bass
1575   \new Voice {
1576     \voiceTwo \relative c' {
1577       <fis, a cis>8[ <fis a cis>
1578       \change Staff = up
1579       cis' cis
1580       \change Staff = down
1581       <fis, a> <fis a>]
1582       \showStaffSwitch
1583       \change Staff = up
1584       dis'4 |
1585       \change Staff = down
1586       <fis, a cis>4 gis <f a d>2 |
1587     }
1588   }
1589 }
1590
1591 \new PianoStaff {
1592   <<
1593     \context Staff = "up" {
1594       \accidentalStyle default
1595       \musicA
1596     }
1597     \context Staff = "down" {
1598       \accidentalStyle default
1599       \musicB
1600     }
1601   >>
1602 }
1603 @end lilypond
1604
1605 Note that the last lines of this example can be replaced by the
1606 following, as long as the same accidental style should be used in
1607 both staves.
1608
1609 @example
1610 \new PianoStaff @{
1611   <<
1612     \context Staff = "up" @{
1613       %%% change the next line as desired:
1614       \accidentalStyle Score.default
1615       \musicA
1616     @}
1617     \context Staff = "down" @{
1618       \musicB
1619     @}
1620   >>
1621 @}
1622 @end example
1623
1624
1625 @c don't use verbatim in this table.
1626 @table @code
1627 @item default
1628
1629 @cindex default accidental style
1630 @cindex accidental style, default
1631
1632 @funindex default
1633
1634 This is the default typesetting behavior.  It corresponds to
1635 eighteenth-century common practice: accidentals are remembered to
1636 the end of the measure in which they occur and only in their own
1637 octave.  Thus, in the example below, no natural signs are printed
1638 before the@tie{}@code{b} in the second measure or the
1639 last@tie{}@code{c}:
1640
1641 @lilypond[quote]
1642 musicA = {
1643   <<
1644     \relative c' {
1645       cis'8 fis, bes4 <a cis>8 f bis4 |
1646       cis2. <c, g'>4 |
1647     }
1648     \\
1649     \relative c' {
1650       ais'2 cis, |
1651       fis8 b a4 cis2 |
1652     }
1653   >>
1654 }
1655
1656 musicB = {
1657   \clef bass
1658   \new Voice {
1659     \voiceTwo \relative c' {
1660       <fis, a cis>8[ <fis a cis>
1661       \change Staff = up
1662       cis' cis
1663       \change Staff = down
1664       <fis, a> <fis a>]
1665       \showStaffSwitch
1666       \change Staff = up
1667       dis'4 |
1668       \change Staff = down
1669       <fis, a cis>4 gis <f a d>2 |
1670     }
1671   }
1672 }
1673
1674 \new PianoStaff {
1675   <<
1676     \context Staff = "up" {
1677       \accidentalStyle default
1678       \musicA
1679     }
1680     \context Staff = "down" {
1681       \accidentalStyle default
1682       \musicB
1683     }
1684   >>
1685 }
1686 @end lilypond
1687
1688 @item voice
1689
1690 @cindex accidental style, voice
1691 @cindex voice accidental style
1692 @cindex accidental style, modern
1693 @cindex modern accidental style
1694 @cindex accidental style, modern-cautionary
1695 @cindex modern-cautionary accidental style
1696
1697 @funindex voice
1698
1699 The normal behavior is to remember the accidentals at
1700 @code{Staff}-level.  In this style, however, accidentals are
1701 typeset individually for each voice.  Apart from that, the rule is
1702 similar to @code{default}.
1703
1704 As a result, accidentals from one voice do not get canceled in
1705 other voices, which is often an unwanted result: in the following
1706 example, it is hard to determine whether the second@tie{}@code{a}
1707 should be played natural or sharp.  The @code{voice} option should
1708 therefore be used only if the voices are to be read solely by
1709 individual musicians.  If the staff is to be used by one musician
1710 (e.g., a conductor or in a piano score) then @code{modern} or
1711 @code{modern-cautionary} should be used instead.
1712
1713
1714 @lilypond[quote]
1715 musicA = {
1716   <<
1717     \relative c' {
1718       cis'8 fis, bes4 <a cis>8 f bis4 |
1719       cis2. <c, g'>4 |
1720     }
1721     \\
1722     \relative c' {
1723       ais'2 cis, |
1724       fis8 b a4 cis2 |
1725     }
1726   >>
1727 }
1728
1729 musicB = {
1730   \clef bass
1731   \new Voice {
1732     \voiceTwo \relative c' {
1733       <fis, a cis>8[ <fis a cis>
1734       \change Staff = up
1735       cis' cis
1736       \change Staff = down
1737       <fis, a> <fis a>]
1738       \showStaffSwitch
1739       \change Staff = up
1740       dis'4 |
1741       \change Staff = down
1742       <fis, a cis>4 gis <f a d>2 |
1743     }
1744   }
1745 }
1746
1747 \new PianoStaff {
1748   <<
1749     \context Staff = "up" {
1750       \accidentalStyle voice
1751       \musicA
1752     }
1753     \context Staff = "down" {
1754       \accidentalStyle voice
1755       \musicB
1756     }
1757   >>
1758 }
1759 @end lilypond
1760
1761 @item modern
1762
1763 @cindex accidentals, modern style
1764 @cindex modern style accidentals
1765
1766 @funindex modern
1767
1768 This rule corresponds to the common practice in the twentieth
1769 century.  It omits some extra natural signs, which were
1770 traditionally prefixed to a sharp following a double sharp,
1771 or a flat following a double flat.  The @code{modern} rule
1772 prints the same accidentals as @code{default}, with
1773 two additions that serve to avoid ambiguity: after temporary
1774 accidentals, cancellation marks are printed also in the following
1775 measure (for notes in the same octave) and, in the same measure,
1776 for notes in other octaves.  Hence the naturals before
1777 the@tie{}@code{b} and the@tie{}@code{c} in the second measure of
1778 the upper staff:
1779
1780 @lilypond[quote]
1781 musicA = {
1782   <<
1783     \relative c' {
1784       cis'8 fis, bes4 <a cis>8 f bis4 |
1785       cis2. <c, g'>4 |
1786     }
1787     \\
1788     \relative c' {
1789       ais'2 cis, |
1790       fis8 b a4 cis2 |
1791     }
1792   >>
1793 }
1794
1795 musicB = {
1796   \clef bass
1797   \new Voice {
1798     \voiceTwo \relative c' {
1799       <fis, a cis>8[ <fis a cis>
1800       \change Staff = up
1801       cis' cis
1802       \change Staff = down
1803       <fis, a> <fis a>]
1804       \showStaffSwitch
1805       \change Staff = up
1806       dis'4 |
1807       \change Staff = down
1808       <fis, a cis>4 gis <f a d>2 |
1809     }
1810   }
1811 }
1812
1813 \new PianoStaff {
1814   <<
1815     \context Staff = "up" {
1816       \accidentalStyle modern
1817       \musicA
1818     }
1819     \context Staff = "down" {
1820       \accidentalStyle modern
1821       \musicB
1822     }
1823   >>
1824 }
1825 @end lilypond
1826
1827 @item modern-cautionary
1828
1829 @cindex accidentals, modern cautionary style
1830 @cindex modern accidental style
1831 @cindex modern cautionary accidental style
1832 @cindex modern style accidentals
1833 @cindex modern style cautionary accidentals
1834
1835 @funindex modern-cautionary
1836
1837 This rule is similar to @code{modern}, but the @q{extra}
1838 accidentals (the ones not typeset by @code{default}) are typeset
1839 as cautionary accidentals.  They are by default printed with
1840 parentheses, but they can also be printed in reduced size by
1841 defining the @code{cautionary-style} property of
1842 @code{AccidentalSuggestion}.
1843
1844 @lilypond[quote]
1845 musicA = {
1846   <<
1847     \relative c' {
1848       cis'8 fis, bes4 <a cis>8 f bis4 |
1849       cis2. <c, g'>4 |
1850     }
1851     \\
1852     \relative c' {
1853       ais'2 cis, |
1854       fis8 b a4 cis2 |
1855     }
1856   >>
1857 }
1858
1859 musicB = {
1860   \clef bass
1861   \new Voice {
1862     \voiceTwo \relative c' {
1863       <fis, a cis>8[ <fis a cis>
1864       \change Staff = up
1865       cis' cis
1866       \change Staff = down
1867       <fis, a> <fis a>]
1868       \showStaffSwitch
1869       \change Staff = up
1870       dis'4 |
1871       \change Staff = down
1872       <fis, a cis>4 gis <f a d>2 |
1873     }
1874   }
1875 }
1876
1877 \new PianoStaff {
1878   <<
1879     \context Staff = "up" {
1880       \accidentalStyle modern-cautionary
1881       \musicA
1882     }
1883     \context Staff = "down" {
1884       \accidentalStyle modern-cautionary
1885       \musicB
1886     }
1887   >>
1888 }
1889 @end lilypond
1890
1891 @item modern-voice
1892
1893 @cindex accidental style, modern
1894 @cindex accidentals, modern
1895 @cindex accidentals, multivoice
1896 @cindex modern accidental style
1897 @cindex modern accidentals
1898 @cindex multivoice accidentals
1899
1900 @funindex modern-voice
1901
1902 This rule is used for multivoice accidentals to be read both by
1903 musicians playing one voice and musicians playing all voices.
1904 Accidentals are typeset for each voice, but they @emph{are}
1905 canceled across voices in the same @code{Staff}.  Hence,
1906 the@tie{}@code{a} in the last measure is canceled because the
1907 previous cancellation was in a different voice, and
1908 the@tie{}@code{d} in the lower staff is canceled because of the
1909 accidental in a different voice in the previous measure:
1910
1911 @lilypond[quote]
1912 musicA = {
1913   <<
1914     \relative c' {
1915       cis'8 fis, bes4 <a cis>8 f bis4 |
1916       cis2. <c, g'>4 |
1917     }
1918     \\
1919     \relative c' {
1920       ais'2 cis, |
1921       fis8 b a4 cis2 |
1922     }
1923   >>
1924 }
1925
1926 musicB = {
1927   \clef bass
1928   \new Voice {
1929     \voiceTwo \relative c' {
1930       <fis, a cis>8[ <fis a cis>
1931       \change Staff = up
1932       cis' cis
1933       \change Staff = down
1934       <fis, a> <fis a>]
1935       \showStaffSwitch
1936       \change Staff = up
1937       dis'4 |
1938       \change Staff = down
1939       <fis, a cis>4 gis <f a d>2 |
1940     }
1941   }
1942 }
1943
1944 \new PianoStaff {
1945   <<
1946     \context Staff = "up" {
1947       \accidentalStyle modern-voice
1948       \musicA
1949     }
1950     \context Staff = "down" {
1951       \accidentalStyle modern-voice
1952       \musicB
1953     }
1954   >>
1955 }
1956 @end lilypond
1957
1958 @cindex accidental style, cautionary, modern voice
1959 @cindex accidental style, modern voice cautionary
1960 @cindex accidental style, voice, modern cautionary
1961
1962 @funindex modern-voice-cautionary
1963
1964 @item modern-voice-cautionary
1965
1966 This rule is the same as @code{modern-voice}, but with the extra
1967 accidentals (the ones not typeset by @code{voice}) typeset as
1968 cautionaries.  Even though all accidentals typeset by
1969 @code{default} @emph{are} typeset with this rule, some of them are
1970 typeset as cautionaries.
1971
1972 @lilypond[quote]
1973 musicA = {
1974   <<
1975     \relative c' {
1976       cis'8 fis, bes4 <a cis>8 f bis4 |
1977       cis2. <c, g'>4 |
1978     }
1979     \\
1980     \relative c' {
1981       ais'2 cis, |
1982       fis8 b a4 cis2 |
1983     }
1984   >>
1985 }
1986
1987 musicB = {
1988   \clef bass
1989   \new Voice {
1990     \voiceTwo \relative c' {
1991       <fis, a cis>8[ <fis a cis>
1992       \change Staff = up
1993       cis' cis
1994       \change Staff = down
1995       <fis, a> <fis a>]
1996       \showStaffSwitch
1997       \change Staff = up
1998       dis'4 |
1999       \change Staff = down
2000       <fis, a cis>4 gis <f a d>2 |
2001     }
2002   }
2003 }
2004
2005 \new PianoStaff {
2006   <<
2007     \context Staff = "up" {
2008       \accidentalStyle modern-voice-cautionary
2009       \musicA
2010     }
2011     \context Staff = "down" {
2012       \accidentalStyle modern-voice-cautionary
2013       \musicB
2014     }
2015   >>
2016 }
2017 @end lilypond
2018
2019 @item piano
2020
2021 @cindex accidental style, piano
2022 @cindex accidentals, piano
2023 @cindex piano accidental style
2024 @cindex piano accidentals
2025
2026 @funindex piano
2027
2028 This rule reflects twentieth-century practice for piano notation.
2029 Its behavior is very similar to @code{modern} style, but here
2030 accidentals also get canceled across the staves in the same
2031 @code{GrandStaff} or @code{PianoStaff}, hence all the
2032 cancellations of the final notes.
2033
2034 This accidental style applies to the current @code{GrandStaff} or
2035 @code{PianoStaff} by default.
2036
2037 @lilypond[quote]
2038 musicA = {
2039   <<
2040     \relative c' {
2041       cis'8 fis, bes4 <a cis>8 f bis4 |
2042       cis2. <c, g'>4 |
2043     }
2044     \\
2045     \relative c' {
2046       ais'2 cis, |
2047       fis8 b a4 cis2 |
2048     }
2049   >>
2050 }
2051
2052 musicB = {
2053   \clef bass
2054   \new Voice {
2055     \voiceTwo \relative c' {
2056       <fis, a cis>8[ <fis a cis>
2057       \change Staff = up
2058       cis' cis
2059       \change Staff = down
2060       <fis, a> <fis a>]
2061       \showStaffSwitch
2062       \change Staff = up
2063       dis'4 |
2064       \change Staff = down
2065       <fis, a cis>4 gis <f a d>2 |
2066     }
2067   }
2068 }
2069
2070 \new PianoStaff {
2071   <<
2072     \context Staff = "up" {
2073       \accidentalStyle piano
2074       \musicA
2075     }
2076     \context Staff = "down" {
2077       \musicB
2078     }
2079   >>
2080 }
2081 @end lilypond
2082
2083 @item piano-cautionary
2084
2085 @cindex accidentals, piano cautionary
2086 @cindex cautionary accidentals, piano
2087 @cindex piano cautionary accidentals
2088 @cindex accidental style, piano cautionary
2089 @cindex cautionary accidental style, piano
2090 @cindex piano cautionary accidental style
2091
2092 @funindex piano-cautionary
2093
2094 This is the same as @code{piano} but with the extra accidentals
2095 typeset as cautionaries.
2096
2097 @lilypond[quote]
2098 musicA = {
2099   <<
2100     \relative c' {
2101       cis'8 fis, bes4 <a cis>8 f bis4 |
2102       cis2. <c, g'>4 |
2103     }
2104     \\
2105     \relative c' {
2106       ais'2 cis, |
2107       fis8 b a4 cis2 |
2108     }
2109   >>
2110 }
2111
2112 musicB = {
2113   \clef bass
2114   \new Voice {
2115     \voiceTwo \relative c' {
2116       <fis, a cis>8[ <fis a cis>
2117       \change Staff = up
2118       cis' cis
2119       \change Staff = down
2120       <fis, a> <fis a>]
2121       \showStaffSwitch
2122       \change Staff = up
2123       dis'4 |
2124       \change Staff = down
2125       <fis, a cis>4 gis <f a d>2 |
2126     }
2127   }
2128 }
2129
2130 \new PianoStaff {
2131   <<
2132     \context Staff = "up" {
2133       \accidentalStyle piano-cautionary
2134       \musicA
2135     }
2136     \context Staff = "down" {
2137       \musicB
2138     }
2139   >>
2140 }
2141 @end lilypond
2142
2143
2144 @item neo-modern
2145
2146 @cindex neo-modern accidental style
2147 @cindex accidental style, neo-modern
2148
2149 @funindex neo-modern
2150
2151 This rule reproduces a common practice in contemporary music:
2152 accidentals are printed like with @code{modern}, but they are printed
2153 again if the same note appears later in the same measure -- except
2154 if the note is immediately repeated.
2155
2156 @lilypond[quote]
2157 musicA = {
2158   <<
2159     \relative c' {
2160       cis'8 fis, bes4 <a cis>8 f bis4 |
2161       cis2. <c, g'>4 |
2162     }
2163     \\
2164     \relative c' {
2165       ais'2 cis, |
2166       fis8 b a4 cis2 |
2167     }
2168   >>
2169 }
2170
2171 musicB = {
2172   \clef bass
2173   \new Voice {
2174     \voiceTwo \relative c' {
2175       <fis, a cis>8[ <fis a cis>
2176       \change Staff = up
2177       cis' cis
2178       \change Staff = down
2179       <fis, a> <fis a>]
2180       \showStaffSwitch
2181       \change Staff = up
2182       dis'4 |
2183       \change Staff = down
2184       <fis, a cis>4 gis <f a d>2 |
2185     }
2186   }
2187 }
2188
2189 \new PianoStaff {
2190   <<
2191     \context Staff = "up" {
2192       \accidentalStyle neo-modern
2193       \musicA
2194     }
2195     \context Staff = "down" {
2196       \accidentalStyle neo-modern
2197       \musicB
2198     }
2199   >>
2200 }
2201 @end lilypond
2202
2203 @item neo-modern-cautionary
2204
2205 @cindex neo-modern-cautionary accidental style
2206 @cindex accidental style, neo-modern-cautionary
2207
2208 @funindex neo-modern-cautionary
2209
2210 This rule is similar to @code{neo-modern}, but the extra
2211 accidentals are printed as cautionary accidentals.
2212
2213 @lilypond[quote]
2214 musicA = {
2215   <<
2216     \relative c' {
2217       cis'8 fis, bes4 <a cis>8 f bis4 |
2218       cis2. <c, g'>4 |
2219     }
2220     \\
2221     \relative c' {
2222       ais'2 cis, |
2223       fis8 b a4 cis2 |
2224     }
2225   >>
2226 }
2227
2228 musicB = {
2229   \clef bass
2230   \new Voice {
2231     \voiceTwo \relative c' {
2232       <fis, a cis>8[ <fis a cis>
2233       \change Staff = up
2234       cis' cis
2235       \change Staff = down
2236       <fis, a> <fis a>]
2237       \showStaffSwitch
2238       \change Staff = up
2239       dis'4 |
2240       \change Staff = down
2241       <fis, a cis>4 gis <f a d>2 |
2242     }
2243   }
2244 }
2245
2246 \new PianoStaff {
2247   <<
2248     \context Staff = "up" {
2249       \accidentalStyle neo-modern-cautionary
2250       \musicA
2251     }
2252     \context Staff = "down" {
2253       \accidentalStyle neo-modern-cautionary
2254       \musicB
2255     }
2256   >>
2257 }
2258 @end lilypond
2259
2260
2261 @item neo-modern-voice
2262
2263 @cindex neo-modern-voice accidental style
2264 @cindex accidental style, neo-modern-voice
2265
2266 @funindex neo-modern-voice
2267
2268 This rule is used for multivoice accidentals to be read both by
2269 musicians playing one voice and musicians playing all voices.
2270 Accidentals are typeset for each voice as with @code{neo-modern},
2271 but they are canceled across voices in the same @code{Staff}.
2272
2273 @lilypond[quote]
2274 musicA = {
2275   <<
2276     \relative c' {
2277       cis'8 fis, bes4 <a cis>8 f bis4 |
2278       cis2. <c, g'>4 |
2279     }
2280     \\
2281     \relative c' {
2282       ais'2 cis, |
2283       fis8 b a4 cis2 |
2284     }
2285   >>
2286 }
2287
2288 musicB = {
2289   \clef bass
2290   \new Voice {
2291     \voiceTwo \relative c' {
2292       <fis, a cis>8[ <fis a cis>
2293       \change Staff = up
2294       cis' cis
2295       \change Staff = down
2296       <fis, a> <fis a>]
2297       \showStaffSwitch
2298       \change Staff = up
2299       dis'4 |
2300       \change Staff = down
2301       <fis, a cis>4 gis <f a d>2 |
2302     }
2303   }
2304 }
2305
2306 \new PianoStaff {
2307   <<
2308     \context Staff = "up" {
2309       \accidentalStyle neo-modern-voice
2310       \musicA
2311     }
2312     \context Staff = "down" {
2313       \accidentalStyle neo-modern-voice
2314       \musicB
2315     }
2316   >>
2317 }
2318 @end lilypond
2319
2320 @item neo-modern-voice-cautionary
2321
2322 @cindex neo-modern-voice-cautionary accidental style
2323 @cindex accidental style, neo-modern-voice-cautionary
2324
2325 @funindex neo-modern-voice-cautionary
2326
2327 This rule is similar to @code{neo-modern-voice}, but the extra
2328 accidentals are printed as cautionary accidentals.
2329
2330 @lilypond[quote]
2331 musicA = {
2332   <<
2333     \relative c' {
2334       cis'8 fis, bes4 <a cis>8 f bis4 |
2335       cis2. <c, g'>4 |
2336     }
2337     \\
2338     \relative c' {
2339       ais'2 cis, |
2340       fis8 b a4 cis2 |
2341     }
2342   >>
2343 }
2344
2345 musicB = {
2346   \clef bass
2347   \new Voice {
2348     \voiceTwo \relative c' {
2349       <fis, a cis>8[ <fis a cis>
2350       \change Staff = up
2351       cis' cis
2352       \change Staff = down
2353       <fis, a> <fis a>]
2354       \showStaffSwitch
2355       \change Staff = up
2356       dis'4 |
2357       \change Staff = down
2358       <fis, a cis>4 gis <f a d>2 |
2359     }
2360   }
2361 }
2362
2363 \new PianoStaff {
2364   <<
2365     \context Staff = "up" {
2366       \accidentalStyle neo-modern-voice-cautionary
2367       \musicA
2368     }
2369     \context Staff = "down" {
2370       \accidentalStyle neo-modern-voice-cautionary
2371       \musicB
2372     }
2373   >>
2374 }
2375 @end lilypond
2376
2377 @item dodecaphonic
2378
2379 @cindex dodecaphonic accidental style
2380 @cindex dodecaphonic style, neo-modern
2381
2382 @funindex dodecaphonic
2383
2384 This rule reflects a practice introduced by composers at
2385 the beginning of the 20th century, in an attempt to
2386 abolish the hierarchy between natural and non-natural notes.
2387 With this style, @emph{every} note gets an accidental sign,
2388 including natural signs.
2389
2390 @lilypond[quote]
2391 musicA = {
2392   <<
2393     \relative c' {
2394       cis'8 fis, bes4 <a cis>8 f bis4 |
2395       cis2. <c, g'>4 |
2396     }
2397     \\
2398     \relative c' {
2399       ais'2 cis, |
2400       fis8 b a4 cis2 |
2401     }
2402   >>
2403 }
2404
2405 musicB = {
2406   \clef bass
2407   \new Voice {
2408     \voiceTwo \relative c' {
2409       <fis, a cis>8[ <fis a cis>
2410       \change Staff = up
2411       cis' cis
2412       \change Staff = down
2413       <fis, a> <fis a>]
2414       \showStaffSwitch
2415       \change Staff = up
2416       dis'4 |
2417       \change Staff = down
2418       <fis, a cis>4 gis <f a d>2 |
2419     }
2420   }
2421 }
2422
2423 \new PianoStaff {
2424   <<
2425     \context Staff = "up" {
2426       \accidentalStyle dodecaphonic
2427       \musicA
2428     }
2429     \context Staff = "down" {
2430       \accidentalStyle dodecaphonic
2431       \musicB
2432     }
2433   >>
2434 }
2435 @end lilypond
2436
2437 @item dodecaphonic-no-repeat
2438
2439 @cindex dodecaphonic accidental style
2440 @cindex dodecaphonic style, neo-modern
2441
2442 @funindex dodecaphonic-no-repeat
2443
2444 Like with the dodecaphonic accidental style @emph{every} note
2445 gets an accidental sign by default, but accidentals are
2446 suppressed for pitches immediately repeated within one voice.
2447
2448 @lilypond[quote]
2449 musicA = {
2450   <<
2451     \relative c' {
2452       cis'8 fis, bes4 <a cis>8 f bis4 |
2453       cis2. <c, g'>4 |
2454     }
2455     \\
2456     \relative c' {
2457       ais'2 cis, |
2458       fis8 b a4 cis2 |
2459     }
2460   >>
2461 }
2462
2463 musicB = {
2464   \clef bass
2465   \new Voice {
2466     \voiceTwo \relative c' {
2467       <fis, a cis>8[ <fis a cis>
2468       \change Staff = up
2469       cis' cis
2470       \change Staff = down
2471       <fis, a> <fis a>]
2472       \showStaffSwitch
2473       \change Staff = up
2474       dis'4 |
2475       \change Staff = down
2476       <fis, a cis>4 gis <f a d>2 |
2477     }
2478   }
2479 }
2480
2481 \new PianoStaff {
2482   <<
2483     \context Staff = "up" {
2484       \accidentalStyle dodecaphonic-no-repeat
2485       \musicA
2486     }
2487     \context Staff = "down" {
2488       \accidentalStyle dodecaphonic-no-repeat
2489       \musicB
2490     }
2491   >>
2492 }
2493 @end lilypond
2494
2495
2496 @item dodecaphonic-first
2497
2498 @cindex dodecaphonic accidental style
2499 @cindex dodecaphonic style, neo-modern
2500
2501 @funindex dodecaphonic-first
2502
2503 Similar to the dodecaphonic accidental style @emph{every} pitch
2504 gets an accidental sign, but only the first time it is encountered
2505 in a measure.  Accidentals are only remembered for the actual octave
2506 but throughout voices.
2507
2508 @lilypond[quote]
2509 musicA = {
2510   <<
2511     \relative c' {
2512       cis'8 fis, bes4 <a cis>8 f bis4 |
2513       cis2. <c, g'>4 |
2514     }
2515     \\
2516     \relative c' {
2517       ais'2 cis, |
2518       fis8 b a4 cis2 |
2519     }
2520   >>
2521 }
2522
2523 musicB = {
2524   \clef bass
2525   \new Voice {
2526     \voiceTwo \relative c' {
2527       <fis, a cis>8[ <fis a cis>
2528       \change Staff = up
2529       cis' cis
2530       \change Staff = down
2531       <fis, a> <fis a>]
2532       \showStaffSwitch
2533       \change Staff = up
2534       dis'4 |
2535       \change Staff = down
2536       <fis, a cis>4 gis <f a d>2 |
2537     }
2538   }
2539 }
2540
2541 \new PianoStaff {
2542   <<
2543     \context Staff = "up" {
2544       \accidentalStyle dodecaphonic-first
2545       \musicA
2546     }
2547     \context Staff = "down" {
2548       \accidentalStyle dodecaphonic-first
2549       \musicB
2550     }
2551   >>
2552 }
2553 @end lilypond
2554
2555
2556 @item teaching
2557
2558 @cindex teaching accidental style
2559 @cindex accidental style, teaching
2560
2561 @funindex teaching
2562
2563 This rule is intended for students, and makes it easy to create
2564 scale sheets with automatically created cautionary accidentals.
2565 Accidentals are printed like with @code{modern}, but cautionary
2566 accidentals are added for all sharp or flat tones specified by the
2567 key signature, except if the note is immediately repeated.
2568
2569 @lilypond[quote,staffsize=18]
2570 musicA = {
2571   <<
2572     \relative c' {
2573       cis'8 fis, bes4 <a cis>8 f bis4 |
2574       cis2. <c, g'>4 |
2575     }
2576     \\
2577     \relative c' {
2578       ais'2 cis, |
2579       fis8 b a4 cis2 |
2580     }
2581   >>
2582 }
2583
2584 musicB = {
2585   \clef bass
2586   \new Voice {
2587     \voiceTwo \relative c' {
2588       <fis, a cis>8[ <fis a cis>
2589       \change Staff = up
2590       cis' cis
2591       \change Staff = down
2592       <fis, a> <fis a>]
2593       \showStaffSwitch
2594       \change Staff = up
2595       dis'4 |
2596       \change Staff = down
2597       <fis, a cis>4 gis <f a d>2 |
2598     }
2599   }
2600 }
2601
2602 \new PianoStaff {
2603   <<
2604     \context Staff = "up" {
2605       \key fis \minor
2606       \accidentalStyle teaching
2607       \musicA
2608     }
2609     \context Staff = "down" {
2610       \key fis \minor
2611       \accidentalStyle teaching
2612       \musicB
2613     }
2614   >>
2615 }
2616 @end lilypond
2617
2618
2619
2620 @item no-reset
2621
2622 @cindex accidental style, no reset
2623 @cindex no reset accidental style
2624
2625 @funindex no-reset
2626
2627 This is the same as @code{default} but with accidentals lasting
2628 @q{forever} and not only within the same measure:
2629
2630 @lilypond[quote]
2631 musicA = {
2632   <<
2633     \relative c' {
2634       cis'8 fis, bes4 <a cis>8 f bis4 |
2635       cis2. <c, g'>4 |
2636     }
2637     \\
2638     \relative c' {
2639       ais'2 cis, |
2640       fis8 b a4 cis2 |
2641     }
2642   >>
2643 }
2644
2645 musicB = {
2646   \clef bass
2647   \new Voice {
2648     \voiceTwo \relative c' {
2649       <fis, a cis>8[ <fis a cis>
2650       \change Staff = up
2651       cis' cis
2652       \change Staff = down
2653       <fis, a> <fis a>]
2654       \showStaffSwitch
2655       \change Staff = up
2656       dis'4 |
2657       \change Staff = down
2658       <fis, a cis>4 gis <f a d>2 |
2659     }
2660   }
2661 }
2662
2663 \new PianoStaff {
2664   <<
2665     \context Staff = "up" {
2666       \accidentalStyle no-reset
2667       \musicA
2668     }
2669     \context Staff = "down" {
2670       \accidentalStyle no-reset
2671       \musicB
2672     }
2673   >>
2674 }
2675 @end lilypond
2676
2677 @item forget
2678
2679 @cindex forget accidental style
2680 @cindex accidental style, forget
2681
2682 @funindex forget
2683
2684 This is the opposite of @code{no-reset}: Accidentals are not
2685 remembered at all -- and hence all accidentals are typeset
2686 relative to the key signature, regardless of what came before in
2687 the music.
2688
2689 @lilypond[quote]
2690 musicA = {
2691   <<
2692     \relative c' {
2693       cis'8 fis, bes4 <a cis>8 f bis4 |
2694       cis2. <c, g'>4 |
2695     }
2696     \\
2697     \relative c' {
2698       ais'2 cis, |
2699       fis8 b a4 cis2 |
2700     }
2701   >>
2702 }
2703
2704 musicB = {
2705   \clef bass
2706   \new Voice {
2707     \voiceTwo \relative c' {
2708       <fis, a cis>8[ <fis a cis>
2709       \change Staff = up
2710       cis' cis
2711       \change Staff = down
2712       <fis, a> <fis a>]
2713       \showStaffSwitch
2714       \change Staff = up
2715       dis'4 |
2716       \change Staff = down
2717       <fis, a cis>4 gis <f a d>2 |
2718     }
2719   }
2720 }
2721
2722 \new PianoStaff {
2723   <<
2724     \context Staff = "up" {
2725       \accidentalStyle forget
2726       \musicA
2727     }
2728     \context Staff = "down" {
2729       \accidentalStyle forget
2730       \musicB
2731     }
2732   >>
2733 }
2734 @end lilypond
2735 @end table
2736
2737 @seealso
2738 Snippets:
2739 @rlsr{Pitches}.
2740
2741 Internals Reference:
2742 @rinternals{Accidental},
2743 @rinternals{Accidental_engraver},
2744 @rinternals{GrandStaff},
2745 @rinternals{PianoStaff},
2746 @rinternals{Staff},
2747 @rinternals{AccidentalSuggestion},
2748 @rinternals{AccidentalPlacement},
2749 @rinternals{accidental-suggestion-interface}.
2750
2751 @cindex accidentals and simultaneous notes
2752 @cindex simultaneous notes and accidentals
2753 @cindex accidentals in chords
2754 @cindex chords, accidentals in
2755
2756 @knownissues
2757 Simultaneous notes are not considered in the automatic
2758 determination of accidentals; only previous notes and the key
2759 signature are considered.  Forcing accidentals with@tie{}@code{!}
2760 or@tie{}@code{?} may be required when the same note name occurs
2761 simultaneously with different alterations, as in @samp{<f! fis!>}.
2762
2763 Cautionary cancellation of accidentals is done by looking at previous measure.
2764 However, in the @code{\alternative} block following a @code{\repeat volta N}
2765 section, one would expect the cancellation being calculated using the previous
2766 @emph{played} measure, not previous @emph{printed} measure.
2767 In the following example, the natural @code{c} in the second alternative does
2768 not need a natural sign:
2769
2770 @lilypond[quote]
2771 {
2772   \accidentalStyle modern
2773   \time 2/4
2774   \repeat volta 2 {
2775     c'2
2776   }
2777   \alternative {
2778      cis'
2779      c'
2780   }
2781 }
2782 @end lilypond
2783
2784 The following work-around can be used: define a function that locally changes
2785 the accidental style to @code{forget}:
2786
2787 @lilypond[verbatim,quote]
2788 forget = #(define-music-function (parser location music) (ly:music?) #{
2789   \accidentalStyle forget
2790   #music
2791   \accidentalStyle modern
2792 #})
2793 {
2794   \accidentalStyle modern
2795   \time 2/4
2796   \repeat volta 2 {
2797     c'2
2798   }
2799   \alternative {
2800      cis'
2801      \forget c'
2802   }
2803 }
2804 @end lilypond
2805
2806
2807 @node Ambitus
2808 @unnumberedsubsubsec Ambitus
2809
2810 @cindex ambitus
2811 @cindex range of pitches
2812 @cindex pitch range
2813
2814 The term @notation{ambitus} (pl. ambitus) denotes a range of
2815 pitches for a given voice in a part of music.  It may also denote
2816 the pitch range that a musical instrument is capable of playing.
2817 Ambitus are printed on vocal parts so that performers can easily
2818 determine if it matches their capabilities.
2819
2820 Ambitus are denoted at the beginning of a piece near the initial
2821 clef.  The range is graphically specified by two note heads that
2822 represent the lowest and highest pitches.  Accidentals are only
2823 printed if they are not part of the key signature.
2824
2825 @lilypond[verbatim,quote]
2826 \layout {
2827   \context {
2828     \Voice
2829     \consists "Ambitus_engraver"
2830   }
2831 }
2832
2833 \relative c'' {
2834   aes c e2
2835   cis,1
2836 }
2837 @end lilypond
2838
2839
2840 @snippets
2841
2842 @lilypondfile[verbatim,quote,texidoc,doctitle]
2843 {adding-ambitus-per-voice.ly}
2844
2845 @lilypondfile[verbatim,quote,texidoc,doctitle]
2846 {ambitus-with-multiple-voices.ly}
2847
2848 @lilypondfile[verbatim,quote,texidoc,doctitle]
2849 {changing-the-ambitus-gap.ly}
2850
2851 @seealso
2852 Music Glossary:
2853 @rglos{ambitus}.
2854
2855 Snippets:
2856 @rlsr{Pitches}.
2857
2858 Internals Reference:
2859 @rinternals{Ambitus_engraver},
2860 @rinternals{Voice},
2861 @rinternals{Staff},
2862 @rinternals{Ambitus},
2863 @rinternals{AmbitusAccidental},
2864 @rinternals{AmbitusLine},
2865 @rinternals{AmbitusNoteHead},
2866 @rinternals{ambitus-interface}.
2867
2868 @knownissues
2869 There is no collision handling in the case of multiple per-voice
2870 ambitus.
2871
2872
2873 @node Note heads
2874 @subsection Note heads
2875
2876 This section suggests ways of altering note heads.
2877
2878 @menu
2879 * Special note heads::
2880 * Easy notation note heads::
2881 * Shape note heads::
2882 * Improvisation::
2883 @end menu
2884
2885 @node Special note heads
2886 @unnumberedsubsubsec Special note heads
2887
2888 @cindex note heads, special
2889 @cindex note heads, cross
2890 @cindex note heads, diamond
2891 @cindex note heads, parlato
2892 @cindex note heads, harmonic
2893 @cindex note heads, guitar
2894 @cindex special note heads
2895 @cindex cross note heads
2896 @cindex diamond note heads
2897 @cindex parlato note heads
2898 @cindex harmonic note heads
2899 @cindex guitar note heads
2900 @cindex note head styles
2901 @cindex styles, note heads
2902
2903 @funindex cross
2904
2905 The appearance of note heads may be altered:
2906
2907 @lilypond[verbatim,quote,relative=2]
2908 c4 b
2909 \override NoteHead.style = #'cross
2910 c4 b
2911 \revert NoteHead.style
2912 a b
2913 \override NoteHead.style = #'harmonic
2914 a b
2915 \revert NoteHead.style
2916 c4 d e f
2917 @end lilypond
2918
2919 To see all note head styles, see @ref{Note head styles}.
2920
2921 The @code{cross} style is used to represent a variety of musical
2922 intentions.  The following generic predefined commands modify the
2923 note head in both staff and tablature contexts and can be used to
2924 represent any musical meaning:
2925
2926 @lilypond[verbatim,quote,relative=2]
2927 c4 b
2928 \xNotesOn
2929  a b c4 b
2930 \xNotesOff
2931 c4 d
2932 @end lilypond
2933
2934 The music function form of this predefined command may be used
2935 inside and outside chords to generate crossed note heads in both
2936 staff and tablature contexts:
2937
2938 @lilypond[verbatim,quote,relative=2]
2939 c4 b
2940 \xNote { e f }
2941 c b < g \xNote c f > b
2942 @end lilypond
2943
2944 As synonyms for @code{\xNote}, @code{\xNotesOn} and @code{\xNotesOff},
2945 @code{\deadNote}, @code{\deadNotesOn} and @code{\deadNotesOff} can
2946 be used.  The term @notation{dead note} is commonly used by guitarists.
2947
2948 There is also a similar shorthand for diamond shapes:
2949
2950 @lilypond[verbatim,quote,relative=2]
2951 <c f\harmonic>2 <d a'\harmonic>4 <c g'\harmonic> f\harmonic
2952 @end lilypond
2953
2954 @predefined
2955 @code{\harmonic},
2956 @code{\xNotesOn},
2957 @code{\xNotesOff},
2958 @code{\xNote}.
2959 @endpredefined
2960
2961 @seealso
2962 Snippets:
2963 @rlsr{Pitches}.
2964
2965 Notation Reference:
2966 @ref{Note head styles},
2967 @ref{Chorded notes},
2968 @ref{Indicating harmonics and dampened notes}.
2969
2970 Internals Reference:
2971 @rinternals{note-event},
2972 @rinternals{Note_heads_engraver},
2973 @rinternals{Ledger_line_engraver},
2974 @rinternals{NoteHead},
2975 @rinternals{LedgerLineSpanner},
2976 @rinternals{note-head-interface},
2977 @rinternals{ledger-line-spanner-interface}.
2978
2979
2980 @node Easy notation note heads
2981 @unnumberedsubsubsec Easy notation note heads
2982
2983 @cindex note heads, practice
2984 @cindex practice note heads
2985 @cindex note heads, easy notation
2986 @cindex easy notation
2987 @cindex beginners' music
2988 @cindex music, beginners'
2989 @cindex easy play note heads
2990 @cindex note heads, easy play
2991
2992 @funindex \easyHeadsOn
2993 @funindex easyHeadsOn
2994 @funindex \easyHeadsOff
2995 @funindex easyHeadsOff
2996
2997 The @q{easy play} note head includes a note name inside the head.
2998 It is used in music for beginners.  To make the letters readable,
2999 it should be printed in a large font size.  To print with a larger
3000 font, see @ref{Setting the staff size}.
3001
3002 @lilypond[verbatim,quote]
3003 #(set-global-staff-size 26)
3004 \relative c' {
3005   \easyHeadsOn
3006   c2 e4 f
3007   g1
3008   \easyHeadsOff
3009   c,1
3010 }
3011 @end lilypond
3012
3013
3014 @predefined
3015 @code{\easyHeadsOn},
3016 @code{\easyHeadsOff}.
3017 @endpredefined
3018
3019
3020 @snippets
3021
3022 @lilypondfile[verbatim,quote,texidoc,doctitle]
3023 {numbers-as-easy-note-heads.ly}
3024
3025 @seealso
3026 Notation Reference:
3027 @ref{Setting the staff size}.
3028
3029 Snippets:
3030 @rlsr{Pitches}.
3031
3032 Internals Reference:
3033 @rinternals{note-event},
3034 @rinternals{Note_heads_engraver},
3035 @rinternals{NoteHead},
3036 @rinternals{note-head-interface}.
3037
3038
3039 @node Shape note heads
3040 @unnumberedsubsubsec Shape note heads
3041
3042 @cindex note heads, shape
3043 @cindex note heads, Aiken
3044 @cindex note heads, sacred harp
3045 @cindex shape notes
3046 @cindex Aiken shape note heads
3047 @cindex sacred harp note heads
3048 @cindex note heads, Southern Harmony
3049 @cindex Southern Harmony note heads
3050 @cindex Funk shape note heads
3051 @cindex note heads, Funk
3052 @cindex note heads, Harmonica Sacra
3053 @cindex Harmonica Sacra note heads
3054 @cindex Christian Harmony note heads
3055 @cindex note heads, Christian Harmony
3056 @cindex Walker shape note heads
3057 @cindex note heads, Walker
3058
3059 @funindex \aikenHeads
3060 @funindex aikenHeads
3061 @funindex \sacredHarpHeads
3062 @funindex sacredHarpHeads
3063 @funindex \southernHarmonyHeads
3064 @funindex southernHarmonyHeads
3065 @funindex \funkHeads
3066 @funindex funkHeads
3067 @funindex \walkerHeads
3068 @funindex walkerHeads
3069
3070 In shape note head notation, the shape of the note head
3071 corresponds to the harmonic function of a note in the scale.  This
3072 notation was popular in nineteenth-century American song books.
3073 Shape note heads can be produced in Sacred Harp, Southern Harmony,
3074 Funk (Harmonica Sacra), Walker, and Aiken (Christian Harmony) styles:
3075
3076 @lilypond[verbatim,quote,relative=2]
3077 \aikenHeads
3078 c, d e f g2 a b1 c \break
3079 \sacredHarpHeads
3080 c,4 d e f g2 a b1 c \break
3081 \southernHarmonyHeads
3082 c,4 d e f g2 a b1 c \break
3083 \funkHeads
3084 c,4 d e f g2 a b1 c \break
3085 \walkerHeads
3086 c,4 d e f g2 a b1 c \break
3087 @end lilypond
3088
3089 @funindex \key
3090 @funindex key
3091 @funindex \aikenHeadsMinor
3092 @funindex aikenHeadsMinor
3093 @funindex \sacredHarpHeadsMinor
3094 @funindex sacredHarpHeadsMinor
3095 @funindex \southernHarmonyHeadsMinor
3096 @funindex southernHarmonyHeadsMinor
3097 @funindex \funkHeadsMinor
3098 @funindex funkHeadsMinor
3099 @funindex \walkerHeadsMinor
3100 @funindex walkerHeadsMinor
3101
3102 Shapes are typeset according to the step in the scale, where the base
3103 of the scale is determined by the @code{\key} command.  When writing
3104 in a minor key, the scale step can be determined from the relative
3105 major:
3106
3107 @lilypond[verbatim,quote,relative=2]
3108 \key a \minor
3109 \aikenHeads
3110 a b c d e2 f g1 a \break
3111 \aikenHeadsMinor
3112 a,4 b c d e2 f g1 a \break
3113 \sacredHarpHeadsMinor
3114 a,2 b c d \break
3115 \southernHarmonyHeadsMinor
3116 a2 b c d \break
3117 \funkHeadsMinor
3118 a2 b c d \break
3119 \walkerHeadsMinor
3120 a2 b c d \break
3121
3122 @end lilypond
3123
3124
3125 @predefined
3126 @code{\aikenHeads},
3127 @code{\aikenHeadsMinor},
3128 @code{\funkHeads},
3129 @code{\funkHeadsMinor},
3130 @code{\sacredHarpHeads},
3131 @code{\sacredHarpHeadsMinor},
3132 @code{\southernHarmonyHeads},
3133 @code{\southernHarmonyHeadsMinor},
3134 @code{\walkerHeads},
3135 @code{\walkerHeadsMinor}.
3136 @endpredefined
3137
3138
3139 @snippets
3140
3141 @lilypondfile[verbatim,quote,texidoc,doctitle]
3142 {applying-note-head-styles-depending-on-the-step-of-the-scale.ly}
3143
3144 To see all note head styles, see @ref{Note head styles}.
3145
3146 @seealso
3147 Snippets:
3148 @rlsr{Pitches}.
3149
3150 Notation Reference:
3151 @ref{Note head styles}.
3152
3153 Internals Reference:
3154 @rinternals{note-event},
3155 @rinternals{Note_heads_engraver},
3156 @rinternals{NoteHead},
3157 @rinternals{note-head-interface}.
3158
3159
3160 @node Improvisation
3161 @unnumberedsubsubsec Improvisation
3162
3163 @cindex improvisation
3164 @cindex slashed note heads
3165 @cindex note heads, improvisation
3166 @cindex note heads, slashed
3167
3168 @funindex \improvisationOn
3169 @funindex improvisationOn
3170 @funindex \improvisationOff
3171 @funindex improvisationOff
3172
3173 Improvisation is sometimes denoted with slashed note heads, where
3174 the performer may choose any pitch but should play the specified
3175 rhythm.  Such note heads can be created:
3176
3177 @lilypond[verbatim,quote,relative=2]
3178 \new Voice \with {
3179   \consists "Pitch_squash_engraver"
3180 } {
3181   e8 e g a a16( bes) a8 g
3182   \improvisationOn
3183   e8 ~
3184   2 ~ 8 f4 f8 ~
3185   2
3186   \improvisationOff
3187   a16( bes) a8 g e
3188 }
3189 @end lilypond
3190
3191 @predefined
3192 @code{\improvisationOn},
3193 @code{\improvisationOff}.
3194 @endpredefined
3195
3196 @seealso
3197 Snippets:
3198 @rlsr{Pitches}.
3199
3200 Internals Reference:
3201 @rinternals{Pitch_squash_engraver},
3202 @rinternals{Voice},
3203 @rinternals{RhythmicStaff}.