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},
 934 @ref{Gregorian clefs}.
 935
 936 Snippets:
 937 @rlsr{Pitches}.
 938
 939 Internals Reference:
 940 @rinternals{Clef_engraver},
 941 @rinternals{Clef},
 942 @rinternals{OctavateEight},
 943 @rinternals{clef-interface}.
 944
 945
 946 @node Key signature
 947 @unnumberedsubsubsec Key signature
 948
 949 @cindex key signature
 950
 951 @funindex \key
 952 @funindex key
 953
 954 @c duplicated in Key signature and Accidentals
 955 @warning{New users are sometimes confused about accidentals and
 956 key signatures.  In LilyPond, note names are the raw input; key
 957 signatures and clefs determine how this raw input is displayed.
 958 An unaltered note like@tie{}@code{c} means @q{C natural},
 959 regardless of the key signature or clef.  For more information,
 960 see @rlearning{Accidentals and key signatures}.}
 961
 962 The key signature indicates the tonality in which a piece is
 963 played.  It is denoted by a set of alterations (flats or sharps)
 964 at the start of the staff.  The key signature may be altered:
 965
 966 @example
 967 \key @var{pitch} @var{mode}
 968 @end example
 969
 970 @funindex \major
 971 @funindex major
 972 @funindex \minor
 973 @funindex minor
 974 @funindex \ionian
 975 @funindex ionian
 976 @funindex \locrian
 977 @funindex locrian
 978 @funindex \aeolian
 979 @funindex aeolian
 980 @funindex \mixolydian
 981 @funindex mixolydian
 982 @funindex \lydian
 983 @funindex lydian
 984 @funindex \phrygian
 985 @funindex phrygian
 986 @funindex \dorian
 987 @funindex dorian
 988
 989 @cindex church modes
 990 @cindex modes
 991 @cindex major
 992 @cindex minor
 993 @cindex ionian
 994 @cindex locrian
 995 @cindex aeolian
 996 @cindex mixolydian
 997 @cindex lydian
 998 @cindex phrygian
 999 @cindex dorian
1000
1001 @noindent
1002 Here, @var{mode} should be @code{\major} or @code{\minor} to get a
1003 key signature of @var{pitch}-major or @var{pitch}-minor,
1004 respectively.  You may also use the standard mode names, also
1005 called @notation{church modes}: @code{\ionian}, @code{\dorian},
1006 @code{\phrygian}, @code{\lydian}, @code{\mixolydian},
1007 @code{\aeolian}, and @code{\locrian}.
1008
1009 @lilypond[verbatim,quote,relative=2]
1010 \key g \major
1011 fis1
1012 f
1013 fis
1014 @end lilypond
1015
1016
1017 @snippets
1018
1019 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
1020 {preventing-natural-signs-from-being-printed-when-the-key-signature-changes.ly}
1021
1022 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
1023 {non-traditional-key-signatures.ly}
1024
1025
1026 @seealso
1027 Music Glossary:
1028 @rglos{church mode},
1029 @rglos{scordatura}.
1030
1031 Learning Manual:
1032 @rlearning{Accidentals and key signatures}.
1033
1034 Snippets:
1035 @rlsr{Pitches}.
1036
1037 Internals Reference:
1038 @rinternals{KeyChangeEvent},
1039 @rinternals{Key_engraver},
1040 @rinternals{Key_performer},
1041 @rinternals{KeyCancellation},
1042 @rinternals{KeySignature},
1043 @rinternals{key-cancellation-interface},
1044 @rinternals{key-signature-interface}.
1045
1046
1047 @node Ottava brackets
1048 @unnumberedsubsubsec Ottava brackets
1049
1050 @cindex ottava
1051 @cindex 15ma
1052 @cindex 8va
1053 @cindex 8ve
1054 @cindex octavation
1055
1056 @funindex set-octavation
1057 @funindex \ottava
1058 @funindex ottava
1059
1060 @notation{Ottava brackets} introduce an extra transposition of an
1061 octave for the staff:
1062
1063 @lilypond[verbatim,quote,relative=2]
1064 a'2 b
1065 \ottava #1
1066 a b
1067 \ottava #0
1068 a b
1069 @end lilypond
1070
1071 The @code{ottava} function also takes -1 (for 8va bassa),
1072 2@tie{}(for 15ma), and -2 (for 15ma bassa) as arguments.
1073
1074
1075 @snippets
1076
1077 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
1078 {ottava-text.ly}
1079
1080
1081 @seealso
1082 Music Glossary:
1083 @rglos{octavation}.
1084
1085 Snippets:
1086 @rlsr{Pitches}.
1087
1088 Internals Reference:
1089 @rinternals{Ottava_spanner_engraver},
1090 @rinternals{OttavaBracket},
1091 @rinternals{ottava-bracket-interface}.
1092
1093
1094 @node Instrument transpositions
1095 @unnumberedsubsubsec Instrument transpositions
1096
1097 @cindex transposition, MIDI
1098 @cindex transposition, instrument
1099 @cindex transposing instrument
1100 @cindex MIDI
1101 @cindex MIDI transposition
1102
1103 @funindex \transposition
1104 @funindex transposition
1105
1106 When typesetting scores that involve transposing instruments, some
1107 parts can be typeset in a different pitch than the
1108 @notation{concert pitch}.  In these cases, the key of the
1109 @notation{transposing instrument} should be specified; otherwise
1110 the MIDI output and cues in other parts will produce incorrect
1111 pitches.  For more information about quotations, see
1112 @ref{Quoting other voices}.
1113
1114 @example
1115 \transposition @var{pitch}
1116 @end example
1117
1118 The pitch to use for @code{\transposition} should correspond to
1119 the real sound heard when a@tie{}@code{c'} written on the staff is
1120 played by the transposing instrument.  This pitch is entered in
1121 absolute mode, so an instrument that produces a real sound which
1122 is one tone higher than the printed music should use
1123 @w{@code{\transposition d'}}.  @code{\transposition} should
1124 @emph{only} be used if the pitches are @emph{not} being entered in
1125 concert pitch.
1126
1127 Here are a few notes for violin and B-flat clarinet where the
1128 parts have been entered using the notes and key as they appear in
1129 each part of the conductor's score.  The two instruments are
1130 playing in unison.
1131
1132 @lilypond[verbatim,quote]
1133 \new GrandStaff <<
1134   \new Staff = "violin" {
1135     \relative c'' {
1136       \set Staff.instrumentName = #"Vln"
1137       \set Staff.midiInstrument = #"violin"
1138       % not strictly necessary, but a good reminder
1139       \transposition c'
1140
1141       \key c \major
1142       g4( c8) r c r c4
1143     }
1144   }
1145   \new Staff = "clarinet" {
1146     \relative c'' {
1147       \set Staff.instrumentName = \markup { Cl (B\flat) }
1148       \set Staff.midiInstrument = #"clarinet"
1149       \transposition bes
1150
1151       \key d \major
1152       a4( d8) r d r d4
1153     }
1154   }
1155 >>
1156 @end lilypond
1157
1158 The @code{\transposition} may be changed during a piece.  For
1159 example, a clarinetist may switch from an A clarinet to a B-flat
1160 clarinet.
1161
1162 @lilypond[verbatim,quote,relative=2]
1163 \set Staff.instrumentName = #"Cl (A)"
1164 \key a \major
1165 \transposition a
1166 c d e f
1167 \textLengthOn
1168 s1*0^\markup { Switch to B\flat clarinet }
1169 R1
1170
1171 \key bes \major
1172 \transposition bes
1173 c2 g
1174 @end lilypond
1175
1176
1177 @seealso
1178 Music Glossary:
1179 @rglos{concert pitch},
1180 @rglos{transposing instrument}.
1181
1182 Notation Reference:
1183 @ref{Quoting other voices},
1184 @ref{Transpose}.
1185
1186 Snippets:
1187 @rlsr{Pitches}.
1188
1189
1190 @node Automatic accidentals
1191 @unnumberedsubsubsec Automatic accidentals
1192
1193 @cindex accidental style
1194 @cindex accidental style, default
1195 @cindex accidentals
1196 @cindex accidentals, automatic
1197 @cindex automatic accidentals
1198 @cindex default accidental style
1199
1200 @funindex set-accidental-style
1201 @funindex voice
1202 @funindex default
1203
1204 There are many different conventions on how to typeset
1205 accidentals.  LilyPond provides a function to specify which
1206 accidental style to use.  This function is called as follows:
1207
1208 @example
1209 \new Staff <<
1210   #(set-accidental-style 'voice)
1211   @{ @dots{} @}
1212 >>
1213 @end example
1214
1215 The accidental style applies to the current @code{Staff} by
1216 default (with the exception of the styles @code{piano} and
1217 @code{piano-cautionary}, which are explained below).  Optionally,
1218 the function can take a second argument that determines in which
1219 scope the style should be changed.  For example, to use the same
1220 style in all staves of the current @code{StaffGroup}, use:
1221
1222 @example
1223 #(set-accidental-style 'voice 'StaffGroup)
1224 @end example
1225
1226 The following accidental styles are supported.  To demonstrate
1227 each style, we use the following example:
1228
1229
1230 @lilypond[verbatim,quote]
1231 musicA = {
1232   <<
1233     \relative c' {
1234       cis'8 fis, d'4 <a cis>8 f bis4 |
1235       cis2. <c, g'>4 |
1236     }
1237     \\
1238     \relative c' {
1239       ais'2 cis, |
1240       fis8 b a4 cis2 |
1241     }
1242   >>
1243 }
1244
1245 musicB = {
1246   \clef bass
1247   \new Voice {
1248     \voiceTwo \relative c' {
1249       <fis, a cis>4
1250       \change Staff = up
1251       cis'
1252       \change Staff = down
1253       <fis, a>
1254       \change Staff = up
1255       dis' |
1256       \change Staff = down
1257       <fis, a cis>4 gis <f a d>2 |
1258     }
1259   }
1260 }
1261
1262 \new PianoStaff {
1263   <<
1264     \context Staff = "up" {
1265       #(set-accidental-style 'default)
1266       \musicA
1267     }
1268     \context Staff = "down" {
1269       #(set-accidental-style 'default)
1270       \musicB
1271     }
1272   >>
1273 }
1274 @end lilypond
1275
1276 Note that the last lines of this example can be replaced by the
1277 following, as long as the same accidental style should be used in
1278 both staves.
1279
1280 @example
1281 \new PianoStaff @{
1282   <<
1283     \context Staff = "up" @{
1284       %%% change the next line as desired:
1285       #(set-accidental-style 'default 'Score)
1286       \musicA
1287     @}
1288     \context Staff = "down" @{
1289       \musicB
1290     @}
1291   >>
1292 @}
1293 @end example
1294
1295
1296 @c don't use verbatim in this table.
1297 @table @code
1298 @item default
1299
1300 @cindex default accidental style
1301 @cindex accidental style, default
1302
1303 @funindex default
1304
1305 This is the default typesetting behavior.  It corresponds to
1306 eighteenth-century common practice: accidentals are remembered to
1307 the end of the measure in which they occur and only in their own
1308 octave.  Thus, in the example below, no natural signs are printed
1309 before the@tie{}@code{b} in the second measure or the
1310 last@tie{}@code{c}:
1311
1312 @lilypond[quote]
1313 musicA = {
1314   <<
1315     \relative c' {
1316       cis'8 fis, d'4 <a cis>8 f bis4 |
1317       cis2. <c, g'>4 |
1318     }
1319     \\
1320     \relative c' {
1321       ais'2 cis, |
1322       fis8 b a4 cis2 |
1323     }
1324   >>
1325 }
1326
1327 musicB = {
1328   \clef bass
1329   \new Voice {
1330     \voiceTwo \relative c' {
1331       <fis, a cis>4
1332       \change Staff = up
1333       cis'
1334       \change Staff = down
1335       <fis, a>
1336       \change Staff = up
1337       dis' |
1338       \change Staff = down
1339       <fis, a cis>4 gis <f a d>2 |
1340     }
1341   }
1342 }
1343
1344 \new PianoStaff {
1345   <<
1346     \context Staff = "up" {
1347       #(set-accidental-style 'default)
1348       \musicA
1349     }
1350     \context Staff = "down" {
1351       #(set-accidental-style 'default)
1352       \musicB
1353     }
1354   >>
1355 }
1356 @end lilypond
1357
1358 @item voice
1359
1360 @cindex accidental style, voice
1361 @cindex voice accidental style
1362 @cindex accidental style, modern
1363 @cindex modern accidental style
1364 @cindex accidental style, modern-cautionary
1365 @cindex modern-cautionary accidental style
1366
1367 @funindex voice
1368
1369 The normal behavior is to remember the accidentals at
1370 @code{Staff}-level.  In this style, however, accidentals are
1371 typeset individually for each voice.  Apart from that, the rule is
1372 similar to @code{default}.
1373
1374 As a result, accidentals from one voice do not get canceled in
1375 other voices, which is often an unwanted result: in the following
1376 example, it is hard to determine whether the second@tie{}@code{a}
1377 should be played natural or sharp.  The @code{voice} option should
1378 therefore be used only if the voices are to be read solely by
1379 individual musicians.  If the staff is to be used by one musician
1380 (e.g., a conductor or in a piano score) then @code{modern} or
1381 @code{modern-cautionary} should be used instead.
1382
1383
1384 @lilypond[quote]
1385 musicA = {
1386   <<
1387     \relative c' {
1388       cis'8 fis, d'4 <a cis>8 f bis4 |
1389       cis2. <c, g'>4 |
1390     }
1391     \\
1392     \relative c' {
1393       ais'2 cis, |
1394       fis8 b a4 cis2 |
1395     }
1396   >>
1397 }
1398
1399 musicB = {
1400   \clef bass
1401   \new Voice {
1402     \voiceTwo \relative c' {
1403       <fis, a cis>4
1404       \change Staff = up
1405       cis'
1406       \change Staff = down
1407       <fis, a>
1408       \change Staff = up
1409       dis' |
1410       \change Staff = down
1411       <fis, a cis>4 gis <f a d>2 |
1412     }
1413   }
1414 }
1415
1416 \new PianoStaff {
1417   <<
1418     \context Staff = "up" {
1419       #(set-accidental-style 'voice)
1420       \musicA
1421     }
1422     \context Staff = "down" {
1423       #(set-accidental-style 'voice)
1424       \musicB
1425     }
1426   >>
1427 }
1428 @end lilypond
1429
1430 @item modern
1431
1432 @cindex accidentals, modern style
1433 @cindex modern style accidentals
1434
1435 @funindex modern
1436
1437 This rule corresponds to the common practice in the twentieth
1438 century.  It prints the same accidentals as @code{default}, with
1439 two exceptions that serve to avoid ambiguity: after temporary
1440 accidentals, cancellation marks are printed also in the following
1441 measure (for notes in the same octave) and, in the same measure,
1442 for notes in other octaves.  Hence the naturals before
1443 the@tie{}@code{b} and the@tie{}@code{c} in the second measure of
1444 the upper staff:
1445
1446 @lilypond[quote]
1447 musicA = {
1448   <<
1449     \relative c' {
1450       cis'8 fis, d'4 <a cis>8 f bis4 |
1451       cis2. <c, g'>4 |
1452     }
1453     \\
1454     \relative c' {
1455       ais'2 cis, |
1456       fis8 b a4 cis2 |
1457     }
1458   >>
1459 }
1460
1461 musicB = {
1462   \clef bass
1463   \new Voice {
1464     \voiceTwo \relative c' {
1465       <fis, a cis>4
1466       \change Staff = up
1467       cis'
1468       \change Staff = down
1469       <fis, a>
1470       \change Staff = up
1471       dis' |
1472       \change Staff = down
1473       <fis, a cis>4 gis <f a d>2 |
1474     }
1475   }
1476 }
1477
1478 \new PianoStaff {
1479   <<
1480     \context Staff = "up" {
1481       #(set-accidental-style 'modern)
1482       \musicA
1483     }
1484     \context Staff = "down" {
1485       #(set-accidental-style 'modern)
1486       \musicB
1487     }
1488   >>
1489 }
1490 @end lilypond
1491
1492 @item modern-cautionary
1493
1494 @cindex accidentals, modern cautionary style
1495 @cindex modern accidental style
1496 @cindex modern cautionary accidental style
1497 @cindex modern style accidentals
1498 @cindex modern style cautionary accidentals
1499
1500 @funindex modern-cautionary
1501
1502 This rule is similar to @code{modern}, but the @q{extra}
1503 accidentals (the ones not typeset by @code{default}) are typeset
1504 as cautionary accidentals.  They are by default printed with
1505 parentheses, but they can also be printed in reduced size by
1506 defining the @code{cautionary-style} property of
1507 @code{AccidentalSuggestion}.
1508
1509 @lilypond[quote]
1510 musicA = {
1511   <<
1512     \relative c' {
1513       cis'8 fis, d'4 <a cis>8 f bis4 |
1514       cis2. <c, g'>4 |
1515     }
1516     \\
1517     \relative c' {
1518       ais'2 cis, |
1519       fis8 b a4 cis2 |
1520     }
1521   >>
1522 }
1523
1524 musicB = {
1525   \clef bass
1526   \new Voice {
1527     \voiceTwo \relative c' {
1528       <fis, a cis>4
1529       \change Staff = up
1530       cis'
1531       \change Staff = down
1532       <fis, a>
1533       \change Staff = up
1534       dis' |
1535       \change Staff = down
1536       <fis, a cis>4 gis <f a d>2 |
1537     }
1538   }
1539 }
1540
1541 \new PianoStaff {
1542   <<
1543     \context Staff = "up" {
1544       #(set-accidental-style 'modern-cautionary)
1545       \musicA
1546     }
1547     \context Staff = "down" {
1548       #(set-accidental-style 'modern-cautionary)
1549       \musicB
1550     }
1551   >>
1552 }
1553 @end lilypond
1554
1555 @item modern-voice
1556
1557 @cindex accidental style, modern
1558 @cindex accidentals, modern
1559 @cindex accidentals, multivoice
1560 @cindex modern accidental style
1561 @cindex modern accidentals
1562 @cindex multivoice accidentals
1563
1564 @funindex modern-voice
1565
1566 This rule is used for multivoice accidentals to be read both by
1567 musicians playing one voice and musicians playing all voices.
1568 Accidentals are typeset for each voice, but they @emph{are}
1569 canceled across voices in the same @code{Staff}.  Hence,
1570 the@tie{}@code{a} in the last measure is canceled because the
1571 previous cancellation was in a different voice, and
1572 the@tie{}@code{d} in the lower staff is canceled because of the
1573 accidental in a different voice in the previous measure:
1574
1575 @lilypond[quote]
1576 musicA = {
1577   <<
1578     \relative c' {
1579       cis'8 fis, d'4 <a cis>8 f bis4 |
1580       cis2. <c, g'>4 |
1581     }
1582     \\
1583     \relative c' {
1584       ais'2 cis, |
1585       fis8 b a4 cis2 |
1586     }
1587   >>
1588 }
1589
1590 musicB = {
1591   \clef bass
1592   \new Voice {
1593     \voiceTwo \relative c' {
1594       <fis, a cis>4
1595       \change Staff = up
1596       cis'
1597       \change Staff = down
1598       <fis, a>
1599       \change Staff = up
1600       dis' |
1601       \change Staff = down
1602       <fis, a cis>4 gis <f a d>2 |
1603     }
1604   }
1605 }
1606
1607 \new PianoStaff {
1608   <<
1609     \context Staff = "up" {
1610       #(set-accidental-style 'modern-voice)
1611       \musicA
1612     }
1613     \context Staff = "down" {
1614       #(set-accidental-style 'modern-voice)
1615       \musicB
1616     }
1617   >>
1618 }
1619 @end lilypond
1620
1621 @cindex accidental style, cautionary, modern voice
1622 @cindex accidental style, modern voice cautionary
1623 @cindex accidental style, voice, modern cautionary
1624
1625 @funindex modern-voice-cautionary
1626
1627 @item modern-voice-cautionary
1628
1629 This rule is the same as @code{modern-voice}, but with the extra
1630 accidentals (the ones not typeset by @code{voice}) typeset as
1631 cautionaries.  Even though all accidentals typeset by
1632 @code{default} @emph{are} typeset with this rule, some of them are
1633 typeset as cautionaries.
1634
1635 @lilypond[quote]
1636 musicA = {
1637   <<
1638     \relative c' {
1639       cis'8 fis, d'4 <a cis>8 f bis4 |
1640       cis2. <c, g'>4 |
1641     }
1642     \\
1643     \relative c' {
1644       ais'2 cis, |
1645       fis8 b a4 cis2 |
1646     }
1647   >>
1648 }
1649
1650 musicB = {
1651   \clef bass
1652   \new Voice {
1653     \voiceTwo \relative c' {
1654       <fis, a cis>4
1655       \change Staff = up
1656       cis'
1657       \change Staff = down
1658       <fis, a>
1659       \change Staff = up
1660       dis' |
1661       \change Staff = down
1662       <fis, a cis>4 gis <f a d>2 |
1663     }
1664   }
1665 }
1666
1667 \new PianoStaff {
1668   <<
1669     \context Staff = "up" {
1670       #(set-accidental-style 'modern-voice-cautionary)
1671       \musicA
1672     }
1673     \context Staff = "down" {
1674       #(set-accidental-style 'modern-voice-cautionary)
1675       \musicB
1676     }
1677   >>
1678 }
1679 @end lilypond
1680
1681 @item piano
1682
1683 @cindex accidental style, piano
1684 @cindex accidentals, piano
1685 @cindex piano accidental style
1686 @cindex piano accidentals
1687
1688 @funindex piano
1689
1690 This rule reflects twentieth-century practice for piano notation.
1691 Its behavior is very similar to @code{modern} style, but here
1692 accidentals also get canceled across the staves in the same
1693 @code{GrandStaff} or @code{PianoStaff}, hence all the
1694 cancellations of the final notes.
1695
1696 This accidental style applies to the current @code{GrandStaff} or
1697 @code{PianoStaff} by default.
1698
1699 @lilypond[quote]
1700 musicA = {
1701   <<
1702     \relative c' {
1703       cis'8 fis, d'4 <a cis>8 f bis4 |
1704       cis2. <c, g'>4 |
1705     }
1706     \\
1707     \relative c' {
1708       ais'2 cis, |
1709       fis8 b a4 cis2 |
1710     }
1711   >>
1712 }
1713
1714 musicB = {
1715   \clef bass
1716   \new Voice {
1717     \voiceTwo \relative c' {
1718       <fis, a cis>4
1719       \change Staff = up
1720       cis'
1721       \change Staff = down
1722       <fis, a>
1723       \change Staff = up
1724       dis' |
1725       \change Staff = down
1726       <fis, a cis>4 gis <f a d>2 |
1727     }
1728   }
1729 }
1730
1731 \new PianoStaff {
1732   <<
1733     \context Staff = "up" {
1734       #(set-accidental-style 'piano)
1735       \musicA
1736     }
1737     \context Staff = "down" {
1738       \musicB
1739     }
1740   >>
1741 }
1742 @end lilypond
1743
1744 @item piano-cautionary
1745
1746 @cindex accidentals, piano cautionary
1747 @cindex cautionary accidentals, piano
1748 @cindex piano cautionary accidentals
1749 @cindex accidental style, piano cautionary
1750 @cindex cautionary accidental style, piano
1751 @cindex piano cautionary accidental style
1752
1753 @funindex piano-cautionary
1754
1755 This is the same as @code{piano} but with the extra accidentals
1756 typeset as cautionaries.
1757
1758 @lilypond[quote]
1759 musicA = {
1760   <<
1761     \relative c' {
1762       cis'8 fis, d'4 <a cis>8 f bis4 |
1763       cis2. <c, g'>4 |
1764     }
1765     \\
1766     \relative c' {
1767       ais'2 cis, |
1768       fis8 b a4 cis2 |
1769     }
1770   >>
1771 }
1772
1773 musicB = {
1774   \clef bass
1775   \new Voice {
1776     \voiceTwo \relative c' {
1777       <fis, a cis>4
1778       \change Staff = up
1779       cis'
1780       \change Staff = down
1781       <fis, a>
1782       \change Staff = up
1783       dis' |
1784       \change Staff = down
1785       <fis, a cis>4 gis <f a d>2 |
1786     }
1787   }
1788 }
1789
1790 \new PianoStaff {
1791   <<
1792     \context Staff = "up" {
1793       #(set-accidental-style 'piano-cautionary)
1794       \musicA
1795     }
1796     \context Staff = "down" {
1797       \musicB
1798     }
1799   >>
1800 }
1801 @end lilypond
1802
1803
1804 @item neo-modern
1805
1806 @cindex neo-modern accidental style
1807 @cindex accidental style, neo-modern
1808
1809 @funindex neo-modern
1810
1811 This rule reproduces a common practice in contemporary music:
1812 accidentals are printed like with @code{modern}, but they are printed
1813 again if the same note appears later in the same measure -- except
1814 if the note is immediately repeated.
1815
1816 @lilypond[quote]
1817 musicA = {
1818   <<
1819     \relative c' {
1820       cis'8 fis, d'4 <a cis>8 f bis4 |
1821       cis2. <c, g'>4 |
1822     }
1823     \\
1824     \relative c' {
1825       ais'2 cis, |
1826       fis8 b a4 cis2 |
1827     }
1828   >>
1829 }
1830
1831 musicB = {
1832   \clef bass
1833   \new Voice {
1834     \voiceTwo \relative c' {
1835       <fis, a cis>4
1836       \change Staff = up
1837       cis'
1838       \change Staff = down
1839       <fis, a>
1840       \change Staff = up
1841       dis' |
1842       \change Staff = down
1843       <fis, a cis>4 gis <f a d>2 |
1844     }
1845   }
1846 }
1847
1848 \new PianoStaff {
1849   <<
1850     \context Staff = "up" {
1851       #(set-accidental-style 'neo-modern)
1852       \musicA
1853     }
1854     \context Staff = "down" {
1855       #(set-accidental-style 'neo-modern)
1856       \musicB
1857     }
1858   >>
1859 }
1860 @end lilypond
1861
1862 @item neo-modern-cautionary
1863
1864 @cindex neo-modern-cautionary accidental style
1865 @cindex accidental style, neo-modern-cautionary
1866
1867 @funindex neo-modern-cautionary
1868
1869 This rule is similar to @code{neo-modern}, but the extra
1870 accidentals are printed as cautionary accidentals.
1871
1872 @lilypond[quote]
1873 musicA = {
1874   <<
1875     \relative c' {
1876       cis'8 fis, d'4 <a cis>8 f bis4 |
1877       cis2. <c, g'>4 |
1878     }
1879     \\
1880     \relative c' {
1881       ais'2 cis, |
1882       fis8 b a4 cis2 |
1883     }
1884   >>
1885 }
1886
1887 musicB = {
1888   \clef bass
1889   \new Voice {
1890     \voiceTwo \relative c' {
1891       <fis, a cis>4
1892       \change Staff = up
1893       cis'
1894       \change Staff = down
1895       <fis, a>
1896       \change Staff = up
1897       dis' |
1898       \change Staff = down
1899       <fis, a cis>4 gis <f a d>2 |
1900     }
1901   }
1902 }
1903
1904 \new PianoStaff {
1905   <<
1906     \context Staff = "up" {
1907       #(set-accidental-style 'neo-modern-cautionary)
1908       \musicA
1909     }
1910     \context Staff = "down" {
1911       #(set-accidental-style 'neo-modern-cautionary)
1912       \musicB
1913     }
1914   >>
1915 }
1916 @end lilypond
1917
1918
1919 @item dodecaphonic
1920
1921 @cindex dodecaphonic accidental style
1922 @cindex dodecaphonic style, neo-modern
1923
1924 @funindex dodecaphonic
1925
1926 This rule reflects a practice introduced by composers at
1927 the beginning of the 20th century, in an attempt to
1928 abolish the hierarchy between natural and non-natural notes.
1929 With this style, @emph{every} note gets an accidental sign,
1930 including natural signs.
1931
1932 @lilypond[quote]
1933 musicA = {
1934   <<
1935     \relative c' {
1936       cis'8 fis, d'4 <a cis>8 f bis4 |
1937       cis2. <c, g'>4 |
1938     }
1939     \\
1940     \relative c' {
1941       ais'2 cis, |
1942       fis8 b a4 cis2 |
1943     }
1944   >>
1945 }
1946
1947 musicB = {
1948   \clef bass
1949   \new Voice {
1950     \voiceTwo \relative c' {
1951       <fis, a cis>4
1952       \change Staff = up
1953       cis'
1954       \change Staff = down
1955       <fis, a>
1956       \change Staff = up
1957       dis' |
1958       \change Staff = down
1959       <fis, a cis>4 gis <f a d>2 |
1960     }
1961   }
1962 }
1963
1964 \new PianoStaff {
1965   <<
1966     \context Staff = "up" {
1967       #(set-accidental-style 'dodecaphonic)
1968       \musicA
1969     }
1970     \context Staff = "down" {
1971       #(set-accidental-style 'dodecaphonic)
1972       \musicB
1973     }
1974   >>
1975 }
1976 @end lilypond
1977
1978
1979 @item teaching
1980
1981 @cindex teaching accidental style
1982 @cindex accidental style, teaching
1983
1984 @funindex teaching
1985
1986 This rule is intended for students, and makes it easy to create
1987 scale sheets with automagically created cautionary accidentals.
1988 Accidentals are printed like with @code{modern}, but cautionary
1989 accidentals are added for all sharp or flat tones specified by the
1990 key signature, except if the note is immediately repeated.
1991
1992 @lilypond[quote]
1993 musicA = {
1994   <<
1995     \relative c' {
1996       cis'8 fis, d'4 <a cis>8 f bis4 |
1997       cis2. <c, g'>4 |
1998     }
1999     \\
2000     \relative c' {
2001       ais'2 cis, |
2002       fis8 b a4 cis2 |
2003     }
2004   >>
2005 }
2006
2007 musicB = {
2008   \clef bass
2009   \new Voice {
2010     \voiceTwo \relative c' {
2011       <fis, a cis>4
2012       \change Staff = up
2013       cis'
2014       \change Staff = down
2015       <fis, a>
2016       \change Staff = up
2017       dis' |
2018       \change Staff = down
2019       <fis, a cis>4 gis <f a d>2 |
2020     }
2021   }
2022 }
2023
2024 \new PianoStaff {
2025   <<
2026     \context Staff = "up" {
2027       \key fis \minor
2028       #(set-accidental-style 'teaching)
2029       \musicA
2030     }
2031     \context Staff = "down" {
2032       \key fis \minor
2033       #(set-accidental-style 'teaching)
2034       \musicB
2035     }
2036   >>
2037 }
2038 @end lilypond
2039
2040
2041
2042 @item no-reset
2043
2044 @cindex accidental style, no reset
2045 @cindex no reset accidental style
2046
2047 @funindex no-reset
2048
2049 This is the same as @code{default} but with accidentals lasting
2050 @q{forever} and not only within the same measure:
2051
2052 @lilypond[quote]
2053 musicA = {
2054   <<
2055     \relative c' {
2056       cis'8 fis, d'4 <a cis>8 f bis4 |
2057       cis2. <c, g'>4 |
2058     }
2059     \\
2060     \relative c' {
2061       ais'2 cis, |
2062       fis8 b a4 cis2 |
2063     }
2064   >>
2065 }
2066
2067 musicB = {
2068   \clef bass
2069   \new Voice {
2070     \voiceTwo \relative c' {
2071       <fis, a cis>4
2072       \change Staff = up
2073       cis'
2074       \change Staff = down
2075       <fis, a>
2076       \change Staff = up
2077       dis' |
2078       \change Staff = down
2079       <fis, a cis>4 gis <f a d>2 |
2080     }
2081   }
2082 }
2083
2084 \new PianoStaff {
2085   <<
2086     \context Staff = "up" {
2087       #(set-accidental-style 'no-reset)
2088       \musicA
2089     }
2090     \context Staff = "down" {
2091       #(set-accidental-style 'no-reset)
2092       \musicB
2093     }
2094   >>
2095 }
2096 @end lilypond
2097
2098 @item forget
2099
2100 @cindex forget accidental style
2101 @cindex accidental style, forget
2102
2103 @funindex forget
2104
2105 This is the opposite of @code{no-reset}: Accidentals are not
2106 remembered at all -- and hence all accidentals are typeset
2107 relative to the key signature, regardless of what came before in
2108 the music.  Unlike @code{dodecaphonic}, this rule never prints
2109 any naturals.
2110
2111 @lilypond[quote]
2112 musicA = {
2113   <<
2114     \relative c' {
2115       cis'8 fis, d'4 <a cis>8 f bis4 |
2116       cis2. <c, g'>4 |
2117     }
2118     \\
2119     \relative c' {
2120       ais'2 cis, |
2121       fis8 b a4 cis2 |
2122     }
2123   >>
2124 }
2125
2126 musicB = {
2127   \clef bass
2128   \new Voice {
2129     \voiceTwo \relative c' {
2130       <fis, a cis>4
2131       \change Staff = up
2132       cis'
2133       \change Staff = down
2134       <fis, a>
2135       \change Staff = up
2136       dis' |
2137       \change Staff = down
2138       <fis, a cis>4 gis <f a d>2 |
2139     }
2140   }
2141 }
2142
2143 \new PianoStaff {
2144   <<
2145     \context Staff = "up" {
2146       #(set-accidental-style 'forget)
2147       \musicA
2148     }
2149     \context Staff = "down" {
2150       #(set-accidental-style 'forget)
2151       \musicB
2152     }
2153   >>
2154 }
2155 @end lilypond
2156 @end table
2157
2158 @snippets
2159
2160 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
2161 {dodecaphonic-style-accidentals-for-each-note-including-naturals.ly}
2162
2163
2164 @seealso
2165 Snippets:
2166 @rlsr{Pitches}.
2167
2168 Internals Reference:
2169 @rinternals{Accidental},
2170 @rinternals{Accidental_engraver},
2171 @rinternals{GrandStaff},
2172 @rinternals{PianoStaff},
2173 @rinternals{Staff},
2174 @rinternals{AccidentalSuggestion},
2175 @rinternals{AccidentalPlacement},
2176 @rinternals{accidental-suggestion-interface}.
2177
2178
2179 @cindex accidentals and simultaneous notes
2180 @cindex simultaneous notes and accidentals
2181 @cindex accidentals in chords
2182 @cindex chords, accidentals in
2183
2184 @knownissues
2185
2186 Simultaneous notes are considered to be entered in sequential
2187 mode.  This means that in a chord the accidentals are typeset as
2188 if the notes in the chord happen one at a time, in the order in
2189 which they appear in the input file.  This is a problem when
2190 accidentals in a chord depend on each other, which does not happen
2191 for the default accidental style.  The problem can be solved by
2192 manually inserting@tie{}@code{!} and@tie{}@code{?} for the
2193 problematic notes.
2194
2195
2196 @node Ambitus
2197 @unnumberedsubsubsec Ambitus
2198
2199 @cindex ambitus
2200 @cindex range of pitches
2201 @cindex pitch range
2202
2203 The term @notation{ambitus} (pl. ambitus) denotes a range of
2204 pitches for a given voice in a part of music.  It may also denote
2205 the pitch range that a musical instrument is capable of playing.
2206 Ambitus are printed on vocal parts so that performers can easily
2207 determine if it matches their capabilities.
2208
2209 Ambitus are denoted at the beginning of a piece near the initial
2210 clef.  The range is graphically specified by two note heads that
2211 represent the lowest and highest pitches.  Accidentals are only
2212 printed if they are not part of the key signature.
2213
2214 @lilypond[verbatim,quote]
2215 \layout {
2216   \context {
2217     \Voice
2218     \consists "Ambitus_engraver"
2219   }
2220 }
2221
2222 \relative c'' {
2223   aes c e2
2224   cis,1
2225 }
2226 @end lilypond
2227
2228
2229 @snippets
2230
2231 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
2232 {adding-ambitus-per-voice.ly}
2233
2234 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
2235 {ambitus-with-multiple-voices.ly}
2236
2237
2238 @seealso
2239 Music Glossary:
2240 @rglos{ambitus}.
2241
2242 Snippets:
2243 @rlsr{Pitches}.
2244
2245 Internals Reference:
2246 @rinternals{Ambitus_engraver},
2247 @rinternals{Voice},
2248 @rinternals{Staff},
2249 @rinternals{Ambitus},
2250 @rinternals{AmbitusAccidental},
2251 @rinternals{AmbitusLine},
2252 @rinternals{AmbitusNoteHead},
2253 @rinternals{ambitus-interface}.
2254
2255
2256 @knownissues
2257
2258 There is no collision handling in the case of multiple per-voice
2259 ambitus.
2260
2261
2262 @node Note heads
2263 @subsection Note heads
2264
2265 This section suggests ways of altering note heads.
2266
2267 @menu
2268 * Special note heads::
2269 * Easy notation note heads::
2270 * Shape note heads::
2271 * Improvisation::
2272 @end menu
2273
2274 @node Special note heads
2275 @unnumberedsubsubsec Special note heads
2276
2277 @cindex note heads, special
2278 @cindex note heads, cross
2279 @cindex note heads, diamond
2280 @cindex note heads, parlato
2281 @cindex note heads, harmonic
2282 @cindex note heads, guitar
2283 @cindex special note heads
2284 @cindex cross note heads
2285 @cindex diamond note heads
2286 @cindex parlato note heads
2287 @cindex harmonic note heads
2288 @cindex guitar note heads
2289 @cindex note head styles
2290 @cindex styles, note heads
2291
2292 @funindex cross
2293
2294 The appearance of note heads may be altered:
2295
2296 @lilypond[verbatim,quote,relative=2]
2297 c4 b
2298 \override NoteHead #'style = #'cross
2299 c4 b
2300 \revert NoteHead #'style
2301 a b
2302 \override NoteHead #'style = #'harmonic
2303 a b
2304 \revert NoteHead #'style
2305 c4 d e f
2306 @end lilypond
2307
2308 To see all note head styles, see @ref{Note head styles}.
2309
2310 The @code{cross} style is used to represent a variety of musical
2311 intentions.  The following generic predefined commands modify the
2312 note head in both staff and tablature contexts and can be used to
2313 represent any musical meaning:
2314
2315 @lilypond[verbatim,quote,relative=2]
2316 c4 b
2317 \xNotesOn
2318  a b c4 b
2319 \xNotesOff
2320 c4 d
2321 @end lilypond
2322
2323 The music function form of this predefined command may be used
2324 inside and outside chords to generate crossed note heads in both
2325 staff and tablature contexts:
2326
2327 @lilypond[verbatim,quote,relative=2]
2328 c4 b
2329 \xNote { e f }
2330 c b < g \xNote c f > b
2331 @end lilypond
2332
2333 There is also a shorthand for diamond shapes which can be used
2334 only inside chords:
2335
2336 @lilypond[verbatim,quote,relative=2]
2337 <c f\harmonic>2 <d a'\harmonic>4 <c g'\harmonic>
2338 @end lilypond
2339
2340 @predefined
2341 @code{\harmonic},
2342 @code{\xNotesOn},
2343 @code{\xNotesOff},
2344 @code{\xNote}.
2345 @endpredefined
2346
2347 @seealso
2348 Snippets:
2349 @rlsr{Pitches}.
2350
2351 Notation Reference:
2352 @ref{Note head styles},
2353 @ref{Chorded notes}.
2354
2355 Internals Reference:
2356 @rinternals{note-event},
2357 @rinternals{Note_heads_engraver},
2358 @rinternals{Ledger_line_engraver},
2359 @rinternals{NoteHead},
2360 @rinternals{LedgerLineSpanner},
2361 @rinternals{note-head-interface},
2362 @rinternals{ledger-line-spanner-interface}.
2363
2364
2365 @node Easy notation note heads
2366 @unnumberedsubsubsec Easy notation note heads
2367
2368 @cindex note heads, practice
2369 @cindex practice note heads
2370 @cindex note heads, easy notation
2371 @cindex easy notation
2372 @cindex Hal Leonard
2373 @cindex beginners' music
2374 @cindex music, beginners'
2375 @cindex easy play note heads
2376 @cindex note heads, easy play
2377
2378 @funindex \easyHeadsOn
2379 @funindex easyHeadsOn
2380 @funindex \easyHeadsOff
2381 @funindex easyHeadsOff
2382
2383 The @q{easy play} note head includes a note name inside the head.
2384 It is used in music for beginners.  To make the letters readable,
2385 it should be printed in a large font size.  To print with a larger
2386 font, see @ref{Setting the staff size}.
2387
2388 @lilypond[verbatim,quote]
2389 #(set-global-staff-size 26)
2390 \relative c' {
2391   \easyHeadsOn
2392   c2 e4 f
2393   g1
2394   \easyHeadsOff
2395   c,1
2396 }
2397 @end lilypond
2398
2399
2400 @predefined
2401 @code{\easyHeadsOn},
2402 @code{\easyHeadsOff}.
2403 @endpredefined
2404
2405
2406 @seealso
2407 Notation Reference:
2408 @ref{Setting the staff size}.
2409
2410 Snippets:
2411 @rlsr{Pitches}.
2412
2413 Internals Reference:
2414 @rinternals{note-event},
2415 @rinternals{Note_heads_engraver},
2416 @rinternals{NoteHead},
2417 @rinternals{note-head-interface}.
2418
2419
2420 @node Shape note heads
2421 @unnumberedsubsubsec Shape note heads
2422
2423 @cindex note heads, shape
2424 @cindex note heads, Aiken
2425 @cindex note heads, sacred harp
2426 @cindex shape notes
2427 @cindex Aiken shape note heads
2428 @cindex sacred harp note heads
2429
2430 @funindex \key
2431 @funindex key
2432 @funindex \aikenHeads
2433 @funindex aikenHeads
2434 @funindex \sacredHarpHeads
2435 @funindex sacredHarpHeads
2436
2437 In shape note head notation, the shape of the note head
2438 corresponds to the harmonic function of a note in the scale.  This
2439 notation was popular in nineteenth-century American song books.
2440 Shape note heads can be produced:
2441
2442 @lilypond[verbatim,quote,relative=2]
2443 \aikenHeads
2444 c, d e f g a b c
2445 \sacredHarpHeads
2446 c, d e f g a b c
2447 @end lilypond
2448
2449 Shapes are typeset according to the step in the scale, where the
2450 base of the scale is determined by the @code{\key} command.
2451
2452
2453 @predefined
2454 @code{\aikenHeads},
2455 @code{\sacredHarpHeads}.
2456 @endpredefined
2457
2458
2459 @snippets
2460
2461 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
2462 {applying-note-head-styles-depending-on-the-step-of-the-scale.ly}
2463
2464 To see all note head styles, see @ref{Note head styles}.
2465
2466
2467 @seealso
2468 Snippets:
2469 @rlsr{Pitches}.
2470
2471 Notation Reference:
2472 @ref{Note head styles}.
2473
2474 Internals Reference:
2475 @rinternals{note-event},
2476 @rinternals{Note_heads_engraver},
2477 @rinternals{NoteHead},
2478 @rinternals{note-head-interface}.
2479
2480
2481 @node Improvisation
2482 @unnumberedsubsubsec Improvisation
2483
2484 @cindex improvisation
2485 @cindex slashed note heads
2486 @cindex note heads, improvisation
2487 @cindex note heads, slashed
2488
2489 @funindex \improvisationOn
2490 @funindex improvisationOn
2491 @funindex \improvisationOff
2492 @funindex improvisationOff
2493
2494 Improvisation is sometimes denoted with slashed note heads, where
2495 the performer may choose any pitch but should play the specified
2496 rhythm.  Such note heads can be created:
2497
2498 @lilypond[verbatim,quote,relative=2]
2499 \new Voice \with {
2500   \consists "Pitch_squash_engraver"
2501 } {
2502   e8 e g a a16( bes) a8 g
2503   \improvisationOn
2504   e8 ~
2505   e2 ~ e8 f4 f8 ~
2506   f2
2507   \improvisationOff
2508   a16( bes) a8 g e
2509 }
2510 @end lilypond
2511
2512
2513 @predefined
2514 @code{\improvisationOn},
2515 @code{\improvisationOff}.
2516 @endpredefined
2517
2518
2519 @seealso
2520 Snippets:
2521 @rlsr{Pitches}.
2522
2523 Internals Reference:
2524 @rinternals{Pitch_squash_engraver},
2525 @rinternals{Voice},
2526 @rinternals{RhythmicStaff}.
2527
2528