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.  See TRANSLATION for details.
   7 @end ignore
   8
   9 @c \version "2.12.0"
  10
  11
  12 @node Pitches
  13 @section Pitches
  14
  15 @lilypondfile[quote]{pitches-headword.ly}
  16
  17 This section discusses how to specify the pitch of notes.  There
  18 are three steps to this process: input, modification, and output.
  19
  20 @menu
  21 * Writing pitches::
  22 * Changing multiple pitches::
  23 * Displaying pitches::
  24 * Note heads::
  25 @end menu
  26
  27
  28 @node Writing pitches
  29 @subsection Writing pitches
  30
  31 This section discusses how to input pitches.  There are two
  32 different ways to place notes in octaves: absolute and relative
  33 mode.  In most cases, relative mode will be more convenient.
  34
  35 @menu
  36 * Absolute octave entry::
  37 * Relative octave entry::
  38 * Accidentals::
  39 * Note names in other languages::
  40 @end menu
  41
  42
  43 @node Absolute octave entry
  44 @unnumberedsubsubsec Absolute octave entry
  45
  46 @cindex pitch names
  47 @cindex pitches
  48 @cindex absolute
  49 @cindex absolute octave specification
  50 @cindex octave specification, absolute
  51 @cindex absolute octave entry
  52 @cindex octave entry, absolute
  53
  54 A pitch name is specified using lowercase letters@tie{}@code{a}
  55 through@tie{}@code{g}.  The note names @code{c} to @code{b} are
  56 engraved in the octave below middle C.
  57
  58 @c don't use c' here.
  59 @lilypond[verbatim,quote,fragment]
  60 \clef bass
  61 c d e f
  62 g a b c
  63 d e f g
  64 @end lilypond
  65
  66 @cindex octave changing mark
  67
  68 @funindex '
  69 @funindex ,
  70
  71 Other octaves may be specified with a single quote@tie{}(@code{'})
  72 or comma@tie{}(@code{,}) character.  Each@tie{}@code{'} raises the
  73 pitch by one octave; each@tie{}@code{,} lowers the pitch by an
  74 octave.
  75
  76 @lilypond[verbatim,quote,fragment]
  77 \clef treble
  78 c' c'' e' g
  79 d'' d' d c
  80 \clef bass
  81 c, c,, e, g
  82 d,, d, d c
  83 @end lilypond
  84
  85
  86 @seealso
  87 Music Glossary:
  88 @rglos{Pitch names}.
  89
  90 Snippets:
  91 @rlsr{Pitches}.
  92
  93
  94 @node Relative octave entry
  95 @unnumberedsubsubsec Relative octave entry
  96
  97 @cindex relative
  98 @cindex relative octave entry
  99 @cindex octave entry, relative
 100 @cindex relative octave specification
 101 @cindex ocatve specification, relative
 102
 103 @funindex relative
 104 @funindex \relative
 105
 106 When octaves are specified in absolute mode it is easy to
 107 accidentally put a pitch in the wrong octave.  Relative octave
 108 mode reduces these errors since most of the time it is not
 109 necessary to indicate any octaves at all.  Furthermore, in
 110 absolute mode a single mistake may be difficult to spot, while in
 111 relative mode a single error puts the rest of the piece off by one
 112 octave.
 113
 114 @example
 115 \relative @var{startpitch} @var{musicexpr}
 116 @end example
 117
 118 In relative mode, each note is assumed to be as close to the
 119 previous note as possible.  This means that the octave of each
 120 pitch inside @var{musicexpr} is calculated as follows:
 121
 122 @itemize
 123 @item
 124 If no octave changing mark is used on a pitch, its octave is
 125 calculated so that the interval with the previous note is less
 126 than a fifth.  This interval is determined without considering
 127 accidentals.
 128
 129 @item
 130 An octave changing mark@tie{}@code{'} or@tie{}@code{,} can be
 131 added to respectively raise or lower a pitch by an extra octave,
 132 relative to the pitch calculated without an octave mark.
 133
 134 @item
 135 Multiple octave changing marks can be used.  For example,
 136 @code{''}@tie{}and@tie{}@code{,,} will alter the pitch by two
 137 octaves.
 138
 139 @item
 140 The pitch of the first note is relative to
 141 @code{@var{startpitch}}.  @var{startpitch} is specified in
 142 absolute octave mode, and it is recommended that it be a octave of
 143 @code{c}.
 144
 145 @end itemize
 146
 147 Here is the relative mode shown in action:
 148
 149 @lilypond[verbatim,quote]
 150 \relative c {
 151   \clef bass
 152   c d e f
 153   g a b c
 154   d e f g
 155 }
 156 @end lilypond
 157
 158 Octave changing marks are used for intervals greater than a
 159 fourth:
 160
 161 @lilypond[verbatim,quote]
 162 \relative c'' {
 163   c g c f,
 164   c' a, e'' c
 165 }
 166 @end lilypond
 167
 168 A note sequence without a single octave mark can nevertheless span
 169 large intervals:
 170
 171 @lilypond[verbatim,quote]
 172 \relative c {
 173   c f b e
 174   a d g c
 175 }
 176 @end lilypond
 177
 178 When @code{\relative} blocks are nested, the innermost
 179 @code{\relative} block applies.
 180
 181 @lilypond[verbatim,quote]
 182 \relative c' {
 183   c d e f
 184   \relative c'' {
 185     c d e f
 186   }
 187 }
 188 @end lilypond
 189
 190 @code{\relative} has no effect on @code{\chordmode} blocks.
 191
 192 @lilypond[verbatim,quote]
 193 \new Staff {
 194   \relative c''' {
 195     \chordmode { c1 }
 196   }
 197   \chordmode { c1 }
 198 }
 199 @end lilypond
 200
 201 @code{\relative} is not allowed inside of @code{\chordmode} blocks.
 202
 203 Music inside a @code{\transpose} block is absolute unless a
 204 @code{\relative} is included.
 205
 206 @lilypond[verbatim,quote]
 207 \relative c' {
 208   d e
 209   \transpose f g {
 210     d e
 211     \relative c' {
 212       d e
 213     }
 214   }
 215 }
 216 @end lilypond
 217
 218
 219 @cindex chords and relative octave entry
 220 @cindex relative octave entry and chords
 221
 222 If the preceding item is a chord, the first note of the chord is
 223 used as the reference point for the octave placement of a
 224 following note or chord.  Inside chords, the next note is always
 225 relative to the preceding one.  Examine the next example
 226 carefully, paying attention to the @code{c} notes.
 227
 228 @lilypond[verbatim,quote]
 229 \relative c' {
 230   c
 231   <c e g>
 232   <c' e g'>
 233   <c, e, g''>
 234 }
 235 @end lilypond
 236
 237 As explained above, the octave of pitches is calculated only with
 238 the note names, regardless of any alterations.  Therefore, an
 239 E-double-sharp following a B will be placed higher, while an
 240 F-double-flat will be placed lower.  In other words, a
 241 double-augmented fourth is considered a smaller interval than a
 242 double-diminished fifth, regardless of the number of semitones
 243 that each interval contains.
 244
 245 @lilypond[verbatim,quote]
 246 \relative c'' {
 247   c2 fis
 248   c2 ges
 249   b2 eisis
 250   b2 feses
 251 }
 252 @end lilypond
 253
 254
 255 @seealso
 256 Music Glossary:
 257 @rglos{fifth},
 258 @rglos{interval},
 259 @rglos{Pitch names}.
 260
 261 Notation Reference:
 262 @ref{Octave checks}.
 263
 264 Snippets:
 265 @rlsr{Pitches}.
 266
 267 Internals Reference:
 268 @rinternals{RelativeOctaveMusic}.
 269
 270
 271 @cindex relative octave entry and transposition
 272 @cindex transposition and relative octave entry
 273
 274 @funindex \transpose
 275 @funindex transpose
 276 @funindex \chordmode
 277 @funindex chordmode
 278 @funindex \relative
 279 @funindex relative
 280
 281
 282 @c DEPRECATED
 283 If no @var{startpitch} is specified for @code{\relative},
 284 then@tie{}@code{c'} is assumed.  However, this is a deprecated
 285 option and may disappear in future versions, so its use is
 286 discouraged.
 287
 288
 289
 290 @node Accidentals
 291 @unnumberedsubsubsec Accidentals
 292
 293 @cindex accidental
 294 @cindex key signature
 295 @cindex clef
 296
 297 @c duplicated in Key signature and Accidentals
 298 @warning{New users are sometimes confused about accidentals and
 299 key signatures.  In LilyPond, note names are the raw input; key
 300 signatures and clefs determine how this raw input is displayed.
 301 An unaltered note like@tie{}@code{c} means @q{C natural},
 302 regardless of the key signature or clef.  For more information,
 303 see @rlearning{Accidentals and key signatures}.}
 304
 305 @cindex note names, Dutch
 306 @cindex note names, default
 307 @cindex default note names
 308 @cindex sharp
 309 @cindex flat
 310 @cindex double sharp
 311 @cindex sharp, double
 312 @cindex double flat
 313 @cindex flat, double
 314 @cindex natural sign
 315 @cindex natural pitch
 316
 317 A @notation{sharp} pitch is made by adding @code{is} to the note
 318 name, and a @notation{flat} pitch by adding @code{es}.  As you
 319 might expect, a @notation{double sharp} or @notation{double flat}
 320 is made by adding @code{isis} or @code{eses}.  This syntax is
 321 derived from Dutch note naming conventions.  To use other names
 322 for accidentals, see @ref{Note names in other languages}.
 323
 324 @lilypond[verbatim,quote,relative=2]
 325 ais1 aes aisis aeses
 326 @end lilypond
 327
 328 A natural will cancel the effect of an accidental or key
 329 signature.  However, naturals are not encoded into the note name
 330 syntax with a suffix; a natural pitch is shown as a simple note
 331 name:
 332
 333 @lilypond[verbatim,quote,relative=2]
 334 a4 aes a2
 335 @end lilypond
 336
 337 @cindex quarter tones
 338 @cindex semi-flats
 339 @cindex semi-sharps
 340
 341 Quarter tones may be added; the following is a series of Cs with
 342 increasing pitches:
 343
 344 @lilypond[verbatim,quote,relative=2]
 345 ceseh1 ces ceh c cih cis cisih
 346 @end lilypond
 347
 348
 349
 350 @cindex accidental, reminder
 351 @cindex accidental, cautionary
 352 @cindex accidental, parenthesized
 353 @cindex reminder accidental
 354 @cindex cautionary accidental
 355 @cindex parenthesized accidental
 356
 357 @funindex ?
 358 @funindex !
 359
 360
 361 Normally accidentals are printed automatically, but you may also
 362 print them manually.  A reminder accidental can be forced by
 363 adding an exclamation mark@tie{}@code{!} after the pitch.  A
 364 cautionary accidental (i.e., an accidental within parentheses) can
 365 be obtained by adding the question mark@tie{}@code{?} after the
 366 pitch.  These extra accidentals can also be used to produce
 367 natural signs.
 368
 369 @lilypond[verbatim,quote,relative=2]
 370 cis cis cis! cis? c c c! c?
 371 @end lilypond
 372
 373 @cindex accidental on tied note
 374 @cindex tied note, accidental
 375
 376 Accidentals on tied notes are only printed at the beginning of a
 377 new system:
 378
 379 @lilypond[verbatim,quote,relative=2]
 380 cis1 ~ cis ~
 381 \break
 382 cis
 383 @end lilypond
 384
 385
 386 @snippets
 387
 388 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 389 {preventing-extra-naturals-from-being-automatically-added.ly}
 390
 391 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 392 {makam-example.ly}
 393
 394
 395 @seealso
 396 Music Glossary:
 397 @rglos{sharp},
 398 @rglos{flat},
 399 @rglos{double sharp},
 400 @rglos{double flat},
 401 @rglos{Pitch names},
 402 @rglos{quarter tone}.
 403
 404 Learning Manual:
 405 @rlearning{Accidentals and key signatures}.
 406
 407 Notation Reference:
 408 @ref{Automatic accidentals},
 409 @ref{Annotational accidentals (musica ficta)},
 410 @ref{Note names in other languages}.
 411
 412 Snippets:
 413 @rlsr{Pitches}.
 414
 415 Internals Reference:
 416 @rinternals{Accidental_engraver},
 417 @rinternals{Accidental},
 418 @rinternals{AccidentalCautionary},
 419 @rinternals{accidental-interface}.
 420
 421
 422 @cindex accidental, quarter-tone
 423 @cindex quarter-tone accidental
 424
 425 @knownissues
 426
 427 There are no generally accepted standards for denoting
 428 quarter-tone accidentals, so LilyPond's symbol does not conform to
 429 any standard.
 430
 431
 432
 433 @node Note names in other languages
 434 @unnumberedsubsubsec Note names in other languages
 435
 436 @cindex note names, other languages
 437 @cindex pitch names, other languages
 438 @cindex language, note names in other
 439 @cindex language, pitch names in other
 440
 441 There are predefined sets of note and accidental names for various
 442 other languages.  To use them, include the language-specific init
 443 file listed below.  For example, to use English note names, add
 444 @code{@w{\include "english.ly"}} to the input file.
 445
 446 @warning{Because some other include files (such as @code{@w{predefined-fretboards.ly}})
 447 use default (Nederlands) note names, the @code{@bs{}include}
 448 command for the language file should be placed after all other
 449 LilyPond distribution files.}
 450
 451 The available language files and the note names they define are:
 452
 453 @quotation
 454 @multitable {@file{nederlands.ly}} {do re mi fa sol la sib si}
 455 @headitem Language File
 456   @tab Note Names
 457 @item @file{nederlands.ly}
 458   @tab c d e f g a bes b
 459 @item @file{arabic.ly}
 460   @tab do re mi fa sol la sib si
 461 @item @file{catalan.ly}
 462   @tab do re mi fa sol la sib si
 463 @item @file{deutsch.ly}
 464   @tab c d e f g a b h
 465 @item @file{english.ly}
 466   @tab c d e f g a bf b
 467 @item @file{espanol.ly}
 468   @tab do re mi fa sol la sib si
 469 @item @file{italiano.ly}
 470   @tab do re mi fa sol la sib si
 471 @item @file{norsk.ly}
 472   @tab c d e f g a b h
 473 @item @file{portugues.ly}
 474   @tab do re mi fa sol la sib si
 475 @item @file{suomi.ly}
 476   @tab c d e f g a b h
 477 @item @file{svenska.ly}
 478   @tab c d e f g a b h
 479 @item @file{vlaams.ly}
 480   @tab do re mi fa sol la sib si
 481 @end multitable
 482 @end quotation
 483
 484 @noindent
 485 and the accidental suffixes they define are:
 486
 487 @quotation
 488 @multitable {@file{nederlands.ly}} {-s/-sharp} {-ess/-es} {-ss/-x/-sharpsharp} {-essess/-eses}
 489 @headitem Language File
 490   @tab sharp @tab flat @tab double sharp @tab double flat
 491 @item @file{nederlands.ly}
 492   @tab -is @tab -es @tab -isis @tab -eses
 493 @item @file{arabic.ly}
 494   @tab -d @tab -b @tab -dd @tab -bb
 495 @item @file{catalan.ly}
 496   @tab -d/-s @tab -b @tab -dd/-ss @tab -bb
 497 @item @file{deutsch.ly}
 498   @tab -is @tab -es @tab -isis @tab -eses
 499 @item @file{english.ly}
 500   @tab -s/-sharp @tab -f/-flat @tab -ss/-x/-sharpsharp
 501     @tab -ff/-flatflat
 502 @item @file{espanol.ly}
 503   @tab -s @tab -b @tab -ss/-x @tab -bb
 504 @item @file{italiano.ly}
 505   @tab -d @tab -b @tab -dd @tab -bb
 506 @item @file{norsk.ly}
 507   @tab -iss/-is @tab -ess/-es @tab -ississ/-isis
 508     @tab -essess/-eses
 509 @item @file{portugues.ly}
 510   @tab -s @tab -b @tab -ss @tab -bb
 511 @item @file{suomi.ly}
 512   @tab -is @tab -es @tab -isis @tab -eses
 513 @item @file{svenska.ly}
 514   @tab -iss @tab -ess @tab -ississ @tab -essess
 515 @item @file{vlaams.ly}
 516   @tab -k @tab -b @tab -kk @tab -bb
 517 @end multitable
 518 @end quotation
 519
 520 In Dutch, @code{aes} is contracted to @code{as}, but both forms
 521 are accepted in LilyPond.  Similarly, both @code{es} and
 522 @code{ees} are accepted.  This also applies to
 523 @code{aeses}@tie{}/@tie{}@code{ases} and
 524 @code{eeses}@tie{}/@tie{}@code{eses}.  Sometimes only these
 525 contracted names are defined in the corresponding language files.
 526
 527 @lilypond[verbatim,quote,relative=2]
 528 a2 as e es a ases e eses
 529 @end lilypond
 530
 531
 532 @cindex microtones
 533 @cindex semi-sharp
 534 @cindex semi-flat
 535 @cindex sesqui-sharp
 536 @cindex sesqui-flat
 537
 538 Some music uses microtones whose alterations are fractions of a
 539 @q{normal} sharp or flat.  The note names for quarter-tones
 540 defined in the various language files are listed in the following
 541 table.  Here the prefixes @notation{semi-} and @notation{sesqui-}
 542 mean @q{half} and @q{one and a half}, respectively.  For the other
 543 languages, no special names have been defined yet.
 544
 545 @quotation
 546 @multitable {@file{nederlands.ly}} {@b{semi-sharp}} {@b{semi-flat}} {@b{sesqui-sharp}} {@b{sesqui-flat}}
 547 @headitem Language File
 548   @tab semi-sharp @tab semi-flat @tab sesqui-sharp @tab sesqui-flat
 549
 550 @item @file{nederlands.ly}
 551   @tab -ih @tab -eh @tab -isih @tab -eseh
 552 @item @file{arabic.ly}
 553   @tab -sd @tab -sb @tab -dsd @tab -bsb
 554 @item @file{deutsch.ly}
 555   @tab -ih @tab -eh @tab -isih @tab -eseh
 556 @item @file{english.ly}
 557   @tab -qs @tab -qf @tab -tqs @tab -tqf
 558 @item @file{espanol.ly}
 559   @tab -cs @tab -cb @tab -tcs @tab -tcb
 560 @item @file{italiano.ly}
 561   @tab -sd @tab -sb @tab -dsd @tab -bsb
 562 @item @file{portugues.ly}
 563   @tab -sqt @tab -bqt @tab -stqt @tab -btqt
 564 @end multitable
 565 @end quotation
 566
 567
 568 @seealso
 569 Music Glossary:
 570 @rglos{Pitch names}.
 571
 572 Snippets:
 573 @rlsr{Pitches}.
 574
 575
 576 @node Changing multiple pitches
 577 @subsection Changing multiple pitches
 578
 579 This section discusses how to modify pitches.
 580
 581 @menu
 582 * Octave checks::
 583 * Transpose::
 584 @end menu
 585
 586 @node Octave checks
 587 @unnumberedsubsubsec Octave checks
 588
 589 @cindex octave correction
 590 @cindex octave check
 591 @cindex control pitch
 592
 593 @funindex =
 594 @funindex \octaveCheck
 595 @funindex octaveCheck
 596 @funindex controlpitch
 597
 598 In relative mode, it is easy to forget an octave changing mark.
 599 Octave checks make such errors easier to find by displaying a
 600 warning and correcting the octave if a note is found in an
 601 unexpected octave.
 602
 603 To check the octave of a note, specify the absolute octave after
 604 the @code{=}@tie{}symbol.  This example will generate a warning
 605 (and change the pitch) because the second note is the absolute
 606 octave @code{d''} instead of @code{d'} as indicated by the octave
 607 correction.
 608
 609 @lilypond[verbatim,quote]
 610 \relative c'' {
 611   c2 d='4 d
 612   e2 f
 613 }
 614 @end lilypond
 615
 616 The octave of notes may also be checked with the
 617 @code{\octaveCheck}@tie{}@var{controlpitch} command.
 618 @var{controlpitch} is specified in absolute mode.  This checks
 619 that the interval between the previous note and the
 620 @var{controlpitch} is within a fourth (i.e., the normal
 621 calculation of relative mode).  If this check fails, a warning is
 622 printed, but the previous note is not changed.  Future notes are
 623 relative to the @var{controlpitch}.
 624
 625 @lilypond[verbatim,quote]
 626 \relative c'' {
 627   c2 d
 628   \octaveCheck c'
 629   e2 f
 630 }
 631 @end lilypond
 632
 633 Compare the two bars below.  The first and third @code{\octaveCheck}
 634 checks fail, but the second one does not fail.
 635
 636 @lilypond[verbatim,quote]
 637 \relative c'' {
 638   c4 f g f
 639
 640   c4
 641   \octaveCheck c'
 642   f
 643   \octaveCheck c'
 644   g
 645   \octaveCheck c'
 646   f
 647 }
 648 @end lilypond
 649
 650
 651 @seealso
 652 Snippets:
 653 @rlsr{Pitches}.
 654
 655 Internals Reference:
 656 @rinternals{RelativeOctaveCheck}.
 657
 658
 659 @node Transpose
 660 @unnumberedsubsubsec Transpose
 661
 662 @cindex transpose
 663 @cindex transposing
 664 @cindex transposition
 665 @cindex transposition of pitches
 666 @cindex transposition of notes
 667 @cindex pitches, transposition of
 668 @cindex notes, transposition of
 669
 670 @funindex \transpose
 671 @funindex transpose
 672
 673 A music expression can be transposed with @code{\transpose}.  The
 674 syntax is
 675
 676 @example
 677 \transpose @var{frompitch} @var{topitch} @var{musicexpr}
 678 @end example
 679
 680 @noindent
 681 This means that @var{musicexpr} is transposed by the interval
 682 between the pitches @var{frompitch} and @var{topitch}: any note
 683 with pitch @var{frompitch} is changed to @var{topitch} and any
 684 other note is transposed by the same interval.  Both pitches are
 685 entered in absolute mode.
 686
 687 @warning{Music inside a @code{@bs{}transpose} block is absolute
 688 unless a @code{@bs{}relative} is included in the block.}
 689
 690 Consider a piece written in the key of D-major.  It can be
 691 transposed up to E-major; note that the key signature is
 692 automatically transposed as well.
 693
 694 @lilypond[verbatim,quote]
 695 \transpose d e {
 696   \relative c' {
 697     \key d \major
 698     d4 fis a d
 699   }
 700 }
 701 @end lilypond
 702
 703 @cindex transposing instruments
 704 @cindex instruments, transposing
 705
 706 If a part written in C (normal @notation{concert pitch}) is to be
 707 played on the A clarinet (for which an A is notated as a C and
 708 thus sounds a minor third lower than notated), the appropriate
 709 part will be produced with:
 710
 711 @lilypond[verbatim,quote]
 712 \transpose a c' {
 713   \relative c' {
 714     \key c \major
 715     c4 d e g
 716   }
 717 }
 718 @end lilypond
 719
 720 @noindent
 721 Note that we specify @w{@code{\key c \major}} explicitly.  If we
 722 do not specify a key signature, the notes will be transposed but
 723 no key signature will be printed.
 724
 725 @code{\transpose} distinguishes between enharmonic pitches: both
 726 @w{@code{\transpose c cis}} or @w{@code{\transpose c des}} will
 727 transpose up a semitone.  The first version will print sharps and
 728 the notes will remain on the same scale step, the second version
 729 will print flats on the scale step above.
 730
 731 @lilypond[verbatim,quote]
 732 music = \relative c' { c d e f }
 733 \new Staff {
 734   \transpose c cis { \music }
 735   \transpose c des { \music }
 736 }
 737 @end lilypond
 738
 739
 740 @code{\transpose} may also be used in a different way, to input
 741 written notes for a transposing instrument.  The previous examples
 742 show how to enter pitches in C (or @notation{concert pitch}) and
 743 typeset them for a transposing instrument, but the opposite is
 744 also possible if you for example have a set of instrumental parts
 745 and want to print a conductor's score.  For example, when entering
 746 music for a B-flat trumpet that begins on a notated E (concert D),
 747 one would write:
 748
 749 @example
 750 musicInBflat = @{ e4 @dots{} @}
 751 \transpose c bes, \musicInBflat
 752 @end example
 753
 754 @noindent
 755 To print this music in F (e.g., rearranging to a French horn) you
 756 could wrap the existing music with another @code{\transpose}:
 757
 758 @example
 759 musicInBflat = @{ e4 @dots{} @}
 760 \transpose f c' @{ \transpose c bes, \musicInBflat @}
 761 @end example
 762
 763 @noindent
 764 For more information about transposing instruments,
 765 see @ref{Instrument transpositions}.
 766
 767
 768 @snippets
 769
 770 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 771 {transposing-pitches-with-minimum-accidentals-smart-transpose.ly}
 772
 773
 774 @seealso
 775 Notation Reference:
 776 @ref{Relative octave entry},
 777 @ref{Instrument transpositions}.
 778
 779 Snippets:
 780 @rlsr{Pitches}.
 781
 782 Internals Reference:
 783 @rinternals{TransposedMusic}.
 784
 785
 786 @funindex \transpose
 787 @funindex transpose
 788 @funindex \chordmode
 789 @funindex chordmode
 790 @funindex \relative
 791 @funindex relative
 792
 793 @knownissues
 794
 795 The relative conversion will not affect @code{\transpose},
 796 @code{\chordmode} or @code{\relative} sections in its argument.
 797 To use relative mode within transposed music, an additional
 798 @code{\relative} must be placed inside @code{\transpose}.
 799
 800 @node Displaying pitches
 801 @subsection Displaying pitches
 802
 803 This section discusses how to alter the output of pitches.
 804
 805 @menu
 806 * Clef::
 807 * Key signature::
 808 * Ottava brackets::
 809 * Instrument transpositions::
 810 * Automatic accidentals::
 811 * Ambitus::
 812 @end menu
 813
 814
 815 @node Clef
 816 @unnumberedsubsubsec Clef
 817
 818 @cindex G clef
 819 @cindex C clef
 820 @cindex F clef
 821 @cindex treble clef
 822 @cindex violin clef
 823 @cindex alto clef
 824 @cindex tenor clef
 825 @cindex bass clef
 826 @cindex french clef
 827 @cindex soprano clef
 828 @cindex mezzosoprano clef
 829 @cindex baritone clef
 830 @cindex varbaritone clef
 831 @cindex subbass clef
 832 @cindex clef
 833 @cindex ancient clef
 834 @cindex clef, ancient
 835 @cindex clef, G
 836 @cindex clef, C
 837 @cindex clef, F
 838 @cindex clef, treble
 839 @cindex clef, violin
 840 @cindex clef, alto
 841 @cindex clef, tenor
 842 @cindex clef, bass
 843 @cindex clef, french
 844 @cindex clef, soprano
 845 @cindex clef, mezzosoprano
 846 @cindex clef, baritone
 847 @cindex clef, varbaritone
 848 @cindex subbass clef, subbass
 849
 850 @funindex \clef
 851 @funindex clef
 852
 853 The clef may be altered.  Middle C is shown in every example.
 854
 855 @lilypond[verbatim,quote,relative=1]
 856 \clef treble
 857 c2 c
 858 \clef alto
 859 c2 c
 860 \clef tenor
 861 c2 c
 862 \clef bass
 863 c2 c
 864 @end lilypond
 865
 866 Other clefs include:
 867
 868 @lilypond[verbatim,quote,relative=1]
 869 \clef french
 870 c2 c
 871 \clef soprano
 872 c2 c
 873 \clef mezzosoprano
 874 c2 c
 875 \clef baritone
 876 c2 c
 877
 878 \break
 879
 880 \clef varbaritone
 881 c2 c
 882 \clef subbass
 883 c2 c
 884 \clef percussion
 885 c2 c
 886 \clef tab
 887 c2 c
 888
 889 \break
 890
 891 \clef G
 892 c2 c
 893 \clef F
 894 c2 c
 895 \clef C
 896 c2 c
 897
 898 @end lilypond
 899
 900 Further supported clefs are described under @ref{Mensural clefs}
 901 and @ref{Gregorian clefs}.
 902
 903 @cindex transposing clefs
 904 @cindex clef, transposing
 905 @cindex octave transposition
 906 @cindex choral tenor clef
 907 @cindex tenor clef, choral
 908
 909 By adding@tie{}@code{_8} or@tie{}@code{^8} to the clef name, the
 910 clef is transposed one octave down or up, respectively,
 911 and@tie{}@code{_15} and@tie{}@code{^15} transpose by two octaves.
 912 The clef name must be enclosed in quotes when it contains
 913 underscores or digits.
 914
 915 @lilypond[verbatim,quote,relative=2]
 916 \clef treble
 917 c2 c
 918 \clef "treble_8"
 919 c2 c
 920 \clef "bass^15"
 921 c2 c
 922 @end lilypond
 923
 924
 925 @snippets
 926
 927 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 928 {tweaking-clef-properties.ly}
 929
 930
 931 @seealso
 932 Notation Reference:
 933 @ref{Mensural clefs}, @ref{Gregorian clefs}.
 934
 935 Snippets:
 936 @rlsr{Pitches}.
 937
 938 Internals Reference:
 939 @rinternals{Clef_engraver},
 940 @rinternals{Clef},
 941 @rinternals{OctavateEight},
 942 @rinternals{clef-interface}.
 943
 944
 945 @node Key signature
 946 @unnumberedsubsubsec Key signature
 947
 948 @cindex key signature
 949
 950 @funindex \key
 951 @funindex key
 952
 953 @c duplicated in Key signature and Accidentals
 954 @warning{New users are sometimes confused about accidentals and
 955 key signatures.  In LilyPond, note names are the raw input; key
 956 signatures and clefs determine how this raw input is displayed.
 957 An unaltered note like@tie{}@code{c} means @q{C natural},
 958 regardless of the key signature or clef.  For more information,
 959 see @rlearning{Accidentals and key signatures}.}
 960
 961 The key signature indicates the tonality in which a piece is
 962 played.  It is denoted by a set of alterations (flats or sharps)
 963 at the start of the staff.  The key signature may be altered:
 964
 965 @example
 966 \key @var{pitch} @var{mode}
 967 @end example
 968
 969 @funindex \major
 970 @funindex major
 971 @funindex \minor
 972 @funindex minor
 973 @funindex \ionian
 974 @funindex ionian
 975 @funindex \locrian
 976 @funindex locrian
 977 @funindex \aeolian
 978 @funindex aeolian
 979 @funindex \mixolydian
 980 @funindex mixolydian
 981 @funindex \lydian
 982 @funindex lydian
 983 @funindex \phrygian
 984 @funindex phrygian
 985 @funindex \dorian
 986 @funindex dorian
 987
 988 @cindex church modes
 989 @cindex modes
 990 @cindex major
 991 @cindex minor
 992 @cindex ionian
 993 @cindex locrian
 994 @cindex aeolian
 995 @cindex mixolydian
 996 @cindex lydian
 997 @cindex phrygian
 998 @cindex dorian
 999
1000 Here, @var{mode} should be @code{\major} or @code{\minor} to get a
1001 key signature of @var{pitch}-major or @var{pitch}-minor,
1002 respectively.  You may also use the standard mode names, also
1003 called @notation{church modes}: @code{\ionian}, @code{\dorian},
1004 @code{\phrygian}, @code{\lydian}, @code{\mixolydian},
1005 @code{\aeolian}, and @code{\locrian}.
1006
1007 @lilypond[verbatim,quote,relative=2]
1008 \key g \major
1009 fis1
1010 f
1011 fis
1012 @end lilypond
1013
1014
1015 @snippets
1016
1017 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
1018 {preventing-natural-signs-from-being-printed-when-the-key-signature-changes.ly}
1019
1020 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
1021 {non-traditional-key-signatures.ly}
1022
1023
1024 @seealso
1025 Music Glossary:
1026 @rglos{church mode},
1027 @rglos{scordatura}.
1028
1029 Learning Manual:
1030 @rlearning{Accidentals and key signatures}.
1031
1032 Snippets:
1033 @rlsr{Pitches}.
1034
1035 Internals Reference:
1036 @rinternals{KeyChangeEvent},
1037 @rinternals{Key_engraver},
1038 @rinternals{Key_performer},
1039 @rinternals{KeyCancellation},
1040 @rinternals{KeySignature},
1041 @rinternals{key-cancellation-interface},
1042 @rinternals{key-signature-interface}.
1043
1044
1045 @node Ottava brackets
1046 @unnumberedsubsubsec Ottava brackets
1047
1048 @cindex ottava
1049 @cindex 15ma
1050 @cindex 8va
1051 @cindex 8ve
1052 @cindex octavation
1053
1054 @funindex set-octavation
1055 @funindex \ottava
1056 @funindex ottava
1057
1058 @notation{Ottava brackets} introduce an extra transposition of an
1059 octave for the staff:
1060
1061 @lilypond[verbatim,quote,relative=2]
1062 a'2 b
1063 \ottava #1
1064 a b
1065 \ottava #0
1066 a b
1067 @end lilypond
1068
1069 The @code{ottava} function also takes -1 (for 8va bassa),
1070 2@tie{}(for 15ma), and -2 (for 15ma bassa) as arguments.
1071
1072
1073 @snippets
1074
1075 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
1076 {ottava-text.ly}
1077
1078
1079 @seealso
1080 Music Glossary:
1081 @rglos{octavation}.
1082
1083 Snippets:
1084 @rlsr{Pitches}.
1085
1086 Internals Reference:
1087 @rinternals{Ottava_spanner_engraver},
1088 @rinternals{OttavaBracket},
1089 @rinternals{ottava-bracket-interface}.
1090
1091
1092 @node Instrument transpositions
1093 @unnumberedsubsubsec Instrument transpositions
1094
1095 @cindex transposition, MIDI
1096 @cindex transposition, instrument
1097 @cindex transposing instrument
1098 @cindex MIDI
1099 @cindex MIDI transposition
1100
1101 @funindex \transposition
1102 @funindex transposition
1103
1104 When typesetting scores that involve transposing instruments, some
1105 parts can be typeset in a different pitch than the
1106 @notation{concert pitch}.  In these cases, the key of the
1107 @notation{transposing instrument} should be specified; otherwise
1108 the MIDI output and cues in other parts will produce incorrect
1109 pitches.  For more information about quotations, see
1110 @ref{Quoting other voices}.
1111
1112 @example
1113 \transposition @var{pitch}
1114 @end example
1115
1116 The pitch to use for @code{\transposition} should correspond to
1117 the real sound heard when a@tie{}@code{c'} written on the staff is
1118 played by the transposing instrument.  This pitch is entered in
1119 absolute mode, so an instrument that produces a real sound which
1120 is one tone higher than the printed music should use
1121 @w{@code{\transposition d'}}.  @code{\transposition} should
1122 @emph{only} be used if the pitches are @emph{not} being entered in
1123 concert pitch.
1124
1125 Here are a few notes for violin and B-flat clarinet where the
1126 parts have been entered using the notes and key as they appear in
1127 each part of the conductor's score.  The two instruments are
1128 playing in unison.
1129
1130 @lilypond[verbatim,quote]
1131 \new GrandStaff <<
1132   \new Staff = "violin" {
1133     \relative c'' {
1134       \set Staff.instrumentName = #"Vln"
1135       \set Staff.midiInstrument = #"violin"
1136       % not strictly necessary, but a good reminder
1137       \transposition c'
1138
1139       \key c \major
1140       g4( c8) r c r c4
1141     }
1142   }
1143   \new Staff = "clarinet" {
1144     \relative c'' {
1145       \set Staff.instrumentName = \markup { Cl (B\flat) }
1146       \set Staff.midiInstrument = #"clarinet"
1147       \transposition bes
1148
1149       \key d \major
1150       a4( d8) r d r d4
1151     }
1152   }
1153 >>
1154 @end lilypond
1155
1156 The @code{\transposition} may be changed during a piece.  For
1157 example, a clarinetist may switch from an A clarinet to a B-flat
1158 clarinet.
1159
1160 @lilypond[verbatim,quote,relative=2]
1161 \set Staff.instrumentName = #"Cl (A)"
1162 \key a \major
1163 \transposition a
1164 c d e f
1165 \textLengthOn
1166 s1*0^\markup { Switch to B\flat clarinet }
1167 R1
1168
1169 \key bes \major
1170 \transposition bes
1171 c2 g
1172 @end lilypond
1173
1174
1175 @seealso
1176 Music Glossary:
1177 @rglos{concert pitch},
1178 @rglos{transposing instrument}.
1179
1180 Notation Reference:
1181 @ref{Quoting other voices}, @ref{Transpose}.
1182
1183 Snippets:
1184 @rlsr{Pitches}.
1185
1186
1187 @node Automatic accidentals
1188 @unnumberedsubsubsec Automatic accidentals
1189
1190 @cindex accidental style
1191 @cindex accidental style, default
1192 @cindex accidentals
1193 @cindex accidentals, automatic
1194 @cindex automatic accidentals
1195 @cindex default accidental style
1196
1197 @funindex set-accidental-style
1198 @funindex voice
1199 @funindex default
1200
1201 There are many different conventions on how to typeset
1202 accidentals.  LilyPond provides a function to specify which
1203 accidental style to use.  This function is called as follows:
1204
1205 @example
1206 \new Staff <<
1207   #(set-accidental-style 'voice)
1208   @{ @dots{} @}
1209 >>
1210 @end example
1211
1212 The accidental style applies to the current @code{Staff} by
1213 default (with the exception of the styles @code{piano} and
1214 @code{piano-cautionary}, which are explained below).  Optionally,
1215 the function can take a second argument that determines in which
1216 scope the style should be changed.  For example, to use the same
1217 style in all staves of the current @code{StaffGroup}, use:
1218
1219 @example
1220 #(set-accidental-style 'voice 'StaffGroup)
1221 @end example
1222
1223 The following accidental styles are supported.  To demonstrate
1224 each style, we use the following example:
1225
1226
1227 @lilypond[verbatim,quote]
1228 musicA = {
1229   <<
1230     \relative c' {
1231       cis'8 fis, d'4 <a cis>8 f bis4 |
1232       cis2. <c, g'>4 |
1233     }
1234     \\
1235     \relative c' {
1236       ais'2 cis, |
1237       fis8 b a4 cis2 |
1238     }
1239   >>
1240 }
1241
1242 musicB = {
1243   \clef bass
1244   \new Voice {
1245     \voiceTwo \relative c' {
1246       <fis, a cis>4
1247       \change Staff = up
1248       cis'
1249       \change Staff = down
1250       <fis, a>
1251       \change Staff = up
1252       dis' |
1253       \change Staff = down
1254       <fis, a cis>4 gis <f a d>2 |
1255     }
1256   }
1257 }
1258
1259 \new PianoStaff {
1260   <<
1261     \context Staff = "up" {
1262       #(set-accidental-style 'default)
1263       \musicA
1264     }
1265     \context Staff = "down" {
1266       #(set-accidental-style 'default)
1267       \musicB
1268     }
1269   >>
1270 }
1271 @end lilypond
1272
1273 Note that the last lines of this example can be replaced by the
1274 following, as long as the same accidental style should be used in
1275 both staves.
1276
1277 @example
1278 \new PianoStaff @{
1279   <<
1280     \context Staff = "up" @{
1281       %%% change the next line as desired:
1282       #(set-accidental-style 'default 'Score)
1283       \musicA
1284     @}
1285     \context Staff = "down" @{
1286       \musicB
1287     @}
1288   >>
1289 @}
1290 @end example
1291
1292
1293 @c don't use verbatim in this table.
1294 @table @code
1295 @item default
1296
1297 @cindex default accidental style
1298 @cindex accidental style, default
1299
1300 @funindex default
1301
1302 This is the default typesetting behavior.  It corresponds to
1303 eighteenth-century common practice: accidentals are remembered to
1304 the end of the measure in which they occur and only in their own
1305 octave.  Thus, in the example below, no natural signs are printed
1306 before the@tie{}@code{b} in the second measure or the
1307 last@tie{}@code{c}:
1308
1309 @lilypond[quote]
1310 musicA = {
1311   <<
1312     \relative c' {
1313       cis'8 fis, d'4 <a cis>8 f bis4 |
1314       cis2. <c, g'>4 |
1315     }
1316     \\
1317     \relative c' {
1318       ais'2 cis, |
1319       fis8 b a4 cis2 |
1320     }
1321   >>
1322 }
1323
1324 musicB = {
1325   \clef bass
1326   \new Voice {
1327     \voiceTwo \relative c' {
1328       <fis, a cis>4
1329       \change Staff = up
1330       cis'
1331       \change Staff = down
1332       <fis, a>
1333       \change Staff = up
1334       dis' |
1335       \change Staff = down
1336       <fis, a cis>4 gis <f a d>2 |
1337     }
1338   }
1339 }
1340
1341 \new PianoStaff {
1342   <<
1343     \context Staff = "up" {
1344       #(set-accidental-style 'default)
1345       \musicA
1346     }
1347     \context Staff = "down" {
1348       #(set-accidental-style 'default)
1349       \musicB
1350     }
1351   >>
1352 }
1353 @end lilypond
1354
1355 @item voice
1356
1357 @cindex accidental style, voice
1358 @cindex voice accidental style
1359 @cindex accidental style, modern
1360 @cindex modern accidental style
1361 @cindex accidental style, modern-cautionary
1362 @cindex modern-cautionary accidental style
1363
1364 @funindex voice
1365
1366 The normal behavior is to remember the accidentals at
1367 @code{Staff}-level.  In this style, however, accidentals are
1368 typeset individually for each voice.  Apart from that, the rule is
1369 similar to @code{default}.
1370
1371 As a result, accidentals from one voice do not get canceled in
1372 other voices, which is often an unwanted result: in the following
1373 example, it is hard to determine whether the second@tie{}@code{a}
1374 should be played natural or sharp.  The @code{voice} option should
1375 therefore be used only if the voices are to be read solely by
1376 individual musicians.  If the staff is to be used by one musician
1377 (e.g., a conductor or in a piano score) then @code{modern} or
1378 @code{modern-cautionary} should be used instead.
1379
1380
1381 @lilypond[quote]
1382 musicA = {
1383   <<
1384     \relative c' {
1385       cis'8 fis, d'4 <a cis>8 f bis4 |
1386       cis2. <c, g'>4 |
1387     }
1388     \\
1389     \relative c' {
1390       ais'2 cis, |
1391       fis8 b a4 cis2 |
1392     }
1393   >>
1394 }
1395
1396 musicB = {
1397   \clef bass
1398   \new Voice {
1399     \voiceTwo \relative c' {
1400       <fis, a cis>4
1401       \change Staff = up
1402       cis'
1403       \change Staff = down
1404       <fis, a>
1405       \change Staff = up
1406       dis' |
1407       \change Staff = down
1408       <fis, a cis>4 gis <f a d>2 |
1409     }
1410   }
1411 }
1412
1413 \new PianoStaff {
1414   <<
1415     \context Staff = "up" {
1416       #(set-accidental-style 'voice)
1417       \musicA
1418     }
1419     \context Staff = "down" {
1420       #(set-accidental-style 'voice)
1421       \musicB
1422     }
1423   >>
1424 }
1425 @end lilypond
1426
1427 @item modern
1428
1429 @cindex accidentals, modern style
1430 @cindex modern style accidentals
1431
1432 @funindex modern
1433
1434 This rule corresponds to the common practice in the twentieth
1435 century.  It prints the same accidentals as @code{default}, with
1436 two exceptions that serve to avoid ambiguity: after temporary
1437 accidentals, cancellation marks are printed also in the following
1438 measure (for notes in the same octave) and, in the same measure,
1439 for notes in other octaves.  Hence the naturals before
1440 the@tie{}@code{b} and the@tie{}@code{c} in the second measure of
1441 the upper staff:
1442
1443 @lilypond[quote]
1444 musicA = {
1445   <<
1446     \relative c' {
1447       cis'8 fis, d'4 <a cis>8 f bis4 |
1448       cis2. <c, g'>4 |
1449     }
1450     \\
1451     \relative c' {
1452       ais'2 cis, |
1453       fis8 b a4 cis2 |
1454     }
1455   >>
1456 }
1457
1458 musicB = {
1459   \clef bass
1460   \new Voice {
1461     \voiceTwo \relative c' {
1462       <fis, a cis>4
1463       \change Staff = up
1464       cis'
1465       \change Staff = down
1466       <fis, a>
1467       \change Staff = up
1468       dis' |
1469       \change Staff = down
1470       <fis, a cis>4 gis <f a d>2 |
1471     }
1472   }
1473 }
1474
1475 \new PianoStaff {
1476   <<
1477     \context Staff = "up" {
1478       #(set-accidental-style 'modern)
1479       \musicA
1480     }
1481     \context Staff = "down" {
1482       #(set-accidental-style 'modern)
1483       \musicB
1484     }
1485   >>
1486 }
1487 @end lilypond
1488
1489 @item modern-cautionary
1490
1491 @cindex accidentals, modern cautionary style
1492 @cindex modern accidental style
1493 @cindex modern cautionary accidental style
1494 @cindex modern style accidentals
1495 @cindex modern style cautionary accidentals
1496
1497 @funindex modern-cautionary
1498
1499 This rule is similar to @code{modern}, but the @q{extra}
1500 accidentals (the ones not typeset by @code{default}) are typeset
1501 as cautionary accidentals.  They are by default printed with
1502 parentheses, but they can also be printed in reduced size by
1503 defining the @code{cautionary-style} property of
1504 @code{AccidentalSuggestion}.
1505
1506 @lilypond[quote]
1507 musicA = {
1508   <<
1509     \relative c' {
1510       cis'8 fis, d'4 <a cis>8 f bis4 |
1511       cis2. <c, g'>4 |
1512     }
1513     \\
1514     \relative c' {
1515       ais'2 cis, |
1516       fis8 b a4 cis2 |
1517     }
1518   >>
1519 }
1520
1521 musicB = {
1522   \clef bass
1523   \new Voice {
1524     \voiceTwo \relative c' {
1525       <fis, a cis>4
1526       \change Staff = up
1527       cis'
1528       \change Staff = down
1529       <fis, a>
1530       \change Staff = up
1531       dis' |
1532       \change Staff = down
1533       <fis, a cis>4 gis <f a d>2 |
1534     }
1535   }
1536 }
1537
1538 \new PianoStaff {
1539   <<
1540     \context Staff = "up" {
1541       #(set-accidental-style 'modern-cautionary)
1542       \musicA
1543     }
1544     \context Staff = "down" {
1545       #(set-accidental-style 'modern-cautionary)
1546       \musicB
1547     }
1548   >>
1549 }
1550 @end lilypond
1551
1552 @item modern-voice
1553
1554 @cindex accidental style, modern
1555 @cindex accidentals, modern
1556 @cindex accidentals, multivoice
1557 @cindex modern accidental style
1558 @cindex modern accidentals
1559 @cindex multivoice accidentals
1560
1561 @funindex modern-voice
1562
1563 This rule is used for multivoice accidentals to be read both by
1564 musicians playing one voice and musicians playing all voices.
1565 Accidentals are typeset for each voice, but they @emph{are}
1566 canceled across voices in the same @code{Staff}.  Hence,
1567 the@tie{}@code{a} in the last measure is canceled because the
1568 previous cancellation was in a different voice, and
1569 the@tie{}@code{d} in the lower staff is canceled because of the
1570 accidental in a different voice in the previous measure:
1571
1572 @lilypond[quote]
1573 musicA = {
1574   <<
1575     \relative c' {
1576       cis'8 fis, d'4 <a cis>8 f bis4 |
1577       cis2. <c, g'>4 |
1578     }
1579     \\
1580     \relative c' {
1581       ais'2 cis, |
1582       fis8 b a4 cis2 |
1583     }
1584   >>
1585 }
1586
1587 musicB = {
1588   \clef bass
1589   \new Voice {
1590     \voiceTwo \relative c' {
1591       <fis, a cis>4
1592       \change Staff = up
1593       cis'
1594       \change Staff = down
1595       <fis, a>
1596       \change Staff = up
1597       dis' |
1598       \change Staff = down
1599       <fis, a cis>4 gis <f a d>2 |
1600     }
1601   }
1602 }
1603
1604 \new PianoStaff {
1605   <<
1606     \context Staff = "up" {
1607       #(set-accidental-style 'modern-voice)
1608       \musicA
1609     }
1610     \context Staff = "down" {
1611       #(set-accidental-style 'modern-voice)
1612       \musicB
1613     }
1614   >>
1615 }
1616 @end lilypond
1617
1618 @cindex accidental style, cautionary, modern voice
1619 @cindex accidental style, modern voice cautionary
1620 @cindex accidental style, voice, modern cautionary
1621
1622 @funindex modern-voice-cautionary
1623
1624 @item modern-voice-cautionary
1625
1626 This rule is the same as @code{modern-voice}, but with the extra
1627 accidentals (the ones not typeset by @code{voice}) typeset as
1628 cautionaries.  Even though all accidentals typeset by
1629 @code{default} @emph{are} typeset with this rule, some of them are
1630 typeset as cautionaries.
1631
1632 @lilypond[quote]
1633 musicA = {
1634   <<
1635     \relative c' {
1636       cis'8 fis, d'4 <a cis>8 f bis4 |
1637       cis2. <c, g'>4 |
1638     }
1639     \\
1640     \relative c' {
1641       ais'2 cis, |
1642       fis8 b a4 cis2 |
1643     }
1644   >>
1645 }
1646
1647 musicB = {
1648   \clef bass
1649   \new Voice {
1650     \voiceTwo \relative c' {
1651       <fis, a cis>4
1652       \change Staff = up
1653       cis'
1654       \change Staff = down
1655       <fis, a>
1656       \change Staff = up
1657       dis' |
1658       \change Staff = down
1659       <fis, a cis>4 gis <f a d>2 |
1660     }
1661   }
1662 }
1663
1664 \new PianoStaff {
1665   <<
1666     \context Staff = "up" {
1667       #(set-accidental-style 'modern-voice-cautionary)
1668       \musicA
1669     }
1670     \context Staff = "down" {
1671       #(set-accidental-style 'modern-voice-cautionary)
1672       \musicB
1673     }
1674   >>
1675 }
1676 @end lilypond
1677
1678 @item piano
1679
1680 @cindex accidental style, piano
1681 @cindex accidentals, piano
1682 @cindex piano accidental style
1683 @cindex piano accidentals
1684
1685 @funindex piano
1686
1687 This rule reflects twentieth-century practice for piano notation.
1688 Its behavior is very similar to @code{modern} style, but here
1689 accidentals also get canceled across the staves in the same
1690 @code{GrandStaff} or @code{PianoStaff}, hence all the
1691 cancellations of the final notes.
1692
1693 This accidental style applies to the current @code{GrandStaff} or
1694 @code{PianoStaff} by default.
1695
1696 @lilypond[quote]
1697 musicA = {
1698   <<
1699     \relative c' {
1700       cis'8 fis, d'4 <a cis>8 f bis4 |
1701       cis2. <c, g'>4 |
1702     }
1703     \\
1704     \relative c' {
1705       ais'2 cis, |
1706       fis8 b a4 cis2 |
1707     }
1708   >>
1709 }
1710
1711 musicB = {
1712   \clef bass
1713   \new Voice {
1714     \voiceTwo \relative c' {
1715       <fis, a cis>4
1716       \change Staff = up
1717       cis'
1718       \change Staff = down
1719       <fis, a>
1720       \change Staff = up
1721       dis' |
1722       \change Staff = down
1723       <fis, a cis>4 gis <f a d>2 |
1724     }
1725   }
1726 }
1727
1728 \new PianoStaff {
1729   <<
1730     \context Staff = "up" {
1731       #(set-accidental-style 'piano)
1732       \musicA
1733     }
1734     \context Staff = "down" {
1735       \musicB
1736     }
1737   >>
1738 }
1739 @end lilypond
1740
1741 @item piano-cautionary
1742
1743 @cindex accidentals, piano cautionary
1744 @cindex cautionary accidentals, piano
1745 @cindex piano cautionary accidentals
1746 @cindex accidental style, piano cautionary
1747 @cindex cautionary accidental style, piano
1748 @cindex piano cautionary accidental style
1749
1750 @funindex piano-cautionary
1751
1752 This is the same as @code{piano} but with the extra accidentals
1753 typeset as cautionaries.
1754
1755 @lilypond[quote]
1756 musicA = {
1757   <<
1758     \relative c' {
1759       cis'8 fis, d'4 <a cis>8 f bis4 |
1760       cis2. <c, g'>4 |
1761     }
1762     \\
1763     \relative c' {
1764       ais'2 cis, |
1765       fis8 b a4 cis2 |
1766     }
1767   >>
1768 }
1769
1770 musicB = {
1771   \clef bass
1772   \new Voice {
1773     \voiceTwo \relative c' {
1774       <fis, a cis>4
1775       \change Staff = up
1776       cis'
1777       \change Staff = down
1778       <fis, a>
1779       \change Staff = up
1780       dis' |
1781       \change Staff = down
1782       <fis, a cis>4 gis <f a d>2 |
1783     }
1784   }
1785 }
1786
1787 \new PianoStaff {
1788   <<
1789     \context Staff = "up" {
1790       #(set-accidental-style 'piano-cautionary)
1791       \musicA
1792     }
1793     \context Staff = "down" {
1794       \musicB
1795     }
1796   >>
1797 }
1798 @end lilypond
1799
1800
1801 @item neo-modern
1802
1803 @cindex neo-modern accidental style
1804 @cindex accidental style, neo-modern
1805
1806 @funindex neo-modern
1807
1808 This rule reproduces a common practice in contemporary music:
1809 accidentals are printed like with @code{modern}, but they are printed
1810 again if the same note appears later in the same measure -- except
1811 if the note is immediately repeated.
1812
1813 @lilypond[quote]
1814 musicA = {
1815   <<
1816     \relative c' {
1817       cis'8 fis, d'4 <a cis>8 f bis4 |
1818       cis2. <c, g'>4 |
1819     }
1820     \\
1821     \relative c' {
1822       ais'2 cis, |
1823       fis8 b a4 cis2 |
1824     }
1825   >>
1826 }
1827
1828 musicB = {
1829   \clef bass
1830   \new Voice {
1831     \voiceTwo \relative c' {
1832       <fis, a cis>4
1833       \change Staff = up
1834       cis'
1835       \change Staff = down
1836       <fis, a>
1837       \change Staff = up
1838       dis' |
1839       \change Staff = down
1840       <fis, a cis>4 gis <f a d>2 |
1841     }
1842   }
1843 }
1844
1845 \new PianoStaff {
1846   <<
1847     \context Staff = "up" {
1848       #(set-accidental-style 'neo-modern)
1849       \musicA
1850     }
1851     \context Staff = "down" {
1852       #(set-accidental-style 'neo-modern)
1853       \musicB
1854     }
1855   >>
1856 }
1857 @end lilypond
1858
1859 @item neo-modern-cautionary
1860
1861 @cindex neo-modern-cautionary accidental style
1862 @cindex accidental style, neo-modern-cautionary
1863
1864 @funindex neo-modern-cautionary
1865
1866 This rule is similar to @code{neo-modern}, but the extra
1867 accidentals are printed as cautionary accidentals.
1868
1869 @lilypond[quote]
1870 musicA = {
1871   <<
1872     \relative c' {
1873       cis'8 fis, d'4 <a cis>8 f bis4 |
1874       cis2. <c, g'>4 |
1875     }
1876     \\
1877     \relative c' {
1878       ais'2 cis, |
1879       fis8 b a4 cis2 |
1880     }
1881   >>
1882 }
1883
1884 musicB = {
1885   \clef bass
1886   \new Voice {
1887     \voiceTwo \relative c' {
1888       <fis, a cis>4
1889       \change Staff = up
1890       cis'
1891       \change Staff = down
1892       <fis, a>
1893       \change Staff = up
1894       dis' |
1895       \change Staff = down
1896       <fis, a cis>4 gis <f a d>2 |
1897     }
1898   }
1899 }
1900
1901 \new PianoStaff {
1902   <<
1903     \context Staff = "up" {
1904       #(set-accidental-style 'neo-modern-cautionary)
1905       \musicA
1906     }
1907     \context Staff = "down" {
1908       #(set-accidental-style 'neo-modern-cautionary)
1909       \musicB
1910     }
1911   >>
1912 }
1913 @end lilypond
1914
1915
1916 @item dodecaphonic
1917
1918 @cindex dodecaphonic accidental style
1919 @cindex dodecaphonic style, neo-modern
1920
1921 @funindex dodecaphonic
1922
1923 This rule reflects a practice introduced by composers at
1924 the beginning of the 20th century, in an attempt to
1925 abolish the hierarchy between natural and non-natural notes.
1926 With this style, @emph{every} note gets an accidental sign,
1927 including natural signs.
1928
1929 @lilypond[quote]
1930 musicA = {
1931   <<
1932     \relative c' {
1933       cis'8 fis, d'4 <a cis>8 f bis4 |
1934       cis2. <c, g'>4 |
1935     }
1936     \\
1937     \relative c' {
1938       ais'2 cis, |
1939       fis8 b a4 cis2 |
1940     }
1941   >>
1942 }
1943
1944 musicB = {
1945   \clef bass
1946   \new Voice {
1947     \voiceTwo \relative c' {
1948       <fis, a cis>4
1949       \change Staff = up
1950       cis'
1951       \change Staff = down
1952       <fis, a>
1953       \change Staff = up
1954       dis' |
1955       \change Staff = down
1956       <fis, a cis>4 gis <f a d>2 |
1957     }
1958   }
1959 }
1960
1961 \new PianoStaff {
1962   <<
1963     \context Staff = "up" {
1964       #(set-accidental-style 'dodecaphonic)
1965       \musicA
1966     }
1967     \context Staff = "down" {
1968       #(set-accidental-style 'dodecaphonic)
1969       \musicB
1970     }
1971   >>
1972 }
1973 @end lilypond
1974
1975
1976 @item teaching
1977
1978 @cindex teaching accidental style
1979 @cindex accidental style, teaching
1980
1981 @funindex teaching
1982
1983 This rule is intended for students, and makes it easy to create
1984 scale sheets with automagically created cautionary accidentals.
1985 Accidentals are printed like with @code{modern}, but cautionary
1986 accidentals are added for all sharp or flat tones specified by the
1987 key signature, except if the note is immediately repeated.
1988
1989 @lilypond[quote]
1990 musicA = {
1991   <<
1992     \relative c' {
1993       cis'8 fis, d'4 <a cis>8 f bis4 |
1994       cis2. <c, g'>4 |
1995     }
1996     \\
1997     \relative c' {
1998       ais'2 cis, |
1999       fis8 b a4 cis2 |
2000     }
2001   >>
2002 }
2003
2004 musicB = {
2005   \clef bass
2006   \new Voice {
2007     \voiceTwo \relative c' {
2008       <fis, a cis>4
2009       \change Staff = up
2010       cis'
2011       \change Staff = down
2012       <fis, a>
2013       \change Staff = up
2014       dis' |
2015       \change Staff = down
2016       <fis, a cis>4 gis <f a d>2 |
2017     }
2018   }
2019 }
2020
2021 \new PianoStaff {
2022   <<
2023     \context Staff = "up" {
2024       \key fis \minor
2025       #(set-accidental-style 'teaching)
2026       \musicA
2027     }
2028     \context Staff = "down" {
2029       \key fis \minor
2030       #(set-accidental-style 'teaching)
2031       \musicB
2032     }
2033   >>
2034 }
2035 @end lilypond
2036
2037
2038
2039 @item no-reset
2040
2041 @cindex accidental style, no reset
2042 @cindex no reset accidental style
2043
2044 @funindex no-reset
2045
2046 This is the same as @code{default} but with accidentals lasting
2047 @q{forever} and not only within the same measure:
2048
2049 @lilypond[quote]
2050 musicA = {
2051   <<
2052     \relative c' {
2053       cis'8 fis, d'4 <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>4
2069       \change Staff = up
2070       cis'
2071       \change Staff = down
2072       <fis, a>
2073       \change Staff = up
2074       dis' |
2075       \change Staff = down
2076       <fis, a cis>4 gis <f a d>2 |
2077     }
2078   }
2079 }
2080
2081 \new PianoStaff {
2082   <<
2083     \context Staff = "up" {
2084       #(set-accidental-style 'no-reset)
2085       \musicA
2086     }
2087     \context Staff = "down" {
2088       #(set-accidental-style 'no-reset)
2089       \musicB
2090     }
2091   >>
2092 }
2093 @end lilypond
2094
2095 @item forget
2096
2097 @cindex forget accidental style
2098 @cindex accidental style, forget
2099
2100 @funindex forget
2101
2102 This is the opposite of @code{no-reset}: Accidentals are not
2103 remembered at all -- and hence all accidentals are typeset
2104 relative to the key signature, regardless of what came before in
2105 the music.  Unlike @code{dodecaphonic}, this rule never prints
2106 any naturals.
2107
2108 @lilypond[quote]
2109 musicA = {
2110   <<
2111     \relative c' {
2112       cis'8 fis, d'4 <a cis>8 f bis4 |
2113       cis2. <c, g'>4 |
2114     }
2115     \\
2116     \relative c' {
2117       ais'2 cis, |
2118       fis8 b a4 cis2 |
2119     }
2120   >>
2121 }
2122
2123 musicB = {
2124   \clef bass
2125   \new Voice {
2126     \voiceTwo \relative c' {
2127       <fis, a cis>4
2128       \change Staff = up
2129       cis'
2130       \change Staff = down
2131       <fis, a>
2132       \change Staff = up
2133       dis' |
2134       \change Staff = down
2135       <fis, a cis>4 gis <f a d>2 |
2136     }
2137   }
2138 }
2139
2140 \new PianoStaff {
2141   <<
2142     \context Staff = "up" {
2143       #(set-accidental-style 'forget)
2144       \musicA
2145     }
2146     \context Staff = "down" {
2147       #(set-accidental-style 'forget)
2148       \musicB
2149     }
2150   >>
2151 }
2152 @end lilypond
2153 @end table
2154
2155 @snippets
2156
2157 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
2158 {dodecaphonic-style-accidentals-for-each-note-including-naturals.ly}
2159
2160
2161 @seealso
2162 Snippets:
2163 @rlsr{Pitches}.
2164
2165 Internals Reference:
2166 @rinternals{Accidental},
2167 @rinternals{Accidental_engraver},
2168 @rinternals{GrandStaff} and
2169 @rinternals{PianoStaff},
2170 @rinternals{Staff},
2171 @rinternals{AccidentalSuggestion},
2172 @rinternals{AccidentalPlacement},
2173 @rinternals{accidental-suggestion-interface}.
2174
2175
2176 @cindex accidentals and simultaneous notes
2177 @cindex simultaneous notes and accidentals
2178 @cindex accidentals in chords
2179 @cindex chords, accidentals in
2180
2181 @knownissues
2182
2183 Simultaneous notes are considered to be entered in sequential
2184 mode.  This means that in a chord the accidentals are typeset as
2185 if the notes in the chord happen one at a time, in the order in
2186 which they appear in the input file.  This is a problem when
2187 accidentals in a chord depend on each other, which does not happen
2188 for the default accidental style.  The problem can be solved by
2189 manually inserting@tie{}@code{!} and@tie{}@code{?} for the
2190 problematic notes.
2191
2192
2193 @node Ambitus
2194 @unnumberedsubsubsec Ambitus
2195
2196 @cindex ambitus
2197 @cindex range of pitches
2198 @cindex pitch range
2199
2200 The term @notation{ambitus} (pl. ambitus) denotes a range of
2201 pitches for a given voice in a part of music.  It may also denote
2202 the pitch range that a musical instrument is capable of playing.
2203 Ambitus are printed on vocal parts so that performers can easily
2204 determine if it matches their capabilities.
2205
2206 Ambitus are denoted at the beginning of a piece near the initial
2207 clef.  The range is graphically specified by two note heads that
2208 represent the lowest and highest pitches.  Accidentals are only
2209 printed if they are not part of the key signature.
2210
2211 @lilypond[verbatim,quote]
2212 \layout {
2213   \context {
2214     \Voice
2215     \consists "Ambitus_engraver"
2216   }
2217 }
2218
2219 \relative c'' {
2220   aes c e2
2221   cis,1
2222 }
2223 @end lilypond
2224
2225
2226 @snippets
2227
2228 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
2229 {adding-ambitus-per-voice.ly}
2230
2231 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
2232 {ambitus-with-multiple-voices.ly}
2233
2234
2235 @seealso
2236 Music Glossary:
2237 @rglos{ambitus}.
2238
2239 Snippets:
2240 @rlsr{Pitches}.
2241
2242 Internals Reference:
2243 @rinternals{Ambitus_engraver},
2244 @rinternals{Voice},
2245 @rinternals{Staff},
2246 @rinternals{Ambitus},
2247 @rinternals{AmbitusAccidental},
2248 @rinternals{AmbitusLine},
2249 @rinternals{AmbitusNoteHead},
2250 @rinternals{ambitus-interface}.
2251
2252
2253 @knownissues
2254
2255 There is no collision handling in the case of multiple per-voice
2256 ambitus.
2257
2258
2259 @node Note heads
2260 @subsection Note heads
2261
2262 This section suggests ways of altering note heads.
2263
2264 @menu
2265 * Special note heads::
2266 * Easy notation note heads::
2267 * Shape note heads::
2268 * Improvisation::
2269 @end menu
2270
2271 @node Special note heads
2272 @unnumberedsubsubsec Special note heads
2273
2274 @cindex note heads, special
2275 @cindex note heads, cross
2276 @cindex note heads, diamond
2277 @cindex note heads, parlato
2278 @cindex note heads, harmonic
2279 @cindex note heads, guitar
2280 @cindex special note heads
2281 @cindex cross note heads
2282 @cindex diamond note heads
2283 @cindex parlato note heads
2284 @cindex harmonic note heads
2285 @cindex guitar note heads
2286 @cindex note head styles
2287 @cindex styles, note heads
2288
2289 @funindex cross
2290
2291 Note heads may be altered:
2292
2293 @lilypond[verbatim,quote,relative=2]
2294 c4 b a b
2295 \override NoteHead #'style = #'cross
2296 c4 b a b
2297 \revert NoteHead #'style
2298 c4 d e f
2299 @end lilypond
2300
2301 There is a shorthand for diamond shapes which can only be used
2302 inside chords:
2303
2304 @lilypond[verbatim,quote,relative=2]
2305 <c f\harmonic>2 <d a'\harmonic>4 <c g'\harmonic>
2306 @end lilypond
2307
2308 @noindent
2309 To see all note head styles, see @ref{Note head styles}.
2310
2311
2312 @seealso
2313 Snippets:
2314 @rlsr{Pitches}.
2315
2316 Notation Reference:
2317 @ref{Note head styles},
2318 @ref{Chorded notes}.
2319
2320 Internals Reference:
2321 @rinternals{note-event},
2322 @rinternals{Note_heads_engraver},
2323 @rinternals{Ledger_line_engraver},
2324 @rinternals{NoteHead},
2325 @rinternals{LedgerLineSpanner},
2326 @rinternals{note-head-interface},
2327 @rinternals{ledger-line-spanner-interface}.
2328
2329
2330 @node Easy notation note heads
2331 @unnumberedsubsubsec Easy notation note heads
2332
2333 @cindex note heads, practice
2334 @cindex practice note heads
2335 @cindex note heads, easy notation
2336 @cindex easy notation
2337 @cindex Hal Leonard
2338 @cindex beginners' music
2339 @cindex music, beginners'
2340 @cindex easy play note heads
2341 @cindex note heads, easy play
2342
2343 @funindex \easyHeadsOn
2344 @funindex easyHeadsOn
2345 @funindex \easyHeadsOff
2346 @funindex easyHeadsOff
2347
2348 The @q{easy play} note head includes a note name inside the head.
2349 It is used in music for beginners.  To make the letters readable,
2350 it should be printed in a large font size.  To print with a larger
2351 font, see @ref{Setting the staff size}.
2352
2353 @lilypond[verbatim,quote]
2354 #(set-global-staff-size 26)
2355 \relative c' {
2356   \easyHeadsOn
2357   c2 e4 f
2358   g1
2359   \easyHeadsOff
2360   c,1
2361 }
2362 @end lilypond
2363
2364
2365 @predefined
2366 @code{\easyHeadsOn},
2367 @code{\easyHeadsOff}.
2368 @endpredefined
2369
2370
2371 @seealso
2372 Notation Reference:
2373 @ref{Setting the staff size}.
2374
2375 Snippets:
2376 @rlsr{Pitches}.
2377
2378 Internals Reference:
2379 @rinternals{note-event},
2380 @rinternals{Note_heads_engraver},
2381 @rinternals{NoteHead},
2382 @rinternals{note-head-interface}.
2383
2384
2385 @node Shape note heads
2386 @unnumberedsubsubsec Shape note heads
2387
2388 @cindex note heads, shape
2389 @cindex note heads, Aiken
2390 @cindex note heads, sacred harp
2391 @cindex shape notes
2392 @cindex Aiken shape note heads
2393 @cindex sacred harp note heads
2394
2395 @funindex \key
2396 @funindex key
2397 @funindex \aikenHeads
2398 @funindex aikenHeads
2399 @funindex \sacredHarpHeads
2400 @funindex sacredHarpHeads
2401
2402 In shape note head notation, the shape of the note head
2403 corresponds to the harmonic function of a note in the scale.  This
2404 notation was popular in nineteenth-century American song books.
2405 Shape note heads can be produced:
2406
2407 @lilypond[verbatim,quote,relative=2]
2408 \aikenHeads
2409 c, d e f g a b c
2410 \sacredHarpHeads
2411 c, d e f g a b c
2412 @end lilypond
2413
2414 Shapes are typeset according to the step in the scale, where the
2415 base of the scale is determined by the @code{\key} command.
2416
2417
2418 @predefined
2419 @code{\aikenHeads},
2420 @code{\sacredHarpHeads}.
2421 @endpredefined
2422
2423
2424 @snippets
2425
2426 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
2427 {applying-note-head-styles-depending-on-the-step-of-the-scale.ly}
2428
2429 @noindent
2430 To see all note head styles, see @ref{Note head styles}.
2431
2432
2433 @seealso
2434 Snippets:
2435 @rlsr{Pitches}.
2436
2437 Notation Reference:
2438 @ref{Note head styles}.
2439
2440 Internals Reference:
2441 @rinternals{note-event},
2442 @rinternals{Note_heads_engraver},
2443 @rinternals{NoteHead},
2444 @rinternals{note-head-interface}.
2445
2446
2447 @node Improvisation
2448 @unnumberedsubsubsec Improvisation
2449
2450 @cindex improvisation
2451 @cindex slashed note heads
2452 @cindex note heads, improvisation
2453 @cindex note heads, slashed
2454
2455 @funindex \improvisationOn
2456 @funindex improvisationOn
2457 @funindex \improvisationOff
2458 @funindex improvisationOff
2459
2460 Improvisation is sometimes denoted with slashed note heads, where
2461 the performer may choose any pitch but should play the specified
2462 rhythm.  Such note heads can be created:
2463
2464 @lilypond[verbatim,quote,relative=2]
2465 \new Voice \with {
2466   \consists "Pitch_squash_engraver"
2467 } {
2468   e8 e g a a16( bes) a8 g
2469   \improvisationOn
2470   e8 ~
2471   e2 ~ e8 f4 f8 ~
2472   f2
2473   \improvisationOff
2474   a16( bes) a8 g e
2475 }
2476 @end lilypond
2477
2478
2479 @predefined
2480 @code{\improvisationOn},
2481 @code{\improvisationOff}.
2482 @endpredefined
2483
2484
2485 @seealso
2486 Snippets:
2487 @rlsr{Pitches}.
2488
2489 Internals Reference:
2490 @rinternals{Pitch_squash_engraver},
2491 @rinternals{Voice},
2492 @rinternals{RhythmicStaff}.
2493
2494