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