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