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.6"
  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 @seealso
  91 Music Glossary:
  92 @rglos{Pitch names}.
  93
  94 Snippets:
  95 @rlsr{Pitches}.
  96
  97
  98 @node Relative octave entry
  99 @unnumberedsubsubsec Relative octave entry
 100
 101 @cindex relative
 102 @cindex relative octave entry
 103 @cindex octave entry, relative
 104 @cindex relative octave specification
 105 @cindex octave specification, relative
 106
 107 @funindex relative
 108 @funindex \relative
 109
 110 When octaves are specified in absolute mode it is easy to
 111 accidentally put a pitch in the wrong octave.  Relative octave
 112 mode reduces these errors since most of the time it is not
 113 necessary to indicate any octaves at all.  Furthermore, in
 114 absolute mode a single mistake may be difficult to spot, while in
 115 relative mode a single error puts the rest of the piece off by one
 116 octave.
 117
 118 @example
 119 \relative @var{startpitch} @var{musicexpr}
 120 @end example
 121
 122 In relative mode, each note is assumed to be as close to the
 123 previous note as possible.  This means that the octave of each
 124 pitch inside @code{@var{musicexpr}} is calculated as follows:
 125
 126 @itemize
 127 @item
 128 If no octave changing mark is used on a pitch, its octave is
 129 calculated so that the interval with the previous note is less
 130 than a fifth.  This interval is determined without considering
 131 accidentals.
 132
 133 @item
 134 An octave changing mark@tie{}@code{'} or@tie{}@code{,} can be
 135 added to respectively raise or lower a pitch by an extra octave,
 136 relative to the pitch calculated without an octave mark.
 137
 138 @item
 139 Multiple octave changing marks can be used.  For example,
 140 @code{''}@tie{}and@tie{}@code{,,} will alter the pitch by two
 141 octaves.
 142
 143 @item
 144 The pitch of the first note is relative to
 145 @code{@var{startpitch}}.  @code{@var{startpitch}} is specified in
 146 absolute octave mode.  Which choices are meaningful?
 147
 148 @table @asis
 149 @item an octave of @code{c}
 150 Identifying middle C with @code{c'} is quite basic, so finding
 151 octaves of @code{c} tends to be straightforward.  If your music
 152 starts with @code{gis} above @code{c'''}, you'd write something
 153 like @code{\relative c''' @{ gis' @dots{} @}}
 154
 155 @item an octave of the first note inside
 156 Writing @code{\relative gis''' @{ gis @dots{} @}} makes it easy to
 157 determine the absolute pitch of the first note inside.
 158
 159 @item no explicit starting pitch
 160 This (namely writing @code{\relative @{ gis''' @dots{} @}}) can be
 161 viewed as a compact version of the previous option: the first note
 162 inside is written in absolute pitch itself.  This happens to be
 163 equivalent to choosing @code{f} as the reference pitch.
 164 @end table
 165
 166 The documentation will usually employ the first option.
 167 @end itemize
 168
 169 Here is the relative mode shown in action:
 170
 171 @lilypond[verbatim,quote]
 172 \relative c {
 173   \clef bass
 174   c d e f
 175   g a b c
 176   d e f g
 177 }
 178 @end lilypond
 179
 180 Octave changing marks are used for intervals greater than a
 181 fourth:
 182
 183 @lilypond[verbatim,quote]
 184 \relative c'' {
 185   c g c f,
 186   c' a, e'' c
 187 }
 188 @end lilypond
 189
 190 A note sequence without a single octave mark can nevertheless span
 191 large intervals:
 192
 193 @lilypond[verbatim,quote]
 194 \relative c {
 195   c f b e
 196   a d g c
 197 }
 198 @end lilypond
 199
 200 When @code{\relative} blocks are nested, the innermost
 201 @code{\relative} block applies.
 202
 203 @lilypond[verbatim,quote]
 204 \relative c' {
 205   c d e f
 206   \relative c'' {
 207     c d e f
 208   }
 209 }
 210 @end lilypond
 211
 212 @code{\relative} has no effect on @code{\chordmode} blocks.
 213
 214 @lilypond[verbatim,quote]
 215 \new Staff {
 216   \relative c''' {
 217     \chordmode { c1 }
 218   }
 219   \chordmode { c1 }
 220 }
 221 @end lilypond
 222
 223 @code{\relative} is not allowed inside of @code{\chordmode} blocks.
 224
 225 Music inside a @code{\transpose} block is absolute unless a
 226 @code{\relative} is included.
 227
 228 @lilypond[verbatim,quote]
 229 \relative c' {
 230   d e
 231   \transpose f g {
 232     d e
 233     \relative c' {
 234       d e
 235     }
 236   }
 237 }
 238 @end lilypond
 239
 240
 241 @cindex chords and relative octave entry
 242 @cindex relative octave entry and chords
 243
 244 If the preceding item is a chord, the first note of the chord is
 245 used as the reference point for the octave placement of a
 246 following note or chord.  Inside chords, the next note is always
 247 relative to the preceding one.  Examine the next example
 248 carefully, paying attention to the @code{c} notes.
 249
 250 @lilypond[verbatim,quote]
 251 \relative c' {
 252   c
 253   <c e g>
 254   <c' e g'>
 255   <c, e, g''>
 256 }
 257 @end lilypond
 258
 259 As explained above, the octave of pitches is calculated only with
 260 the note names, regardless of any alterations.  Therefore, an
 261 E-double-sharp following a B will be placed higher, while an
 262 F-double-flat will be placed lower.  In other words, a
 263 double-augmented fourth is considered a smaller interval than a
 264 double-diminished fifth, regardless of the number of semitones
 265 that each interval contains.
 266
 267 @lilypond[verbatim,quote]
 268 \relative c'' {
 269   c2 fis
 270   c2 ges
 271   b2 eisis
 272   b2 feses
 273 }
 274 @end lilypond
 275
 276 One consequence of these rules is that the first note inside
 277 @code{@w{\relative f}} music is interpreted just the same as
 278 if it was written in absolute pitch mode.
 279
 280 @seealso
 281 Music Glossary:
 282 @rglos{fifth},
 283 @rglos{interval},
 284 @rglos{Pitch names}.
 285
 286 Notation Reference:
 287 @ref{Octave checks}.
 288
 289 Snippets:
 290 @rlsr{Pitches}.
 291
 292 Internals Reference:
 293 @rinternals{RelativeOctaveMusic}.
 294
 295 @cindex relative octave entry and transposition
 296 @cindex transposition and relative octave entry
 297
 298 @funindex \transpose
 299 @funindex transpose
 300 @funindex \chordmode
 301 @funindex chordmode
 302 @funindex \relative
 303 @funindex relative
 304
 305 @c DEPRECATED
 306 If no @code{@var{startpitch}} is specified for @code{\relative},
 307 then@tie{}@code{c'} is assumed.  However, this is a deprecated
 308 option and may disappear in future versions, so its use is
 309 discouraged.
 310
 311
 312 @node Accidentals
 313 @unnumberedsubsubsec Accidentals
 314
 315 @cindex accidental
 316 @cindex key signature
 317 @cindex clef
 318
 319 @c duplicated in Key signature and Accidentals
 320 @warning{New users are sometimes confused about accidentals and
 321 key signatures.  In LilyPond, note names are the raw input; key
 322 signatures and clefs determine how this raw input is displayed.
 323 An unaltered note like@tie{}@code{c} means @q{C natural},
 324 regardless of the key signature or clef.  For more information,
 325 see @rlearning{Accidentals and key signatures}.}
 326
 327 @cindex note names, Dutch
 328 @cindex note names, default
 329 @cindex default note names
 330 @cindex sharp
 331 @cindex flat
 332 @cindex double sharp
 333 @cindex sharp, double
 334 @cindex double flat
 335 @cindex flat, double
 336 @cindex natural sign
 337 @cindex natural pitch
 338
 339 A @notation{sharp} pitch is made by adding @code{is} to the note
 340 name, and a @notation{flat} pitch by adding @code{es}.  As you
 341 might expect, a @notation{double sharp} or @notation{double flat}
 342 is made by adding @code{isis} or @code{eses}.  This syntax is
 343 derived from Dutch note naming conventions.  To use other names
 344 for accidentals, see @ref{Note names in other languages}.
 345
 346 @lilypond[verbatim,quote,relative=2]
 347 ais1 aes aisis aeses
 348 @end lilypond
 349
 350 A natural will cancel the effect of an accidental or key
 351 signature.  However, naturals are not encoded into the note name
 352 syntax with a suffix; a natural pitch is shown as a simple note
 353 name:
 354
 355 @lilypond[verbatim,quote,relative=2]
 356 a4 aes a2
 357 @end lilypond
 358
 359 @cindex quarter tones
 360 @cindex semi-flats
 361 @cindex semi-sharps
 362
 363 Quarter tones may be added; the following is a series of Cs with
 364 increasing pitches:
 365
 366 @lilypond[verbatim,quote,relative=2]
 367 ceseh1 ces ceh c cih cis cisih
 368 @end lilypond
 369
 370
 371
 372 @cindex accidental, reminder
 373 @cindex accidental, cautionary
 374 @cindex accidental, parenthesized
 375 @cindex reminder accidental
 376 @cindex cautionary accidental
 377 @cindex parenthesized accidental
 378
 379 @funindex ?
 380 @funindex !
 381
 382
 383 Normally accidentals are printed automatically, but you may also
 384 print them manually.  A reminder accidental can be forced by
 385 adding an exclamation mark@tie{}@code{!} after the pitch.  A
 386 cautionary accidental (i.e., an accidental within parentheses) can
 387 be obtained by adding the question mark@tie{}@code{?} after the
 388 pitch.  These extra accidentals can also be used to produce
 389 natural signs.
 390
 391 @lilypond[verbatim,quote,relative=2]
 392 cis cis cis! cis? c c c! c?
 393 @end lilypond
 394
 395 @cindex accidental on tied note
 396 @cindex tied note, accidental
 397
 398 Accidentals on tied notes are only printed at the beginning of a
 399 new system:
 400
 401 @lilypond[verbatim,quote,relative=2]
 402 cis1~ cis~
 403 \break
 404 cis
 405 @end lilypond
 406
 407
 408 @snippets
 409
 410 @lilypondfile[verbatim,quote,texidoc,doctitle,ragged-right]
 411 {hiding-accidentals-on-tied-notes-at-the-start-of-a-new-system.ly}
 412
 413 @lilypondfile[verbatim,quote,texidoc,doctitle]
 414 {preventing-extra-naturals-from-being-automatically-added.ly}
 415
 416 @seealso
 417 Music Glossary:
 418 @rglos{sharp},
 419 @rglos{flat},
 420 @rglos{double sharp},
 421 @rglos{double flat},
 422 @rglos{Pitch names},
 423 @rglos{quarter tone}.
 424
 425 Learning Manual:
 426 @rlearning{Accidentals and key signatures}.
 427
 428 Notation Reference:
 429 @ref{Automatic accidentals},
 430 @ref{Annotational accidentals (musica ficta)},
 431 @ref{Note names in other languages}.
 432
 433 Snippets:
 434 @rlsr{Pitches}.
 435
 436 Internals Reference:
 437 @rinternals{Accidental_engraver},
 438 @rinternals{Accidental},
 439 @rinternals{AccidentalCautionary},
 440 @rinternals{accidental-interface}.
 441
 442 @cindex accidental, quarter-tone
 443 @cindex quarter-tone accidental
 444
 445 @knownissues
 446 There are no generally accepted standards for denoting
 447 quarter-tone accidentals, so LilyPond's symbol does not conform to
 448 any standard.
 449
 450
 451 @node Note names in other languages
 452 @unnumberedsubsubsec Note names in other languages
 453
 454 @cindex note names, other languages
 455 @cindex pitch names, other languages
 456 @cindex language, note names in other
 457 @cindex language, pitch names in other
 458
 459 There are predefined sets of note and accidental names for various
 460 other languages.  Selecting the note name language is usually done
 461 at the beginning of the file; the following example is written
 462 using Italian note names:
 463
 464 @lilypond[quote,verbatim]
 465 \language "italiano"
 466
 467 \relative do' {
 468   do re mi sib
 469 }
 470 @end lilypond
 471
 472 The available languages and the note names they define are:
 473
 474 @quotation
 475 @multitable {@code{nederlands}} {do re mi fa sol la sib si}
 476 @headitem Language
 477   @tab Note Names
 478 @item @code{nederlands}
 479   @tab c d e f g a bes b
 480 @item @code{catalan}
 481   @tab do re mi fa sol la sib si
 482 @item @code{deutsch}
 483   @tab c d e f g a b h
 484 @item @code{english}
 485   @tab c d e f g a bf b
 486 @item @code{espanol} or @code{español}
 487   @tab do re mi fa sol la sib si
 488 @item @code{italiano} or @code{français}
 489   @tab do re mi fa sol la sib si
 490 @item @code{norsk}
 491   @tab c d e f g a b h
 492 @item @code{portugues}
 493   @tab do re mi fa sol la sib si
 494 @item @code{suomi}
 495   @tab c d e f g a b h
 496 @item @code{svenska}
 497   @tab c d e f g a b h
 498 @item @code{vlaams}
 499   @tab do re mi fa sol la sib si
 500 @end multitable
 501 @end quotation
 502
 503 In addition to note names, accidental suffixes may
 504 also vary depending on the language:
 505
 506 @quotation
 507 @multitable {@code{nederlands}} {-s/-sharp} {-ess/-es} {-ss/-x/-sharpsharp} {-essess/-eses}
 508 @headitem Language
 509   @tab sharp @tab flat @tab double sharp @tab double flat
 510 @item @code{nederlands}
 511   @tab -is @tab -es @tab -isis @tab -eses
 512 @item @code{catalan}
 513   @tab -d/-s @tab -b @tab -dd/-ss @tab -bb
 514 @item @code{deutsch}
 515   @tab -is @tab -es @tab -isis @tab -eses
 516 @item @code{english}
 517   @tab -s/-sharp @tab -f/-flat @tab -ss/-x/-sharpsharp
 518     @tab -ff/-flatflat
 519 @item @code{espanol} or @code{español}
 520   @tab -s @tab -b @tab -ss/-x @tab -bb
 521 @item @code{italiano} or @code{français}
 522   @tab -d @tab -b @tab -dd @tab -bb
 523 @item @code{norsk}
 524   @tab -iss/-is @tab -ess/-es @tab -ississ/-isis
 525     @tab -essess/-eses
 526 @item @code{portugues}
 527   @tab -s @tab -b @tab -ss @tab -bb
 528 @item @code{suomi}
 529   @tab -is @tab -es @tab -isis @tab -eses
 530 @item @code{svenska}
 531   @tab -iss @tab -ess @tab -ississ @tab -essess
 532 @item @code{vlaams}
 533   @tab -k @tab -b @tab -kk @tab -bb
 534 @end multitable
 535 @end quotation
 536
 537 In Dutch, @code{aes} is contracted to @code{as}, but both forms
 538 are accepted in LilyPond.  Similarly, both @code{es} and
 539 @code{ees} are accepted.  This also applies to
 540 @code{aeses}@tie{}/@tie{}@code{ases} and
 541 @code{eeses}@tie{}/@tie{}@code{eses}.  Sometimes only these
 542 contracted names are defined in the corresponding language files.
 543
 544 @lilypond[verbatim,quote,relative=2]
 545 a2 as e es a ases e eses
 546 @end lilypond
 547
 548
 549 @cindex microtones
 550 @cindex semi-sharp
 551 @cindex semi-flat
 552 @cindex sesqui-sharp
 553 @cindex sesqui-flat
 554
 555 Some music uses microtones whose alterations are fractions of a
 556 @q{normal} sharp or flat.  The following table lists note names
 557 for quarter-tone accidentals in various languages; here the prefixes
 558 @notation{semi-} and @notation{sesqui-} respectively
 559 mean @q{half} and @q{one and a half}.  Languages that do not
 560 appear in this table do not provide special note names yet.
 561
 562 @quotation
 563 @multitable {@code{nederlands}} {@b{semi-sharp}} {@b{semi-flat}} {@b{sesqui-sharp}} {@b{sesqui-flat}}
 564 @headitem Language
 565   @tab semi-sharp @tab semi-flat @tab sesqui-sharp @tab sesqui-flat
 566
 567 @item @code{nederlands}
 568   @tab -ih @tab -eh @tab -isih @tab -eseh
 569 @item @code{deutsch}
 570   @tab -ih @tab -eh @tab -isih @tab -eseh
 571 @item @code{english}
 572   @tab -qs @tab -qf @tab -tqs @tab -tqf
 573 @item @code{espanol} or @code{español}
 574   @tab -cs @tab -cb @tab -tcs @tab -tcb
 575 @item @code{italiano} or @code{français}
 576   @tab -sd @tab -sb @tab -dsd @tab -bsb
 577 @item @code{portugues}
 578   @tab -sqt @tab -bqt @tab -stqt @tab -btqt
 579 @end multitable
 580 @end quotation
 581
 582 Most languages presented here are commonly associated with
 583 Western classical music, also referred to as
 584 @notation{Common Practice Period}.  However, alternate
 585 pitches and tuning systems are also supported: see
 586 @ref{Common notation for non-Western music}.
 587
 588 @seealso
 589 Music Glossary:
 590 @rglos{Pitch names},
 591 @rglos{Common Practice Period}.
 592
 593 Notation Reference:
 594 @ref{Common notation for non-Western music}.
 595
 596 Installed Files:
 597 @file{scm/define-note-names.scm}.
 598
 599 Snippets:
 600 @rlsr{Pitches}.
 601
 602
 603 @node Changing multiple pitches
 604 @subsection Changing multiple pitches
 605
 606 This section discusses how to modify pitches.
 607
 608 @menu
 609 * Octave checks::
 610 * Transpose::
 611 * Inversion::
 612 * Retrograde::
 613 * Modal transformations::
 614 @end menu
 615
 616 @node Octave checks
 617 @unnumberedsubsubsec Octave checks
 618
 619 @cindex octave correction
 620 @cindex octave check
 621 @cindex control pitch
 622
 623 @funindex =
 624 @funindex \octaveCheck
 625 @funindex octaveCheck
 626 @funindex controlpitch
 627
 628 In relative mode, it is easy to forget an octave changing mark.
 629 Octave checks make such errors easier to find by displaying a
 630 warning and correcting the octave if a note is found in an
 631 unexpected octave.
 632
 633 To check the octave of a note, specify the absolute octave after
 634 the @code{=}@tie{}symbol.  This example will generate a warning
 635 (and change the pitch) because the second note is the absolute
 636 octave @code{d''} instead of @code{d'} as indicated by the octave
 637 correction.
 638
 639 @lilypond[verbatim,quote]
 640 \relative c'' {
 641   c2 d='4 d
 642   e2 f
 643 }
 644 @end lilypond
 645
 646 The octave of notes may also be checked with the
 647 @code{\octaveCheck@tie{}@var{controlpitch}} command.
 648 @code{@var{controlpitch}} is specified in absolute mode.  This
 649 checks that the interval between the previous note and the
 650 @code{@var{controlpitch}} is within a fourth (i.e., the normal
 651 calculation of relative mode).  If this check fails, a warning is
 652 printed, but the previous note is not changed.  Future notes are
 653 relative to the @code{@var{controlpitch}}.
 654
 655 @lilypond[verbatim,quote]
 656 \relative c'' {
 657   c2 d
 658   \octaveCheck c'
 659   e2 f
 660 }
 661 @end lilypond
 662
 663 Compare the two bars below.  The first and third @code{\octaveCheck}
 664 checks fail, but the second one does not fail.
 665
 666 @lilypond[verbatim,quote]
 667 \relative c'' {
 668   c4 f g f
 669
 670   c4
 671   \octaveCheck c'
 672   f
 673   \octaveCheck c'
 674   g
 675   \octaveCheck c'
 676   f
 677 }
 678 @end lilypond
 679
 680 @seealso
 681 Snippets:
 682 @rlsr{Pitches}.
 683
 684 Internals Reference:
 685 @rinternals{RelativeOctaveCheck}.
 686
 687
 688 @node Transpose
 689 @unnumberedsubsubsec Transpose
 690
 691 @cindex transpose
 692 @cindex transposing
 693 @cindex transposition
 694 @cindex transposition of pitches
 695 @cindex transposition of notes
 696 @cindex pitches, transposition of
 697 @cindex notes, transposition of
 698
 699 @funindex \transpose
 700 @funindex transpose
 701
 702 A music expression can be transposed with @code{\transpose}.  The
 703 syntax is
 704
 705 @example
 706 \transpose @var{frompitch} @var{topitch} @var{musicexpr}
 707 @end example
 708
 709 @noindent
 710 This means that @code{@var{musicexpr}} is transposed by the
 711 interval between the pitches @code{@var{frompitch}} and
 712 @code{@var{topitch}}: any note with pitch @code{@var{frompitch}}
 713 is changed to @code{@var{topitch}} and any other note is
 714 transposed by the same interval.  Both pitches are entered in
 715 absolute mode.
 716
 717 @warning{Music inside a @code{@bs{}transpose} block is absolute
 718 unless a @code{@bs{}relative} is included in the block.}
 719
 720 Consider a piece written in the key of D-major.  It can be
 721 transposed up to E-major; note that the key signature is
 722 automatically transposed as well.
 723
 724 @lilypond[verbatim,quote]
 725 \transpose d e {
 726   \relative c' {
 727     \key d \major
 728     d4 fis a d
 729   }
 730 }
 731 @end lilypond
 732
 733 @cindex transposing instruments
 734 @cindex instruments, transposing
 735
 736 If a part written in C (normal @notation{concert pitch}) is to be
 737 played on the A clarinet (for which an A is notated as a C and
 738 thus sounds a minor third lower than notated), the appropriate
 739 part will be produced with:
 740
 741 @lilypond[verbatim,quote]
 742 \transpose a c' {
 743   \relative c' {
 744     \key c \major
 745     c4 d e g
 746   }
 747 }
 748 @end lilypond
 749
 750 @noindent
 751 Note that we specify @w{@code{\key c \major}} explicitly.  If we
 752 do not specify a key signature, the notes will be transposed but
 753 no key signature will be printed.
 754
 755 @code{\transpose} distinguishes between enharmonic pitches: both
 756 @w{@code{\transpose c cis}} or @w{@code{\transpose c des}} will
 757 transpose up a semitone.  The first version will print sharps and
 758 the notes will remain on the same scale step, the second version
 759 will print flats on the scale step above.
 760
 761 @lilypond[verbatim,quote]
 762 music = \relative c' { c d e f }
 763 \new Staff {
 764   \transpose c cis { \music }
 765   \transpose c des { \music }
 766 }
 767 @end lilypond
 768
 769
 770 @code{\transpose} may also be used in a different way, to input
 771 written notes for a transposing instrument.  The previous examples
 772 show how to enter pitches in C (or @notation{concert pitch}) and
 773 typeset them for a transposing instrument, but the opposite is
 774 also possible if you for example have a set of instrumental parts
 775 and want to print a conductor's score.  For example, when entering
 776 music for a B-flat trumpet that begins on a notated E (concert D),
 777 one would write:
 778
 779 @example
 780 musicInBflat = @{ e4 @dots{} @}
 781 \transpose c bes, \musicInBflat
 782 @end example
 783
 784 @noindent
 785 To print this music in F (e.g., rearranging to a French horn) you
 786 could wrap the existing music with another @code{\transpose}:
 787
 788 @example
 789 musicInBflat = @{ e4 @dots{} @}
 790 \transpose f c' @{ \transpose c bes, \musicInBflat @}
 791 @end example
 792
 793 @noindent
 794 For more information about transposing instruments,
 795 see @ref{Instrument transpositions}.
 796
 797
 798 @snippets
 799
 800 @lilypondfile[verbatim,quote,texidoc,doctitle]
 801 {transposing-pitches-with-minimum-accidentals-smart-transpose.ly}
 802
 803 @seealso
 804 Notation Reference:
 805 @ref{Instrument transpositions},
 806 @ref{Inversion},
 807 @ref{Modal transformations},
 808 @ref{Relative octave entry},
 809 @ref{Retrograde}.
 810
 811 Snippets:
 812 @rlsr{Pitches}.
 813
 814 Internals Reference:
 815 @rinternals{TransposedMusic}.
 816
 817 @funindex \transpose
 818 @funindex transpose
 819 @funindex \chordmode
 820 @funindex chordmode
 821 @funindex \relative
 822 @funindex relative
 823
 824 @knownissues
 825 The relative conversion will not affect @code{\transpose},
 826 @code{\chordmode} or @code{\relative} sections in its argument.  To use
 827 relative mode within transposed music, an additional @code{\relative}
 828 must be placed inside @code{\transpose}.
 829
 830 Triple accidentals will not be printed if using @code{\transpose}. An
 831 @q{enharmonically equivalent} pitch will be used instead (e.g. d-flat
 832 rather than e-triple-flat).
 833
 834
 835 @node Inversion
 836 @unnumberedsubsubsec Inversion
 837
 838 @cindex inversion
 839 @cindex operation, inversion
 840 @funindex \inversion
 841
 842 A music expression can be inverted and transposed in a single
 843 operation with:
 844
 845 @example
 846 \inversion @var{around-pitch} @var{to-pitch} @var{musicexpr}
 847 @end example
 848
 849 The @code{@var{musicexpr}} is inverted interval-by-interval around
 850 @code{@var{around-pitch}}, and then transposed so that
 851 @code{@var{around-pitch}} is mapped to @code{@var{to-pitch}}.
 852
 853 @lilypond[verbatim,quote]
 854 music = \relative c' { c d e f }
 855 \new Staff {
 856   \music
 857   \inversion d' d' \music
 858   \inversion d' ees' \music
 859 }
 860 @end lilypond
 861
 862 @warning{Motifs to be inverted should be expressed in absolute form
 863 or be first converted to absolute form by enclosing them in a
 864 @code{\relative} block.}
 865
 866 @seealso
 867 Notation Reference:
 868 @ref{Modal transformations},
 869 @ref{Retrograde},
 870 @ref{Transpose}.
 871
 872
 873 @node Retrograde
 874 @unnumberedsubsubsec Retrograde
 875
 876 @cindex retrograde transformation
 877 @cindex transformation, retrograde
 878 @cindex operation, retrograde
 879 @funindex \retrograde
 880 @funindex retrograde
 881
 882 A music expression can be reversed to produce its retrograde:
 883
 884 @lilypond[verbatim,quote]
 885 music = \relative c' { c8. ees16( fis8. a16 b8.) gis16 f8. d16 }
 886
 887 \new Staff {
 888   \music
 889   \retrograde \music
 890 }
 891 @end lilypond
 892
 893 @knownissues
 894 Manual ties inside @code{\retrograde} will be broken and
 895 generate warnings.  Some ties can be generated automatically
 896 by enabling @ref{Automatic note splitting}.
 897
 898 @seealso
 899 Notation Reference:
 900 @ref{Inversion},
 901 @ref{Modal transformations},
 902 @ref{Transpose}.
 903
 904
 905 @node Modal transformations
 906 @unnumberedsubsubsec Modal transformations
 907
 908 @cindex modal transformations
 909 @cindex transformations, modal
 910 @cindex operations, modal
 911
 912 In a musical composition that is based on a scale, a motif is
 913 frequently transformed in various ways.  It may be
 914 @notation{transposed} to start at different places in the scale or
 915 it may be @notation{inverted} around a pivot point in the scale.
 916 It may also be reversed to produce its @notation{retrograde}, see
 917 @ref{Retrograde}.
 918
 919 @warning{Any note that does not lie within the given scale will be
 920 left untransformed.}
 921
 922 @subsubsubheading Modal transposition
 923
 924 @cindex modal transposition
 925 @cindex transposition, modal
 926 @cindex operation, transposition
 927 @funindex \modalTranspose
 928 @funindex modalTranspose
 929
 930 A motif can be transposed within a given scale with:
 931
 932 @example
 933 \modalTranspose @var{from-pitch} @var{to-pitch} @var{scale} @var{motif}
 934 @end example
 935
 936 The notes of @var{motif} are shifted within the @var{scale} by the
 937 number of scale degrees given by the interval between @var{to-pitch}
 938 and @var{from-pitch}:
 939
 940 @lilypond[verbatim,quote]
 941 diatonicScale = \relative c' { c d e f g a b }
 942 motif = \relative c' { c8 d e f g a b c }
 943
 944 \new Staff {
 945   \motif
 946   \modalTranspose c f \diatonicScale \motif
 947   \modalTranspose c b, \diatonicScale \motif
 948 }
 949 @end lilypond
 950
 951 An ascending scale of any length and with any intervals may be
 952 specified:
 953
 954 @lilypond[verbatim,quote]
 955 pentatonicScale = \relative c' { ges aes bes des ees }
 956 motif = \relative c' { ees8 des ges,4 <ges' bes,> <ges bes,> }
 957
 958 \new Staff {
 959   \motif
 960   \modalTranspose ges ees' \pentatonicScale \motif
 961 }
 962 @end lilypond
 963
 964 When used with a chromatic scale @code{\modalTranspose} has a
 965 similar effect to @code{\transpose}, but with the ability to
 966 specify the names of the notes to be used:
 967
 968 @lilypond[verbatim,quote]
 969 chromaticScale = \relative c' { c cis d dis e f fis g gis a ais b }
 970 motif = \relative c' { c8 d e f g a b c }
 971
 972 \new Staff {
 973   \motif
 974   \transpose c f \motif
 975   \modalTranspose c f \chromaticScale \motif
 976 }
 977 @end lilypond
 978
 979 @subsubsubheading Modal inversion
 980
 981 @cindex modal inversion
 982 @cindex inversion, modal
 983 @cindex operation, modal inversion
 984 @funindex \modalInversion
 985 @funindex modalInversion
 986
 987 A motif can be inverted within a given scale around a given pivot
 988 note and transposed in a single operation with:
 989
 990 @example
 991 \modalInversion @var{around-pitch} @var{to-pitch} @var{scale} @var{motif}
 992 @end example
 993
 994 The notes of @var{motif} are placed the same number of scale degrees
 995 from the @var{around-pitch} note within the @var{scale}, but in the
 996 opposite direction, and the result is then shifted within the
 997 @var{scale} by the number of scale degrees given by the interval between
 998 @var{to-pitch} and @var{around-pitch}.
 999
1000 So to simply invert around a note in the scale use the same value for
1001 @var{around-pitch} and @var{to-pitch}:
1002
1003 @lilypond[verbatim,quote]
1004 octatonicScale = \relative c' { ees f fis gis a b c d }
1005 motif = \relative c' { c8. ees16 fis8. a16 b8. gis16 f8. d16 }
1006
1007 \new Staff {
1008   \motif
1009   \modalInversion fis' fis' \octatonicScale \motif
1010 }
1011 @end lilypond
1012
1013 To invert around a pivot between two notes in the scale, invert around
1014 one of the notes and then transpose by one scale degree.  The two notes
1015 specified can be interpreted as bracketing the pivot point:
1016
1017 @lilypond[verbatim,quote]
1018 scale = \relative c' { c g' }
1019 motive = \relative c' { c c g' c, }
1020
1021 \new Staff {
1022   \motive
1023   \modalInversion c' g' \scale \motive
1024 }
1025 @end lilypond
1026
1027 The combined operation of inversion and retrograde produce the
1028 retrograde-inversion:
1029
1030 @lilypond[verbatim,quote]
1031 octatonicScale = \relative c' { ees f fis gis a b c d }
1032 motif = \relative c' { c8. ees16 fis8. a16 b8. gis16 f8. d16 }
1033
1034 \new Staff {
1035   \motif
1036   \retrograde \modalInversion c' c' \octatonicScale \motif
1037 }
1038 @end lilypond
1039
1040 @seealso
1041 Notation Reference:
1042 @ref{Inversion},
1043 @ref{Retrograde},
1044 @ref{Transpose}.
1045
1046
1047 @node Displaying pitches
1048 @subsection Displaying pitches
1049
1050 This section discusses how to alter the output of pitches.
1051
1052 @menu
1053 * Clef::
1054 * Key signature::
1055 * Ottava brackets::
1056 * Instrument transpositions::
1057 * Automatic accidentals::
1058 * Ambitus::
1059 @end menu
1060
1061
1062 @node Clef
1063 @unnumberedsubsubsec Clef
1064
1065 @cindex G clef
1066 @cindex C clef
1067 @cindex F clef
1068 @cindex treble clef
1069 @cindex violin clef
1070 @cindex alto clef
1071 @cindex tenor clef
1072 @cindex bass clef
1073 @cindex french clef
1074 @cindex soprano clef
1075 @cindex mezzosoprano clef
1076 @cindex baritone clef
1077 @cindex varbaritone clef
1078 @cindex subbass clef
1079 @cindex clef
1080 @cindex ancient clef
1081 @cindex clef, ancient
1082 @cindex clef, G
1083 @cindex clef, C
1084 @cindex clef, F
1085 @cindex clef, treble
1086 @cindex clef, violin
1087 @cindex clef, alto
1088 @cindex clef, tenor
1089 @cindex clef, bass
1090 @cindex clef, french
1091 @cindex clef, soprano
1092 @cindex clef, mezzosoprano
1093 @cindex clef, baritone
1094 @cindex clef, varbaritone
1095 @cindex clef, subbass
1096
1097
1098 @funindex \clef
1099 @funindex clef
1100
1101 The clef may be altered.  Middle C is shown in every example.  The
1102 following clef names can (but do not need to) be enclosed in quotes.
1103
1104 @lilypond[verbatim,quote,relative=1]
1105 \clef treble
1106 c2 c
1107 \clef alto
1108 c2 c
1109 \clef tenor
1110 c2 c
1111 \clef bass
1112 c2 c
1113 @end lilypond
1114
1115 Other clefs include:
1116
1117 @lilypond[verbatim,quote,relative=1]
1118 \clef french
1119 c2 c
1120 \clef soprano
1121 c2 c
1122 \clef mezzosoprano
1123 c2 c
1124 \clef baritone
1125 c2 c
1126
1127 \break
1128
1129 \clef varbaritone
1130 c2 c
1131 \clef subbass
1132 c2 c
1133 \clef percussion
1134 c2 c
1135
1136 \break
1137
1138 \clef G   % synonym for treble
1139 c2 c
1140 \clef F   % synonym for bass
1141 c2 c
1142 \clef C   % synonym for alto
1143 c2 c
1144 @end lilypond
1145
1146 @cindex transposing clef
1147 @cindex clef, transposing
1148 @cindex octave transposition
1149 @cindex optional octave transposition
1150 @cindex octave transposition, optional
1151 @cindex choral tenor clef
1152 @cindex tenor clef, choral
1153
1154 By adding@tie{}@code{_8} or@tie{}@code{^8} to the clef name, the
1155 clef is transposed one octave down or up respectively,
1156 and@tie{}@code{_15} and@tie{}@code{^15} transpose by two octaves.
1157 Other integers can be used if required.  Clef names containing
1158 non-alphabetic characters must be enclosed in quotes
1159
1160 @lilypond[verbatim,quote,relative=1]
1161 \clef treble
1162 c2 c
1163 \clef "treble_8"
1164 c2 c
1165 \clef "bass^15"
1166 c2 c
1167 \clef "alto_2"
1168 c2 c
1169 \clef "G_8"
1170 c2 c
1171 \clef "F^5"
1172 c2 c
1173 @end lilypond
1174
1175 Optional octavation can be obtained by enclosing the numeric
1176 argument in parentheses or brackets:
1177
1178 @lilypond[verbatim,quote,relative=1]
1179 \clef "treble_(8)"
1180 c2 c
1181 \clef "bass^[15]"
1182 c2 c
1183 @end lilypond
1184
1185 The pitches are displayed as if the numeric argument were
1186 given without parentheses/brackets.
1187
1188 Some special purpose clefs are described in @ref{Mensural clefs},
1189 @ref{Gregorian clefs}, @ref{Default tablatures}, and @ref{Custom
1190 tablatures}.  For mixing different clefs when using cue notes within a
1191 score, see the @code{\cueClef} and @code{\cueDuringWithClef} functions
1192 in @ref{Formatting cue notes}.
1193
1194 @snippets
1195
1196 @lilypondfile[verbatim,quote,texidoc,doctitle]
1197 {tweaking-clef-properties.ly}
1198
1199 @seealso
1200 Notation Reference:
1201 @ref{Mensural clefs},
1202 @ref{Gregorian clefs},
1203 @ref{Default tablatures},
1204 @ref{Custom tablatures},
1205 @ref{Formatting cue notes}.
1206
1207 Snippets:
1208 @rlsr{Pitches}.
1209
1210 Internals Reference:
1211 @rinternals{Clef_engraver},
1212 @rinternals{Clef},
1213 @rinternals{OctavateEight},
1214 @rinternals{clef-interface}.
1215
1216 @knownissues
1217 Ottavation numbers attached to clefs are treated as separate grobs.  So
1218 any @code{\override} done to the @var{Clef} will also need to be
1219 applied, as a separate @code{\override}, to the @var{OctavateEight}
1220 grob.
1221
1222 @lilypond[fragment,quote,relative=1]
1223 \new Staff \with {
1224   \override OctavateEight.color = #red
1225   \override Clef.color = #blue
1226 }
1227
1228 \clef "treble_8" c4
1229 @end lilypond
1230
1231
1232 @node Key signature
1233 @unnumberedsubsubsec Key signature
1234
1235 @cindex key signature
1236
1237 @funindex \key
1238 @funindex key
1239
1240 @c duplicated in Key signature and Accidentals
1241 @warning{New users are sometimes confused about accidentals and
1242 key signatures.  In LilyPond, note names are the raw input; key
1243 signatures and clefs determine how this raw input is displayed.
1244 An unaltered note like@tie{}@code{c} means @q{C natural},
1245 regardless of the key signature or clef.  For more information,
1246 see @rlearning{Accidentals and key signatures}.}
1247
1248 The key signature indicates the tonality in which a piece is
1249 played.  It is denoted by a set of alterations (flats or sharps)
1250 at the start of the staff.  The key signature may be altered:
1251
1252 @example
1253 \key @var{pitch} @var{mode}
1254 @end example
1255
1256 @funindex \major
1257 @funindex major
1258 @funindex \minor
1259 @funindex minor
1260 @funindex \ionian
1261 @funindex ionian
1262 @funindex \locrian
1263 @funindex locrian
1264 @funindex \aeolian
1265 @funindex aeolian
1266 @funindex \mixolydian
1267 @funindex mixolydian
1268 @funindex \lydian
1269 @funindex lydian
1270 @funindex \phrygian
1271 @funindex phrygian
1272 @funindex \dorian
1273 @funindex dorian
1274
1275 @cindex church modes
1276 @cindex modes
1277 @cindex major
1278 @cindex minor
1279 @cindex ionian
1280 @cindex locrian
1281 @cindex aeolian
1282 @cindex mixolydian
1283 @cindex lydian
1284 @cindex phrygian
1285 @cindex dorian
1286
1287 @noindent
1288 Here, @code{@var{mode}} should be @code{\major} or @code{\minor}
1289 to get a key signature of @code{@var{pitch}}-major or
1290 @code{@var{pitch}}-minor, respectively.  You may also use the
1291 standard mode names, also called @notation{church modes}:
1292 @code{\ionian}, @code{\dorian}, @code{\phrygian}, @code{\lydian},
1293 @code{\mixolydian}, @code{\aeolian}, and @code{\locrian}.
1294
1295 @lilypond[verbatim,quote,relative=2]
1296 \key g \major
1297 fis1
1298 f
1299 fis
1300 @end lilypond
1301
1302 Additional modes can be defined, by listing the alterations
1303 for each scale step when the mode starts on C.
1304
1305 @lilypond[verbatim,quote]
1306 freygish = #`((0 . ,NATURAL) (1 . ,FLAT) (2 . ,NATURAL)
1307     (3 . ,NATURAL) (4 . ,NATURAL) (5 . ,FLAT) (6 . ,FLAT))
1308
1309 \relative c' {
1310   \key c\freygish c4 des e f
1311   \bar "||" \key d\freygish d es fis g
1312 }
1313 @end lilypond
1314
1315 Accidentals in the key signature may be printed in octaves other
1316 than their traditional positions, or in multiple octaves, by
1317 using the @code{flat-positions} and @code{sharp-positions}
1318 properties of @code{KeySignature}.  Entries in these properties
1319 specify the range of staff-positions where accidentals will be
1320 printed.  If a single position is specified in an entry, the
1321 accidentals are placed within the octave ending at that staff
1322 position.
1323
1324 @lilypond[verbatim, quote,relative=0]
1325 \override Staff.KeySignature.flat-positions = #'((-5 . 5))
1326 \override Staff.KeyCancellation.flat-positions = #'((-5 . 5))
1327 \clef bass \key es\major es g bes d
1328 \clef treble \bar "||" \key es\major es g bes d
1329
1330 \override Staff.KeySignature.sharp-positions = #'(2)
1331 \bar "||" \key b\major b fis b2
1332 @end lilypond
1333
1334 @snippets
1335
1336 @lilypondfile[verbatim,quote,texidoc,doctitle]
1337 {preventing-natural-signs-from-being-printed-when-the-key-signature-changes.ly}
1338
1339 @lilypondfile[verbatim,quote,texidoc,doctitle]
1340 {non-traditional-key-signatures.ly}
1341
1342 @seealso
1343 Music Glossary:
1344 @rglos{church mode},
1345 @rglos{scordatura}.
1346
1347 Learning Manual:
1348 @rlearning{Accidentals and key signatures}.
1349
1350 Snippets:
1351 @rlsr{Pitches}.
1352
1353 Internals Reference:
1354 @rinternals{KeyChangeEvent},
1355 @rinternals{Key_engraver},
1356 @rinternals{Key_performer},
1357 @rinternals{KeyCancellation},
1358 @rinternals{KeySignature},
1359 @rinternals{key-signature-interface}.
1360
1361
1362 @node Ottava brackets
1363 @unnumberedsubsubsec Ottava brackets
1364
1365 @cindex ottava
1366 @cindex 15ma
1367 @cindex 8va
1368 @cindex 8ve
1369 @cindex octavation
1370
1371 @funindex set-octavation
1372 @funindex \ottava
1373 @funindex ottava
1374
1375 @notation{Ottava brackets} introduce an extra transposition of an
1376 octave for the staff:
1377
1378 @lilypond[verbatim,quote,relative=2]
1379 a2 b
1380 \ottava #-2
1381 a2 b
1382 \ottava #-1
1383 a2 b
1384 \ottava #0
1385 a2 b
1386 \ottava #1
1387 a2 b
1388 \ottava #2
1389 a2 b
1390 @end lilypond
1391
1392 @snippets
1393
1394 @lilypondfile[verbatim,quote,texidoc,doctitle]
1395 {ottava-text.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
2438 @item teaching
2439
2440 @cindex teaching accidental style
2441 @cindex accidental style, teaching
2442
2443 @funindex teaching
2444
2445 This rule is intended for students, and makes it easy to create
2446 scale sheets with automatically created cautionary accidentals.
2447 Accidentals are printed like with @code{modern}, but cautionary
2448 accidentals are added for all sharp or flat tones specified by the
2449 key signature, except if the note is immediately repeated.
2450
2451 @lilypond[quote,staffsize=18]
2452 musicA = {
2453   <<
2454     \relative c' {
2455       cis'8 fis, bes4 <a cis>8 f bis4 |
2456       cis2. <c, g'>4 |
2457     }
2458     \\
2459     \relative c' {
2460       ais'2 cis, |
2461       fis8 b a4 cis2 |
2462     }
2463   >>
2464 }
2465
2466 musicB = {
2467   \clef bass
2468   \new Voice {
2469     \voiceTwo \relative c' {
2470       <fis, a cis>8[ <fis a cis>
2471       \change Staff = up
2472       cis' cis
2473       \change Staff = down
2474       <fis, a> <fis a>]
2475       \showStaffSwitch
2476       \change Staff = up
2477       dis'4 |
2478       \change Staff = down
2479       <fis, a cis>4 gis <f a d>2 |
2480     }
2481   }
2482 }
2483
2484 \new PianoStaff {
2485   <<
2486     \context Staff = "up" {
2487       \key fis \minor
2488       \accidentalStyle teaching
2489       \musicA
2490     }
2491     \context Staff = "down" {
2492       \key fis \minor
2493       \accidentalStyle teaching
2494       \musicB
2495     }
2496   >>
2497 }
2498 @end lilypond
2499
2500
2501
2502 @item no-reset
2503
2504 @cindex accidental style, no reset
2505 @cindex no reset accidental style
2506
2507 @funindex no-reset
2508
2509 This is the same as @code{default} but with accidentals lasting
2510 @q{forever} and not only within the same measure:
2511
2512 @lilypond[quote]
2513 musicA = {
2514   <<
2515     \relative c' {
2516       cis'8 fis, bes4 <a cis>8 f bis4 |
2517       cis2. <c, g'>4 |
2518     }
2519     \\
2520     \relative c' {
2521       ais'2 cis, |
2522       fis8 b a4 cis2 |
2523     }
2524   >>
2525 }
2526
2527 musicB = {
2528   \clef bass
2529   \new Voice {
2530     \voiceTwo \relative c' {
2531       <fis, a cis>8[ <fis a cis>
2532       \change Staff = up
2533       cis' cis
2534       \change Staff = down
2535       <fis, a> <fis a>]
2536       \showStaffSwitch
2537       \change Staff = up
2538       dis'4 |
2539       \change Staff = down
2540       <fis, a cis>4 gis <f a d>2 |
2541     }
2542   }
2543 }
2544
2545 \new PianoStaff {
2546   <<
2547     \context Staff = "up" {
2548       \accidentalStyle no-reset
2549       \musicA
2550     }
2551     \context Staff = "down" {
2552       \accidentalStyle no-reset
2553       \musicB
2554     }
2555   >>
2556 }
2557 @end lilypond
2558
2559 @item forget
2560
2561 @cindex forget accidental style
2562 @cindex accidental style, forget
2563
2564 @funindex forget
2565
2566 This is the opposite of @code{no-reset}: Accidentals are not
2567 remembered at all -- and hence all accidentals are typeset
2568 relative to the key signature, regardless of what came before in
2569 the music.
2570
2571 @lilypond[quote]
2572 musicA = {
2573   <<
2574     \relative c' {
2575       cis'8 fis, bes4 <a cis>8 f bis4 |
2576       cis2. <c, g'>4 |
2577     }
2578     \\
2579     \relative c' {
2580       ais'2 cis, |
2581       fis8 b a4 cis2 |
2582     }
2583   >>
2584 }
2585
2586 musicB = {
2587   \clef bass
2588   \new Voice {
2589     \voiceTwo \relative c' {
2590       <fis, a cis>8[ <fis a cis>
2591       \change Staff = up
2592       cis' cis
2593       \change Staff = down
2594       <fis, a> <fis a>]
2595       \showStaffSwitch
2596       \change Staff = up
2597       dis'4 |
2598       \change Staff = down
2599       <fis, a cis>4 gis <f a d>2 |
2600     }
2601   }
2602 }
2603
2604 \new PianoStaff {
2605   <<
2606     \context Staff = "up" {
2607       \accidentalStyle forget
2608       \musicA
2609     }
2610     \context Staff = "down" {
2611       \accidentalStyle forget
2612       \musicB
2613     }
2614   >>
2615 }
2616 @end lilypond
2617 @end table
2618
2619 @seealso
2620 Snippets:
2621 @rlsr{Pitches}.
2622
2623 Internals Reference:
2624 @rinternals{Accidental},
2625 @rinternals{Accidental_engraver},
2626 @rinternals{GrandStaff},
2627 @rinternals{PianoStaff},
2628 @rinternals{Staff},
2629 @rinternals{AccidentalSuggestion},
2630 @rinternals{AccidentalPlacement},
2631 @rinternals{accidental-suggestion-interface}.
2632
2633 @cindex accidentals and simultaneous notes
2634 @cindex simultaneous notes and accidentals
2635 @cindex accidentals in chords
2636 @cindex chords, accidentals in
2637
2638 @knownissues
2639 Simultaneous notes are not considered in the automatic
2640 determination of accidentals; only previous notes and the key
2641 signature are considered.  Forcing accidentals with@tie{}@code{!}
2642 or@tie{}@code{?} may be required when the same note name occurs
2643 simultaneously with different alterations, as in @samp{<f! fis!>}.
2644
2645 Cautionary cancellation of accidentals is done by looking at previous measure.
2646 However, in the @code{\alternative} block following a @code{\repeat volta N}
2647 section, one would expect the cancellation being calculated using the previous
2648 @emph{played} measure, not previous @emph{printed} measure.
2649 In the following example, the natural @code{c} in the second alternative does
2650 not need a natural sign:
2651
2652 @lilypond[quote]
2653 {
2654   \accidentalStyle modern
2655   \time 2/4
2656   \repeat volta 2 {
2657     c'2
2658   }
2659   \alternative {
2660      cis'
2661      c'
2662   }
2663 }
2664 @end lilypond
2665
2666 The following work-around can be used: define a function that locally changes
2667 the accidental style to @code{forget}:
2668
2669 @lilypond[verbatim,quote]
2670 forget = #(define-music-function (parser location music) (ly:music?) #{
2671   \accidentalStyle forget
2672   #music
2673   \accidentalStyle modern
2674 #})
2675 {
2676   \accidentalStyle modern
2677   \time 2/4
2678   \repeat volta 2 {
2679     c'2
2680   }
2681   \alternative {
2682      cis'
2683      \forget c'
2684   }
2685 }
2686 @end lilypond
2687
2688
2689 @node Ambitus
2690 @unnumberedsubsubsec Ambitus
2691
2692 @cindex ambitus
2693 @cindex range of pitches
2694 @cindex pitch range
2695
2696 The term @notation{ambitus} (pl. ambitus) denotes a range of
2697 pitches for a given voice in a part of music.  It may also denote
2698 the pitch range that a musical instrument is capable of playing.
2699 Ambitus are printed on vocal parts so that performers can easily
2700 determine if it matches their capabilities.
2701
2702 Ambitus are denoted at the beginning of a piece near the initial
2703 clef.  The range is graphically specified by two note heads that
2704 represent the lowest and highest pitches.  Accidentals are only
2705 printed if they are not part of the key signature.
2706
2707 @lilypond[verbatim,quote]
2708 \layout {
2709   \context {
2710     \Voice
2711     \consists "Ambitus_engraver"
2712   }
2713 }
2714
2715 \relative c'' {
2716   aes c e2
2717   cis,1
2718 }
2719 @end lilypond
2720
2721
2722 @snippets
2723
2724 @lilypondfile[verbatim,quote,texidoc,doctitle]
2725 {adding-ambitus-per-voice.ly}
2726
2727 @lilypondfile[verbatim,quote,texidoc,doctitle]
2728 {ambitus-with-multiple-voices.ly}
2729
2730 @lilypondfile[verbatim,quote,texidoc,doctitle]
2731 {changing-the-ambitus-gap.ly}
2732
2733 @seealso
2734 Music Glossary:
2735 @rglos{ambitus}.
2736
2737 Snippets:
2738 @rlsr{Pitches}.
2739
2740 Internals Reference:
2741 @rinternals{Ambitus_engraver},
2742 @rinternals{Voice},
2743 @rinternals{Staff},
2744 @rinternals{Ambitus},
2745 @rinternals{AmbitusAccidental},
2746 @rinternals{AmbitusLine},
2747 @rinternals{AmbitusNoteHead},
2748 @rinternals{ambitus-interface}.
2749
2750 @knownissues
2751 There is no collision handling in the case of multiple per-voice
2752 ambitus.
2753
2754
2755 @node Note heads
2756 @subsection Note heads
2757
2758 This section suggests ways of altering note heads.
2759
2760 @menu
2761 * Special note heads::
2762 * Easy notation note heads::
2763 * Shape note heads::
2764 * Improvisation::
2765 @end menu
2766
2767 @node Special note heads
2768 @unnumberedsubsubsec Special note heads
2769
2770 @cindex note heads, special
2771 @cindex note heads, cross
2772 @cindex note heads, diamond
2773 @cindex note heads, parlato
2774 @cindex note heads, harmonic
2775 @cindex note heads, guitar
2776 @cindex special note heads
2777 @cindex cross note heads
2778 @cindex diamond note heads
2779 @cindex parlato note heads
2780 @cindex harmonic note heads
2781 @cindex guitar note heads
2782 @cindex note head styles
2783 @cindex styles, note heads
2784
2785 @funindex cross
2786
2787 The appearance of note heads may be altered:
2788
2789 @lilypond[verbatim,quote,relative=2]
2790 c4 b
2791 \override NoteHead.style = #'cross
2792 c4 b
2793 \revert NoteHead.style
2794 a b
2795 \override NoteHead.style = #'harmonic
2796 a b
2797 \revert NoteHead.style
2798 c4 d e f
2799 @end lilypond
2800
2801 To see all note head styles, see @ref{Note head styles}.
2802
2803 The @code{cross} style is used to represent a variety of musical
2804 intentions.  The following generic predefined commands modify the
2805 note head in both staff and tablature contexts and can be used to
2806 represent any musical meaning:
2807
2808 @lilypond[verbatim,quote,relative=2]
2809 c4 b
2810 \xNotesOn
2811  a b c4 b
2812 \xNotesOff
2813 c4 d
2814 @end lilypond
2815
2816 The music function form of this predefined command may be used
2817 inside and outside chords to generate crossed note heads in both
2818 staff and tablature contexts:
2819
2820 @lilypond[verbatim,quote,relative=2]
2821 c4 b
2822 \xNote { e f }
2823 c b < g \xNote c f > b
2824 @end lilypond
2825
2826 As synonyms for @code{\xNote}, @code{\xNotesOn} and @code{\xNotesOff},
2827 @code{\deadNote}, @code{\deadNotesOn} and @code{\deadNotesOff} can
2828 be used.  The term @notation{dead note} is commonly used by guitarists.
2829
2830 There is also a shorthand for diamond shapes which can be used
2831 only inside chords:
2832
2833 @lilypond[verbatim,quote,relative=2]
2834 <c f\harmonic>2 <d a'\harmonic>4 <c g'\harmonic>
2835 @end lilypond
2836
2837 @predefined
2838 @code{\harmonic},
2839 @code{\xNotesOn},
2840 @code{\xNotesOff},
2841 @code{\xNote}.
2842 @endpredefined
2843
2844 @seealso
2845 Snippets:
2846 @rlsr{Pitches}.
2847
2848 Notation Reference:
2849 @ref{Note head styles},
2850 @ref{Chorded notes},
2851 @ref{Indicating harmonics and dampened notes}.
2852
2853 Internals Reference:
2854 @rinternals{note-event},
2855 @rinternals{Note_heads_engraver},
2856 @rinternals{Ledger_line_engraver},
2857 @rinternals{NoteHead},
2858 @rinternals{LedgerLineSpanner},
2859 @rinternals{note-head-interface},
2860 @rinternals{ledger-line-spanner-interface}.
2861
2862
2863 @node Easy notation note heads
2864 @unnumberedsubsubsec Easy notation note heads
2865
2866 @cindex note heads, practice
2867 @cindex practice note heads
2868 @cindex note heads, easy notation
2869 @cindex easy notation
2870 @cindex beginners' music
2871 @cindex music, beginners'
2872 @cindex easy play note heads
2873 @cindex note heads, easy play
2874
2875 @funindex \easyHeadsOn
2876 @funindex easyHeadsOn
2877 @funindex \easyHeadsOff
2878 @funindex easyHeadsOff
2879
2880 The @q{easy play} note head includes a note name inside the head.
2881 It is used in music for beginners.  To make the letters readable,
2882 it should be printed in a large font size.  To print with a larger
2883 font, see @ref{Setting the staff size}.
2884
2885 @lilypond[verbatim,quote]
2886 #(set-global-staff-size 26)
2887 \relative c' {
2888   \easyHeadsOn
2889   c2 e4 f
2890   g1
2891   \easyHeadsOff
2892   c,1
2893 }
2894 @end lilypond
2895
2896
2897 @predefined
2898 @code{\easyHeadsOn},
2899 @code{\easyHeadsOff}.
2900 @endpredefined
2901
2902
2903 @snippets
2904
2905 @lilypondfile[verbatim,quote,texidoc,doctitle]
2906 {numbers-as-easy-note-heads.ly}
2907
2908 @seealso
2909 Notation Reference:
2910 @ref{Setting the staff size}.
2911
2912 Snippets:
2913 @rlsr{Pitches}.
2914
2915 Internals Reference:
2916 @rinternals{note-event},
2917 @rinternals{Note_heads_engraver},
2918 @rinternals{NoteHead},
2919 @rinternals{note-head-interface}.
2920
2921
2922 @node Shape note heads
2923 @unnumberedsubsubsec Shape note heads
2924
2925 @cindex note heads, shape
2926 @cindex note heads, Aiken
2927 @cindex note heads, sacred harp
2928 @cindex shape notes
2929 @cindex Aiken shape note heads
2930 @cindex sacred harp note heads
2931 @cindex note heads, Southern Harmony
2932 @cindex Southern Harmony note heads
2933 @cindex Funk shape note heads
2934 @cindex note heads, Funk
2935 @cindex note heads, Harmonica Sacra
2936 @cindex Harmonica Sacra note heads
2937 @cindex Christian Harmony note heads
2938 @cindex note heads, Christian Harmony
2939 @cindex Walker shape note heads
2940 @cindex note heads, Walker
2941
2942 @funindex \aikenHeads
2943 @funindex aikenHeads
2944 @funindex \sacredHarpHeads
2945 @funindex sacredHarpHeads
2946 @funindex \southernHarmonyHeads
2947 @funindex southernHarmonyHeads
2948 @funindex \funkHeads
2949 @funindex funkHeads
2950 @funindex \walkerHeads
2951 @funindex walkerHeads
2952
2953 In shape note head notation, the shape of the note head
2954 corresponds to the harmonic function of a note in the scale.  This
2955 notation was popular in nineteenth-century American song books.
2956 Shape note heads can be produced in Sacred Harp, Southern Harmony,
2957 Funk (Harmonica Sacra), Walker, and Aiken (Christian Harmony) styles:
2958
2959 @lilypond[verbatim,quote,relative=2]
2960 \aikenHeads
2961 c, d e f g2 a b1 c \break
2962 \sacredHarpHeads
2963 c,4 d e f g2 a b1 c \break
2964 \southernHarmonyHeads
2965 c,4 d e f g2 a b1 c \break
2966 \funkHeads
2967 c,4 d e f g2 a b1 c \break
2968 \walkerHeads
2969 c,4 d e f g2 a b1 c \break
2970 @end lilypond
2971
2972 @funindex \key
2973 @funindex key
2974 @funindex \aikenHeadsMinor
2975 @funindex aikenHeadsMinor
2976 @funindex \sacredHarpHeadsMinor
2977 @funindex sacredHarpHeadsMinor
2978 @funindex \southernHarmonyHeadsMinor
2979 @funindex southernHarmonyHeadsMinor
2980 @funindex \funkHeadsMinor
2981 @funindex funkHeadsMinor
2982 @funindex \walkerHeadsMinor
2983 @funindex walkerHeadsMinor
2984
2985 Shapes are typeset according to the step in the scale, where the base
2986 of the scale is determined by the @code{\key} command.  When writing
2987 in a minor key, the scale step can be determined from the relative
2988 major:
2989
2990 @lilypond[verbatim,quote,relative=2]
2991 \key a \minor
2992 \aikenHeads
2993 a b c d e2 f g1 a \break
2994 \aikenHeadsMinor
2995 a,4 b c d e2 f g1 a \break
2996 \sacredHarpHeadsMinor
2997 a,2 b c d \break
2998 \southernHarmonyHeadsMinor
2999 a2 b c d \break
3000 \funkHeadsMinor
3001 a2 b c d \break
3002 \walkerHeadsMinor
3003 a2 b c d \break
3004
3005 @end lilypond
3006
3007
3008 @predefined
3009 @code{\aikenHeads},
3010 @code{\aikenHeadsMinor},
3011 @code{\funkHeads},
3012 @code{\funkHeadsMinor},
3013 @code{\sacredHarpHeads},
3014 @code{\sacredHarpHeadsMinor},
3015 @code{\southernHarmonyHeads},
3016 @code{\southernHarmonyHeadsMinor},
3017 @code{\walkerHeads},
3018 @code{\walkerHeadsMinor}.
3019 @endpredefined
3020
3021
3022 @snippets
3023
3024 @lilypondfile[verbatim,quote,texidoc,doctitle]
3025 {applying-note-head-styles-depending-on-the-step-of-the-scale.ly}
3026
3027 To see all note head styles, see @ref{Note head styles}.
3028
3029 @seealso
3030 Snippets:
3031 @rlsr{Pitches}.
3032
3033 Notation Reference:
3034 @ref{Note head styles}.
3035
3036 Internals Reference:
3037 @rinternals{note-event},
3038 @rinternals{Note_heads_engraver},
3039 @rinternals{NoteHead},
3040 @rinternals{note-head-interface}.
3041
3042
3043 @node Improvisation
3044 @unnumberedsubsubsec Improvisation
3045
3046 @cindex improvisation
3047 @cindex slashed note heads
3048 @cindex note heads, improvisation
3049 @cindex note heads, slashed
3050
3051 @funindex \improvisationOn
3052 @funindex improvisationOn
3053 @funindex \improvisationOff
3054 @funindex improvisationOff
3055
3056 Improvisation is sometimes denoted with slashed note heads, where
3057 the performer may choose any pitch but should play the specified
3058 rhythm.  Such note heads can be created:
3059
3060 @lilypond[verbatim,quote,relative=2]
3061 \new Voice \with {
3062   \consists "Pitch_squash_engraver"
3063 } {
3064   e8 e g a a16( bes) a8 g
3065   \improvisationOn
3066   e8 ~
3067   e2 ~ e8 f4 f8 ~
3068   f2
3069   \improvisationOff
3070   a16( bes) a8 g e
3071 }
3072 @end lilypond
3073
3074 @predefined
3075 @code{\improvisationOn},
3076 @code{\improvisationOff}.
3077 @endpredefined
3078
3079 @seealso
3080 Snippets:
3081 @rlsr{Pitches}.
3082
3083 Internals Reference:
3084 @rinternals{Pitch_squash_engraver},
3085 @rinternals{Voice},
3086 @rinternals{RhythmicStaff}.