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