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
  83 @seealso
  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 Music Glossary:
 206 @rglos{fifth},
 207 @rglos{interval},
 208 @rglos{Pitch names}.
 209
 210 Notation Reference:
 211 @ref{Octave checks}.
 212
 213 Snippets:
 214 @rlsr{Pitches}.
 215
 216 Internals Reference:
 217 @rinternals{RelativeOctaveMusic}.
 218
 219
 220 @cindex relative octave entry and transposition
 221 @cindex transposition and relative octave entry
 222 @funindex \transpose
 223 @funindex \chordmode
 224 @funindex \relative
 225
 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
 343 @seealso
 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 Music Glossary:
 511 @rglos{Pitch names}.
 512
 513 Snippets:
 514 @rlsr{Pitches}.
 515
 516
 517 @node Changing multiple pitches
 518 @subsection Changing multiple pitches
 519
 520 This section discusses how to modify pitches.
 521
 522 @menu
 523 * Octave checks::
 524 * Transpose::
 525 @end menu
 526
 527 @node Octave checks
 528 @unnumberedsubsubsec Octave checks
 529
 530 @cindex octave correction
 531 @cindex octave check
 532 @cindex control pitch
 533 @funindex =
 534 @funindex \octaveCheck
 535 @funindex controlpitch
 536
 537 In relative mode, it is easy to forget an octave changing mark.
 538 Octave checks make such errors easier to find by displaying a
 539 warning and correcting the octave if a note is found in an
 540 unexpected octave.
 541
 542 To check the octave of a note, specify the absolute octave after
 543 the @code{=}@tie{}symbol.  This example will generate a warning
 544 (and change the pitch) because the second note is the absolute
 545 octave @code{d''} instead of @code{d'} as indicated by the octave
 546 correction.
 547
 548 @lilypond[verbatim,quote]
 549 \relative c'' {
 550   c2 d='4 d
 551   e2 f
 552 }
 553 @end lilypond
 554
 555 The octave of notes may also be checked with the
 556 @code{\octaveCheck}@tie{}@var{controlpitch} command.
 557 @var{controlpitch} is specified in absolute mode.  This checks
 558 that the interval between the previous note and the
 559 @var{controlpitch} is within a fourth (i.e., the normal
 560 calculation of relative mode).  If this check fails, a warning is
 561 printed, but the previous note is not changed.  Future notes are
 562 relative to the @var{controlpitch}.
 563
 564 @lilypond[verbatim,quote]
 565 \relative c'' {
 566   c2 d
 567   \octaveCheck c'
 568   e2 f
 569 }
 570 @end lilypond
 571
 572 Compare the two bars below.  The first and third @code{\octaveCheck}
 573 checks fail, but the second one does not fail.
 574
 575 @lilypond[verbatim,quote]
 576 \relative c'' {
 577   c4 f g f
 578
 579   c4
 580   \octaveCheck c'
 581   f
 582   \octaveCheck c'
 583   g
 584   \octaveCheck c'
 585   f
 586 }
 587 @end lilypond
 588
 589
 590 @seealso
 591 Snippets:
 592 @rlsr{Pitches}.
 593
 594 Internals Reference:
 595 @rinternals{RelativeOctaveCheck}.
 596
 597
 598 @node Transpose
 599 @unnumberedsubsubsec Transpose
 600
 601 @cindex transpose
 602 @cindex transposing
 603 @cindex transposition
 604 @cindex transposition of pitches
 605 @cindex transposition of notes
 606 @cindex pitches, transposition of
 607 @cindex notes, transposition of
 608 @funindex \transpose
 609
 610 A music expression can be transposed with @code{\transpose}.  The
 611 syntax is
 612
 613 @example
 614 \transpose @var{frompitch} @var{topitch} @var{musicexpr}
 615 @end example
 616
 617 @noindent
 618 This means that @var{musicexpr} is transposed by the interval
 619 between the pitches @var{frompitch} and @var{topitch}: any note
 620 with pitch @var{frompitch} is changed to @var{topitch} and any
 621 other note is transposed by the same interval.  Both pitches are
 622 entered in absolute mode.
 623
 624 Consider a piece written in the key of D-major.  It can be
 625 transposed up to E-major; note that the key signature is
 626 automatically transposed as well.
 627
 628 @lilypond[verbatim,quote]
 629 \transpose d e {
 630   \relative c' {
 631     \key d \major
 632     d4 fis a d
 633   }
 634 }
 635 @end lilypond
 636
 637 @cindex transposing instruments
 638 @cindex instruments, transposing
 639
 640 If a part written in C (normal @notation{concert pitch}) is to be
 641 played on the A clarinet (for which an A is notated as a C and
 642 thus sounds a minor third lower than notated), the appropriate
 643 part will be produced with:
 644
 645 @lilypond[verbatim,quote]
 646 \transpose a c' {
 647   \relative c' {
 648     \key c \major
 649     c4 d e g
 650   }
 651 }
 652 @end lilypond
 653
 654 @noindent
 655 Note that we specify @w{@code{\key c \major}} explicitly.  If we
 656 do not specify a key signature, the notes will be transposed but
 657 no key signature will be printed.
 658
 659 @code{\transpose} distinguishes between enharmonic pitches: both
 660 @w{@code{\transpose c cis}} or @w{@code{\transpose c des}} will
 661 transpose up a semitone.  The first version will print sharps and
 662 the notes will remain on the same scale step, the second version
 663 will print flats on the scale step above.
 664
 665 @lilypond[verbatim,quote]
 666 music = \relative c' { c d e f }
 667 \new Staff {
 668   \transpose c cis { \music }
 669   \transpose c des { \music }
 670 }
 671 @end lilypond
 672
 673 @cindex transposing instruments
 674 @cindex instruments, transposing
 675
 676 @code{\transpose} may also be used in a different way, to input
 677 written notes for a transposing instrument.  The previous examples
 678 show how to enter pitches in C (or @notation{concert pitch}) and
 679 typeset them for a transposing instrument, but the opposite is
 680 also possible if you for example have a set of instrumental parts
 681 and want to print a conductor's score.  For example, when entering
 682 music for a B-flat trumpet that begins on a notated E (concert D),
 683 one would write:
 684
 685 @example
 686 musicInBflat = @{ e4 @dots{} @}
 687 \transpose c bes, \musicInBflat
 688 @end example
 689
 690 @noindent
 691 To print this music in F (e.g., rearranging to a French horn) you
 692 could wrap the existing music with another @code{\transpose}:
 693
 694 @example
 695 musicInBflat = @{ e4 @dots{} @}
 696 \transpose f c' @{ \transpose c bes, \musicInBflat @}
 697 @end example
 698
 699 @noindent
 700 For more information about transposing instruments,
 701 see @ref{Instrument transpositions}.
 702
 703
 704 @snippets
 705
 706 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 707 {transposing-pitches-with-minimum-accidentals-smart-transpose.ly}
 708
 709
 710 @seealso
 711 Notation Reference:
 712 @ref{Instrument transpositions}.
 713
 714 Snippets:
 715 @rlsr{Pitches}.
 716
 717 Internals Reference:
 718 @rinternals{TransposedMusic}.
 719
 720
 721 @funindex \transpose
 722 @funindex \chordmode
 723 @funindex \relative
 724
 725 @knownissues
 726
 727 The relative conversion will not affect @code{\transpose},
 728 @code{\chordmode} or @code{\relative} sections in its argument.
 729 To use relative mode within transposed music, an additional
 730 @code{\relative} must be placed inside @code{\transpose}.
 731
 732
 733 @node Displaying pitches
 734 @subsection Displaying pitches
 735
 736 This section discusses how to alter the output of pitches.
 737
 738 @menu
 739 * Clef::
 740 * Key signature::
 741 * Ottava brackets::
 742 * Instrument transpositions::
 743 * Automatic accidentals::
 744 * Ambitus::
 745 @end menu
 746
 747
 748 @node Clef
 749 @unnumberedsubsubsec Clef
 750
 751 @funindex \clef
 752 @cindex G clef
 753 @cindex C clef
 754 @cindex F clef
 755 @cindex treble clef
 756 @cindex violin clef
 757 @cindex alto clef
 758 @cindex tenor clef
 759 @cindex bass clef
 760 @cindex french clef
 761 @cindex soprano clef
 762 @cindex mezzosoprano clef
 763 @cindex baritone clef
 764 @cindex varbaritone clef
 765 @cindex subbass clef
 766 @cindex clef
 767 @cindex ancient clef
 768 @cindex clef, ancient
 769 @cindex clef, G
 770 @cindex clef, C
 771 @cindex clef, F
 772 @cindex clef, treble
 773 @cindex clef, violin
 774 @cindex clef, alto
 775 @cindex clef, tenor
 776 @cindex clef, bass
 777 @cindex clef, french
 778 @cindex clef, soprano
 779 @cindex clef, mezzosoprano
 780 @cindex clef, baritone
 781 @cindex clef, varbaritone
 782 @cindex subbass clef, subbass
 783
 784 The clef may be altered.  Middle C is shown in every example.
 785
 786 @lilypond[verbatim,quote,relative=1]
 787 \clef treble
 788 c2 c
 789 \clef alto
 790 c2 c
 791 \clef tenor
 792 c2 c
 793 \clef bass
 794 c2 c
 795 @end lilypond
 796
 797 Other clefs include:
 798
 799 @lilypond[verbatim,quote,relative=1]
 800 \clef french
 801 c2 c
 802 \clef soprano
 803 c2 c
 804 \clef mezzosoprano
 805 c2 c
 806 \clef baritone
 807 c2 c
 808
 809 \break
 810
 811 \clef varbaritone
 812 c2 c
 813 \clef subbass
 814 c2 c
 815 \clef percussion
 816 c2 c
 817 \clef tab
 818 c2 c
 819 @end lilypond
 820
 821 Further supported clefs are described under @ref{Mensural clefs}
 822 and @ref{Gregorian clefs}.
 823
 824 @cindex transposing clefs
 825 @cindex clef, transposing
 826 @cindex octave transposition
 827 @cindex choral tenor clef
 828
 829 By adding@tie{}@code{_8} or@tie{}@code{^8} to the clef name, the
 830 clef is transposed one octave down or up, respectively,
 831 and@tie{}@code{_15} and@tie{}@code{^15} transpose by two octaves.
 832 The clef name must be enclosed in quotes when it contains
 833 underscores or digits.
 834
 835 @lilypond[verbatim,quote,relative=2]
 836 \clef treble
 837 c2 c
 838 \clef "treble_8"
 839 c2 c
 840 \clef "bass^15"
 841 c2 c
 842 @end lilypond
 843
 844
 845 @snippets
 846
 847 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 848 {tweaking-clef-properties.ly}
 849
 850
 851 @seealso
 852 Notation Reference:
 853 @ref{Mensural clefs}, @ref{Gregorian clefs}.
 854
 855 Snippets:
 856 @rlsr{Pitches}.
 857
 858 Internals Reference:
 859 @rinternals{Clef_engraver},
 860 @rinternals{Clef},
 861 @rinternals{OctavateEight},
 862 @rinternals{clef-interface}.
 863
 864
 865 @node Key signature
 866 @unnumberedsubsubsec Key signature
 867
 868 @cindex key signature
 869 @funindex \key
 870
 871 @c duplicated in Key signature and Accidentals
 872 @warning{New users are sometimes confused about accidentals and
 873 key signatures.  In LilyPond, note names are the raw input; key
 874 signatures and clefs determine how this raw input is displayed.
 875 An unaltered note like@tie{}@code{c} means @q{C natural},
 876 regardless of the key signature or clef.  For more information,
 877 see @rlearning{Accidentals and key signatures}.}
 878
 879 The key signature indicates the tonality in which a piece is
 880 played.  It is denoted by a set of alterations (flats or sharps)
 881 at the start of the staff.  The key signature may be altered:
 882
 883 @example
 884 \key @var{pitch} @var{mode}
 885 @end example
 886
 887 @funindex \major
 888 @funindex \minor
 889 @funindex \ionian
 890 @funindex \locrian
 891 @funindex \aeolian
 892 @funindex \mixolydian
 893 @funindex \lydian
 894 @funindex \phrygian
 895 @funindex \dorian
 896 @cindex church modes
 897 @cindex modes
 898 @cindex major
 899 @cindex minor
 900 @cindex ionian
 901 @cindex locrian
 902 @cindex aeolian
 903 @cindex mixolydian
 904 @cindex lydian
 905 @cindex phrygian
 906 @cindex dorian
 907
 908 Here, @var{mode} should be @code{\major} or @code{\minor} to get a
 909 key signature of @var{pitch}-major or @var{pitch}-minor,
 910 respectively.  You may also use the standard mode names, also
 911 called @notation{church modes}: @code{\ionian}, @code{\dorian},
 912 @code{\phrygian}, @code{\lydian}, @code{\mixolydian},
 913 @code{\aeolian}, and @code{\locrian}.
 914
 915 @lilypond[verbatim,quote,relative=2]
 916 \key g \major
 917 fis1
 918 f
 919 fis
 920 @end lilypond
 921
 922
 923 @snippets
 924
 925 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 926 {preventing-natural-signs-from-being-printed-when-the-key-signature-changes.ly}
 927
 928 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 929 {non-traditional-key-signatures.ly}
 930
 931
 932 @seealso
 933 Music Glossary:
 934 @rglos{church mode},
 935 @rglos{scordatura}.
 936
 937 Learning Manual:
 938 @rlearning{Accidentals and key signatures}.
 939
 940 Snippets:
 941 @rlsr{Pitches}.
 942
 943 Internals Reference:
 944 @rinternals{KeyChangeEvent},
 945 @rinternals{Key_engraver},
 946 @rinternals{Key_performer},
 947 @rinternals{KeyCancellation},
 948 @rinternals{KeySignature},
 949 @rinternals{key-cancellation-interface},
 950 @rinternals{key-signature-interface}.
 951
 952
 953 @node Ottava brackets
 954 @unnumberedsubsubsec Ottava brackets
 955
 956 @cindex ottava
 957 @cindex 15ma
 958 @cindex 8va
 959 @cindex 8ve
 960 @cindex octavation
 961 @funindex set-octavation
 962
 963 @notation{Ottava brackets} introduce an extra transposition of an
 964 octave for the staff:
 965
 966 @lilypond[verbatim,quote,relative=2]
 967 a'2 b
 968 \ottava #1
 969 a b
 970 \ottava #0
 971 a b
 972 @end lilypond
 973
 974 The @code{ottava} function also takes -1 (for 8va bassa),
 975 2@tie{}(for 15ma), and -2 (for 15ma bassa) as arguments.
 976
 977
 978 @snippets
 979
 980 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 981 {ottava-text.ly}
 982
 983
 984 @seealso
 985 Music Glossary:
 986 @rglos{octavation}.
 987
 988 Snippets:
 989 @rlsr{Pitches}.
 990
 991 Internals Reference:
 992 @rinternals{Ottava_spanner_engraver},
 993 @rinternals{OttavaBracket},
 994 @rinternals{ottava-bracket-interface}.
 995
 996
 997 @node Instrument transpositions
 998 @unnumberedsubsubsec Instrument transpositions
 999
1000 @cindex transposition, MIDI
1001 @cindex transposition, instrument
1002 @cindex transposing instrument
1003 @cindex MIDI
1004 @cindex MIDI transposition
1005 @funindex \transposition
1006
1007 When typesetting scores that involve transposing instruments, some
1008 parts can be typeset in a different pitch than the
1009 @notation{concert pitch}.  In these cases, the key of the
1010 @notation{transposing instrument} should be specified; otherwise
1011 the MIDI output and cues in other parts will produce incorrect
1012 pitches.  For more information about quotations, see
1013 @ref{Quoting other voices}.
1014
1015 @example
1016 \transposition @var{pitch}
1017 @end example
1018
1019 The pitch to use for @code{\transposition} should correspond to
1020 the real sound heard when a@tie{}@code{c'} written on the staff is
1021 played by the transposing instrument.  This pitch is entered in
1022 absolute mode, so an instrument that produces a real sound which
1023 is one tone higher than the printed music should use
1024 @w{@code{\transposition d'}}.  @code{\transposition} should
1025 @emph{only} be used if the pitches are @emph{not} being entered in
1026 concert pitch.
1027
1028 Here are a few notes for violin and B-flat clarinet where the
1029 parts have been entered using the notes and key as they appear in
1030 each part of the conductor's score.  The two instruments are
1031 playing in unison.
1032
1033 @lilypond[verbatim,quote]
1034 \new GrandStaff <<
1035   \new Staff = "violin" {
1036     \relative c'' {
1037       \set Staff.instrumentName = "Vln"
1038       \set Staff.midiInstrument = "violin"
1039       % not strictly necessary, but a good reminder
1040       \transposition c'
1041
1042       \key c \major
1043       g4( c8) r c r c4
1044     }
1045   }
1046   \new Staff = "clarinet" {
1047     \relative c'' {
1048       \set Staff.instrumentName = \markup { Cl (B\flat) }
1049       \set Staff.midiInstrument = "clarinet"
1050       \transposition bes
1051
1052       \key d \major
1053       a4( d8) r d r d4
1054     }
1055   }
1056 >>
1057 @end lilypond
1058
1059 The @code{\transposition} may be changed during a piece.  For
1060 example, a clarinetist may switch from an A clarinet to a B-flat
1061 clarinet.
1062
1063 @lilypond[verbatim,quote,relative=2]
1064 \set Staff.instrumentName = "Cl (A)"
1065 \key a \major
1066 \transposition a
1067 c d e f
1068 \textLengthOn
1069 s1*0^\markup { Switch to B\flat clarinet }
1070 R1
1071
1072 \key bes \major
1073 \transposition bes
1074 c2 g
1075 @end lilypond
1076
1077
1078 @seealso
1079 Music Glossary:
1080 @rglos{concert pitch},
1081 @rglos{transposing instrument}.
1082
1083 Notation Reference:
1084 @ref{Quoting other voices}, @ref{Transpose}.
1085
1086 Snippets:
1087 @rlsr{Pitches}.
1088
1089
1090 @node Automatic accidentals
1091 @unnumberedsubsubsec Automatic accidentals
1092
1093 @cindex accidental style
1094 @cindex accidental style, default
1095 @cindex accidentals
1096 @cindex accidentals, automatic
1097 @cindex automatic accidentals
1098 @cindex default accidental style
1099 @funindex set-accidental-style
1100 @funindex voice
1101
1102 There are many different conventions on how to typeset
1103 accidentals.  LilyPond provides a function to specify which
1104 accidental style to use.  This function is called as follows:
1105
1106 @example
1107 \new Staff <<
1108   #(set-accidental-style 'voice)
1109   @{ @dots{} @}
1110 >>
1111 @end example
1112
1113 The accidental style applies to the current @code{Staff} by
1114 default (with the exception of the styles @code{piano} and
1115 @code{piano-cautionary}, which are explained below).  Optionally,
1116 the function can take a second argument that determines in which
1117 scope the style should be changed.  For example, to use the same
1118 style in all staves of the current @code{StaffGroup}, use:
1119
1120 @example
1121 #(set-accidental-style 'voice 'StaffGroup)
1122 @end example
1123
1124 The following accidental styles are supported.  To demonstrate
1125 each style, we use the following example:
1126
1127 @funindex default
1128
1129 @lilypond[verbatim,quote]
1130 musicA = {
1131   <<
1132     \relative c' {
1133       cis'8 fis, d'4 <a cis>8 f bis4 |
1134       cis2. <c, g'>4 |
1135     }
1136     \\
1137     \relative c' {
1138       ais'2 cis, |
1139       fis8 b a4 cis2 |
1140     }
1141   >>
1142 }
1143
1144 musicB = {
1145   \clef bass
1146   \new Voice {
1147     \voiceTwo \relative c' {
1148       <fis, a cis>4
1149       \change Staff = up
1150       cis'
1151       \change Staff = down
1152       <fis, a>
1153       \change Staff = up
1154       dis' |
1155       \change Staff = down
1156       <fis, a cis>4 gis <f a d>2 |
1157     }
1158   }
1159 }
1160
1161 \new PianoStaff {
1162   <<
1163     \context Staff = "up" {
1164       #(set-accidental-style 'default)
1165       \musicA
1166     }
1167     \context Staff = "down" {
1168       #(set-accidental-style 'default)
1169       \musicB
1170     }
1171   >>
1172 }
1173 @end lilypond
1174
1175 Note that the last lines of this example can be replaced by the
1176 following, as long as the same accidental style should be used in
1177 both staves.
1178
1179 @example
1180 \new PianoStaff @{
1181   <<
1182     \context Staff = "up" @{
1183       %%% change the next line as desired:
1184       #(set-accidental-style 'default 'Score)
1185       \musicA
1186     @}
1187     \context Staff = "down" @{
1188       \musicB
1189     @}
1190   >>
1191 @}
1192 @end example
1193
1194
1195 @c don't use verbatim in this table.
1196 @table @code
1197 @item default
1198
1199 @cindex default accidental style
1200 @cindex accidental style, default
1201 @funindex default
1202
1203 This is the default typesetting behavior.  It corresponds to
1204 eighteenth-century common practice: accidentals are remembered to
1205 the end of the measure in which they occur and only in their own
1206 octave.  Thus, in the example below, no natural signs are printed
1207 before the@tie{}@code{b} in the second measure or the
1208 last@tie{}@code{c}:
1209
1210 @lilypond[quote]
1211 musicA = {
1212   <<
1213     \relative c' {
1214       cis'8 fis, d'4 <a cis>8 f bis4 |
1215       cis2. <c, g'>4 |
1216     }
1217     \\
1218     \relative c' {
1219       ais'2 cis, |
1220       fis8 b a4 cis2 |
1221     }
1222   >>
1223 }
1224
1225 musicB = {
1226   \clef bass
1227   \new Voice {
1228     \voiceTwo \relative c' {
1229       <fis, a cis>4
1230       \change Staff = up
1231       cis'
1232       \change Staff = down
1233       <fis, a>
1234       \change Staff = up
1235       dis' |
1236       \change Staff = down
1237       <fis, a cis>4 gis <f a d>2 |
1238     }
1239   }
1240 }
1241
1242 \new PianoStaff {
1243   <<
1244     \context Staff = "up" {
1245       #(set-accidental-style 'default)
1246       \musicA
1247     }
1248     \context Staff = "down" {
1249       #(set-accidental-style 'default)
1250       \musicB
1251     }
1252   >>
1253 }
1254 @end lilypond
1255
1256 @item voice
1257
1258 @cindex accidental style, voice
1259 @cindex voice accidental style
1260 @cindex accidental style, modern
1261 @cindex modern accidental style
1262 @cindex accidental style, modern-cautionary
1263 @cindex modern-cautionary accidental style
1264 @funindex voice
1265
1266 The normal behavior is to remember the accidentals at
1267 @code{Staff}-level.  In this style, however, accidentals are
1268 typeset individually for each voice.  Apart from that, the rule is
1269 similar to @code{default}.
1270
1271 As a result, accidentals from one voice do not get canceled in
1272 other voices, which is often an unwanted result: in the following
1273 example, it is hard to determine whether the second@tie{}@code{a}
1274 should be played natural or sharp.  The @code{voice} option should
1275 therefore be used only if the voices are to be read solely by
1276 individual musicians.  If the staff is to be used by one musician
1277 (e.g., a conductor or in a piano score) then @code{modern} or
1278 @code{modern-cautionary} should be used instead.
1279
1280
1281 @lilypond[quote]
1282 musicA = {
1283   <<
1284     \relative c' {
1285       cis'8 fis, d'4 <a cis>8 f bis4 |
1286       cis2. <c, g'>4 |
1287     }
1288     \\
1289     \relative c' {
1290       ais'2 cis, |
1291       fis8 b a4 cis2 |
1292     }
1293   >>
1294 }
1295
1296 musicB = {
1297   \clef bass
1298   \new Voice {
1299     \voiceTwo \relative c' {
1300       <fis, a cis>4
1301       \change Staff = up
1302       cis'
1303       \change Staff = down
1304       <fis, a>
1305       \change Staff = up
1306       dis' |
1307       \change Staff = down
1308       <fis, a cis>4 gis <f a d>2 |
1309     }
1310   }
1311 }
1312
1313 \new PianoStaff {
1314   <<
1315     \context Staff = "up" {
1316       #(set-accidental-style 'voice)
1317       \musicA
1318     }
1319     \context Staff = "down" {
1320       #(set-accidental-style 'voice)
1321       \musicB
1322     }
1323   >>
1324 }
1325 @end lilypond
1326
1327 @item modern
1328
1329 @cindex accidentals, modern style
1330 @cindex modern style accidentals
1331 @funindex modern
1332
1333 This rule corresponds to the common practice in the twentieth
1334 century.  It prints the same accidentals as @code{default}, with
1335 two exceptions that serve to avoid ambiguity: after temporary
1336 accidentals, cancellation marks are printed also in the following
1337 measure (for notes in the same octave) and, in the same measure,
1338 for notes in other octaves.  Hence the naturals before
1339 the@tie{}@code{b} and the@tie{}@code{c} in the second measure of
1340 the upper staff:
1341
1342 @lilypond[quote]
1343 musicA = {
1344   <<
1345     \relative c' {
1346       cis'8 fis, d'4 <a cis>8 f bis4 |
1347       cis2. <c, g'>4 |
1348     }
1349     \\
1350     \relative c' {
1351       ais'2 cis, |
1352       fis8 b a4 cis2 |
1353     }
1354   >>
1355 }
1356
1357 musicB = {
1358   \clef bass
1359   \new Voice {
1360     \voiceTwo \relative c' {
1361       <fis, a cis>4
1362       \change Staff = up
1363       cis'
1364       \change Staff = down
1365       <fis, a>
1366       \change Staff = up
1367       dis' |
1368       \change Staff = down
1369       <fis, a cis>4 gis <f a d>2 |
1370     }
1371   }
1372 }
1373
1374 \new PianoStaff {
1375   <<
1376     \context Staff = "up" {
1377       #(set-accidental-style 'modern)
1378       \musicA
1379     }
1380     \context Staff = "down" {
1381       #(set-accidental-style 'modern)
1382       \musicB
1383     }
1384   >>
1385 }
1386 @end lilypond
1387
1388 @item modern-cautionary
1389
1390 @cindex accidentals, modern cautionary style
1391 @cindex modern accidental style
1392 @cindex modern cautionary accidental style
1393 @cindex modern style accidentals
1394 @cindex modern style cautionary accidentals
1395 @funindex modern-cautionary
1396
1397 This rule is similar to @code{modern}, but the @q{extra}
1398 accidentals (the ones not typeset by @code{default}) are typeset
1399 as cautionary accidentals.  They are by default printed with
1400 parentheses, but they can also be printed in reduced size by
1401 defining the @code{cautionary-style} property of
1402 @code{AccidentalSuggestion}.
1403
1404 @lilypond[quote]
1405 musicA = {
1406   <<
1407     \relative c' {
1408       cis'8 fis, d'4 <a cis>8 f bis4 |
1409       cis2. <c, g'>4 |
1410     }
1411     \\
1412     \relative c' {
1413       ais'2 cis, |
1414       fis8 b a4 cis2 |
1415     }
1416   >>
1417 }
1418
1419 musicB = {
1420   \clef bass
1421   \new Voice {
1422     \voiceTwo \relative c' {
1423       <fis, a cis>4
1424       \change Staff = up
1425       cis'
1426       \change Staff = down
1427       <fis, a>
1428       \change Staff = up
1429       dis' |
1430       \change Staff = down
1431       <fis, a cis>4 gis <f a d>2 |
1432     }
1433   }
1434 }
1435
1436 \new PianoStaff {
1437   <<
1438     \context Staff = "up" {
1439       #(set-accidental-style 'modern-cautionary)
1440       \musicA
1441     }
1442     \context Staff = "down" {
1443       #(set-accidental-style 'modern-cautionary)
1444       \musicB
1445     }
1446   >>
1447 }
1448 @end lilypond
1449
1450 @item modern-voice
1451
1452 @cindex accidental style, modern
1453 @cindex accidentals, modern
1454 @cindex accidentals, multivoice
1455 @cindex modern accidental style
1456 @cindex modern accidentals
1457 @cindex multivoice accidentals
1458 @funindex modern-voice
1459
1460 This rule is used for multivoice accidentals to be read both by
1461 musicians playing one voice and musicians playing all voices.
1462 Accidentals are typeset for each voice, but they @emph{are}
1463 canceled across voices in the same @code{Staff}.  Hence,
1464 the@tie{}@code{a} in the last measure is canceled because the
1465 previous cancellation was in a different voice, and
1466 the@tie{}@code{d} in the lower staff is canceled because of the
1467 accidental in a different voice in the previous measure:
1468
1469 @lilypond[quote]
1470 musicA = {
1471   <<
1472     \relative c' {
1473       cis'8 fis, d'4 <a cis>8 f bis4 |
1474       cis2. <c, g'>4 |
1475     }
1476     \\
1477     \relative c' {
1478       ais'2 cis, |
1479       fis8 b a4 cis2 |
1480     }
1481   >>
1482 }
1483
1484 musicB = {
1485   \clef bass
1486   \new Voice {
1487     \voiceTwo \relative c' {
1488       <fis, a cis>4
1489       \change Staff = up
1490       cis'
1491       \change Staff = down
1492       <fis, a>
1493       \change Staff = up
1494       dis' |
1495       \change Staff = down
1496       <fis, a cis>4 gis <f a d>2 |
1497     }
1498   }
1499 }
1500
1501 \new PianoStaff {
1502   <<
1503     \context Staff = "up" {
1504       #(set-accidental-style 'modern-voice)
1505       \musicA
1506     }
1507     \context Staff = "down" {
1508       #(set-accidental-style 'modern-voice)
1509       \musicB
1510     }
1511   >>
1512 }
1513 @end lilypond
1514
1515 @cindex accidental style, cautionary, modern voice
1516 @cindex accidental style, modern voice cautionary
1517 @cindex accidental style, voice, modern cautionary
1518 @funindex modern-voice-cautionary
1519
1520 @item modern-voice-cautionary
1521
1522 This rule is the same as @code{modern-voice}, but with the extra
1523 accidentals (the ones not typeset by @code{voice}) typeset as
1524 cautionaries.  Even though all accidentals typeset by
1525 @code{default} @emph{are} typeset with this rule, some of them are
1526 typeset as cautionaries.
1527
1528 @lilypond[quote]
1529 musicA = {
1530   <<
1531     \relative c' {
1532       cis'8 fis, d'4 <a cis>8 f bis4 |
1533       cis2. <c, g'>4 |
1534     }
1535     \\
1536     \relative c' {
1537       ais'2 cis, |
1538       fis8 b a4 cis2 |
1539     }
1540   >>
1541 }
1542
1543 musicB = {
1544   \clef bass
1545   \new Voice {
1546     \voiceTwo \relative c' {
1547       <fis, a cis>4
1548       \change Staff = up
1549       cis'
1550       \change Staff = down
1551       <fis, a>
1552       \change Staff = up
1553       dis' |
1554       \change Staff = down
1555       <fis, a cis>4 gis <f a d>2 |
1556     }
1557   }
1558 }
1559
1560 \new PianoStaff {
1561   <<
1562     \context Staff = "up" {
1563       #(set-accidental-style 'modern-voice-cautionary)
1564       \musicA
1565     }
1566     \context Staff = "down" {
1567       #(set-accidental-style 'modern-voice-cautionary)
1568       \musicB
1569     }
1570   >>
1571 }
1572 @end lilypond
1573
1574 @item piano
1575
1576 @cindex accidental style, piano
1577 @cindex accidentals, piano
1578 @cindex piano accidental style
1579 @cindex piano accidentals
1580 @funindex piano
1581
1582 This rule reflects twentieth-century practice for piano notation.
1583 Its behavior is very similar to @code{modern} style, but here
1584 accidentals also get canceled across the staves in the same
1585 @code{GrandStaff} or @code{PianoStaff}, hence all the
1586 cancellations of the final notes.
1587
1588 This accidental style applies to the current @code{GrandStaff} or
1589 @code{PianoStaff} by default.
1590
1591 @lilypond[quote]
1592 musicA = {
1593   <<
1594     \relative c' {
1595       cis'8 fis, d'4 <a cis>8 f bis4 |
1596       cis2. <c, g'>4 |
1597     }
1598     \\
1599     \relative c' {
1600       ais'2 cis, |
1601       fis8 b a4 cis2 |
1602     }
1603   >>
1604 }
1605
1606 musicB = {
1607   \clef bass
1608   \new Voice {
1609     \voiceTwo \relative c' {
1610       <fis, a cis>4
1611       \change Staff = up
1612       cis'
1613       \change Staff = down
1614       <fis, a>
1615       \change Staff = up
1616       dis' |
1617       \change Staff = down
1618       <fis, a cis>4 gis <f a d>2 |
1619     }
1620   }
1621 }
1622
1623 \new PianoStaff {
1624   <<
1625     \context Staff = "up" {
1626       #(set-accidental-style 'piano)
1627       \musicA
1628     }
1629     \context Staff = "down" {
1630       \musicB
1631     }
1632   >>
1633 }
1634 @end lilypond
1635
1636 @item piano-cautionary
1637
1638 @funindex piano-cautionary
1639 @cindex accidentals, piano cautionary
1640 @cindex cautionary accidentals, piano
1641 @cindex piano cautionary accidentals
1642 @cindex accidental style, piano cautionary
1643 @cindex cautionary accidental style, piano
1644 @cindex piano cautionary accidental style
1645
1646 This is the same as @code{piano} but with the extra accidentals
1647 typeset as cautionaries.
1648
1649 @lilypond[quote]
1650 musicA = {
1651   <<
1652     \relative c' {
1653       cis'8 fis, d'4 <a cis>8 f bis4 |
1654       cis2. <c, g'>4 |
1655     }
1656     \\
1657     \relative c' {
1658       ais'2 cis, |
1659       fis8 b a4 cis2 |
1660     }
1661   >>
1662 }
1663
1664 musicB = {
1665   \clef bass
1666   \new Voice {
1667     \voiceTwo \relative c' {
1668       <fis, a cis>4
1669       \change Staff = up
1670       cis'
1671       \change Staff = down
1672       <fis, a>
1673       \change Staff = up
1674       dis' |
1675       \change Staff = down
1676       <fis, a cis>4 gis <f a d>2 |
1677     }
1678   }
1679 }
1680
1681 \new PianoStaff {
1682   <<
1683     \context Staff = "up" {
1684       #(set-accidental-style 'piano-cautionary)
1685       \musicA
1686     }
1687     \context Staff = "down" {
1688       \musicB
1689     }
1690   >>
1691 }
1692 @end lilypond
1693
1694
1695 @item neo-modern
1696
1697 @funindex neo-modern
1698 @cindex neo-modern accidental style
1699 @cindex accidental style, neo-modern
1700
1701 This rule reproduces a common practice in contemporary music:
1702 accidentals are printed like with @code{modern}, but they are printed
1703 again if the same note appears later in the same measure -- except
1704 if the note is immediately repeated.
1705
1706 @lilypond[quote]
1707 musicA = {
1708   <<
1709     \relative c' {
1710       cis'8 fis, d'4 <a cis>8 f bis4 |
1711       cis2. <c, g'>4 |
1712     }
1713     \\
1714     \relative c' {
1715       ais'2 cis, |
1716       fis8 b a4 cis2 |
1717     }
1718   >>
1719 }
1720
1721 musicB = {
1722   \clef bass
1723   \new Voice {
1724     \voiceTwo \relative c' {
1725       <fis, a cis>4
1726       \change Staff = up
1727       cis'
1728       \change Staff = down
1729       <fis, a>
1730       \change Staff = up
1731       dis' |
1732       \change Staff = down
1733       <fis, a cis>4 gis <f a d>2 |
1734     }
1735   }
1736 }
1737
1738 \new PianoStaff {
1739   <<
1740     \context Staff = "up" {
1741       #(set-accidental-style 'neo-modern)
1742       \musicA
1743     }
1744     \context Staff = "down" {
1745       #(set-accidental-style 'neo-modern)
1746       \musicB
1747     }
1748   >>
1749 }
1750 @end lilypond
1751
1752 @item neo-modern-cautionary
1753
1754 @funindex neo-modern-cautionary
1755 @cindex neo-modern-cautionary accidental style
1756 @cindex accidental style, neo-modern-cautionary
1757
1758 This rule is similar to @code{neo-modern}, but the extra
1759 accidentals are printed as cautionary accidentals.
1760
1761 @lilypond[quote]
1762 musicA = {
1763   <<
1764     \relative c' {
1765       cis'8 fis, d'4 <a cis>8 f bis4 |
1766       cis2. <c, g'>4 |
1767     }
1768     \\
1769     \relative c' {
1770       ais'2 cis, |
1771       fis8 b a4 cis2 |
1772     }
1773   >>
1774 }
1775
1776 musicB = {
1777   \clef bass
1778   \new Voice {
1779     \voiceTwo \relative c' {
1780       <fis, a cis>4
1781       \change Staff = up
1782       cis'
1783       \change Staff = down
1784       <fis, a>
1785       \change Staff = up
1786       dis' |
1787       \change Staff = down
1788       <fis, a cis>4 gis <f a d>2 |
1789     }
1790   }
1791 }
1792
1793 \new PianoStaff {
1794   <<
1795     \context Staff = "up" {
1796       #(set-accidental-style 'neo-modern-cautionary)
1797       \musicA
1798     }
1799     \context Staff = "down" {
1800       #(set-accidental-style 'neo-modern-cautionary)
1801       \musicB
1802     }
1803   >>
1804 }
1805 @end lilypond
1806
1807
1808 @item dodecaphonic
1809
1810 @funindex dodecaphonic
1811 @cindex dodecaphonic accidental style
1812 @cindex dodecaphonic style, neo-modern
1813
1814 This rule reflects a practice introduced by composers at
1815 the beginning of the 20th century, in an attempt to
1816 abolish the hierarchy between natural and non-natural notes.
1817 With this style, @emph{every} note gets an accidental sign,
1818 including natural signs.
1819
1820 @lilypond[quote]
1821 musicA = {
1822   <<
1823     \relative c' {
1824       cis'8 fis, d'4 <a cis>8 f bis4 |
1825       cis2. <c, g'>4 |
1826     }
1827     \\
1828     \relative c' {
1829       ais'2 cis, |
1830       fis8 b a4 cis2 |
1831     }
1832   >>
1833 }
1834
1835 musicB = {
1836   \clef bass
1837   \new Voice {
1838     \voiceTwo \relative c' {
1839       <fis, a cis>4
1840       \change Staff = up
1841       cis'
1842       \change Staff = down
1843       <fis, a>
1844       \change Staff = up
1845       dis' |
1846       \change Staff = down
1847       <fis, a cis>4 gis <f a d>2 |
1848     }
1849   }
1850 }
1851
1852 \new PianoStaff {
1853   <<
1854     \context Staff = "up" {
1855       #(set-accidental-style 'dodecaphonic)
1856       \musicA
1857     }
1858     \context Staff = "down" {
1859       #(set-accidental-style 'dodecaphonic)
1860       \musicB
1861     }
1862   >>
1863 }
1864 @end lilypond
1865
1866
1867 @item teaching
1868
1869 @funindex teaching
1870 @cindex teaching accidental style
1871 @cindex accidental style, teaching
1872
1873 This rule is intended for students, and makes it easy to create
1874 scale sheets with automagically created cautionary accidentals.
1875 Accidentals are printed like with @code{modern}, but cautionary
1876 accidentals are added for all sharp or flat tones specified by the
1877 key signature, except if the note is immediately repeated.
1878
1879 @lilypond[quote]
1880 musicA = {
1881   <<
1882     \relative c' {
1883       cis'8 fis, d'4 <a cis>8 f bis4 |
1884       cis2. <c, g'>4 |
1885     }
1886     \\
1887     \relative c' {
1888       ais'2 cis, |
1889       fis8 b a4 cis2 |
1890     }
1891   >>
1892 }
1893
1894 musicB = {
1895   \clef bass
1896   \new Voice {
1897     \voiceTwo \relative c' {
1898       <fis, a cis>4
1899       \change Staff = up
1900       cis'
1901       \change Staff = down
1902       <fis, a>
1903       \change Staff = up
1904       dis' |
1905       \change Staff = down
1906       <fis, a cis>4 gis <f a d>2 |
1907     }
1908   }
1909 }
1910
1911 \new PianoStaff {
1912   <<
1913     \context Staff = "up" {
1914       \key fis \minor
1915       #(set-accidental-style 'teaching)
1916       \musicA
1917     }
1918     \context Staff = "down" {
1919       \key fis \minor
1920       #(set-accidental-style 'teaching)
1921       \musicB
1922     }
1923   >>
1924 }
1925 @end lilypond
1926
1927
1928
1929 @item no-reset
1930
1931 @funindex no-reset
1932 @cindex accidental style, no reset
1933 @cindex no reset accidental style
1934
1935 This is the same as @code{default} but with accidentals lasting
1936 @q{forever} and not only within the same measure:
1937
1938 @lilypond[quote]
1939 musicA = {
1940   <<
1941     \relative c' {
1942       cis'8 fis, d'4 <a cis>8 f bis4 |
1943       cis2. <c, g'>4 |
1944     }
1945     \\
1946     \relative c' {
1947       ais'2 cis, |
1948       fis8 b a4 cis2 |
1949     }
1950   >>
1951 }
1952
1953 musicB = {
1954   \clef bass
1955   \new Voice {
1956     \voiceTwo \relative c' {
1957       <fis, a cis>4
1958       \change Staff = up
1959       cis'
1960       \change Staff = down
1961       <fis, a>
1962       \change Staff = up
1963       dis' |
1964       \change Staff = down
1965       <fis, a cis>4 gis <f a d>2 |
1966     }
1967   }
1968 }
1969
1970 \new PianoStaff {
1971   <<
1972     \context Staff = "up" {
1973       #(set-accidental-style 'no-reset)
1974       \musicA
1975     }
1976     \context Staff = "down" {
1977       #(set-accidental-style 'no-reset)
1978       \musicB
1979     }
1980   >>
1981 }
1982 @end lilypond
1983
1984 @item forget
1985
1986 @funindex forget
1987 @cindex forget accidental style
1988 @cindex accidental style, forget
1989
1990 This is the opposite of @code{no-reset}: Accidentals are not
1991 remembered at all -- and hence all accidentals are typeset
1992 relative to the key signature, regardless of what came before in
1993 the music.  Unlike @code{dodecaphonic}, this rule never prints
1994 any naturals.
1995
1996 @lilypond[quote]
1997 musicA = {
1998   <<
1999     \relative c' {
2000       cis'8 fis, d'4 <a cis>8 f bis4 |
2001       cis2. <c, g'>4 |
2002     }
2003     \\
2004     \relative c' {
2005       ais'2 cis, |
2006       fis8 b a4 cis2 |
2007     }
2008   >>
2009 }
2010
2011 musicB = {
2012   \clef bass
2013   \new Voice {
2014     \voiceTwo \relative c' {
2015       <fis, a cis>4
2016       \change Staff = up
2017       cis'
2018       \change Staff = down
2019       <fis, a>
2020       \change Staff = up
2021       dis' |
2022       \change Staff = down
2023       <fis, a cis>4 gis <f a d>2 |
2024     }
2025   }
2026 }
2027
2028 \new PianoStaff {
2029   <<
2030     \context Staff = "up" {
2031       #(set-accidental-style 'forget)
2032       \musicA
2033     }
2034     \context Staff = "down" {
2035       #(set-accidental-style 'forget)
2036       \musicB
2037     }
2038   >>
2039 }
2040 @end lilypond
2041 @end table
2042
2043 @snippets
2044
2045 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
2046 {dodecaphonic-style-accidentals-for-each-note-including-naturals.ly}
2047
2048
2049 @seealso
2050 Snippets:
2051 @rlsr{Pitches}.
2052
2053 Internals Reference:
2054 @rinternals{Accidental},
2055 @rinternals{Accidental_engraver},
2056 @rinternals{GrandStaff} and
2057 @rinternals{PianoStaff},
2058 @rinternals{Staff},
2059 @rinternals{AccidentalSuggestion},
2060 @rinternals{AccidentalPlacement},
2061 @rinternals{accidental-suggestion-interface}.
2062
2063
2064 @cindex accidentals and simultaneous notes
2065 @cindex simultaneous notes and accidentals
2066 @cindex accidentals in chords
2067 @cindex chords, accidentals in
2068
2069 @knownissues
2070
2071 Simultaneous notes are considered to be entered in sequential
2072 mode.  This means that in a chord the accidentals are typeset as
2073 if the notes in the chord happen one at a time, in the order in
2074 which they appear in the input file.  This is a problem when
2075 accidentals in a chord depend on each other, which does not happen
2076 for the default accidental style.  The problem can be solved by
2077 manually inserting@tie{}@code{!} and@tie{}@code{?} for the
2078 problematic notes.
2079
2080
2081 @node Ambitus
2082 @unnumberedsubsubsec Ambitus
2083
2084 @cindex ambitus
2085 @cindex range of pitches
2086 @cindex pitch range
2087
2088 The term @notation{ambitus} (pl. ambitus) denotes a range of
2089 pitches for a given voice in a part of music.  It may also denote
2090 the pitch range that a musical instrument is capable of playing.
2091 Ambitus are printed on vocal parts so that performers can easily
2092 determine if it matches their capabilities.
2093
2094 Ambitus are denoted at the beginning of a piece near the initial
2095 clef.  The range is graphically specified by two note heads that
2096 represent the lowest and highest pitches.  Accidentals are only
2097 printed if they are not part of the key signature.
2098
2099 @lilypond[verbatim,quote]
2100 \layout {
2101   \context {
2102     \Voice
2103     \consists "Ambitus_engraver"
2104   }
2105 }
2106
2107 \relative c'' {
2108   aes c e2
2109   cis,1
2110 }
2111 @end lilypond
2112
2113
2114 @snippets
2115
2116 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
2117 {adding-ambitus-per-voice.ly}
2118
2119 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
2120 {ambitus-with-multiple-voices.ly}
2121
2122
2123 @seealso
2124 Music Glossary:
2125 @rglos{ambitus}.
2126
2127 Snippets:
2128 @rlsr{Pitches}.
2129
2130 Internals Reference:
2131 @rinternals{Ambitus_engraver},
2132 @rinternals{Voice},
2133 @rinternals{Staff},
2134 @rinternals{Ambitus},
2135 @rinternals{AmbitusAccidental},
2136 @rinternals{AmbitusLine},
2137 @rinternals{AmbitusNoteHead},
2138 @rinternals{ambitus-interface}.
2139
2140
2141 @knownissues
2142
2143 There is no collision handling in the case of multiple per-voice
2144 ambitus.
2145
2146
2147 @node Note heads
2148 @subsection Note heads
2149
2150 This section suggests ways of altering note heads.
2151
2152 @menu
2153 * Special note heads::
2154 * Easy notation note heads::
2155 * Shape note heads::
2156 * Improvisation::
2157 @end menu
2158
2159 @node Special note heads
2160 @unnumberedsubsubsec Special note heads
2161
2162 @cindex note heads, special
2163 @cindex note heads, cross
2164 @cindex note heads, diamond
2165 @cindex note heads, parlato
2166 @cindex note heads, harmonic
2167 @cindex note heads, guitar
2168 @cindex special note heads
2169 @cindex cross note heads
2170 @cindex diamond note heads
2171 @cindex parlato note heads
2172 @cindex harmonic note heads
2173 @cindex guitar note heads
2174 @cindex note head styles
2175 @cindex styles, note heads
2176 @funindex cross
2177
2178 Note heads may be altered:
2179
2180 @lilypond[verbatim,quote,relative=2]
2181 c4 b a b
2182 \override NoteHead #'style = #'cross
2183 c4 b a b
2184 \revert NoteHead #'style
2185 c4 d e f
2186 @end lilypond
2187
2188 There is a shorthand for diamond shapes which can only be used
2189 inside chords:
2190
2191 @lilypond[verbatim,quote,relative=2]
2192 <c f\harmonic>2 <d a'\harmonic>4 <c g'\harmonic>
2193 @end lilypond
2194
2195 @noindent
2196 To see all note head styles, see @ref{Note head styles}.
2197
2198
2199 @seealso
2200 Snippets:
2201 @rlsr{Pitches}.
2202
2203 Notation Reference:
2204 @ref{Note head styles},
2205 @ref{Chorded notes}.
2206
2207 Internals Reference:
2208 @rinternals{note-event},
2209 @rinternals{Note_heads_engraver},
2210 @rinternals{Ledger_line_engraver},
2211 @rinternals{NoteHead},
2212 @rinternals{LedgerLineSpanner},
2213 @rinternals{note-head-interface},
2214 @rinternals{ledger-line-spanner-interface}.
2215
2216
2217 @node Easy notation note heads
2218 @unnumberedsubsubsec Easy notation note heads
2219
2220 @cindex note heads, practice
2221 @cindex practice note heads
2222 @cindex note heads, easy notation
2223 @cindex easy notation
2224 @cindex Hal Leonard
2225 @cindex beginners' music
2226 @cindex music, beginners'
2227 @cindex easy play note heads
2228 @cindex note heads, easy play
2229
2230 The @q{easy play} note head includes a note name inside the head.
2231 It is used in music for beginners.  To make the letters readable,
2232 it should be printed in a large font size.  To print with a larger
2233 font, see @ref{Setting the staff size}.
2234
2235 @lilypond[verbatim,quote]
2236 #(set-global-staff-size 26)
2237 \relative c' {
2238   \easyHeadsOn
2239   c2 e4 f
2240   g1
2241   \easyHeadsOff
2242   c,1
2243 }
2244 @end lilypond
2245
2246
2247 @predefined
2248 @funindex \easyHeadsOn
2249 @code{\easyHeadsOn},
2250 @funindex \easyHeadsOff
2251 @code{\easyHeadsOff}.
2252 @endpredefined
2253
2254
2255 @seealso
2256 Notation Reference:
2257 @ref{Setting the staff size}.
2258
2259 Snippets:
2260 @rlsr{Pitches}.
2261
2262 Internals Reference:
2263 @rinternals{note-event},
2264 @rinternals{Note_heads_engraver},
2265 @rinternals{NoteHead},
2266 @rinternals{note-head-interface}.
2267
2268
2269 @node Shape note heads
2270 @unnumberedsubsubsec Shape note heads
2271
2272 @cindex note heads, shape
2273 @cindex note heads, Aiken
2274 @cindex note heads, sacred harp
2275 @cindex shape notes
2276 @cindex Aiken shape note heads
2277 @cindex sacred harp note heads
2278 @funindex \key
2279 @funindex \aikenHeads
2280 @funindex \sacredHarpHeads
2281
2282 In shape note head notation, the shape of the note head
2283 corresponds to the harmonic function of a note in the scale.  This
2284 notation was popular in nineteenth-century American song books.
2285 Shape note heads can be produced:
2286
2287 @lilypond[verbatim,quote,relative=2]
2288 \aikenHeads
2289 c, d e f g a b c
2290 \sacredHarpHeads
2291 c, d e f g a b c
2292 @end lilypond
2293
2294 Shapes are typeset according to the step in the scale, where the
2295 base of the scale is determined by the @code{\key} command.
2296
2297
2298 @predefined
2299 @funindex \aikenHeads
2300 @code{\aikenHeads},
2301 @funindex \sacredHarpHeads
2302 @code{\sacredHarpHeads}.
2303 @endpredefined
2304
2305
2306 @snippets
2307
2308 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
2309 {applying-note-head-styles-depending-on-the-step-of-the-scale.ly}
2310
2311 @noindent
2312 To see all note head styles, see @ref{Note head styles}.
2313
2314
2315 @seealso
2316 Snippets:
2317 @rlsr{Pitches}.
2318
2319 Notation Reference:
2320 @ref{Note head styles}.
2321
2322 Internals Reference:
2323 @rinternals{note-event},
2324 @rinternals{Note_heads_engraver},
2325 @rinternals{NoteHead},
2326 @rinternals{note-head-interface}.
2327
2328
2329 @node Improvisation
2330 @unnumberedsubsubsec Improvisation
2331
2332 @cindex improvisation
2333 @cindex slashed note heads
2334 @cindex note heads, improvisation
2335 @cindex note heads, slashed
2336
2337 Improvisation is sometimes denoted with slashed note heads, where
2338 the performer may choose any pitch but should play the specified
2339 rhythm.  Such note heads can be created:
2340
2341 @lilypond[verbatim,quote,relative=2]
2342 \new Voice \with {
2343   \consists "Pitch_squash_engraver"
2344 } {
2345   e8 e g a a16( bes) a8 g
2346   \improvisationOn
2347   e8 ~
2348   e2 ~ e8 f4 f8 ~
2349   f2
2350   \improvisationOff
2351   a16( bes) a8 g e
2352 }
2353 @end lilypond
2354
2355
2356 @predefined
2357 @funindex \improvisationOn
2358 @code{\improvisationOn},
2359 @funindex \improvisationOff
2360 @code{\improvisationOff}.
2361 @endpredefined
2362
2363
2364 @seealso
2365 Snippets:
2366 @rlsr{Pitches}.
2367
2368 Internals Reference:
2369 @rinternals{Pitch_squash_engraver},
2370 @rinternals{Voice},
2371 @rinternals{RhythmicStaff}.
2372
2373