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