Documentation/notation/pitches.itely

   1 @c -*- coding: utf-8; mode: texinfo; -*-
   2 @ignore
   3    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
   4
   5     When revising a translation, copy the HEAD committish of the
   6     version that you are working on.  For details, see the Contributors'
   7     Guide, node Updating translation committishes..
   8 @end ignore
   9
  10 @c \version "2.19.53"
  11
  12
  13 @node Pitches
  14 @section Pitches
  15
  16 @lilypondfile[quote]{pitches-headword.ly}
  17
  18 This section discusses how to specify the pitch of notes.  There
  19 are three steps to this process: input, modification, and output.
  20
  21 @menu
  22 * Writing pitches::
  23 * Changing multiple pitches::
  24 * Displaying pitches::
  25 * Note heads::
  26 @end menu
  27
  28
  29 @node Writing pitches
  30 @subsection Writing pitches
  31
  32 This section discusses how to input pitches.  There are two
  33 different ways to place notes in octaves: absolute and relative
  34 mode.  In most cases, relative mode will be more convenient.
  35
  36 @menu
  37 * Absolute octave entry::
  38 * Relative octave entry::
  39 * Accidentals::
  40 * Note names in other languages::
  41 @end menu
  42
  43
  44 @node Absolute octave entry
  45 @unnumberedsubsubsec Absolute octave entry
  46
  47 @cindex pitch names
  48 @cindex pitches
  49 @cindex absolute
  50 @cindex absolute octave specification
  51 @cindex octave specification, absolute
  52 @cindex absolute octave entry
  53 @cindex octave entry, absolute
  54
  55 A pitch name is specified using lowercase letters@tie{}@code{a}
  56 through@tie{}@code{g}.  The note names @code{c} to @code{b} are
  57 engraved in the octave below middle C.
  58
  59 @c don't use c' here.
  60 @lilypond[verbatim,quote]
  61 {
  62   \clef bass
  63   c4 d e f
  64   g4 a b c
  65   d4 e f g
  66 }
  67 @end lilypond
  68
  69 @cindex octave changing mark
  70
  71 @funindex '
  72 @funindex ,
  73
  74 Other octaves may be specified with a single quote@tie{}(@code{'})
  75 or comma@tie{}(@code{,}) character.  Each@tie{}@code{'} raises the
  76 pitch by one octave; each@tie{}@code{,} lowers the pitch by an
  77 octave.
  78
  79 @lilypond[verbatim,quote]
  80 {
  81   \clef treble
  82   c'4 e' g' c''
  83   c'4 g b c'
  84   \clef bass
  85   c,4 e, g, c
  86   c,4 g,, b,, c,
  87 }
  88 @end lilypond
  89
  90 @funindex \fixed
  91 Common octave marks can be entered just once on a reference pitch
  92 after @code{\fixed} placed before the music.  Pitches inside
  93 @code{\fixed} only need @code{'} or@tie{}@code{,} marks
  94 when they are above or below the octave of the reference pitch.
  95
  96 @lilypond[verbatim,quote]
  97 {
  98   \fixed c' {
  99     \clef treble
 100     c4 e g c'
 101     c4 g, b, c
 102   }
 103   \clef bass
 104   \fixed c, {
 105     c4 e g c'
 106     c4 g, b, c
 107   }
 108 }
 109 @end lilypond
 110
 111 Pitches in the music expression following @code{\fixed} are
 112 unaffected by any enclosing @code{\relative}, discussed next.
 113
 114 @seealso
 115 Music Glossary:
 116 @rglos{Pitch names}.
 117
 118 Snippets:
 119 @rlsr{Pitches}.
 120
 121
 122 @node Relative octave entry
 123 @unnumberedsubsubsec Relative octave entry
 124
 125 @cindex relative
 126 @cindex relative octave entry
 127 @cindex octave entry, relative
 128 @cindex relative octave specification
 129 @cindex octave specification, relative
 130
 131 @funindex \relative
 132
 133 Absolute octave entry requires specifying the octave for every
 134 single note.  Relative octave entry, in contrast, specifies each
 135 octave in relation to the last note: changing one note's octave
 136 will affect all of the following notes.
 137
 138 Relative note mode has to be entered explicitly using the
 139 @code{\relative} command:
 140
 141 @example
 142 \relative @var{startpitch} @var{musicexpr}
 143 @end example
 144
 145 In relative mode, each note is assumed to be as close to the
 146 previous note as possible.  This means that the octave of each
 147 pitch inside @code{@var{musicexpr}} is calculated as follows:
 148
 149 @itemize
 150 @item
 151 If no octave changing mark is used on a pitch, its octave is
 152 calculated so that the interval with the previous note is less
 153 than a fifth.  This interval is determined without considering
 154 accidentals.
 155
 156 @item
 157 An octave changing mark@tie{}@code{'} or@tie{}@code{,} can be
 158 added to respectively raise or lower a pitch by an extra octave,
 159 relative to the pitch calculated without an octave mark.
 160
 161 @item
 162 Multiple octave changing marks can be used.  For example,
 163 @code{''}@tie{}and@tie{}@code{,,} will alter the pitch by two
 164 octaves.
 165
 166 @item
 167 The pitch of the first note is relative to
 168 @code{@var{startpitch}}.  @code{@var{startpitch}} is specified in
 169 absolute octave mode.  Which choices are meaningful?
 170
 171 @table @asis
 172 @item an octave of @code{c}
 173 Identifying middle C with @code{c'} is quite basic, so finding
 174 octaves of @code{c} tends to be straightforward.  If your music
 175 starts with @code{gis} above @code{c'''}, you'd write something
 176 like @code{\relative c''' @{ gis' @dots{} @}}
 177
 178 @item an octave of the first note inside
 179 Writing @code{\relative gis''' @{ gis @dots{} @}} makes it easy to
 180 determine the absolute pitch of the first note inside.
 181
 182 @item no explicit starting pitch
 183 The form @code{\relative @{ gis''' @dots{} @}} serves
 184 as a compact version of the previous option: the first note
 185 inside is written in absolute pitch itself.  (This happens to be
 186 equivalent to choosing @code{f} as the reference pitch.)
 187 @end table
 188
 189 The documentation will usually employ the last option.
 190 @end itemize
 191
 192 Here is the relative mode shown in action:
 193
 194 @lilypond[verbatim,quote]
 195 \relative {
 196   \clef bass
 197   c d e f
 198   g a b c
 199   d e f g
 200 }
 201 @end lilypond
 202
 203 Octave changing marks are used for intervals greater than a
 204 fourth:
 205
 206 @lilypond[verbatim,quote]
 207 \relative {
 208   c'' g c f,
 209   c' a, e'' c
 210 }
 211 @end lilypond
 212
 213 A note sequence without a single octave mark can nevertheless span
 214 large intervals:
 215
 216 @lilypond[verbatim,quote]
 217 \relative {
 218   c f b e
 219   a d g c
 220 }
 221 @end lilypond
 222
 223 When @code{\relative} blocks are nested, the innermost
 224 @code{\relative} block starts with its own reference pitch
 225 independently of the outer @code{\relative}.
 226
 227 @lilypond[verbatim,quote]
 228 \relative {
 229   c' d e f
 230   \relative {
 231     c'' d e f
 232   }
 233 }
 234 @end lilypond
 235
 236 @code{\relative} has no effect on @code{\chordmode} blocks.
 237
 238 @lilypond[verbatim,quote]
 239 \new Staff {
 240   \relative c''' {
 241     \chordmode { c1 }
 242   }
 243   \chordmode { c1 }
 244 }
 245 @end lilypond
 246
 247 @code{\relative} is not allowed inside of @code{\chordmode} blocks.
 248
 249 Music inside a @code{\transpose} block is absolute unless a
 250 @code{\relative} is included.
 251
 252 @lilypond[verbatim,quote]
 253 \relative {
 254   d' e
 255   \transpose f g {
 256     d e
 257     \relative {
 258       d' e
 259     }
 260   }
 261 }
 262 @end lilypond
 263
 264
 265 @cindex chords and relative octave entry
 266 @cindex relative octave entry and chords
 267
 268 If the preceding item is a chord, the first note of the chord is
 269 used as the reference point for the octave placement of a
 270 following note or chord.  Inside chords, the next note is always
 271 relative to the preceding one.  Examine the next example
 272 carefully, paying attention to the @code{c} notes.
 273
 274 @lilypond[verbatim,quote]
 275 \relative {
 276   c'
 277   <c e g>
 278   <c' e g'>
 279   <c, e, g''>
 280 }
 281 @end lilypond
 282
 283 As explained above, the octave of pitches is calculated only with
 284 the note names, regardless of any alterations.  Therefore, an
 285 E-double-sharp following a B will be placed higher, while an
 286 F-double-flat will be placed lower.  In other words, a
 287 double-augmented fourth is considered a smaller interval than a
 288 double-diminished fifth, regardless of the number of semitones
 289 that each interval contains.
 290
 291 @lilypond[verbatim,quote]
 292 \relative {
 293   c''2 fis
 294   c2 ges
 295   b2 eisis
 296   b2 feses
 297 }
 298 @end lilypond
 299
 300 In complex situations, it is sometimes useful to get back to a
 301 certain pitch regardless of what happened before. This can be
 302 done using @code{\resetRelativeOctave}:
 303
 304 @lilypond[verbatim,quote]
 305 \relative {
 306   <<
 307     { c''2 d }
 308     \\
 309     { e,,2 f }
 310   >>
 311   \resetRelativeOctave c''
 312   c2
 313 }
 314 @end lilypond
 315
 316 @funindex \resetRelativeOctave
 317
 318
 319 @seealso
 320 Music Glossary:
 321 @rglos{fifth},
 322 @rglos{interval},
 323 @rglos{Pitch names}.
 324
 325 Notation Reference:
 326 @ref{Octave checks}.
 327
 328 Snippets:
 329 @rlsr{Pitches}.
 330
 331 Internals Reference:
 332 @rinternals{RelativeOctaveMusic}.
 333
 334 @cindex relative octave entry and transposition
 335 @cindex transposition and relative octave entry
 336
 337 @funindex \transpose
 338 @funindex \chordmode
 339 @funindex \relative
 340
 341
 342 @node Accidentals
 343 @unnumberedsubsubsec Accidentals
 344
 345 @cindex accidental
 346 @cindex key signature
 347 @cindex clef
 348
 349 @c duplicated in Key signature and Accidentals
 350 @warning{New users are sometimes confused about accidentals and
 351 key signatures.  In LilyPond, note names specify pitches; key
 352 signatures and clefs determine how these pitches are displayed.
 353 An unaltered note like@tie{}@code{c} means @q{C natural},
 354 regardless of the key signature or clef.  For more information,
 355 see @rlearning{Pitches and key signatures}.}
 356
 357 @cindex note names, Dutch
 358 @cindex note names, default
 359 @cindex default note names
 360 @cindex sharp
 361 @cindex flat
 362 @cindex double sharp
 363 @cindex sharp, double
 364 @cindex double flat
 365 @cindex flat, double
 366 @cindex natural sign
 367 @cindex natural pitch
 368
 369 A @notation{sharp} pitch is made by adding @code{is} to the note
 370 name, and a @notation{flat} pitch by adding @code{es}.  As you
 371 might expect, a @notation{double sharp} or @notation{double flat}
 372 is made by adding @code{isis} or @code{eses}.  This syntax is
 373 derived from Dutch note naming conventions.  To use other names
 374 for accidentals, see @ref{Note names in other languages}.
 375
 376 @lilypond[verbatim,quote,fragment]
 377 \relative c'' { ais1 aes aisis aeses }
 378 @end lilypond
 379
 380 A natural pitch is entered as a simple note name; no suffix is
 381 required.  A natural sign will be printed when needed to cancel
 382 the effect of an earlier accidental or key signature.
 383
 384 @lilypond[verbatim,quote,fragment]
 385 \relative c'' { a4 aes a2 }
 386 @end lilypond
 387
 388 @cindex quarter tones
 389 @cindex semi-flats
 390 @cindex semi-sharps
 391
 392 Quarter tones may be added; the following is a series of Cs with
 393 increasing pitches:
 394
 395 @lilypond[verbatim,quote,fragment]
 396 \relative c'' { ceseh1 ces ceh c cih cis cisih }
 397 @end lilypond
 398
 399
 400
 401 @cindex accidental, reminder
 402 @cindex accidental, cautionary
 403 @cindex accidental, parenthesized
 404 @cindex reminder accidental
 405 @cindex cautionary accidental
 406 @cindex parenthesized accidental
 407
 408 @funindex ?
 409 @funindex !
 410
 411
 412 Normally accidentals are printed automatically, but you may also
 413 print them manually.  A reminder accidental can be forced by
 414 adding an exclamation mark@tie{}@code{!} after the pitch.  A
 415 cautionary accidental (i.e., an accidental within parentheses) can
 416 be obtained by adding the question mark@tie{}@code{?} after the
 417 pitch.
 418
 419 @lilypond[verbatim,quote,fragment]
 420 \relative c'' { cis cis cis! cis? c c c! c? }
 421 @end lilypond
 422
 423 @cindex accidental on tied note
 424 @cindex tied note, accidental
 425
 426 Accidentals on tied notes are only printed at the beginning of a
 427 new system:
 428
 429 @lilypond[verbatim,quote,fragment,ragged-right]
 430 \relative c'' {
 431   cis1~ 1~
 432   \break
 433   cis
 434 }
 435 @end lilypond
 436
 437
 438 @snippets
 439
 440 @lilypondfile[verbatim,quote,texidoc,doctitle,ragged-right]
 441 {hiding-accidentals-on-tied-notes-at-the-start-of-a-new-system.ly}
 442
 443 @lilypondfile[verbatim,quote,texidoc,doctitle]
 444 {preventing-extra-naturals-from-being-automatically-added.ly}
 445
 446 @seealso
 447 Music Glossary:
 448 @rglos{sharp},
 449 @rglos{flat},
 450 @rglos{double sharp},
 451 @rglos{double flat},
 452 @rglos{Pitch names},
 453 @rglos{quarter tone}.
 454
 455 Learning Manual:
 456 @rlearning{Pitches and key signatures}.
 457
 458 Notation Reference:
 459 @ref{Automatic accidentals},
 460 @ref{Annotational accidentals (musica ficta)},
 461 @ref{Note names in other languages}.
 462
 463 Snippets:
 464 @rlsr{Pitches}.
 465
 466 Internals Reference:
 467 @rinternals{Accidental_engraver},
 468 @rinternals{Accidental},
 469 @rinternals{AccidentalCautionary},
 470 @rinternals{accidental-interface}.
 471
 472 @cindex accidental, quarter-tone
 473 @cindex quarter-tone accidental
 474
 475 @knownissues
 476 There are no generally accepted standards for denoting
 477 quarter-tone accidentals, so LilyPond's symbols do not conform to
 478 any standard.
 479
 480
 481 @node Note names in other languages
 482 @unnumberedsubsubsec Note names in other languages
 483
 484 @cindex note names, other languages
 485 @cindex pitch names, other languages
 486 @cindex language, note names in other
 487 @cindex language, pitch names in other
 488
 489 There are predefined sets of note and accidental names for various
 490 other languages.  Selecting the note name language is usually done
 491 at the beginning of the file; the following example is written
 492 using Italian note names:
 493
 494 @lilypond[quote,verbatim]
 495 \language "italiano"
 496
 497 \relative {
 498   do' re mi sib
 499 }
 500 @end lilypond
 501
 502 The available languages and the note names they define are:
 503
 504 @quotation
 505 @multitable {@code{nederlands}} {do re/re mi fa sol la sib si}
 506 @headitem Language
 507   @tab Note Names
 508 @item @code{nederlands}
 509   @tab c d e f g a bes b
 510 @item @code{catalan}
 511   @tab do re mi fa sol la sib si
 512 @item @code{deutsch}
 513   @tab c d e f g a b h
 514 @item @code{english}
 515   @tab c d e f g a bf b
 516 @item @code{espanol} or @code{español}
 517   @tab do re mi fa sol la sib si
 518 @item @code{français}
 519   @tab do ré/re mi fa sol la sib si
 520 @item @code{italiano}
 521   @tab do re mi fa sol la sib si
 522 @item @code{norsk}
 523   @tab c d e f g a b h
 524 @item @code{portugues}
 525   @tab do re mi fa sol la sib si
 526 @item @code{suomi}
 527   @tab c d e f g a b h
 528 @item @code{svenska}
 529   @tab c d e f g a b h
 530 @item @code{vlaams}
 531   @tab do re mi fa sol la sib si
 532 @end multitable
 533 @end quotation
 534
 535 In addition to note names, accidental suffixes may
 536 also vary depending on the language:
 537
 538 @quotation
 539 @multitable {@code{nederlands}} {-@code{s}/-@code{-sharp}} {-@code{f}/-@code{-flat}} {-@code{ss}/-@code{x}/-@code{-sharpsharp}} {-@code{ff}/-@code{-flatflat}}
 540 @headitem Language
 541   @tab sharp @tab flat @tab double sharp @tab double flat
 542 @item @code{nederlands}
 543   @tab -@code{is} @tab -@code{es} @tab -@code{isis} @tab -@code{eses}
 544 @item @code{catalan}
 545   @tab -@code{d}/-@code{s} @tab -@code{b} @tab -@code{dd}/-@code{ss} @tab -@code{bb}
 546 @item @code{deutsch}
 547   @tab -@code{is} @tab -@code{es} @tab -@code{isis} @tab -@code{eses}
 548 @item @code{english}
 549   @tab -@code{s}/-@code{-sharp} @tab -@code{f}/-@code{-flat} @tab -@code{ss}/-@code{x}/-@code{-sharpsharp}
 550     @tab -@code{ff}/-@code{-flatflat}
 551 @item @code{espanol} or @code{español}
 552   @tab -@code{s} @tab -@code{b} @tab -@code{ss}/-@code{x} @tab -@code{bb}
 553 @item @code{français}
 554   @tab -@code{d} @tab -@code{b} @tab -@code{dd}/-@code{x} @tab -@code{bb}
 555 @item @code{italiano}
 556   @tab -@code{d} @tab -@code{b} @tab -@code{dd} @tab -@code{bb}
 557 @item @code{norsk}
 558   @tab -@code{iss}/-@code{is} @tab -@code{ess}/-@code{es} @tab -@code{ississ}/-@code{isis}
 559     @tab -@code{essess}/-@code{eses}
 560 @item @code{portugues}
 561   @tab -@code{s} @tab -@code{b} @tab -@code{ss} @tab -@code{bb}
 562 @item @code{suomi}
 563   @tab -@code{is} @tab -@code{es} @tab -@code{isis} @tab -@code{eses}
 564 @item @code{svenska}
 565   @tab -@code{iss} @tab -@code{ess} @tab -@code{ississ} @tab -@code{essess}
 566 @item @code{vlaams}
 567   @tab -@code{k} @tab -@code{b} @tab -@code{kk} @tab -@code{bb}
 568 @end multitable
 569 @end quotation
 570
 571 In Dutch, @code{aes} is contracted to @code{as}, but both forms
 572 are accepted in LilyPond.  Similarly, both @code{es} and
 573 @code{ees} are accepted.  This also applies to
 574 @code{aeses}@tie{}/@tie{}@code{ases} and
 575 @code{eeses}@tie{}/@tie{}@code{eses}.  Sometimes only these
 576 contracted names are defined in the corresponding language files.
 577
 578 @lilypond[verbatim,quote,fragment]
 579 \relative c'' { a2 as e es a ases e eses }
 580 @end lilypond
 581
 582
 583 @cindex microtones
 584 @cindex semi-sharp
 585 @cindex semi-flat
 586 @cindex sesqui-sharp
 587 @cindex sesqui-flat
 588
 589 Some music uses microtones whose alterations are fractions of a
 590 @q{normal} sharp or flat.  The following table lists note names
 591 for quarter-tone accidentals in various languages; here the prefixes
 592 @notation{semi-} and @notation{sesqui-} respectively
 593 mean @q{half} and @q{one and a half}.  Languages that do not
 594 appear in this table do not provide special note names yet.
 595
 596 @quotation
 597 @multitable {@code{nederlands}} {@b{semi-sharp}} {@b{semi-flat}} {@b{sesqui-sharp}} {@b{sesqui-flat}}
 598 @headitem Language
 599   @tab semi-sharp @tab semi-flat @tab sesqui-sharp @tab sesqui-flat
 600
 601 @item @code{nederlands}
 602   @tab -ih @tab -eh @tab -isih @tab -eseh
 603 @item @code{deutsch}
 604   @tab -ih @tab -eh @tab -isih @tab -eseh
 605 @item @code{english}
 606   @tab -qs @tab -qf @tab -tqs @tab -tqf
 607 @item @code{espanol} or @code{español}
 608   @tab -cs @tab -cb @tab -tcs @tab -tcb
 609 @item @code{français}
 610   @tab -sd @tab -sb @tab -dsd @tab -bsb
 611 @item @code{italiano}
 612   @tab -sd @tab -sb @tab -dsd @tab -bsb
 613 @item @code{portugues}
 614   @tab -sqt @tab -bqt @tab -stqt @tab -btqt
 615 @end multitable
 616 @end quotation
 617
 618 Most languages presented here are commonly associated with
 619 Western classical music, also referred to as
 620 @notation{Common Practice Period}.  However, alternate
 621 pitches and tuning systems are also supported: see
 622 @ref{Common notation for non-Western music}.
 623
 624 @seealso
 625 Music Glossary:
 626 @rglos{Pitch names},
 627 @rglos{Common Practice Period}.
 628
 629 Notation Reference:
 630 @ref{Common notation for non-Western music}.
 631
 632 Installed Files:
 633 @file{scm/define-note-names.scm}.
 634
 635 Snippets:
 636 @rlsr{Pitches}.
 637
 638
 639 @node Changing multiple pitches
 640 @subsection Changing multiple pitches
 641
 642 This section discusses how to modify pitches.
 643
 644 @menu
 645 * Octave checks::
 646 * Transpose::
 647 * Inversion::
 648 * Retrograde::
 649 * Modal transformations::
 650 @end menu
 651
 652 @node Octave checks
 653 @unnumberedsubsubsec Octave checks
 654
 655 @cindex octave correction
 656 @cindex octave check
 657 @cindex control pitch
 658
 659 @funindex =
 660 @funindex \octaveCheck
 661 @funindex controlpitch
 662
 663 In relative mode, it is easy to forget an octave changing mark.
 664 Octave checks make such errors easier to find by displaying a
 665 warning and correcting the octave if a note is found in an
 666 unexpected octave.
 667
 668 To check the octave of a note, specify the absolute octave after
 669 the @code{=}@tie{}symbol.  This example will generate a warning
 670 (and change the pitch) because the second note is the absolute
 671 octave @code{d''} instead of @code{d'} as indicated by the octave
 672 correction.
 673
 674 @lilypond[verbatim,quote]
 675 \relative {
 676   c''2 d='4 d
 677   e2 f
 678 }
 679 @end lilypond
 680
 681 The octave of notes may also be checked with the
 682 @code{\octaveCheck@tie{}@var{controlpitch}} command.
 683 @code{@var{controlpitch}} is specified in absolute mode.  This
 684 checks that the interval between the previous note and the
 685 @code{@var{controlpitch}} is within a fourth (i.e., the normal
 686 calculation of relative mode).  If this check fails, a warning is
 687 printed.  While the previous note itself is not changed, future
 688 notes are relative to the corrected value.
 689
 690 @lilypond[verbatim,quote]
 691 \relative {
 692   c''2 d
 693   \octaveCheck c'
 694   e2 f
 695 }
 696 @end lilypond
 697
 698 Compare the two bars below.  The first and third @code{\octaveCheck}
 699 checks fail, but the second one does not fail.
 700
 701 @lilypond[verbatim,quote]
 702 \relative {
 703   c''4 f g f
 704
 705   c4
 706   \octaveCheck c'
 707   f
 708   \octaveCheck c'
 709   g
 710   \octaveCheck c'
 711   f
 712 }
 713 @end lilypond
 714
 715 @seealso
 716 Snippets:
 717 @rlsr{Pitches}.
 718
 719 Internals Reference:
 720 @rinternals{RelativeOctaveCheck}.
 721
 722
 723 @node Transpose
 724 @unnumberedsubsubsec Transpose
 725
 726 @cindex transpose
 727 @cindex transposing
 728 @cindex transposition
 729 @cindex transposition of pitches
 730 @cindex transposition of notes
 731 @cindex pitches, transposition of
 732 @cindex notes, transposition of
 733
 734 @funindex \transpose
 735
 736 A music expression can be transposed with @code{\transpose}.  The
 737 syntax is
 738
 739 @example
 740 \transpose @var{frompitch} @var{topitch} @var{musicexpr}
 741 @end example
 742
 743 @noindent
 744 This means that @code{@var{musicexpr}} is transposed by the
 745 interval between the pitches @code{@var{frompitch}} and
 746 @code{@var{topitch}}: any note with pitch @code{@var{frompitch}}
 747 is changed to @code{@var{topitch}} and any other note is
 748 transposed by the same interval.  Both pitches are entered in
 749 absolute mode.
 750
 751 @warning{Music inside a @code{@bs{}transpose} block is absolute
 752 unless a @code{@bs{}relative} is included in the block.}
 753
 754 Consider a piece written in the key of D-major.  It can be
 755 transposed up to E-major; note that the key signature is
 756 automatically transposed as well.
 757
 758 @lilypond[verbatim,quote]
 759 \transpose d e {
 760   \relative {
 761     \key d \major
 762     d'4 fis a d
 763   }
 764 }
 765 @end lilypond
 766
 767 @cindex transposing instruments
 768 @cindex instruments, transposing
 769
 770 If a part written in C (normal @notation{concert pitch}) is to be
 771 played on the A clarinet (for which an A is notated as a C and
 772 thus sounds a minor third lower than notated), the appropriate
 773 part will be produced with:
 774
 775 @lilypond[verbatim,quote]
 776 \transpose a c' {
 777   \relative {
 778     \key c \major
 779     c'4 d e g
 780   }
 781 }
 782 @end lilypond
 783
 784 @noindent
 785 Note that we specify @w{@code{\key c \major}} explicitly.  If we
 786 do not specify a key signature, the notes will be transposed but
 787 no key signature will be printed.
 788
 789 @code{\transpose} distinguishes between enharmonic pitches: both
 790 @w{@code{\transpose c cis}} or @w{@code{\transpose c des}} will
 791 transpose up a semitone.  The first version will print sharps and
 792 the notes will remain on the same scale step, the second version
 793 will print flats on the scale step above.
 794
 795 @lilypond[verbatim,quote]
 796 music = \relative { c' d e f }
 797 \new Staff {
 798   \transpose c cis { \music }
 799   \transpose c des { \music }
 800 }
 801 @end lilypond
 802
 803
 804 @code{\transpose} may also be used in a different way, to input
 805 written notes for a transposing instrument.  The previous examples
 806 show how to enter pitches in C (or @notation{concert pitch}) and
 807 typeset them for a transposing instrument, but the opposite is
 808 also possible if you for example have a set of instrumental parts
 809 and want to print a conductor's score.  For example, when entering
 810 music for a B-flat trumpet that begins on a notated E (concert D),
 811 one would write:
 812
 813 @example
 814 musicInBflat = @{ e4 @dots{} @}
 815 \transpose c bes, \musicInBflat
 816 @end example
 817
 818 @noindent
 819 To print this music in F (e.g., rearranging to a French horn) you
 820 could wrap the existing music with another @code{\transpose}:
 821
 822 @example
 823 musicInBflat = @{ e4 @dots{} @}
 824 \transpose f c' @{ \transpose c bes, \musicInBflat @}
 825 @end example
 826
 827 @noindent
 828 For more information about transposing instruments,
 829 see @ref{Instrument transpositions}.
 830
 831
 832 @snippets
 833
 834 @lilypondfile[verbatim,quote,texidoc,doctitle]
 835 {transposing-pitches-with-minimum-accidentals-smart-transpose.ly}
 836
 837 @seealso
 838 Notation Reference:
 839 @ref{Instrument transpositions},
 840 @ref{Inversion},
 841 @ref{Modal transformations},
 842 @ref{Relative octave entry},
 843 @ref{Retrograde}.
 844
 845 Snippets:
 846 @rlsr{Pitches}.
 847
 848 Internals Reference:
 849 @rinternals{TransposedMusic}.
 850
 851 @funindex \transpose
 852 @funindex \chordmode
 853 @funindex \relative
 854
 855 @knownissues
 856 The relative conversion will not affect @code{\transpose},
 857 @code{\chordmode} or @code{\relative} sections in its argument.  To use
 858 relative mode within transposed music, an additional @code{\relative}
 859 must be placed inside @code{\transpose}.
 860
 861 Triple accidentals will not be printed if using @code{\transpose}. An
 862 @q{enharmonically equivalent} pitch will be used instead (e.g., d-flat
 863 rather than e-triple-flat).
 864
 865
 866 @node Inversion
 867 @unnumberedsubsubsec Inversion
 868
 869 @cindex inversion
 870 @cindex operation, inversion
 871 @funindex \inversion
 872
 873 A music expression can be inverted and transposed in a single
 874 operation with:
 875
 876 @example
 877 \inversion @var{around-pitch} @var{to-pitch} @var{musicexpr}
 878 @end example
 879
 880 The @code{@var{musicexpr}} is inverted interval-by-interval around
 881 @code{@var{around-pitch}}, and then transposed so that
 882 @code{@var{around-pitch}} is mapped to @code{@var{to-pitch}}.
 883
 884 @lilypond[verbatim,quote]
 885 music = \relative { c' d e f }
 886 \new Staff {
 887   \music
 888   \inversion d' d' \music
 889   \inversion d' ees' \music
 890 }
 891 @end lilypond
 892
 893 @warning{Motifs to be inverted should be expressed in absolute form
 894 or be first converted to absolute form by enclosing them in a
 895 @code{\relative} block.}
 896
 897 @seealso
 898 Notation Reference:
 899 @ref{Modal transformations},
 900 @ref{Retrograde},
 901 @ref{Transpose}.
 902
 903
 904 @node Retrograde
 905 @unnumberedsubsubsec Retrograde
 906
 907 @cindex retrograde transformation
 908 @cindex transformation, retrograde
 909 @cindex operation, retrograde
 910 @funindex \retrograde
 911
 912 A music expression can be reversed to produce its retrograde:
 913
 914 @lilypond[verbatim,quote]
 915 music = \relative { c'8. ees16( fis8. a16 b8.) gis16 f8. d16 }
 916
 917 \new Staff {
 918   \music
 919   \retrograde \music
 920 }
 921 @end lilypond
 922
 923 @knownissues
 924 @code{\retrograde} is a rather simple tool.  Since many events are
 925 @q{mirrored} rather than exchanged, tweaks and directional
 926 modifiers for opening spanners need to be added at the matching
 927 closing spanners: @code{^(} needs to be ended by @code{^)}, every
 928 @code{\<} or @code{\cresc} needs to be ended by @code{\!} or
 929 @code{\endcr}, every @code{\>} or @code{\decr} needs to be ended
 930 by @code{\enddecr}.  Property-changing commands/overrides with a
 931 lasting effect will likely cause surprises.
 932
 933 @seealso
 934 Notation Reference:
 935 @ref{Inversion},
 936 @ref{Modal transformations},
 937 @ref{Transpose}.
 938
 939
 940 @node Modal transformations
 941 @unnumberedsubsubsec Modal transformations
 942
 943 @cindex modal transformations
 944 @cindex transformations, modal
 945 @cindex operations, modal
 946
 947 In a musical composition that is based on a scale, a motif is
 948 frequently transformed in various ways.  It may be
 949 @notation{transposed} to start at different places in the scale or
 950 it may be @notation{inverted} around a pivot point in the scale.
 951 It may also be reversed to produce its @notation{retrograde}, see
 952 @ref{Retrograde}.
 953
 954 @warning{Any note that does not lie within the given scale will be
 955 left untransformed.}
 956
 957 @subsubsubheading Modal transposition
 958
 959 @cindex modal transposition
 960 @cindex transposition, modal
 961 @cindex operation, transposition
 962 @funindex \modalTranspose
 963
 964 A motif can be transposed within a given scale with:
 965
 966 @example
 967 \modalTranspose @var{from-pitch} @var{to-pitch} @var{scale} @var{motif}
 968 @end example
 969
 970 The notes of @var{motif} are shifted within the @var{scale} by the
 971 number of scale degrees given by the interval between @var{to-pitch}
 972 and @var{from-pitch}:
 973
 974 @lilypond[verbatim,quote]
 975 diatonicScale = \relative { c' d e f g a b }
 976 motif = \relative { c'8 d e f g a b c }
 977
 978 \new Staff {
 979   \motif
 980   \modalTranspose c f \diatonicScale \motif
 981   \modalTranspose c b, \diatonicScale \motif
 982 }
 983 @end lilypond
 984
 985 An ascending scale of any length and with any intervals may be
 986 specified:
 987
 988 @lilypond[verbatim,quote]
 989 pentatonicScale = \relative { ges aes bes des ees }
 990 motif = \relative { ees'8 des ges,4 <ges' bes,> <ges bes,> }
 991
 992 \new Staff {
 993   \motif
 994   \modalTranspose ges ees' \pentatonicScale \motif
 995 }
 996 @end lilypond
 997
 998 When used with a chromatic scale @code{\modalTranspose} has a
 999 similar effect to @code{\transpose}, but with the ability to
1000 specify the names of the notes to be used:
1001
1002 @lilypond[verbatim,quote]
1003 chromaticScale = \relative { c' cis d dis e f fis g gis a ais b }
1004 motif = \relative { c'8 d e f g a b c }
1005
1006 \new Staff {
1007   \motif
1008   \transpose c f \motif
1009   \modalTranspose c f \chromaticScale \motif
1010 }
1011 @end lilypond
1012
1013 @subsubsubheading Modal inversion
1014
1015 @cindex modal inversion
1016 @cindex inversion, modal
1017 @cindex operation, modal inversion
1018 @funindex \modalInversion
1019
1020 A motif can be inverted within a given scale around a given pivot
1021 note and transposed in a single operation with:
1022
1023 @example
1024 \modalInversion @var{around-pitch} @var{to-pitch} @var{scale} @var{motif}
1025 @end example
1026
1027 The notes of @var{motif} are placed the same number of scale degrees
1028 from the @var{around-pitch} note within the @var{scale}, but in the
1029 opposite direction, and the result is then shifted within the
1030 @var{scale} by the number of scale degrees given by the interval between
1031 @var{to-pitch} and @var{around-pitch}.
1032
1033 So to simply invert around a note in the scale use the same value for
1034 @var{around-pitch} and @var{to-pitch}:
1035
1036 @lilypond[verbatim,quote]
1037 octatonicScale = \relative { ees' f fis gis a b c d }
1038 motif = \relative { c'8. ees16 fis8. a16 b8. gis16 f8. d16 }
1039
1040 \new Staff {
1041   \motif
1042   \modalInversion fis' fis' \octatonicScale \motif
1043 }
1044 @end lilypond
1045
1046 To invert around a pivot between two notes in the scale, invert around
1047 one of the notes and then transpose by one scale degree.  The two notes
1048 specified can be interpreted as bracketing the pivot point:
1049
1050 @lilypond[verbatim,quote]
1051 scale = \relative { c' g' }
1052 motive = \relative { c' c g' c, }
1053
1054 \new Staff {
1055   \motive
1056   \modalInversion c' g' \scale \motive
1057 }
1058 @end lilypond
1059
1060 The combined operation of inversion and retrograde produce the
1061 retrograde-inversion:
1062
1063 @lilypond[verbatim,quote]
1064 octatonicScale = \relative { ees' f fis gis a b c d }
1065 motif = \relative { c'8. ees16 fis8. a16 b8. gis16 f8. d16 }
1066
1067 \new Staff {
1068   \motif
1069   \retrograde \modalInversion c' c' \octatonicScale \motif
1070 }
1071 @end lilypond
1072
1073 @seealso
1074 Notation Reference:
1075 @ref{Inversion},
1076 @ref{Retrograde},
1077 @ref{Transpose}.
1078
1079
1080 @node Displaying pitches
1081 @subsection Displaying pitches
1082
1083 This section discusses how to alter the output of pitches.
1084
1085 @menu
1086 * Clef::
1087 * Key signature::
1088 * Ottava brackets::
1089 * Instrument transpositions::
1090 * Automatic accidentals::
1091 * Ambitus::
1092 @end menu
1093
1094
1095 @node Clef
1096 @unnumberedsubsubsec Clef
1097
1098 @cindex G clef
1099 @cindex C clef
1100 @cindex F clef
1101 @cindex treble clef
1102 @cindex violin clef
1103 @cindex alto clef
1104 @cindex tenor clef
1105 @cindex bass clef
1106 @cindex french clef
1107 @cindex soprano clef
1108 @cindex mezzosoprano clef
1109 @cindex baritone clef
1110 @cindex varbaritone clef
1111 @cindex subbass clef
1112 @cindex clef
1113 @cindex ancient clef
1114 @cindex clef, ancient
1115 @cindex clef, G
1116 @cindex clef, C
1117 @cindex clef, F
1118 @cindex clef, treble
1119 @cindex clef, violin
1120 @cindex clef, alto
1121 @cindex clef, tenor
1122 @cindex clef, bass
1123 @cindex clef, french
1124 @cindex clef, soprano
1125 @cindex clef, mezzosoprano
1126 @cindex clef, baritone
1127 @cindex clef, varbaritone
1128 @cindex clef, subbass
1129
1130
1131 @funindex \clef
1132
1133 Without any explicit command, the default clef for LilyPond is the
1134 treble (or @emph{G}) clef.
1135
1136 @lilypond[verbatim,quote,fragment,ragged-right]
1137 c'2 c'
1138 @end lilypond
1139
1140 However, the clef can be changed by using the @code{\clef} command and
1141 an appropriate clef name.  @emph{Middle C} is shown in each of the
1142 following examples.
1143
1144 @lilypond[verbatim,quote,fragment]
1145 \clef treble
1146 c'2 c'
1147 \clef alto
1148 c'2 c'
1149 \clef tenor
1150 c'2 c'
1151 \clef bass
1152 c'2 c'
1153 @end lilypond
1154
1155 For the full range of possible clef names see @ref{Clef styles}.
1156
1157 Specialized clefs, such as those used in @emph{Ancient} music, are
1158 described in @ref{Mensural clefs} and @ref{Gregorian clefs}.  Music that
1159 requires tablature clefs is discussed in @ref{Default tablatures} and
1160 @ref{Custom tablatures}.
1161
1162 @cindex Cue clefs
1163 @cindex Clefs with cue notes
1164 For mixing clefs when using cue notes, see the @code{\cueClef} and
1165 @code{\cueDuringWithClef} commands in @ref{Formatting cue notes}.
1166
1167 @cindex transposing clef
1168 @cindex clef, transposing
1169 @cindex octave transposition
1170 @cindex optional octave transposition
1171 @cindex octave transposition, optional
1172 @cindex choral tenor clef
1173 @cindex tenor clef, choral
1174
1175 By adding@tie{}@code{_8} or@tie{}@code{^8} to the clef name, the
1176 clef is transposed one octave down or up respectively,
1177 and@tie{}@code{_15} and@tie{}@code{^15} transpose by two octaves.
1178 Other integers can be used if required.  Clef names containing
1179 non-alphabetic characters must be enclosed in quotes
1180
1181 @lilypond[verbatim,quote,fragment]
1182 \clef treble
1183 c'2 c'
1184 \clef "treble_8"
1185 c'2 c'
1186 \clef "bass^15"
1187 c'2 c'
1188 \clef "alto_2"
1189 c'2 c'
1190 \clef "G_8"
1191 c'2 c'
1192 \clef "F^5"
1193 c'2 c'
1194 @end lilypond
1195
1196 Optional octavation can be obtained by enclosing the numeric
1197 argument in parentheses or brackets:
1198
1199 @lilypond[verbatim,quote,fragment]
1200 \clef "treble_(8)"
1201 c'2 c'
1202 \clef "bass^[15]"
1203 c'2 c'
1204 @end lilypond
1205
1206 The pitches are displayed as if the numeric argument were
1207 given without parentheses/brackets.
1208
1209 By default, a clef change taking place at a line break will cause
1210 the new clef symbol to be printed at the end of the previous line,
1211 as a @emph{warning} clef, as well as the beginning of the next.
1212 This @emph{warning} clef can be suppressed.
1213
1214 @lilypond[verbatim,quote,fragment]
1215 \clef treble { c'2 c' } \break
1216 \clef bass { c'2 c' } \break
1217 \clef alto
1218   \set Staff.explicitClefVisibility = #end-of-line-invisible
1219   { c'2 c' } \break
1220   \unset Staff.explicitClefVisibility
1221 \clef bass { c'2 c' } \break
1222 @end lilypond
1223
1224 By default, a clef that has previously been printed will not be
1225 re-printed if the same @code{\clef} command is issued again and
1226 will be ignored.  The command
1227 @code{\set Staff.forceClef = ##t} changes this behaviour.
1228
1229 @lilypond[verbatim,quote,fragment]
1230   \clef treble
1231   c'1
1232   \clef treble
1233   c'1
1234   \set Staff.forceClef = ##t
1235   c'1
1236   \clef treble
1237   c'1
1238 @end lilypond
1239
1240 @noindent
1241 To be more precise, it is not the @code{\clef} command itself that
1242 prints a clef.  Instead, it sets or changes a property of the
1243 @code{Clef_engraver}, which then decides by its own whether to
1244 display a clef or not in the current staff.  The @code{forceClef}
1245 property overrides this decision locally to re-print a clef once.
1246
1247 When there is a manual clef change, the glyph of the changed clef
1248 will be smaller than normal.  This behaviour can be overridden.
1249
1250 @lilypond[verbatim,quote,fragment]
1251   \clef "treble"
1252   c'1
1253   \clef "bass"
1254   c'1
1255   \clef "treble"
1256   c'1
1257   \override Staff.Clef.full-size-change = ##t
1258   \clef "bass"
1259   c'1
1260   \clef "treble"
1261   c'1
1262   \revert Staff.Clef.full-size-change
1263   \clef "bass"
1264   c'1
1265   \clef "treble"
1266   c'1
1267 @end lilypond
1268
1269 @snippets
1270 @lilypondfile[verbatim,quote,texidoc,doctitle]
1271 {tweaking-clef-properties.ly}
1272
1273 @seealso
1274 Notation Reference:
1275 @ref{Mensural clefs},
1276 @ref{Gregorian clefs},
1277 @ref{Default tablatures},
1278 @ref{Custom tablatures},
1279 @ref{Formatting cue notes}.
1280
1281 Installed Files:
1282 @file{scm/parser-clef.scm}.
1283
1284 Snippets:
1285 @rlsr{Pitches}.
1286
1287 Internals Reference:
1288 @rinternals{Clef_engraver},
1289 @rinternals{Clef},
1290 @rinternals{ClefModifier},
1291 @rinternals{clef-interface}.
1292
1293 @knownissues
1294 Ottavation numbers attached to clefs are treated as separate
1295 grobs.  So any @code{\override} done to the @var{Clef} will also
1296 need to be applied, as a separate @code{\override}, to the
1297 @var{ClefModifier} grob.
1298
1299 @lilypond[fragment,quote,verbatim]
1300 \new Staff \with {
1301   \override Clef.color = #blue
1302   \override ClefModifier.color = #red
1303 }
1304
1305 \clef "treble_8" c'4
1306 @end lilypond
1307
1308
1309 @node Key signature
1310 @unnumberedsubsubsec Key signature
1311
1312 @cindex key signature
1313
1314 @funindex \key
1315
1316 @c duplicated in Key signature and Accidentals
1317 @warning{New users are sometimes confused about accidentals and
1318 key signatures.  In LilyPond, note names are the raw input; key
1319 signatures and clefs determine how this raw input is displayed.
1320 An unaltered note like@tie{}@code{c} means @q{C natural},
1321 regardless of the key signature or clef.  For more information,
1322 see @rlearning{Pitches and key signatures}.}
1323
1324 The key signature indicates the tonality in which a piece is
1325 played.  It is denoted by a set of alterations (flats or sharps)
1326 at the start of the staff.  The key signature may be altered:
1327
1328 @example
1329 \key @var{pitch} @var{mode}
1330 @end example
1331
1332 @funindex \major
1333 @funindex \minor
1334 @funindex \ionian
1335 @funindex \locrian
1336 @funindex \aeolian
1337 @funindex \mixolydian
1338 @funindex \lydian
1339 @funindex \phrygian
1340 @funindex \dorian
1341
1342 @cindex church modes
1343 @cindex modes
1344 @cindex major
1345 @cindex minor
1346 @cindex ionian
1347 @cindex locrian
1348 @cindex aeolian
1349 @cindex mixolydian
1350 @cindex lydian
1351 @cindex phrygian
1352 @cindex dorian
1353
1354 @noindent
1355 Here, @code{@var{mode}} should be @code{\major} or @code{\minor}
1356 to get a key signature of @code{@var{pitch}}-major or
1357 @code{@var{pitch}}-minor, respectively.  You may also use the
1358 standard mode names, also called @notation{church modes}:
1359 @code{\ionian}, @code{\dorian}, @code{\phrygian}, @code{\lydian},
1360 @code{\mixolydian}, @code{\aeolian}, and @code{\locrian}.
1361
1362 @lilypond[verbatim,quote,fragment]
1363 \relative {
1364   \key g \major
1365   fis''1
1366   f
1367   fis
1368 }
1369 @end lilypond
1370
1371 Additional modes can be defined, by listing the alterations
1372 for each scale step when the mode starts on C.
1373
1374 @lilypond[verbatim,quote]
1375 freygish = #`((0 . ,NATURAL) (1 . ,FLAT) (2 . ,NATURAL)
1376     (3 . ,NATURAL) (4 . ,NATURAL) (5 . ,FLAT) (6 . ,FLAT))
1377
1378 \relative {
1379   \key c \freygish c'4 des e f
1380   \bar "||" \key d \freygish d es fis g
1381 }
1382 @end lilypond
1383
1384 Accidentals in the key signature may be printed in octaves other
1385 than their traditional positions, or in multiple octaves, by
1386 using the @code{flat-positions} and @code{sharp-positions}
1387 properties of @code{KeySignature}.  Entries in these properties
1388 specify the range of staff-positions where accidentals will be
1389 printed.  If a single position is specified in an entry, the
1390 accidentals are placed within the octave ending at that staff
1391 position.
1392
1393 @lilypond[verbatim, quote,fragment]
1394 \override Staff.KeySignature.flat-positions = #'((-5 . 5))
1395 \override Staff.KeyCancellation.flat-positions = #'((-5 . 5))
1396 \clef bass \key es \major es g bes d'
1397 \clef treble \bar "||" \key es \major es' g' bes' d''
1398
1399 \override Staff.KeySignature.sharp-positions = #'(2)
1400 \bar "||" \key b \major b' fis' b'2
1401 @end lilypond
1402
1403 @snippets
1404
1405 @lilypondfile[verbatim,quote,texidoc,doctitle]
1406 {preventing-natural-signs-from-being-printed-when-the-key-signature-changes.ly}
1407
1408 @lilypondfile[verbatim,quote,texidoc,doctitle]
1409 {non-traditional-key-signatures.ly}
1410
1411
1412 @seealso
1413 Music Glossary:
1414 @rglos{church mode},
1415 @rglos{scordatura}.
1416
1417 Learning Manual:
1418 @rlearning{Pitches and key signatures}.
1419
1420 Snippets:
1421 @rlsr{Pitches}.
1422
1423 Internals Reference:
1424 @rinternals{KeyChangeEvent},
1425 @rinternals{Key_engraver},
1426 @rinternals{Key_performer},
1427 @rinternals{KeyCancellation},
1428 @rinternals{KeySignature},
1429 @rinternals{key-signature-interface}.
1430
1431
1432 @node Ottava brackets
1433 @unnumberedsubsubsec Ottava brackets
1434
1435 @cindex ottava
1436 @cindex 15ma
1437 @cindex 8va
1438 @cindex 8ve
1439 @cindex octavation
1440
1441 @funindex set-octavation
1442 @funindex \ottava
1443
1444 @notation{Ottava brackets} introduce an extra transposition of an
1445 octave for the staff:
1446
1447 @lilypond[verbatim,quote]
1448 \relative a' {
1449   a2 b
1450   \ottava #-2
1451   a2 b
1452   \ottava #-1
1453   a2 b
1454   \ottava #0
1455   a2 b
1456   \ottava #1
1457   a2 b
1458   \ottava #2
1459   a2 b
1460 }
1461 @end lilypond
1462
1463 @snippets
1464
1465 @lilypondfile[verbatim,quote,texidoc,doctitle]
1466 {ottava-text.ly}
1467
1468 @lilypondfile[verbatim,quote,texidoc,doctitle]
1469 {adding-an-ottava-marking-to-a-single-voice.ly}
1470
1471 @lilypondfile[verbatim,quote,texidoc,doctitle]
1472 {modifying-the-ottava-spanner-slope.ly}
1473
1474 @seealso
1475 Music Glossary:
1476 @rglos{octavation}.
1477
1478 Snippets:
1479 @rlsr{Pitches}.
1480
1481 Internals Reference:
1482 @rinternals{Ottava_spanner_engraver},
1483 @rinternals{OttavaBracket},
1484 @rinternals{ottava-bracket-interface}.
1485
1486
1487 @node Instrument transpositions
1488 @unnumberedsubsubsec Instrument transpositions
1489
1490 @cindex transposition, MIDI
1491 @cindex transposition, instrument
1492 @cindex transposing instrument
1493 @cindex MIDI
1494 @cindex MIDI transposition
1495
1496 @funindex \transposition
1497
1498 When typesetting scores that involve transposing instruments, some
1499 parts can be typeset in a different pitch than the
1500 @notation{concert pitch}.  In these cases, the key of the
1501 @notation{transposing instrument} should be specified; otherwise
1502 the MIDI output and cues in other parts will produce incorrect
1503 pitches.  For more information about quotations, see
1504 @ref{Quoting other voices}.
1505
1506 @example
1507 \transposition @var{pitch}
1508 @end example
1509
1510 The pitch to use for @code{\transposition} should correspond to
1511 the real sound heard when a@tie{}@code{c'} written on the staff is
1512 played by the transposing instrument.  This pitch is entered in
1513 absolute mode, so an instrument that produces a real sound which
1514 is one tone higher than the printed music should use
1515 @w{@code{\transposition d'}}.  @code{\transposition} should
1516 @emph{only} be used if the pitches are @emph{not} being entered in
1517 concert pitch.
1518
1519 Here are a few notes for violin and B-flat clarinet where the
1520 parts have been entered using the notes and key as they appear in
1521 each part of the conductor's score.  The two instruments are
1522 playing in unison.
1523
1524 @lilypond[verbatim,quote]
1525 \new GrandStaff <<
1526   \new Staff = "violin" {
1527     \relative c'' {
1528       \set Staff.instrumentName = #"Vln"
1529       \set Staff.midiInstrument = #"violin"
1530       % not strictly necessary, but a good reminder
1531       \transposition c'
1532
1533       \key c \major
1534       g4( c8) r c r c4
1535     }
1536   }
1537   \new Staff = "clarinet" {
1538     \relative c'' {
1539       \set Staff.instrumentName = \markup { Cl (B\flat) }
1540       \set Staff.midiInstrument = #"clarinet"
1541       \transposition bes
1542
1543       \key d \major
1544       a4( d8) r d r d4
1545     }
1546   }
1547 >>
1548 @end lilypond
1549
1550 The @code{\transposition} may be changed during a piece.  For
1551 example, a clarinetist may be required to switch from an A clarinet
1552 to a B-flat clarinet.
1553
1554 @lilypond[verbatim,quote]
1555 flute = \relative c'' {
1556   \key f \major
1557   \cueDuring #"clarinet" #DOWN {
1558     R1 _\markup\tiny "clarinet"
1559     c4 f e d
1560     R1 _\markup\tiny "clarinet"
1561   }
1562 }
1563 clarinet = \relative c'' {
1564   \key aes \major
1565   \transposition a
1566   aes4 bes c des
1567   R1^\markup { muta in B\flat }
1568   \key g \major
1569   \transposition bes
1570   d2 g,
1571 }
1572 \addQuote "clarinet" \clarinet
1573 <<
1574   \new Staff \with { instrumentName = #"Flute" }
1575     \flute
1576   \new Staff \with { instrumentName = #"Cl (A)" }
1577     \clarinet
1578 >>
1579 @end lilypond
1580
1581 @seealso
1582 Music Glossary:
1583 @rglos{concert pitch},
1584 @rglos{transposing instrument}.
1585
1586 Notation Reference:
1587 @ref{Quoting other voices},
1588 @ref{Transpose}.
1589
1590 Snippets:
1591 @rlsr{Pitches}.
1592
1593
1594 @node Automatic accidentals
1595 @unnumberedsubsubsec Automatic accidentals
1596
1597 @cindex accidental style
1598 @cindex accidental style, default
1599 @cindex accidentals
1600 @cindex accidentals, automatic
1601 @cindex automatic accidentals
1602 @cindex default accidental style
1603
1604 @funindex \accidentalStyle
1605 @funindex voice
1606 @funindex default
1607
1608 There are many different conventions on how to typeset
1609 accidentals.  LilyPond provides a function to specify which
1610 accidental style to use.  This function is called as follows:
1611
1612 @example
1613 \new Staff <<
1614   \accidentalStyle voice
1615   @{ @dots{} @}
1616 >>
1617 @end example
1618
1619 The accidental style applies to the current @code{Staff} by
1620 default (with the exception of the styles @code{piano} and
1621 @code{piano-cautionary}, which are explained below).  Optionally,
1622 the function can take a second argument that determines in which
1623 scope the style should be changed.  For example, to use the same
1624 style in all staves of the current @code{StaffGroup}, use:
1625
1626 @example
1627 \accidentalStyle StaffGroup.voice
1628 @end example
1629
1630 The following accidental styles are supported.  To demonstrate
1631 each style, we use the following example:
1632
1633
1634 @lilypond[verbatim,quote]
1635 musicA = {
1636   <<
1637     \relative {
1638       cis''8 fis, bes4 <a cis>8 f bis4 |
1639       cis2. <c, g'>4 |
1640     }
1641     \\
1642     \relative {
1643       ais'2 cis, |
1644       fis8 b a4 cis2 |
1645     }
1646   >>
1647 }
1648
1649 musicB = {
1650   \clef bass
1651   \new Voice {
1652     \voiceTwo \relative {
1653       <fis a cis>8[ <fis a cis>
1654       \change Staff = up
1655       cis' cis
1656       \change Staff = down
1657       <fis, a> <fis a>]
1658       \showStaffSwitch
1659       \change Staff = up
1660       dis'4 |
1661       \change Staff = down
1662       <fis, a cis>4 gis <f a d>2 |
1663     }
1664   }
1665 }
1666
1667 \new PianoStaff {
1668   <<
1669     \context Staff = "up" {
1670       \accidentalStyle default
1671       \musicA
1672     }
1673     \context Staff = "down" {
1674       \accidentalStyle default
1675       \musicB
1676     }
1677   >>
1678 }
1679 @end lilypond
1680
1681 Note that the last lines of this example can be replaced by the
1682 following, as long as the same accidental style should be used in
1683 both staves.
1684
1685 @example
1686 \new PianoStaff @{
1687   <<
1688     \context Staff = "up" @{
1689       %%% change the next line as desired:
1690       \accidentalStyle Score.default
1691       \musicA
1692     @}
1693     \context Staff = "down" @{
1694       \musicB
1695     @}
1696   >>
1697 @}
1698 @end example
1699
1700
1701 @c don't use verbatim in this table.
1702 @table @code
1703 @item default
1704
1705 @cindex default accidental style
1706 @cindex accidental style, default
1707
1708 @funindex default
1709
1710 This is the default typesetting behavior.  It corresponds to
1711 eighteenth-century common practice: accidentals are remembered to
1712 the end of the measure in which they occur and only in their own
1713 octave.  Thus, in the example below, no natural signs are printed
1714 before the@tie{}@code{b} in the second measure or the
1715 last@tie{}@code{c}:
1716
1717 @lilypond[quote]
1718 musicA = {
1719   <<
1720     \relative {
1721       cis''8 fis, bes4 <a cis>8 f bis4 |
1722       cis2. <c, g'>4 |
1723     }
1724     \\
1725     \relative {
1726       ais'2 cis, |
1727       fis8 b a4 cis2 |
1728     }
1729   >>
1730 }
1731
1732 musicB = {
1733   \clef bass
1734   \new Voice {
1735     \voiceTwo \relative {
1736       <fis a cis>8[ <fis a cis>
1737       \change Staff = up
1738       cis' cis
1739       \change Staff = down
1740       <fis, a> <fis a>]
1741       \showStaffSwitch
1742       \change Staff = up
1743       dis'4 |
1744       \change Staff = down
1745       <fis, a cis>4 gis <f a d>2 |
1746     }
1747   }
1748 }
1749
1750 \new PianoStaff {
1751   <<
1752     \context Staff = "up" {
1753       \accidentalStyle default
1754       \musicA
1755     }
1756     \context Staff = "down" {
1757       \accidentalStyle default
1758       \musicB
1759     }
1760   >>
1761 }
1762 @end lilypond
1763
1764 @item voice
1765
1766 @cindex accidental style, voice
1767 @cindex voice accidental style
1768 @cindex accidental style, modern
1769 @cindex modern accidental style
1770 @cindex accidental style, modern-cautionary
1771 @cindex modern-cautionary accidental style
1772
1773 @funindex voice
1774
1775 The normal behavior is to remember the accidentals at
1776 @code{Staff}-level.  In this style, however, accidentals are
1777 typeset individually for each voice.  Apart from that, the rule is
1778 similar to @code{default}.
1779
1780 As a result, accidentals from one voice do not get canceled in
1781 other voices, which is often an unwanted result: in the following
1782 example, it is hard to determine whether the second@tie{}@code{a}
1783 should be played natural or sharp.  The @code{voice} option should
1784 therefore be used only if the voices are to be read solely by
1785 individual musicians.  If the staff is to be used by one musician
1786 (e.g., a conductor or in a piano score) then @code{modern} or
1787 @code{modern-cautionary} should be used instead.
1788
1789
1790 @lilypond[quote]
1791 musicA = {
1792   <<
1793     \relative {
1794       cis''8 fis, bes4 <a cis>8 f bis4 |
1795       cis2. <c, g'>4 |
1796     }
1797     \\
1798     \relative {
1799       ais'2 cis, |
1800       fis8 b a4 cis2 |
1801     }
1802   >>
1803 }
1804
1805 musicB = {
1806   \clef bass
1807   \new Voice {
1808     \voiceTwo \relative {
1809       <fis a cis>8[ <fis a cis>
1810       \change Staff = up
1811       cis' cis
1812       \change Staff = down
1813       <fis, a> <fis a>]
1814       \showStaffSwitch
1815       \change Staff = up
1816       dis'4 |
1817       \change Staff = down
1818       <fis, a cis>4 gis <f a d>2 |
1819     }
1820   }
1821 }
1822
1823 \new PianoStaff {
1824   <<
1825     \context Staff = "up" {
1826       \accidentalStyle voice
1827       \musicA
1828     }
1829     \context Staff = "down" {
1830       \accidentalStyle voice
1831       \musicB
1832     }
1833   >>
1834 }
1835 @end lilypond
1836
1837 @item modern
1838
1839 @cindex accidentals, modern style
1840 @cindex modern style accidentals
1841
1842 @funindex modern
1843
1844 This rule corresponds to the common practice in the twentieth
1845 century.  It omits some extra natural signs, which were
1846 traditionally prefixed to a sharp following a double sharp,
1847 or a flat following a double flat.  The @code{modern} rule
1848 prints the same accidentals as @code{default}, with
1849 two additions that serve to avoid ambiguity: after temporary
1850 accidentals, cancellation marks are printed also in the following
1851 measure (for notes in the same octave) and, in the same measure,
1852 for notes in other octaves.  Hence the naturals before
1853 the@tie{}@code{b} and the@tie{}@code{c} in the second measure of
1854 the upper staff:
1855
1856 @lilypond[quote]
1857 musicA = {
1858   <<
1859     \relative {
1860       cis''8 fis, bes4 <a cis>8 f bis4 |
1861       cis2. <c, g'>4 |
1862     }
1863     \\
1864     \relative {
1865       ais'2 cis, |
1866       fis8 b a4 cis2 |
1867     }
1868   >>
1869 }
1870
1871 musicB = {
1872   \clef bass
1873   \new Voice {
1874     \voiceTwo \relative {
1875       <fis a cis>8[ <fis a cis>
1876       \change Staff = up
1877       cis' cis
1878       \change Staff = down
1879       <fis, a> <fis a>]
1880       \showStaffSwitch
1881       \change Staff = up
1882       dis'4 |
1883       \change Staff = down
1884       <fis, a cis>4 gis <f a d>2 |
1885     }
1886   }
1887 }
1888
1889 \new PianoStaff {
1890   <<
1891     \context Staff = "up" {
1892       \accidentalStyle modern
1893       \musicA
1894     }
1895     \context Staff = "down" {
1896       \accidentalStyle modern
1897       \musicB
1898     }
1899   >>
1900 }
1901 @end lilypond
1902
1903 @item modern-cautionary
1904
1905 @cindex accidentals, modern cautionary style
1906 @cindex modern accidental style
1907 @cindex modern cautionary accidental style
1908 @cindex modern style accidentals
1909 @cindex modern style cautionary accidentals
1910
1911 @funindex modern-cautionary
1912
1913 This rule is similar to @code{modern}, but the @q{extra} accidentals
1914 are printed as cautionary accidentals (with parentheses).  They can also
1915 be printed at a different size by overriding
1916 @code{AccidentalCautionary}'s @code{font-size} property.
1917
1918 @lilypond[quote]
1919 musicA = {
1920   <<
1921     \relative {
1922       cis''8 fis, bes4 <a cis>8 f bis4 |
1923       cis2. <c, g'>4 |
1924     }
1925     \\
1926     \relative {
1927       ais'2 cis, |
1928       fis8 b a4 cis2 |
1929     }
1930   >>
1931 }
1932
1933 musicB = {
1934   \clef bass
1935   \new Voice {
1936     \voiceTwo \relative {
1937       <fis a cis>8[ <fis a cis>
1938       \change Staff = up
1939       cis' cis
1940       \change Staff = down
1941       <fis, a> <fis a>]
1942       \showStaffSwitch
1943       \change Staff = up
1944       dis'4 |
1945       \change Staff = down
1946       <fis, a cis>4 gis <f a d>2 |
1947     }
1948   }
1949 }
1950
1951 \new PianoStaff {
1952   <<
1953     \context Staff = "up" {
1954       \accidentalStyle modern-cautionary
1955       \musicA
1956     }
1957     \context Staff = "down" {
1958       \accidentalStyle modern-cautionary
1959       \musicB
1960     }
1961   >>
1962 }
1963 @end lilypond
1964
1965 @item modern-voice
1966
1967 @cindex accidental style, modern
1968 @cindex accidentals, modern
1969 @cindex accidentals, multivoice
1970 @cindex modern accidental style
1971 @cindex modern accidentals
1972 @cindex multivoice accidentals
1973
1974 @funindex modern-voice
1975
1976 This rule is used for multivoice accidentals to be read both by
1977 musicians playing one voice and musicians playing all voices.
1978 Accidentals are typeset for each voice, but they @emph{are}
1979 canceled across voices in the same @code{Staff}.  Hence,
1980 the@tie{}@code{a} in the last measure is canceled because the
1981 previous cancellation was in a different voice, and
1982 the@tie{}@code{d} in the lower staff is canceled because of the
1983 accidental in a different voice in the previous measure:
1984
1985 @lilypond[quote]
1986 musicA = {
1987   <<
1988     \relative {
1989       cis''8 fis, bes4 <a cis>8 f bis4 |
1990       cis2. <c, g'>4 |
1991     }
1992     \\
1993     \relative {
1994       ais'2 cis, |
1995       fis8 b a4 cis2 |
1996     }
1997   >>
1998 }
1999
2000 musicB = {
2001   \clef bass
2002   \new Voice {
2003     \voiceTwo \relative {
2004       <fis a cis>8[ <fis a cis>
2005       \change Staff = up
2006       cis' cis
2007       \change Staff = down
2008       <fis, a> <fis a>]
2009       \showStaffSwitch
2010       \change Staff = up
2011       dis'4 |
2012       \change Staff = down
2013       <fis, a cis>4 gis <f a d>2 |
2014     }
2015   }
2016 }
2017
2018 \new PianoStaff {
2019   <<
2020     \context Staff = "up" {
2021       \accidentalStyle modern-voice
2022       \musicA
2023     }
2024     \context Staff = "down" {
2025       \accidentalStyle modern-voice
2026       \musicB
2027     }
2028   >>
2029 }
2030 @end lilypond
2031
2032 @cindex accidental style, cautionary, modern voice
2033 @cindex accidental style, modern voice cautionary
2034 @cindex accidental style, voice, modern cautionary
2035
2036 @funindex modern-voice-cautionary
2037
2038 @item modern-voice-cautionary
2039
2040 This rule is the same as @code{modern-voice}, but with the extra
2041 accidentals (the ones not typeset by @code{voice}) typeset as
2042 cautionaries.  Even though all accidentals typeset by
2043 @code{default} @emph{are} typeset with this rule, some of them are
2044 typeset as cautionaries.
2045
2046 @lilypond[quote]
2047 musicA = {
2048   <<
2049     \relative {
2050       cis''8 fis, bes4 <a cis>8 f bis4 |
2051       cis2. <c, g'>4 |
2052     }
2053     \\
2054     \relative {
2055       ais'2 cis, |
2056       fis8 b a4 cis2 |
2057     }
2058   >>
2059 }
2060
2061 musicB = {
2062   \clef bass
2063   \new Voice {
2064     \voiceTwo \relative {
2065       <fis a cis>8[ <fis a cis>
2066       \change Staff = up
2067       cis' cis
2068       \change Staff = down
2069       <fis, a> <fis a>]
2070       \showStaffSwitch
2071       \change Staff = up
2072       dis'4 |
2073       \change Staff = down
2074       <fis, a cis>4 gis <f a d>2 |
2075     }
2076   }
2077 }
2078
2079 \new PianoStaff {
2080   <<
2081     \context Staff = "up" {
2082       \accidentalStyle modern-voice-cautionary
2083       \musicA
2084     }
2085     \context Staff = "down" {
2086       \accidentalStyle modern-voice-cautionary
2087       \musicB
2088     }
2089   >>
2090 }
2091 @end lilypond
2092
2093 @item piano
2094
2095 @cindex accidental style, piano
2096 @cindex accidentals, piano
2097 @cindex piano accidental style
2098 @cindex piano accidentals
2099
2100 @funindex piano
2101
2102 This rule reflects twentieth-century practice for piano notation.
2103 Its behavior is very similar to @code{modern} style, but here
2104 accidentals also get canceled across the staves in the same
2105 @code{GrandStaff} or @code{PianoStaff}, hence all the
2106 cancellations of the final notes.
2107
2108 This accidental style applies to the current @code{GrandStaff} or
2109 @code{PianoStaff} by default.
2110
2111 @lilypond[quote]
2112 musicA = {
2113   <<
2114     \relative {
2115       cis''8 fis, bes4 <a cis>8 f bis4 |
2116       cis2. <c, g'>4 |
2117     }
2118     \\
2119     \relative {
2120       ais'2 cis, |
2121       fis8 b a4 cis2 |
2122     }
2123   >>
2124 }
2125
2126 musicB = {
2127   \clef bass
2128   \new Voice {
2129     \voiceTwo \relative {
2130       <fis a cis>8[ <fis a cis>
2131       \change Staff = up
2132       cis' cis
2133       \change Staff = down
2134       <fis, a> <fis a>]
2135       \showStaffSwitch
2136       \change Staff = up
2137       dis'4 |
2138       \change Staff = down
2139       <fis, a cis>4 gis <f a d>2 |
2140     }
2141   }
2142 }
2143
2144 \new PianoStaff {
2145   <<
2146     \context Staff = "up" {
2147       \accidentalStyle piano
2148       \musicA
2149     }
2150     \context Staff = "down" {
2151       \musicB
2152     }
2153   >>
2154 }
2155 @end lilypond
2156
2157 @item piano-cautionary
2158
2159 @cindex accidentals, piano cautionary
2160 @cindex cautionary accidentals, piano
2161 @cindex piano cautionary accidentals
2162 @cindex accidental style, piano cautionary
2163 @cindex cautionary accidental style, piano
2164 @cindex piano cautionary accidental style
2165
2166 @funindex piano-cautionary
2167
2168 This is the same as @code{piano} but with the extra accidentals
2169 typeset as cautionaries.
2170
2171 @lilypond[quote]
2172 musicA = {
2173   <<
2174     \relative {
2175       cis''8 fis, bes4 <a cis>8 f bis4 |
2176       cis2. <c, g'>4 |
2177     }
2178     \\
2179     \relative {
2180       ais'2 cis, |
2181       fis8 b a4 cis2 |
2182     }
2183   >>
2184 }
2185
2186 musicB = {
2187   \clef bass
2188   \new Voice {
2189     \voiceTwo \relative {
2190       <fis a cis>8[ <fis a cis>
2191       \change Staff = up
2192       cis' cis
2193       \change Staff = down
2194       <fis, a> <fis a>]
2195       \showStaffSwitch
2196       \change Staff = up
2197       dis'4 |
2198       \change Staff = down
2199       <fis, a cis>4 gis <f a d>2 |
2200     }
2201   }
2202 }
2203
2204 \new PianoStaff {
2205   <<
2206     \context Staff = "up" {
2207       \accidentalStyle piano-cautionary
2208       \musicA
2209     }
2210     \context Staff = "down" {
2211       \musicB
2212     }
2213   >>
2214 }
2215 @end lilypond
2216
2217
2218 @item choral
2219
2220 @cindex accidental style, choral
2221 @cindex accidentals, choral
2222 @cindex choral accidental style
2223 @cindex choral accidentals
2224
2225 @funindex choral
2226
2227 This rule is a combination of the @code{modern-voice} and the @code{piano}
2228 style. It shows all accidentals required for singers that only follow their
2229 own voice, as well as additional accidentals for readers that follow all
2230 voices of an entire @code{ChoirStaff} simultaneously.
2231
2232 This accidental style applies to the current @code{ChoirStaff} by default.
2233
2234 @lilypond[quote]
2235 musicA = {
2236   <<
2237     \relative {
2238       cis''8 fis, bes4 <a cis>8 f bis4 |
2239       cis2. <c, g'>4 |
2240     }
2241     \\
2242     \relative {
2243       ais'2 cis, |
2244       fis8 b a4 cis2 |
2245     }
2246   >>
2247 }
2248
2249 musicB = {
2250   \clef bass
2251   \new Voice {
2252     \voiceTwo \relative {
2253       <fis a cis>8[ <fis a cis>
2254       \change Staff = up
2255       cis' cis
2256       \change Staff = down
2257       <fis, a> <fis a>]
2258       \showStaffSwitch
2259       \change Staff = up
2260       dis'4 |
2261       \change Staff = down
2262       <fis, a cis>4 gis <f a d>2 |
2263     }
2264   }
2265 }
2266
2267 \new ChoirStaff {
2268   <<
2269     \context Staff = "up" {
2270       \accidentalStyle choral
2271       \musicA
2272     }
2273     \context Staff = "down" {
2274       \musicB
2275     }
2276   >>
2277 }
2278 @end lilypond
2279
2280 @item choral-cautionary
2281
2282 @cindex accidentals, choral cautionary
2283 @cindex cautionary accidentals, choral
2284 @cindex choral cautionary accidentals
2285 @cindex accidental style, choral cautionary
2286 @cindex cautionary accidental style, choral
2287 @cindex choral cautionary accidental style
2288
2289 @funindex choral-cautionary
2290
2291 This is the same as @code{choral} but with the extra accidentals
2292 typeset as cautionaries.
2293
2294 @lilypond[quote]
2295 musicA = {
2296   <<
2297     \relative {
2298       cis''8 fis, bes4 <a cis>8 f bis4 |
2299       cis2. <c, g'>4 |
2300     }
2301     \\
2302     \relative {
2303       ais'2 cis, |
2304       fis8 b a4 cis2 |
2305     }
2306   >>
2307 }
2308
2309 musicB = {
2310   \clef bass
2311   \new Voice {
2312     \voiceTwo \relative {
2313       <fis a cis>8[ <fis a cis>
2314       \change Staff = up
2315       cis' cis
2316       \change Staff = down
2317       <fis, a> <fis a>]
2318       \showStaffSwitch
2319       \change Staff = up
2320       dis'4 |
2321       \change Staff = down
2322       <fis, a cis>4 gis <f a d>2 |
2323     }
2324   }
2325 }
2326
2327 \new ChoirStaff {
2328   <<
2329     \context Staff = "up" {
2330       \accidentalStyle choral-cautionary
2331       \musicA
2332     }
2333     \context Staff = "down" {
2334       \musicB
2335     }
2336   >>
2337 }
2338 @end lilypond
2339
2340
2341 @item neo-modern
2342
2343 @cindex neo-modern accidental style
2344 @cindex accidental style, neo-modern
2345
2346 @funindex neo-modern
2347
2348 This rule reproduces a common practice in contemporary music:
2349 accidentals are printed like with @code{modern}, but they are printed
2350 again if the same note appears later in the same measure -- except
2351 if the note is immediately repeated.
2352
2353 @lilypond[quote]
2354 musicA = {
2355   <<
2356     \relative {
2357       cis''8 fis, bes4 <a cis>8 f bis4 |
2358       cis2. <c, g'>4 |
2359     }
2360     \\
2361     \relative {
2362       ais'2 cis, |
2363       fis8 b a4 cis2 |
2364     }
2365   >>
2366 }
2367
2368 musicB = {
2369   \clef bass
2370   \new Voice {
2371     \voiceTwo \relative {
2372       <fis a cis>8[ <fis a cis>
2373       \change Staff = up
2374       cis' cis
2375       \change Staff = down
2376       <fis, a> <fis a>]
2377       \showStaffSwitch
2378       \change Staff = up
2379       dis'4 |
2380       \change Staff = down
2381       <fis, a cis>4 gis <f a d>2 |
2382     }
2383   }
2384 }
2385
2386 \new PianoStaff {
2387   <<
2388     \context Staff = "up" {
2389       \accidentalStyle neo-modern
2390       \musicA
2391     }
2392     \context Staff = "down" {
2393       \accidentalStyle neo-modern
2394       \musicB
2395     }
2396   >>
2397 }
2398 @end lilypond
2399
2400 @item neo-modern-cautionary
2401
2402 @cindex neo-modern-cautionary accidental style
2403 @cindex accidental style, neo-modern-cautionary
2404
2405 @funindex neo-modern-cautionary
2406
2407 This rule is similar to @code{neo-modern}, but the @q{extra} accidentals
2408 are printed as cautionary accidentals (with parentheses).  They can also
2409 be printed at a different size by overriding
2410 @code{AccidentalCautionary}'s @code{font-size} property.
2411
2412 @lilypond[quote]
2413 musicA = {
2414   <<
2415     \relative {
2416       cis''8 fis, bes4 <a cis>8 f bis4 |
2417       cis2. <c, g'>4 |
2418     }
2419     \\
2420     \relative {
2421       ais'2 cis, |
2422       fis8 b a4 cis2 |
2423     }
2424   >>
2425 }
2426
2427 musicB = {
2428   \clef bass
2429   \new Voice {
2430     \voiceTwo \relative {
2431       <fis a cis>8[ <fis a cis>
2432       \change Staff = up
2433       cis' cis
2434       \change Staff = down
2435       <fis, a> <fis a>]
2436       \showStaffSwitch
2437       \change Staff = up
2438       dis'4 |
2439       \change Staff = down
2440       <fis, a cis>4 gis <f a d>2 |
2441     }
2442   }
2443 }
2444
2445 \new PianoStaff {
2446   <<
2447     \context Staff = "up" {
2448       \accidentalStyle neo-modern-cautionary
2449       \musicA
2450     }
2451     \context Staff = "down" {
2452       \accidentalStyle neo-modern-cautionary
2453       \musicB
2454     }
2455   >>
2456 }
2457 @end lilypond
2458
2459
2460 @item neo-modern-voice
2461
2462 @cindex neo-modern-voice accidental style
2463 @cindex accidental style, neo-modern-voice
2464
2465 @funindex neo-modern-voice
2466
2467 This rule is used for multivoice accidentals to be read both by
2468 musicians playing one voice and musicians playing all voices.
2469 Accidentals are typeset for each voice as with @code{neo-modern},
2470 but they are canceled across voices in the same @code{Staff}.
2471
2472 @lilypond[quote]
2473 musicA = {
2474   <<
2475     \relative {
2476       cis''8 fis, bes4 <a cis>8 f bis4 |
2477       cis2. <c, g'>4 |
2478     }
2479     \\
2480     \relative {
2481       ais'2 cis, |
2482       fis8 b a4 cis2 |
2483     }
2484   >>
2485 }
2486
2487 musicB = {
2488   \clef bass
2489   \new Voice {
2490     \voiceTwo \relative {
2491       <fis a cis>8[ <fis a cis>
2492       \change Staff = up
2493       cis' cis
2494       \change Staff = down
2495       <fis, a> <fis a>]
2496       \showStaffSwitch
2497       \change Staff = up
2498       dis'4 |
2499       \change Staff = down
2500       <fis, a cis>4 gis <f a d>2 |
2501     }
2502   }
2503 }
2504
2505 \new PianoStaff {
2506   <<
2507     \context Staff = "up" {
2508       \accidentalStyle neo-modern-voice
2509       \musicA
2510     }
2511     \context Staff = "down" {
2512       \accidentalStyle neo-modern-voice
2513       \musicB
2514     }
2515   >>
2516 }
2517 @end lilypond
2518
2519 @item neo-modern-voice-cautionary
2520
2521 @cindex neo-modern-voice-cautionary accidental style
2522 @cindex accidental style, neo-modern-voice-cautionary
2523
2524 @funindex neo-modern-voice-cautionary
2525
2526 This rule is similar to @code{neo-modern-voice}, but the extra
2527 accidentals are printed as cautionary accidentals.
2528
2529 @lilypond[quote]
2530 musicA = {
2531   <<
2532     \relative {
2533       cis''8 fis, bes4 <a cis>8 f bis4 |
2534       cis2. <c, g'>4 |
2535     }
2536     \\
2537     \relative {
2538       ais'2 cis, |
2539       fis8 b a4 cis2 |
2540     }
2541   >>
2542 }
2543
2544 musicB = {
2545   \clef bass
2546   \new Voice {
2547     \voiceTwo \relative {
2548       <fis a cis>8[ <fis a cis>
2549       \change Staff = up
2550       cis' cis
2551       \change Staff = down
2552       <fis, a> <fis a>]
2553       \showStaffSwitch
2554       \change Staff = up
2555       dis'4 |
2556       \change Staff = down
2557       <fis, a cis>4 gis <f a d>2 |
2558     }
2559   }
2560 }
2561
2562 \new PianoStaff {
2563   <<
2564     \context Staff = "up" {
2565       \accidentalStyle neo-modern-voice-cautionary
2566       \musicA
2567     }
2568     \context Staff = "down" {
2569       \accidentalStyle neo-modern-voice-cautionary
2570       \musicB
2571     }
2572   >>
2573 }
2574 @end lilypond
2575
2576 @item dodecaphonic
2577
2578 @cindex dodecaphonic accidental style
2579 @cindex dodecaphonic style, neo-modern
2580
2581 @funindex dodecaphonic
2582
2583 This rule reflects a practice introduced by composers at
2584 the beginning of the 20th century, in an attempt to
2585 abolish the hierarchy between natural and non-natural notes.
2586 With this style, @emph{every} note gets an accidental sign,
2587 including natural signs.
2588
2589 @lilypond[quote]
2590 musicA = {
2591   <<
2592     \relative {
2593       cis''8 fis, bes4 <a cis>8 f bis4 |
2594       cis2. <c, g'>4 |
2595     }
2596     \\
2597     \relative {
2598       ais'2 cis, |
2599       fis8 b a4 cis2 |
2600     }
2601   >>
2602 }
2603
2604 musicB = {
2605   \clef bass
2606   \new Voice {
2607     \voiceTwo \relative {
2608       <fis a cis>8[ <fis a cis>
2609       \change Staff = up
2610       cis' cis
2611       \change Staff = down
2612       <fis, a> <fis a>]
2613       \showStaffSwitch
2614       \change Staff = up
2615       dis'4 |
2616       \change Staff = down
2617       <fis, a cis>4 gis <f a d>2 |
2618     }
2619   }
2620 }
2621
2622 \new PianoStaff {
2623   <<
2624     \context Staff = "up" {
2625       \accidentalStyle dodecaphonic
2626       \musicA
2627     }
2628     \context Staff = "down" {
2629       \accidentalStyle dodecaphonic
2630       \musicB
2631     }
2632   >>
2633 }
2634 @end lilypond
2635
2636 @item dodecaphonic-no-repeat
2637
2638 @cindex dodecaphonic accidental style
2639 @cindex dodecaphonic style, neo-modern
2640
2641 @funindex dodecaphonic-no-repeat
2642
2643 Like with the dodecaphonic accidental style @emph{every} note
2644 gets an accidental sign by default, but accidentals are
2645 suppressed for pitches immediately repeated within the same staff.
2646
2647 @lilypond[quote]
2648 musicA = {
2649   <<
2650     \relative {
2651       cis''8 fis, bes4 <a cis>8 f bis4 |
2652       cis2. <c, g'>4 |
2653     }
2654     \\
2655     \relative {
2656       ais'2 cis, |
2657       fis8 b a4 cis2 |
2658     }
2659   >>
2660 }
2661
2662 musicB = {
2663   \clef bass
2664   \new Voice {
2665     \voiceTwo \relative {
2666       <fis a cis>8[ <fis a cis>
2667       \change Staff = up
2668       cis' cis
2669       \change Staff = down
2670       <fis, a> <fis a>]
2671       \showStaffSwitch
2672       \change Staff = up
2673       dis'4 |
2674       \change Staff = down
2675       <fis, a cis>4 gis <f a d>2 |
2676     }
2677   }
2678 }
2679
2680 \new PianoStaff {
2681   <<
2682     \context Staff = "up" {
2683       \accidentalStyle dodecaphonic-no-repeat
2684       \musicA
2685     }
2686     \context Staff = "down" {
2687       \accidentalStyle dodecaphonic-no-repeat
2688       \musicB
2689     }
2690   >>
2691 }
2692 @end lilypond
2693
2694
2695 @item dodecaphonic-first
2696
2697 @cindex dodecaphonic accidental style
2698 @cindex dodecaphonic style, neo-modern
2699
2700 @funindex dodecaphonic-first
2701
2702 Similar to the dodecaphonic accidental style @emph{every} pitch
2703 gets an accidental sign, but only the first time it is encountered
2704 in a measure.  Accidentals are only remembered for the actual octave
2705 but throughout voices.
2706
2707 @lilypond[quote]
2708 musicA = {
2709   <<
2710     \relative {
2711       cis''8 fis, bes4 <a cis>8 f bis4 |
2712       cis2. <c, g'>4 |
2713     }
2714     \\
2715     \relative {
2716       ais'2 cis, |
2717       fis8 b a4 cis2 |
2718     }
2719   >>
2720 }
2721
2722 musicB = {
2723   \clef bass
2724   \new Voice {
2725     \voiceTwo \relative {
2726       <fis a cis>8[ <fis a cis>
2727       \change Staff = up
2728       cis' cis
2729       \change Staff = down
2730       <fis, a> <fis a>]
2731       \showStaffSwitch
2732       \change Staff = up
2733       dis'4 |
2734       \change Staff = down
2735       <fis, a cis>4 gis <f a d>2 |
2736     }
2737   }
2738 }
2739
2740 \new PianoStaff {
2741   <<
2742     \context Staff = "up" {
2743       \accidentalStyle dodecaphonic-first
2744       \musicA
2745     }
2746     \context Staff = "down" {
2747       \accidentalStyle dodecaphonic-first
2748       \musicB
2749     }
2750   >>
2751 }
2752 @end lilypond
2753
2754
2755 @item teaching
2756
2757 @cindex teaching accidental style
2758 @cindex accidental style, teaching
2759
2760 @funindex teaching
2761
2762 This rule is intended for students, and makes it easy to create
2763 scale sheets with automatically created cautionary accidentals.
2764 Accidentals are printed like with @code{modern}, but cautionary
2765 accidentals are added for all sharp or flat tones specified by the
2766 key signature, except if the note is immediately repeated.
2767
2768 @lilypond[quote,staffsize=18]
2769 musicA = {
2770   <<
2771     \relative {
2772       cis''8 fis, bes4 <a cis>8 f bis4 |
2773       cis2. <c, g'>4 |
2774     }
2775     \\
2776     \relative {
2777       ais'2 cis, |
2778       fis8 b a4 cis2 |
2779     }
2780   >>
2781 }
2782
2783 musicB = {
2784   \clef bass
2785   \new Voice {
2786     \voiceTwo \relative {
2787       <fis a cis>8[ <fis a cis>
2788       \change Staff = up
2789       cis' cis
2790       \change Staff = down
2791       <fis, a> <fis a>]
2792       \showStaffSwitch
2793       \change Staff = up
2794       dis'4 |
2795       \change Staff = down
2796       <fis, a cis>4 gis <f a d>2 |
2797     }
2798   }
2799 }
2800
2801 \new PianoStaff {
2802   <<
2803     \context Staff = "up" {
2804       \key fis \minor
2805       \accidentalStyle teaching
2806       \musicA
2807     }
2808     \context Staff = "down" {
2809       \key fis \minor
2810       \accidentalStyle teaching
2811       \musicB
2812     }
2813   >>
2814 }
2815 @end lilypond
2816
2817
2818
2819 @item no-reset
2820
2821 @cindex accidental style, no reset
2822 @cindex no reset accidental style
2823
2824 @funindex no-reset
2825
2826 This is the same as @code{default} but with accidentals lasting
2827 @q{forever} and not only within the same measure:
2828
2829 @lilypond[quote]
2830 musicA = {
2831   <<
2832     \relative {
2833       cis''8 fis, bes4 <a cis>8 f bis4 |
2834       cis2. <c, g'>4 |
2835     }
2836     \\
2837     \relative {
2838       ais'2 cis, |
2839       fis8 b a4 cis2 |
2840     }
2841   >>
2842 }
2843
2844 musicB = {
2845   \clef bass
2846   \new Voice {
2847     \voiceTwo \relative {
2848       <fis a cis>8[ <fis a cis>
2849       \change Staff = up
2850       cis' cis
2851       \change Staff = down
2852       <fis, a> <fis a>]
2853       \showStaffSwitch
2854       \change Staff = up
2855       dis'4 |
2856       \change Staff = down
2857       <fis, a cis>4 gis <f a d>2 |
2858     }
2859   }
2860 }
2861
2862 \new PianoStaff {
2863   <<
2864     \context Staff = "up" {
2865       \accidentalStyle no-reset
2866       \musicA
2867     }
2868     \context Staff = "down" {
2869       \accidentalStyle no-reset
2870       \musicB
2871     }
2872   >>
2873 }
2874 @end lilypond
2875
2876 @item forget
2877
2878 @cindex forget accidental style
2879 @cindex accidental style, forget
2880
2881 @funindex forget
2882
2883 This is the opposite of @code{no-reset}: Accidentals are not
2884 remembered at all -- and hence all accidentals are typeset
2885 relative to the key signature, regardless of what came before in
2886 the music.
2887
2888 @lilypond[quote]
2889 musicA = {
2890   <<
2891     \relative {
2892       cis''8 fis, bes4 <a cis>8 f bis4 |
2893       cis2. <c, g'>4 |
2894     }
2895     \\
2896     \relative {
2897       ais'2 cis, |
2898       fis8 b a4 cis2 |
2899     }
2900   >>
2901 }
2902
2903 musicB = {
2904   \clef bass
2905   \new Voice {
2906     \voiceTwo \relative {
2907       <fis a cis>8[ <fis a cis>
2908       \change Staff = up
2909       cis' cis
2910       \change Staff = down
2911       <fis, a> <fis a>]
2912       \showStaffSwitch
2913       \change Staff = up
2914       dis'4 |
2915       \change Staff = down
2916       <fis, a cis>4 gis <f a d>2 |
2917     }
2918   }
2919 }
2920
2921 \new PianoStaff {
2922   <<
2923     \context Staff = "up" {
2924       \accidentalStyle forget
2925       \musicA
2926     }
2927     \context Staff = "down" {
2928       \accidentalStyle forget
2929       \musicB
2930     }
2931   >>
2932 }
2933 @end lilypond
2934 @end table
2935
2936 @seealso
2937 Snippets:
2938 @rlsr{Pitches}.
2939
2940 Internals Reference:
2941 @rinternals{Accidental},
2942 @rinternals{Accidental_engraver},
2943 @rinternals{GrandStaff},
2944 @rinternals{PianoStaff},
2945 @rinternals{Staff},
2946 @rinternals{AccidentalSuggestion},
2947 @rinternals{AccidentalPlacement},
2948 @rinternals{accidental-suggestion-interface}.
2949
2950 @cindex accidentals and simultaneous notes
2951 @cindex simultaneous notes and accidentals
2952 @cindex accidentals in chords
2953 @cindex chords, accidentals in
2954
2955 @knownissues
2956 Simultaneous notes are not considered in the automatic
2957 determination of accidentals; only previous notes and the key
2958 signature are considered.  Forcing accidentals with@tie{}@code{!}
2959 or@tie{}@code{?} may be required when the same note name occurs
2960 simultaneously with different alterations, as in @samp{<f! fis!>}.
2961
2962 Cautionary cancellation of accidentals is done by looking at previous measure.
2963 However, in the @code{\alternative} block following a @code{\repeat volta N}
2964 section, one would expect the cancellation being calculated using the previous
2965 @emph{played} measure, not previous @emph{printed} measure.
2966 In the following example, the natural @code{c} in the second alternative does
2967 not need a natural sign:
2968
2969 @lilypond[quote]
2970 {
2971   \accidentalStyle modern
2972   \time 2/4
2973   \repeat volta 2 {
2974     c'2
2975   }
2976   \alternative {
2977      cis'
2978      c'
2979   }
2980 }
2981 @end lilypond
2982
2983 The following work-around can be used: define a function that locally changes
2984 the accidental style to @code{forget}:
2985
2986 @lilypond[verbatim,quote]
2987 forget = #(define-music-function (music) (ly:music?) #{
2988   \accidentalStyle forget
2989   #music
2990   \accidentalStyle modern
2991 #})
2992 {
2993   \accidentalStyle modern
2994   \time 2/4
2995   \repeat volta 2 {
2996     c'2
2997   }
2998   \alternative {
2999      cis'
3000      \forget c'
3001   }
3002 }
3003 @end lilypond
3004
3005
3006 @node Ambitus
3007 @unnumberedsubsubsec Ambitus
3008
3009 @cindex ambitus
3010 @cindex range of pitches
3011 @cindex pitch range
3012
3013 The term @notation{ambitus} (pl. ambitus) denotes a range of
3014 pitches for a given voice in a part of music.  It may also denote
3015 the pitch range that a musical instrument is capable of playing.
3016 Ambitus are printed on vocal parts so that performers can easily
3017 determine if it matches their capabilities.
3018
3019 Ambitus are denoted at the beginning of a piece near the initial
3020 clef.  The range is graphically specified by two note heads that
3021 represent the lowest and highest pitches.  Accidentals are only
3022 printed if they are not part of the key signature.
3023
3024 @lilypond[verbatim,quote]
3025 \layout {
3026   \context {
3027     \Voice
3028     \consists "Ambitus_engraver"
3029   }
3030 }
3031
3032 \relative {
3033   aes' c e2
3034   cis,1
3035 }
3036 @end lilypond
3037
3038
3039 @snippets
3040
3041 @lilypondfile[verbatim,quote,texidoc,doctitle]
3042 {adding-ambitus-per-voice.ly}
3043
3044 @lilypondfile[verbatim,quote,texidoc,doctitle]
3045 {ambitus-with-multiple-voices.ly}
3046
3047 @lilypondfile[verbatim,quote,texidoc,doctitle]
3048 {changing-the-ambitus-gap.ly}
3049
3050 @seealso
3051 Music Glossary:
3052 @rglos{ambitus}.
3053
3054 Snippets:
3055 @rlsr{Pitches}.
3056
3057 Internals Reference:
3058 @rinternals{Ambitus_engraver},
3059 @rinternals{Voice},
3060 @rinternals{Staff},
3061 @rinternals{Ambitus},
3062 @rinternals{AmbitusAccidental},
3063 @rinternals{AmbitusLine},
3064 @rinternals{AmbitusNoteHead},
3065 @rinternals{ambitus-interface}.
3066
3067 @knownissues
3068 There is no collision handling in the case of multiple per-voice
3069 ambitus.
3070
3071
3072 @node Note heads
3073 @subsection Note heads
3074
3075 This section suggests ways of altering note heads.
3076
3077 @menu
3078 * Special note heads::
3079 * Easy notation note heads::
3080 * Shape note heads::
3081 * Improvisation::
3082 @end menu
3083
3084 @node Special note heads
3085 @unnumberedsubsubsec Special note heads
3086
3087 @cindex note heads, special
3088 @cindex note heads, cross
3089 @cindex note heads, diamond
3090 @cindex note heads, parlato
3091 @cindex note heads, harmonic
3092 @cindex note heads, guitar
3093 @cindex special note heads
3094 @cindex cross note heads
3095 @cindex diamond note heads
3096 @cindex parlato note heads
3097 @cindex harmonic note heads
3098 @cindex guitar note heads
3099 @cindex note head styles
3100 @cindex styles, note heads
3101
3102 @funindex cross
3103
3104 The appearance of note heads may be altered:
3105
3106 @lilypond[verbatim,quote]
3107 \relative c'' {
3108   c4 b
3109   \override NoteHead.style = #'cross
3110   c4 b
3111   \revert NoteHead.style
3112   a b
3113   \override NoteHead.style = #'harmonic
3114   a b
3115   \revert NoteHead.style
3116   c4 d e f
3117 }
3118 @end lilypond
3119
3120 To see all note head styles, see @ref{Note head styles}.
3121
3122 The @code{cross} style is used to represent a variety of musical
3123 intentions.  The following generic predefined commands modify the
3124 note head in both staff and tablature contexts and can be used to
3125 represent any musical meaning:
3126
3127 @lilypond[verbatim,quote]
3128 \relative {
3129   c''4 b
3130   \xNotesOn
3131    a b c4 b
3132   \xNotesOff
3133   c4 d
3134 }
3135 @end lilypond
3136
3137 The music function form of this predefined command may be used
3138 inside and outside chords to generate crossed note heads in both
3139 staff and tablature contexts:
3140
3141 @lilypond[verbatim,quote]
3142 \relative {
3143   c''4 b
3144   \xNote { e f }
3145   c b < g \xNote c f > b
3146 }
3147 @end lilypond
3148
3149 As synonyms for @code{\xNote}, @code{\xNotesOn} and @code{\xNotesOff},
3150 @code{\deadNote}, @code{\deadNotesOn} and @code{\deadNotesOff} can
3151 be used.  The term @notation{dead note} is commonly used by guitarists.
3152
3153 There is also a similar shorthand for diamond shapes:
3154
3155 @lilypond[verbatim,quote]
3156 \relative c'' {
3157   <c f\harmonic>2 <d a'\harmonic>4 <c g'\harmonic> f\harmonic
3158 }
3159 @end lilypond
3160
3161 @predefined
3162 @code{\harmonic},
3163 @code{\xNotesOn},
3164 @code{\xNotesOff},
3165 @code{\xNote}.
3166 @endpredefined
3167
3168 @seealso
3169 Snippets:
3170 @rlsr{Pitches}.
3171
3172 Notation Reference:
3173 @ref{Note head styles},
3174 @ref{Chorded notes},
3175 @ref{Indicating harmonics and dampened notes}.
3176
3177 Internals Reference:
3178 @rinternals{note-event},
3179 @rinternals{Note_heads_engraver},
3180 @rinternals{Ledger_line_engraver},
3181 @rinternals{NoteHead},
3182 @rinternals{LedgerLineSpanner},
3183 @rinternals{note-head-interface},
3184 @rinternals{ledger-line-spanner-interface}.
3185
3186
3187 @node Easy notation note heads
3188 @unnumberedsubsubsec Easy notation note heads
3189
3190 @cindex note heads, practice
3191 @cindex practice note heads
3192 @cindex note heads, easy notation
3193 @cindex easy notation
3194 @cindex beginners' music
3195 @cindex music, beginners'
3196 @cindex easy play note heads
3197 @cindex note heads, easy play
3198
3199 @funindex \easyHeadsOn
3200 @funindex \easyHeadsOff
3201
3202 The @q{easy play} note head includes a note name inside the head.
3203 It is used in music for beginners.  To make the letters readable,
3204 it should be printed in a large font size.  To print with a larger
3205 font, see @ref{Setting the staff size}.
3206
3207 @lilypond[verbatim,quote]
3208 #(set-global-staff-size 26)
3209 \relative c' {
3210   \easyHeadsOn
3211   c2 e4 f
3212   g1
3213   \easyHeadsOff
3214   c,1
3215 }
3216 @end lilypond
3217
3218
3219 @predefined
3220 @code{\easyHeadsOn},
3221 @code{\easyHeadsOff}.
3222 @endpredefined
3223
3224
3225 @snippets
3226
3227 @lilypondfile[verbatim,quote,texidoc,doctitle]
3228 {numbers-as-easy-note-heads.ly}
3229
3230 @seealso
3231 Notation Reference:
3232 @ref{Setting the staff size}.
3233
3234 Snippets:
3235 @rlsr{Pitches}.
3236
3237 Internals Reference:
3238 @rinternals{note-event},
3239 @rinternals{Note_heads_engraver},
3240 @rinternals{NoteHead},
3241 @rinternals{note-head-interface}.
3242
3243
3244 @node Shape note heads
3245 @unnumberedsubsubsec Shape note heads
3246
3247 @cindex note heads, shape
3248 @cindex note heads, Aiken
3249 @cindex note heads, sacred harp
3250 @cindex shape notes
3251 @cindex Aiken shape note heads
3252 @cindex sacred harp note heads
3253 @cindex note heads, Southern Harmony
3254 @cindex Southern Harmony note heads
3255 @cindex Funk shape note heads
3256 @cindex note heads, Funk
3257 @cindex note heads, Harmonica Sacra
3258 @cindex Harmonica Sacra note heads
3259 @cindex Christian Harmony note heads
3260 @cindex note heads, Christian Harmony
3261 @cindex Walker shape note heads
3262 @cindex note heads, Walker
3263
3264 @funindex \aikenHeads
3265 @funindex \sacredHarpHeads
3266 @funindex \southernHarmonyHeads
3267 @funindex \funkHeads
3268 @funindex \walkerHeads
3269
3270 In shape note head notation, the shape of the note head
3271 corresponds to the harmonic function of a note in the scale.  This
3272 notation was popular in nineteenth-century American song books.
3273 Shape note heads can be produced in Sacred Harp, Southern Harmony,
3274 Funk (Harmonica Sacra), Walker, and Aiken (Christian Harmony) styles:
3275
3276 @lilypond[verbatim,quote]
3277 \relative c'' {
3278   \aikenHeads
3279   c, d e f g2 a b1 c \break
3280   \sacredHarpHeads
3281   c,4 d e f g2 a b1 c \break
3282   \southernHarmonyHeads
3283   c,4 d e f g2 a b1 c \break
3284   \funkHeads
3285   c,4 d e f g2 a b1 c \break
3286   \walkerHeads
3287   c,4 d e f g2 a b1 c \break
3288 }
3289 @end lilypond
3290
3291 @funindex \key
3292 @funindex \aikenHeadsMinor
3293 @funindex \sacredHarpHeadsMinor
3294 @funindex \southernHarmonyHeadsMinor
3295 @funindex \funkHeadsMinor
3296 @funindex \walkerHeadsMinor
3297
3298 Shapes are typeset according to the step in the scale, where the base
3299 of the scale is determined by the @code{\key} command.  When writing
3300 in a minor key, the scale step can be determined from the relative
3301 major:
3302
3303 @lilypond[verbatim,quote]
3304 \relative c'' {
3305   \key a \minor
3306   \aikenHeads
3307   a b c d e2 f g1 a \break
3308   \aikenHeadsMinor
3309   a,4 b c d e2 f g1 a \break
3310   \sacredHarpHeadsMinor
3311   a,2 b c d \break
3312   \southernHarmonyHeadsMinor
3313   a2 b c d \break
3314   \funkHeadsMinor
3315   a2 b c d \break
3316   \walkerHeadsMinor
3317   a2 b c d \break
3318 }
3319 @end lilypond
3320
3321
3322 @predefined
3323 @code{\aikenHeads},
3324 @code{\aikenHeadsMinor},
3325 @code{\funkHeads},
3326 @code{\funkHeadsMinor},
3327 @code{\sacredHarpHeads},
3328 @code{\sacredHarpHeadsMinor},
3329 @code{\southernHarmonyHeads},
3330 @code{\southernHarmonyHeadsMinor},
3331 @code{\walkerHeads},
3332 @code{\walkerHeadsMinor}.
3333 @endpredefined
3334
3335
3336 @snippets
3337
3338 @lilypondfile[verbatim,quote,texidoc,doctitle]
3339 {applying-note-head-styles-depending-on-the-step-of-the-scale.ly}
3340
3341 To see all note head styles, see @ref{Note head styles}.
3342
3343 @seealso
3344 Snippets:
3345 @rlsr{Pitches}.
3346
3347 Notation Reference:
3348 @ref{Note head styles}.
3349
3350 Internals Reference:
3351 @rinternals{note-event},
3352 @rinternals{Note_heads_engraver},
3353 @rinternals{NoteHead},
3354 @rinternals{note-head-interface}.
3355
3356
3357 @node Improvisation
3358 @unnumberedsubsubsec Improvisation
3359
3360 @cindex improvisation
3361 @cindex slashed note heads
3362 @cindex note heads, improvisation
3363 @cindex note heads, slashed
3364
3365 @funindex \improvisationOn
3366 @funindex \improvisationOff
3367
3368 Improvisation is sometimes denoted with slashed note heads, where
3369 the performer may choose any pitch but should play the specified
3370 rhythm.  Such note heads can be created:
3371
3372 @lilypond[verbatim,quote]
3373 \new Voice \with {
3374   \consists "Pitch_squash_engraver"
3375 } \relative {
3376   e''8 e g a a16( bes) a8 g
3377   \improvisationOn
3378   e8 ~
3379   2 ~ 8 f4 f8 ~
3380   2
3381   \improvisationOff
3382   a16( bes) a8 g e
3383 }
3384 @end lilypond
3385
3386 @predefined
3387 @code{\improvisationOn},
3388 @code{\improvisationOff}.
3389 @endpredefined
3390
3391 @seealso
3392 Snippets:
3393 @rlsr{Pitches}.
3394
3395 Internals Reference:
3396 @rinternals{Pitch_squash_engraver},
3397 @rinternals{Voice},
3398 @rinternals{RhythmicStaff}.