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