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" \with {
1527     instrumentName = #"Vln"
1528     midiInstrument = #"violin"
1529   }
1530   \relative c'' {
1531     % not strictly necessary, but a good reminder
1532     \transposition c'
1533     \key c \major
1534     g4( c8) r c r c4
1535   }
1536   \new Staff = "clarinet" \with {
1537     instrumentName = \markup { Cl (B\flat) }
1538     midiInstrument = #"clarinet"
1539   }
1540   \relative c'' {
1541     \transposition bes
1542     \key d \major
1543     a4( d8) r d r d4
1544   }
1545 >>
1546 @end lilypond
1547
1548 The @code{\transposition} may be changed during a piece.  For
1549 example, a clarinetist may be required to switch from an A clarinet
1550 to a B-flat clarinet.
1551
1552 @lilypond[verbatim,quote]
1553 flute = \relative c'' {
1554   \key f \major
1555   \cueDuring #"clarinet" #DOWN {
1556     R1 _\markup\tiny "clarinet"
1557     c4 f e d
1558     R1 _\markup\tiny "clarinet"
1559   }
1560 }
1561 clarinet = \relative c'' {
1562   \key aes \major
1563   \transposition a
1564   aes4 bes c des
1565   R1^\markup { muta in B\flat }
1566   \key g \major
1567   \transposition bes
1568   d2 g,
1569 }
1570 \addQuote "clarinet" \clarinet
1571 <<
1572   \new Staff \with { instrumentName = #"Flute" }
1573     \flute
1574   \new Staff \with { instrumentName = #"Cl (A)" }
1575     \clarinet
1576 >>
1577 @end lilypond
1578
1579 @seealso
1580 Music Glossary:
1581 @rglos{concert pitch},
1582 @rglos{transposing instrument}.
1583
1584 Notation Reference:
1585 @ref{Quoting other voices},
1586 @ref{Transpose}.
1587
1588 Snippets:
1589 @rlsr{Pitches}.
1590
1591
1592 @node Automatic accidentals
1593 @unnumberedsubsubsec Automatic accidentals
1594
1595 @cindex accidental style
1596 @cindex accidental style, default
1597 @cindex accidentals
1598 @cindex accidentals, automatic
1599 @cindex automatic accidentals
1600 @cindex default accidental style
1601
1602 @funindex \accidentalStyle
1603 @funindex voice
1604 @funindex default
1605
1606 There are many different conventions on how to typeset
1607 accidentals.  LilyPond provides a function to specify which
1608 accidental style to use.  This function is called as follows:
1609
1610 @example
1611 \new Staff <<
1612   \accidentalStyle voice
1613   @{ @dots{} @}
1614 >>
1615 @end example
1616
1617 The accidental style applies to the current @code{Staff} by
1618 default (with the exception of the styles @code{piano} and
1619 @code{piano-cautionary}, which are explained below).  Optionally,
1620 the function can take a second argument that determines in which
1621 scope the style should be changed.  For example, to use the same
1622 style in all staves of the current @code{StaffGroup}, use:
1623
1624 @example
1625 \accidentalStyle StaffGroup.voice
1626 @end example
1627
1628 The following accidental styles are supported.  To demonstrate
1629 each style, we use the following example:
1630
1631
1632 @lilypond[verbatim,quote]
1633 musicA = {
1634   <<
1635     \relative {
1636       cis''8 fis, bes4 <a cis>8 f bis4 |
1637       cis2. <c, g'>4 |
1638     }
1639     \\
1640     \relative {
1641       ais'2 cis, |
1642       fis8 b a4 cis2 |
1643     }
1644   >>
1645 }
1646
1647 musicB = {
1648   \clef bass
1649   \new Voice {
1650     \voiceTwo \relative {
1651       <fis a cis>8[ <fis a cis>
1652       \change Staff = up
1653       cis' cis
1654       \change Staff = down
1655       <fis, a> <fis a>]
1656       \showStaffSwitch
1657       \change Staff = up
1658       dis'4 |
1659       \change Staff = down
1660       <fis, a cis>4 gis <f a d>2 |
1661     }
1662   }
1663 }
1664
1665 \new PianoStaff {
1666   <<
1667     \context Staff = "up" {
1668       \accidentalStyle default
1669       \musicA
1670     }
1671     \context Staff = "down" {
1672       \accidentalStyle default
1673       \musicB
1674     }
1675   >>
1676 }
1677 @end lilypond
1678
1679 Note that the last lines of this example can be replaced by the
1680 following, as long as the same accidental style should be used in
1681 both staves.
1682
1683 @example
1684 \new PianoStaff @{
1685   <<
1686     \context Staff = "up" @{
1687       %%% change the next line as desired:
1688       \accidentalStyle Score.default
1689       \musicA
1690     @}
1691     \context Staff = "down" @{
1692       \musicB
1693     @}
1694   >>
1695 @}
1696 @end example
1697
1698
1699 @c don't use verbatim in this table.
1700 @table @code
1701 @item default
1702
1703 @cindex default accidental style
1704 @cindex accidental style, default
1705
1706 @funindex default
1707
1708 This is the default typesetting behavior.  It corresponds to
1709 eighteenth-century common practice: accidentals are remembered to
1710 the end of the measure in which they occur and only in their own
1711 octave.  Thus, in the example below, no natural signs are printed
1712 before the@tie{}@code{b} in the second measure or the
1713 last@tie{}@code{c}:
1714
1715 @lilypond[quote]
1716 musicA = {
1717   <<
1718     \relative {
1719       cis''8 fis, bes4 <a cis>8 f bis4 |
1720       cis2. <c, g'>4 |
1721     }
1722     \\
1723     \relative {
1724       ais'2 cis, |
1725       fis8 b a4 cis2 |
1726     }
1727   >>
1728 }
1729
1730 musicB = {
1731   \clef bass
1732   \new Voice {
1733     \voiceTwo \relative {
1734       <fis a cis>8[ <fis a cis>
1735       \change Staff = up
1736       cis' cis
1737       \change Staff = down
1738       <fis, a> <fis a>]
1739       \showStaffSwitch
1740       \change Staff = up
1741       dis'4 |
1742       \change Staff = down
1743       <fis, a cis>4 gis <f a d>2 |
1744     }
1745   }
1746 }
1747
1748 \new PianoStaff {
1749   <<
1750     \context Staff = "up" {
1751       \accidentalStyle default
1752       \musicA
1753     }
1754     \context Staff = "down" {
1755       \accidentalStyle default
1756       \musicB
1757     }
1758   >>
1759 }
1760 @end lilypond
1761
1762 @item voice
1763
1764 @cindex accidental style, voice
1765 @cindex voice accidental style
1766 @cindex accidental style, modern
1767 @cindex modern accidental style
1768 @cindex accidental style, modern-cautionary
1769 @cindex modern-cautionary accidental style
1770
1771 @funindex voice
1772
1773 The normal behavior is to remember the accidentals at
1774 @code{Staff}-level.  In this style, however, accidentals are
1775 typeset individually for each voice.  Apart from that, the rule is
1776 similar to @code{default}.
1777
1778 As a result, accidentals from one voice do not get canceled in
1779 other voices, which is often an unwanted result: in the following
1780 example, it is hard to determine whether the second@tie{}@code{a}
1781 should be played natural or sharp.  The @code{voice} option should
1782 therefore be used only if the voices are to be read solely by
1783 individual musicians.  If the staff is to be used by one musician
1784 (e.g., a conductor or in a piano score) then @code{modern} or
1785 @code{modern-cautionary} should be used instead.
1786
1787
1788 @lilypond[quote]
1789 musicA = {
1790   <<
1791     \relative {
1792       cis''8 fis, bes4 <a cis>8 f bis4 |
1793       cis2. <c, g'>4 |
1794     }
1795     \\
1796     \relative {
1797       ais'2 cis, |
1798       fis8 b a4 cis2 |
1799     }
1800   >>
1801 }
1802
1803 musicB = {
1804   \clef bass
1805   \new Voice {
1806     \voiceTwo \relative {
1807       <fis a cis>8[ <fis a cis>
1808       \change Staff = up
1809       cis' cis
1810       \change Staff = down
1811       <fis, a> <fis a>]
1812       \showStaffSwitch
1813       \change Staff = up
1814       dis'4 |
1815       \change Staff = down
1816       <fis, a cis>4 gis <f a d>2 |
1817     }
1818   }
1819 }
1820
1821 \new PianoStaff {
1822   <<
1823     \context Staff = "up" {
1824       \accidentalStyle voice
1825       \musicA
1826     }
1827     \context Staff = "down" {
1828       \accidentalStyle voice
1829       \musicB
1830     }
1831   >>
1832 }
1833 @end lilypond
1834
1835 @item modern
1836
1837 @cindex accidentals, modern style
1838 @cindex modern style accidentals
1839
1840 @funindex modern
1841
1842 This rule corresponds to the common practice in the twentieth
1843 century.  It omits some extra natural signs, which were
1844 traditionally prefixed to a sharp following a double sharp,
1845 or a flat following a double flat.  The @code{modern} rule
1846 prints the same accidentals as @code{default}, with
1847 two additions that serve to avoid ambiguity: after temporary
1848 accidentals, cancellation marks are printed also in the following
1849 measure (for notes in the same octave) and, in the same measure,
1850 for notes in other octaves.  Hence the naturals before
1851 the@tie{}@code{b} and the@tie{}@code{c} in the second measure of
1852 the upper staff:
1853
1854 @lilypond[quote]
1855 musicA = {
1856   <<
1857     \relative {
1858       cis''8 fis, bes4 <a cis>8 f bis4 |
1859       cis2. <c, g'>4 |
1860     }
1861     \\
1862     \relative {
1863       ais'2 cis, |
1864       fis8 b a4 cis2 |
1865     }
1866   >>
1867 }
1868
1869 musicB = {
1870   \clef bass
1871   \new Voice {
1872     \voiceTwo \relative {
1873       <fis a cis>8[ <fis a cis>
1874       \change Staff = up
1875       cis' cis
1876       \change Staff = down
1877       <fis, a> <fis a>]
1878       \showStaffSwitch
1879       \change Staff = up
1880       dis'4 |
1881       \change Staff = down
1882       <fis, a cis>4 gis <f a d>2 |
1883     }
1884   }
1885 }
1886
1887 \new PianoStaff {
1888   <<
1889     \context Staff = "up" {
1890       \accidentalStyle modern
1891       \musicA
1892     }
1893     \context Staff = "down" {
1894       \accidentalStyle modern
1895       \musicB
1896     }
1897   >>
1898 }
1899 @end lilypond
1900
1901 @item modern-cautionary
1902
1903 @cindex accidentals, modern cautionary style
1904 @cindex modern accidental style
1905 @cindex modern cautionary accidental style
1906 @cindex modern style accidentals
1907 @cindex modern style cautionary accidentals
1908
1909 @funindex modern-cautionary
1910
1911 This rule is similar to @code{modern}, but the @q{extra} accidentals
1912 are printed as cautionary accidentals (with parentheses).  They can also
1913 be printed at a different size by overriding
1914 @code{AccidentalCautionary}'s @code{font-size} property.
1915
1916 @lilypond[quote]
1917 musicA = {
1918   <<
1919     \relative {
1920       cis''8 fis, bes4 <a cis>8 f bis4 |
1921       cis2. <c, g'>4 |
1922     }
1923     \\
1924     \relative {
1925       ais'2 cis, |
1926       fis8 b a4 cis2 |
1927     }
1928   >>
1929 }
1930
1931 musicB = {
1932   \clef bass
1933   \new Voice {
1934     \voiceTwo \relative {
1935       <fis a cis>8[ <fis a cis>
1936       \change Staff = up
1937       cis' cis
1938       \change Staff = down
1939       <fis, a> <fis a>]
1940       \showStaffSwitch
1941       \change Staff = up
1942       dis'4 |
1943       \change Staff = down
1944       <fis, a cis>4 gis <f a d>2 |
1945     }
1946   }
1947 }
1948
1949 \new PianoStaff {
1950   <<
1951     \context Staff = "up" {
1952       \accidentalStyle modern-cautionary
1953       \musicA
1954     }
1955     \context Staff = "down" {
1956       \accidentalStyle modern-cautionary
1957       \musicB
1958     }
1959   >>
1960 }
1961 @end lilypond
1962
1963 @item modern-voice
1964
1965 @cindex accidental style, modern
1966 @cindex accidentals, modern
1967 @cindex accidentals, multivoice
1968 @cindex modern accidental style
1969 @cindex modern accidentals
1970 @cindex multivoice accidentals
1971
1972 @funindex modern-voice
1973
1974 This rule is used for multivoice accidentals to be read both by
1975 musicians playing one voice and musicians playing all voices.
1976 Accidentals are typeset for each voice, but they @emph{are}
1977 canceled across voices in the same @code{Staff}.  Hence,
1978 the@tie{}@code{a} in the last measure is canceled because the
1979 previous cancellation was in a different voice, and
1980 the@tie{}@code{d} in the lower staff is canceled because of the
1981 accidental in a different voice in the previous measure:
1982
1983 @lilypond[quote]
1984 musicA = {
1985   <<
1986     \relative {
1987       cis''8 fis, bes4 <a cis>8 f bis4 |
1988       cis2. <c, g'>4 |
1989     }
1990     \\
1991     \relative {
1992       ais'2 cis, |
1993       fis8 b a4 cis2 |
1994     }
1995   >>
1996 }
1997
1998 musicB = {
1999   \clef bass
2000   \new Voice {
2001     \voiceTwo \relative {
2002       <fis a cis>8[ <fis a cis>
2003       \change Staff = up
2004       cis' cis
2005       \change Staff = down
2006       <fis, a> <fis a>]
2007       \showStaffSwitch
2008       \change Staff = up
2009       dis'4 |
2010       \change Staff = down
2011       <fis, a cis>4 gis <f a d>2 |
2012     }
2013   }
2014 }
2015
2016 \new PianoStaff {
2017   <<
2018     \context Staff = "up" {
2019       \accidentalStyle modern-voice
2020       \musicA
2021     }
2022     \context Staff = "down" {
2023       \accidentalStyle modern-voice
2024       \musicB
2025     }
2026   >>
2027 }
2028 @end lilypond
2029
2030 @cindex accidental style, cautionary, modern voice
2031 @cindex accidental style, modern voice cautionary
2032 @cindex accidental style, voice, modern cautionary
2033
2034 @funindex modern-voice-cautionary
2035
2036 @item modern-voice-cautionary
2037
2038 This rule is the same as @code{modern-voice}, but with the extra
2039 accidentals (the ones not typeset by @code{voice}) typeset as
2040 cautionaries.  Even though all accidentals typeset by
2041 @code{default} @emph{are} typeset with this rule, some of them are
2042 typeset as cautionaries.
2043
2044 @lilypond[quote]
2045 musicA = {
2046   <<
2047     \relative {
2048       cis''8 fis, bes4 <a cis>8 f bis4 |
2049       cis2. <c, g'>4 |
2050     }
2051     \\
2052     \relative {
2053       ais'2 cis, |
2054       fis8 b a4 cis2 |
2055     }
2056   >>
2057 }
2058
2059 musicB = {
2060   \clef bass
2061   \new Voice {
2062     \voiceTwo \relative {
2063       <fis a cis>8[ <fis a cis>
2064       \change Staff = up
2065       cis' cis
2066       \change Staff = down
2067       <fis, a> <fis a>]
2068       \showStaffSwitch
2069       \change Staff = up
2070       dis'4 |
2071       \change Staff = down
2072       <fis, a cis>4 gis <f a d>2 |
2073     }
2074   }
2075 }
2076
2077 \new PianoStaff {
2078   <<
2079     \context Staff = "up" {
2080       \accidentalStyle modern-voice-cautionary
2081       \musicA
2082     }
2083     \context Staff = "down" {
2084       \accidentalStyle modern-voice-cautionary
2085       \musicB
2086     }
2087   >>
2088 }
2089 @end lilypond
2090
2091 @item piano
2092
2093 @cindex accidental style, piano
2094 @cindex accidentals, piano
2095 @cindex piano accidental style
2096 @cindex piano accidentals
2097
2098 @funindex piano
2099
2100 This rule reflects twentieth-century practice for piano notation.
2101 Its behavior is very similar to @code{modern} style, but here
2102 accidentals also get canceled across the staves in the same
2103 @code{GrandStaff} or @code{PianoStaff}, hence all the
2104 cancellations of the final notes.
2105
2106 This accidental style applies to the current @code{GrandStaff} or
2107 @code{PianoStaff} by default.
2108
2109 @lilypond[quote]
2110 musicA = {
2111   <<
2112     \relative {
2113       cis''8 fis, bes4 <a cis>8 f bis4 |
2114       cis2. <c, g'>4 |
2115     }
2116     \\
2117     \relative {
2118       ais'2 cis, |
2119       fis8 b a4 cis2 |
2120     }
2121   >>
2122 }
2123
2124 musicB = {
2125   \clef bass
2126   \new Voice {
2127     \voiceTwo \relative {
2128       <fis a cis>8[ <fis a cis>
2129       \change Staff = up
2130       cis' cis
2131       \change Staff = down
2132       <fis, a> <fis a>]
2133       \showStaffSwitch
2134       \change Staff = up
2135       dis'4 |
2136       \change Staff = down
2137       <fis, a cis>4 gis <f a d>2 |
2138     }
2139   }
2140 }
2141
2142 \new PianoStaff {
2143   <<
2144     \context Staff = "up" {
2145       \accidentalStyle piano
2146       \musicA
2147     }
2148     \context Staff = "down" {
2149       \musicB
2150     }
2151   >>
2152 }
2153 @end lilypond
2154
2155 @item piano-cautionary
2156
2157 @cindex accidentals, piano cautionary
2158 @cindex cautionary accidentals, piano
2159 @cindex piano cautionary accidentals
2160 @cindex accidental style, piano cautionary
2161 @cindex cautionary accidental style, piano
2162 @cindex piano cautionary accidental style
2163
2164 @funindex piano-cautionary
2165
2166 This is the same as @code{piano} but with the extra accidentals
2167 typeset as cautionaries.
2168
2169 @lilypond[quote]
2170 musicA = {
2171   <<
2172     \relative {
2173       cis''8 fis, bes4 <a cis>8 f bis4 |
2174       cis2. <c, g'>4 |
2175     }
2176     \\
2177     \relative {
2178       ais'2 cis, |
2179       fis8 b a4 cis2 |
2180     }
2181   >>
2182 }
2183
2184 musicB = {
2185   \clef bass
2186   \new Voice {
2187     \voiceTwo \relative {
2188       <fis a cis>8[ <fis a cis>
2189       \change Staff = up
2190       cis' cis
2191       \change Staff = down
2192       <fis, a> <fis a>]
2193       \showStaffSwitch
2194       \change Staff = up
2195       dis'4 |
2196       \change Staff = down
2197       <fis, a cis>4 gis <f a d>2 |
2198     }
2199   }
2200 }
2201
2202 \new PianoStaff {
2203   <<
2204     \context Staff = "up" {
2205       \accidentalStyle piano-cautionary
2206       \musicA
2207     }
2208     \context Staff = "down" {
2209       \musicB
2210     }
2211   >>
2212 }
2213 @end lilypond
2214
2215
2216 @item choral
2217
2218 @cindex accidental style, choral
2219 @cindex accidentals, choral
2220 @cindex choral accidental style
2221 @cindex choral accidentals
2222
2223 @funindex choral
2224
2225 This rule is a combination of the @code{modern-voice} and the @code{piano}
2226 style. It shows all accidentals required for singers that only follow their
2227 own voice, as well as additional accidentals for readers that follow all
2228 voices of an entire @code{ChoirStaff} simultaneously.
2229
2230 This accidental style applies to the current @code{ChoirStaff} by default.
2231
2232 @lilypond[quote]
2233 musicA = {
2234   <<
2235     \relative {
2236       cis''8 fis, bes4 <a cis>8 f bis4 |
2237       cis2. <c, g'>4 |
2238     }
2239     \\
2240     \relative {
2241       ais'2 cis, |
2242       fis8 b a4 cis2 |
2243     }
2244   >>
2245 }
2246
2247 musicB = {
2248   \clef bass
2249   \new Voice {
2250     \voiceTwo \relative {
2251       <fis a cis>8[ <fis a cis>
2252       \change Staff = up
2253       cis' cis
2254       \change Staff = down
2255       <fis, a> <fis a>]
2256       \showStaffSwitch
2257       \change Staff = up
2258       dis'4 |
2259       \change Staff = down
2260       <fis, a cis>4 gis <f a d>2 |
2261     }
2262   }
2263 }
2264
2265 \new ChoirStaff {
2266   <<
2267     \context Staff = "up" {
2268       \accidentalStyle choral
2269       \musicA
2270     }
2271     \context Staff = "down" {
2272       \musicB
2273     }
2274   >>
2275 }
2276 @end lilypond
2277
2278 @item choral-cautionary
2279
2280 @cindex accidentals, choral cautionary
2281 @cindex cautionary accidentals, choral
2282 @cindex choral cautionary accidentals
2283 @cindex accidental style, choral cautionary
2284 @cindex cautionary accidental style, choral
2285 @cindex choral cautionary accidental style
2286
2287 @funindex choral-cautionary
2288
2289 This is the same as @code{choral} but with the extra accidentals
2290 typeset as cautionaries.
2291
2292 @lilypond[quote]
2293 musicA = {
2294   <<
2295     \relative {
2296       cis''8 fis, bes4 <a cis>8 f bis4 |
2297       cis2. <c, g'>4 |
2298     }
2299     \\
2300     \relative {
2301       ais'2 cis, |
2302       fis8 b a4 cis2 |
2303     }
2304   >>
2305 }
2306
2307 musicB = {
2308   \clef bass
2309   \new Voice {
2310     \voiceTwo \relative {
2311       <fis a cis>8[ <fis a cis>
2312       \change Staff = up
2313       cis' cis
2314       \change Staff = down
2315       <fis, a> <fis a>]
2316       \showStaffSwitch
2317       \change Staff = up
2318       dis'4 |
2319       \change Staff = down
2320       <fis, a cis>4 gis <f a d>2 |
2321     }
2322   }
2323 }
2324
2325 \new ChoirStaff {
2326   <<
2327     \context Staff = "up" {
2328       \accidentalStyle choral-cautionary
2329       \musicA
2330     }
2331     \context Staff = "down" {
2332       \musicB
2333     }
2334   >>
2335 }
2336 @end lilypond
2337
2338
2339 @item neo-modern
2340
2341 @cindex neo-modern accidental style
2342 @cindex accidental style, neo-modern
2343
2344 @funindex neo-modern
2345
2346 This rule reproduces a common practice in contemporary music:
2347 accidentals are printed like with @code{modern}, but they are printed
2348 again if the same note appears later in the same measure -- except
2349 if the note is immediately repeated.
2350
2351 @lilypond[quote]
2352 musicA = {
2353   <<
2354     \relative {
2355       cis''8 fis, bes4 <a cis>8 f bis4 |
2356       cis2. <c, g'>4 |
2357     }
2358     \\
2359     \relative {
2360       ais'2 cis, |
2361       fis8 b a4 cis2 |
2362     }
2363   >>
2364 }
2365
2366 musicB = {
2367   \clef bass
2368   \new Voice {
2369     \voiceTwo \relative {
2370       <fis a cis>8[ <fis a cis>
2371       \change Staff = up
2372       cis' cis
2373       \change Staff = down
2374       <fis, a> <fis a>]
2375       \showStaffSwitch
2376       \change Staff = up
2377       dis'4 |
2378       \change Staff = down
2379       <fis, a cis>4 gis <f a d>2 |
2380     }
2381   }
2382 }
2383
2384 \new PianoStaff {
2385   <<
2386     \context Staff = "up" {
2387       \accidentalStyle neo-modern
2388       \musicA
2389     }
2390     \context Staff = "down" {
2391       \accidentalStyle neo-modern
2392       \musicB
2393     }
2394   >>
2395 }
2396 @end lilypond
2397
2398 @item neo-modern-cautionary
2399
2400 @cindex neo-modern-cautionary accidental style
2401 @cindex accidental style, neo-modern-cautionary
2402
2403 @funindex neo-modern-cautionary
2404
2405 This rule is similar to @code{neo-modern}, but the @q{extra} accidentals
2406 are printed as cautionary accidentals (with parentheses).  They can also
2407 be printed at a different size by overriding
2408 @code{AccidentalCautionary}'s @code{font-size} property.
2409
2410 @lilypond[quote]
2411 musicA = {
2412   <<
2413     \relative {
2414       cis''8 fis, bes4 <a cis>8 f bis4 |
2415       cis2. <c, g'>4 |
2416     }
2417     \\
2418     \relative {
2419       ais'2 cis, |
2420       fis8 b a4 cis2 |
2421     }
2422   >>
2423 }
2424
2425 musicB = {
2426   \clef bass
2427   \new Voice {
2428     \voiceTwo \relative {
2429       <fis a cis>8[ <fis a cis>
2430       \change Staff = up
2431       cis' cis
2432       \change Staff = down
2433       <fis, a> <fis a>]
2434       \showStaffSwitch
2435       \change Staff = up
2436       dis'4 |
2437       \change Staff = down
2438       <fis, a cis>4 gis <f a d>2 |
2439     }
2440   }
2441 }
2442
2443 \new PianoStaff {
2444   <<
2445     \context Staff = "up" {
2446       \accidentalStyle neo-modern-cautionary
2447       \musicA
2448     }
2449     \context Staff = "down" {
2450       \accidentalStyle neo-modern-cautionary
2451       \musicB
2452     }
2453   >>
2454 }
2455 @end lilypond
2456
2457
2458 @item neo-modern-voice
2459
2460 @cindex neo-modern-voice accidental style
2461 @cindex accidental style, neo-modern-voice
2462
2463 @funindex neo-modern-voice
2464
2465 This rule is used for multivoice accidentals to be read both by
2466 musicians playing one voice and musicians playing all voices.
2467 Accidentals are typeset for each voice as with @code{neo-modern},
2468 but they are canceled across voices in the same @code{Staff}.
2469
2470 @lilypond[quote]
2471 musicA = {
2472   <<
2473     \relative {
2474       cis''8 fis, bes4 <a cis>8 f bis4 |
2475       cis2. <c, g'>4 |
2476     }
2477     \\
2478     \relative {
2479       ais'2 cis, |
2480       fis8 b a4 cis2 |
2481     }
2482   >>
2483 }
2484
2485 musicB = {
2486   \clef bass
2487   \new Voice {
2488     \voiceTwo \relative {
2489       <fis a cis>8[ <fis a cis>
2490       \change Staff = up
2491       cis' cis
2492       \change Staff = down
2493       <fis, a> <fis a>]
2494       \showStaffSwitch
2495       \change Staff = up
2496       dis'4 |
2497       \change Staff = down
2498       <fis, a cis>4 gis <f a d>2 |
2499     }
2500   }
2501 }
2502
2503 \new PianoStaff {
2504   <<
2505     \context Staff = "up" {
2506       \accidentalStyle neo-modern-voice
2507       \musicA
2508     }
2509     \context Staff = "down" {
2510       \accidentalStyle neo-modern-voice
2511       \musicB
2512     }
2513   >>
2514 }
2515 @end lilypond
2516
2517 @item neo-modern-voice-cautionary
2518
2519 @cindex neo-modern-voice-cautionary accidental style
2520 @cindex accidental style, neo-modern-voice-cautionary
2521
2522 @funindex neo-modern-voice-cautionary
2523
2524 This rule is similar to @code{neo-modern-voice}, but the extra
2525 accidentals are printed as cautionary accidentals.
2526
2527 @lilypond[quote]
2528 musicA = {
2529   <<
2530     \relative {
2531       cis''8 fis, bes4 <a cis>8 f bis4 |
2532       cis2. <c, g'>4 |
2533     }
2534     \\
2535     \relative {
2536       ais'2 cis, |
2537       fis8 b a4 cis2 |
2538     }
2539   >>
2540 }
2541
2542 musicB = {
2543   \clef bass
2544   \new Voice {
2545     \voiceTwo \relative {
2546       <fis a cis>8[ <fis a cis>
2547       \change Staff = up
2548       cis' cis
2549       \change Staff = down
2550       <fis, a> <fis a>]
2551       \showStaffSwitch
2552       \change Staff = up
2553       dis'4 |
2554       \change Staff = down
2555       <fis, a cis>4 gis <f a d>2 |
2556     }
2557   }
2558 }
2559
2560 \new PianoStaff {
2561   <<
2562     \context Staff = "up" {
2563       \accidentalStyle neo-modern-voice-cautionary
2564       \musicA
2565     }
2566     \context Staff = "down" {
2567       \accidentalStyle neo-modern-voice-cautionary
2568       \musicB
2569     }
2570   >>
2571 }
2572 @end lilypond
2573
2574 @item dodecaphonic
2575
2576 @cindex dodecaphonic accidental style
2577 @cindex dodecaphonic style, neo-modern
2578
2579 @funindex dodecaphonic
2580
2581 This rule reflects a practice introduced by composers at
2582 the beginning of the 20th century, in an attempt to
2583 abolish the hierarchy between natural and non-natural notes.
2584 With this style, @emph{every} note gets an accidental sign,
2585 including natural signs.
2586
2587 @lilypond[quote]
2588 musicA = {
2589   <<
2590     \relative {
2591       cis''8 fis, bes4 <a cis>8 f bis4 |
2592       cis2. <c, g'>4 |
2593     }
2594     \\
2595     \relative {
2596       ais'2 cis, |
2597       fis8 b a4 cis2 |
2598     }
2599   >>
2600 }
2601
2602 musicB = {
2603   \clef bass
2604   \new Voice {
2605     \voiceTwo \relative {
2606       <fis a cis>8[ <fis a cis>
2607       \change Staff = up
2608       cis' cis
2609       \change Staff = down
2610       <fis, a> <fis a>]
2611       \showStaffSwitch
2612       \change Staff = up
2613       dis'4 |
2614       \change Staff = down
2615       <fis, a cis>4 gis <f a d>2 |
2616     }
2617   }
2618 }
2619
2620 \new PianoStaff {
2621   <<
2622     \context Staff = "up" {
2623       \accidentalStyle dodecaphonic
2624       \musicA
2625     }
2626     \context Staff = "down" {
2627       \accidentalStyle dodecaphonic
2628       \musicB
2629     }
2630   >>
2631 }
2632 @end lilypond
2633
2634 @item dodecaphonic-no-repeat
2635
2636 @cindex dodecaphonic accidental style
2637 @cindex dodecaphonic style, neo-modern
2638
2639 @funindex dodecaphonic-no-repeat
2640
2641 Like with the dodecaphonic accidental style @emph{every} note
2642 gets an accidental sign by default, but accidentals are
2643 suppressed for pitches immediately repeated within the same staff.
2644
2645 @lilypond[quote]
2646 musicA = {
2647   <<
2648     \relative {
2649       cis''8 fis, bes4 <a cis>8 f bis4 |
2650       cis2. <c, g'>4 |
2651     }
2652     \\
2653     \relative {
2654       ais'2 cis, |
2655       fis8 b a4 cis2 |
2656     }
2657   >>
2658 }
2659
2660 musicB = {
2661   \clef bass
2662   \new Voice {
2663     \voiceTwo \relative {
2664       <fis a cis>8[ <fis a cis>
2665       \change Staff = up
2666       cis' cis
2667       \change Staff = down
2668       <fis, a> <fis a>]
2669       \showStaffSwitch
2670       \change Staff = up
2671       dis'4 |
2672       \change Staff = down
2673       <fis, a cis>4 gis <f a d>2 |
2674     }
2675   }
2676 }
2677
2678 \new PianoStaff {
2679   <<
2680     \context Staff = "up" {
2681       \accidentalStyle dodecaphonic-no-repeat
2682       \musicA
2683     }
2684     \context Staff = "down" {
2685       \accidentalStyle dodecaphonic-no-repeat
2686       \musicB
2687     }
2688   >>
2689 }
2690 @end lilypond
2691
2692
2693 @item dodecaphonic-first
2694
2695 @cindex dodecaphonic accidental style
2696 @cindex dodecaphonic style, neo-modern
2697
2698 @funindex dodecaphonic-first
2699
2700 Similar to the dodecaphonic accidental style @emph{every} pitch
2701 gets an accidental sign, but only the first time it is encountered
2702 in a measure.  Accidentals are only remembered for the actual octave
2703 but throughout voices.
2704
2705 @lilypond[quote]
2706 musicA = {
2707   <<
2708     \relative {
2709       cis''8 fis, bes4 <a cis>8 f bis4 |
2710       cis2. <c, g'>4 |
2711     }
2712     \\
2713     \relative {
2714       ais'2 cis, |
2715       fis8 b a4 cis2 |
2716     }
2717   >>
2718 }
2719
2720 musicB = {
2721   \clef bass
2722   \new Voice {
2723     \voiceTwo \relative {
2724       <fis a cis>8[ <fis a cis>
2725       \change Staff = up
2726       cis' cis
2727       \change Staff = down
2728       <fis, a> <fis a>]
2729       \showStaffSwitch
2730       \change Staff = up
2731       dis'4 |
2732       \change Staff = down
2733       <fis, a cis>4 gis <f a d>2 |
2734     }
2735   }
2736 }
2737
2738 \new PianoStaff {
2739   <<
2740     \context Staff = "up" {
2741       \accidentalStyle dodecaphonic-first
2742       \musicA
2743     }
2744     \context Staff = "down" {
2745       \accidentalStyle dodecaphonic-first
2746       \musicB
2747     }
2748   >>
2749 }
2750 @end lilypond
2751
2752
2753 @item teaching
2754
2755 @cindex teaching accidental style
2756 @cindex accidental style, teaching
2757
2758 @funindex teaching
2759
2760 This rule is intended for students, and makes it easy to create
2761 scale sheets with automatically created cautionary accidentals.
2762 Accidentals are printed like with @code{modern}, but cautionary
2763 accidentals are added for all sharp or flat tones specified by the
2764 key signature, except if the note is immediately repeated.
2765
2766 @lilypond[quote,staffsize=18]
2767 musicA = {
2768   <<
2769     \relative {
2770       cis''8 fis, bes4 <a cis>8 f bis4 |
2771       cis2. <c, g'>4 |
2772     }
2773     \\
2774     \relative {
2775       ais'2 cis, |
2776       fis8 b a4 cis2 |
2777     }
2778   >>
2779 }
2780
2781 musicB = {
2782   \clef bass
2783   \new Voice {
2784     \voiceTwo \relative {
2785       <fis a cis>8[ <fis a cis>
2786       \change Staff = up
2787       cis' cis
2788       \change Staff = down
2789       <fis, a> <fis a>]
2790       \showStaffSwitch
2791       \change Staff = up
2792       dis'4 |
2793       \change Staff = down
2794       <fis, a cis>4 gis <f a d>2 |
2795     }
2796   }
2797 }
2798
2799 \new PianoStaff {
2800   <<
2801     \context Staff = "up" {
2802       \key fis \minor
2803       \accidentalStyle teaching
2804       \musicA
2805     }
2806     \context Staff = "down" {
2807       \key fis \minor
2808       \accidentalStyle teaching
2809       \musicB
2810     }
2811   >>
2812 }
2813 @end lilypond
2814
2815
2816
2817 @item no-reset
2818
2819 @cindex accidental style, no reset
2820 @cindex no reset accidental style
2821
2822 @funindex no-reset
2823
2824 This is the same as @code{default} but with accidentals lasting
2825 @q{forever} and not only within the same measure:
2826
2827 @lilypond[quote]
2828 musicA = {
2829   <<
2830     \relative {
2831       cis''8 fis, bes4 <a cis>8 f bis4 |
2832       cis2. <c, g'>4 |
2833     }
2834     \\
2835     \relative {
2836       ais'2 cis, |
2837       fis8 b a4 cis2 |
2838     }
2839   >>
2840 }
2841
2842 musicB = {
2843   \clef bass
2844   \new Voice {
2845     \voiceTwo \relative {
2846       <fis a cis>8[ <fis a cis>
2847       \change Staff = up
2848       cis' cis
2849       \change Staff = down
2850       <fis, a> <fis a>]
2851       \showStaffSwitch
2852       \change Staff = up
2853       dis'4 |
2854       \change Staff = down
2855       <fis, a cis>4 gis <f a d>2 |
2856     }
2857   }
2858 }
2859
2860 \new PianoStaff {
2861   <<
2862     \context Staff = "up" {
2863       \accidentalStyle no-reset
2864       \musicA
2865     }
2866     \context Staff = "down" {
2867       \accidentalStyle no-reset
2868       \musicB
2869     }
2870   >>
2871 }
2872 @end lilypond
2873
2874 @item forget
2875
2876 @cindex forget accidental style
2877 @cindex accidental style, forget
2878
2879 @funindex forget
2880
2881 This is the opposite of @code{no-reset}: Accidentals are not
2882 remembered at all -- and hence all accidentals are typeset
2883 relative to the key signature, regardless of what came before in
2884 the music.
2885
2886 @lilypond[quote]
2887 musicA = {
2888   <<
2889     \relative {
2890       cis''8 fis, bes4 <a cis>8 f bis4 |
2891       cis2. <c, g'>4 |
2892     }
2893     \\
2894     \relative {
2895       ais'2 cis, |
2896       fis8 b a4 cis2 |
2897     }
2898   >>
2899 }
2900
2901 musicB = {
2902   \clef bass
2903   \new Voice {
2904     \voiceTwo \relative {
2905       <fis a cis>8[ <fis a cis>
2906       \change Staff = up
2907       cis' cis
2908       \change Staff = down
2909       <fis, a> <fis a>]
2910       \showStaffSwitch
2911       \change Staff = up
2912       dis'4 |
2913       \change Staff = down
2914       <fis, a cis>4 gis <f a d>2 |
2915     }
2916   }
2917 }
2918
2919 \new PianoStaff {
2920   <<
2921     \context Staff = "up" {
2922       \accidentalStyle forget
2923       \musicA
2924     }
2925     \context Staff = "down" {
2926       \accidentalStyle forget
2927       \musicB
2928     }
2929   >>
2930 }
2931 @end lilypond
2932 @end table
2933
2934 @seealso
2935 Snippets:
2936 @rlsr{Pitches}.
2937
2938 Internals Reference:
2939 @rinternals{Accidental},
2940 @rinternals{Accidental_engraver},
2941 @rinternals{GrandStaff},
2942 @rinternals{PianoStaff},
2943 @rinternals{Staff},
2944 @rinternals{AccidentalSuggestion},
2945 @rinternals{AccidentalPlacement},
2946 @rinternals{accidental-suggestion-interface}.
2947
2948 @cindex accidentals and simultaneous notes
2949 @cindex simultaneous notes and accidentals
2950 @cindex accidentals in chords
2951 @cindex chords, accidentals in
2952
2953 @knownissues
2954 Simultaneous notes are not considered in the automatic
2955 determination of accidentals; only previous notes and the key
2956 signature are considered.  Forcing accidentals with@tie{}@code{!}
2957 or@tie{}@code{?} may be required when the same note name occurs
2958 simultaneously with different alterations, as in @samp{<f! fis!>}.
2959
2960 Cautionary cancellation of accidentals is done by looking at previous measure.
2961 However, in the @code{\alternative} block following a @code{\repeat volta N}
2962 section, one would expect the cancellation being calculated using the previous
2963 @emph{played} measure, not previous @emph{printed} measure.
2964 In the following example, the natural @code{c} in the second alternative does
2965 not need a natural sign:
2966
2967 @lilypond[quote]
2968 {
2969   \accidentalStyle modern
2970   \time 2/4
2971   \repeat volta 2 {
2972     c'2
2973   }
2974   \alternative {
2975      cis'
2976      c'
2977   }
2978 }
2979 @end lilypond
2980
2981 The following work-around can be used: define a function that locally changes
2982 the accidental style to @code{forget}:
2983
2984 @lilypond[verbatim,quote]
2985 forget = #(define-music-function (music) (ly:music?) #{
2986   \accidentalStyle forget
2987   #music
2988   \accidentalStyle modern
2989 #})
2990 {
2991   \accidentalStyle modern
2992   \time 2/4
2993   \repeat volta 2 {
2994     c'2
2995   }
2996   \alternative {
2997      cis'
2998      \forget c'
2999   }
3000 }
3001 @end lilypond
3002
3003
3004 @node Ambitus
3005 @unnumberedsubsubsec Ambitus
3006
3007 @cindex ambitus
3008 @cindex range of pitches
3009 @cindex pitch range
3010
3011 The term @notation{ambitus} (pl. ambitus) denotes a range of
3012 pitches for a given voice in a part of music.  It may also denote
3013 the pitch range that a musical instrument is capable of playing.
3014 Ambitus are printed on vocal parts so that performers can easily
3015 determine if it matches their capabilities.
3016
3017 Ambitus are denoted at the beginning of a piece near the initial
3018 clef.  The range is graphically specified by two note heads that
3019 represent the lowest and highest pitches.  Accidentals are only
3020 printed if they are not part of the key signature.
3021
3022 @lilypond[verbatim,quote]
3023 \layout {
3024   \context {
3025     \Voice
3026     \consists "Ambitus_engraver"
3027   }
3028 }
3029
3030 \relative {
3031   aes' c e2
3032   cis,1
3033 }
3034 @end lilypond
3035
3036
3037 @snippets
3038
3039 @lilypondfile[verbatim,quote,texidoc,doctitle]
3040 {adding-ambitus-per-voice.ly}
3041
3042 @lilypondfile[verbatim,quote,texidoc,doctitle]
3043 {ambitus-with-multiple-voices.ly}
3044
3045 @lilypondfile[verbatim,quote,texidoc,doctitle]
3046 {changing-the-ambitus-gap.ly}
3047
3048 @seealso
3049 Music Glossary:
3050 @rglos{ambitus}.
3051
3052 Snippets:
3053 @rlsr{Pitches}.
3054
3055 Internals Reference:
3056 @rinternals{Ambitus_engraver},
3057 @rinternals{Voice},
3058 @rinternals{Staff},
3059 @rinternals{Ambitus},
3060 @rinternals{AmbitusAccidental},
3061 @rinternals{AmbitusLine},
3062 @rinternals{AmbitusNoteHead},
3063 @rinternals{ambitus-interface}.
3064
3065 @knownissues
3066 There is no collision handling in the case of multiple per-voice
3067 ambitus.
3068
3069
3070 @node Note heads
3071 @subsection Note heads
3072
3073 This section suggests ways of altering note heads.
3074
3075 @menu
3076 * Special note heads::
3077 * Easy notation note heads::
3078 * Shape note heads::
3079 * Improvisation::
3080 @end menu
3081
3082 @node Special note heads
3083 @unnumberedsubsubsec Special note heads
3084
3085 @cindex note heads, special
3086 @cindex note heads, cross
3087 @cindex note heads, diamond
3088 @cindex note heads, parlato
3089 @cindex note heads, harmonic
3090 @cindex note heads, guitar
3091 @cindex special note heads
3092 @cindex cross note heads
3093 @cindex diamond note heads
3094 @cindex parlato note heads
3095 @cindex harmonic note heads
3096 @cindex guitar note heads
3097 @cindex note head styles
3098 @cindex styles, note heads
3099
3100 @funindex cross
3101
3102 The appearance of note heads may be altered:
3103
3104 @lilypond[verbatim,quote]
3105 \relative c'' {
3106   c4 b
3107   \override NoteHead.style = #'cross
3108   c4 b
3109   \revert NoteHead.style
3110   a b
3111   \override NoteHead.style = #'harmonic
3112   a b
3113   \revert NoteHead.style
3114   c4 d e f
3115 }
3116 @end lilypond
3117
3118 To see all note head styles, see @ref{Note head styles}.
3119
3120 The @code{cross} style is used to represent a variety of musical
3121 intentions.  The following generic predefined commands modify the
3122 note head in both staff and tablature contexts and can be used to
3123 represent any musical meaning:
3124
3125 @lilypond[verbatim,quote]
3126 \relative {
3127   c''4 b
3128   \xNotesOn
3129    a b c4 b
3130   \xNotesOff
3131   c4 d
3132 }
3133 @end lilypond
3134
3135 The music function form of this predefined command may be used
3136 inside and outside chords to generate crossed note heads in both
3137 staff and tablature contexts:
3138
3139 @lilypond[verbatim,quote]
3140 \relative {
3141   c''4 b
3142   \xNote { e f }
3143   c b < g \xNote c f > b
3144 }
3145 @end lilypond
3146
3147 As synonyms for @code{\xNote}, @code{\xNotesOn} and @code{\xNotesOff},
3148 @code{\deadNote}, @code{\deadNotesOn} and @code{\deadNotesOff} can
3149 be used.  The term @notation{dead note} is commonly used by guitarists.
3150
3151 There is also a similar shorthand for diamond shapes:
3152
3153 @lilypond[verbatim,quote]
3154 \relative c'' {
3155   <c f\harmonic>2 <d a'\harmonic>4 <c g'\harmonic> f\harmonic
3156 }
3157 @end lilypond
3158
3159 @predefined
3160 @code{\harmonic},
3161 @code{\xNotesOn},
3162 @code{\xNotesOff},
3163 @code{\xNote}.
3164 @endpredefined
3165
3166 @seealso
3167 Snippets:
3168 @rlsr{Pitches}.
3169
3170 Notation Reference:
3171 @ref{Note head styles},
3172 @ref{Chorded notes},
3173 @ref{Indicating harmonics and dampened notes}.
3174
3175 Internals Reference:
3176 @rinternals{note-event},
3177 @rinternals{Note_heads_engraver},
3178 @rinternals{Ledger_line_engraver},
3179 @rinternals{NoteHead},
3180 @rinternals{LedgerLineSpanner},
3181 @rinternals{note-head-interface},
3182 @rinternals{ledger-line-spanner-interface}.
3183
3184
3185 @node Easy notation note heads
3186 @unnumberedsubsubsec Easy notation note heads
3187
3188 @cindex note heads, practice
3189 @cindex practice note heads
3190 @cindex note heads, easy notation
3191 @cindex easy notation
3192 @cindex beginners' music
3193 @cindex music, beginners'
3194 @cindex easy play note heads
3195 @cindex note heads, easy play
3196
3197 @funindex \easyHeadsOn
3198 @funindex \easyHeadsOff
3199
3200 The @q{easy play} note head includes a note name inside the head.
3201 It is used in music for beginners.  To make the letters readable,
3202 it should be printed in a large font size.  To print with a larger
3203 font, see @ref{Setting the staff size}.
3204
3205 @lilypond[verbatim,quote]
3206 #(set-global-staff-size 26)
3207 \relative c' {
3208   \easyHeadsOn
3209   c2 e4 f
3210   g1
3211   \easyHeadsOff
3212   c,1
3213 }
3214 @end lilypond
3215
3216
3217 @predefined
3218 @code{\easyHeadsOn},
3219 @code{\easyHeadsOff}.
3220 @endpredefined
3221
3222
3223 @snippets
3224
3225 @lilypondfile[verbatim,quote,texidoc,doctitle]
3226 {numbers-as-easy-note-heads.ly}
3227
3228 @seealso
3229 Notation Reference:
3230 @ref{Setting the staff size}.
3231
3232 Snippets:
3233 @rlsr{Pitches}.
3234
3235 Internals Reference:
3236 @rinternals{note-event},
3237 @rinternals{Note_heads_engraver},
3238 @rinternals{NoteHead},
3239 @rinternals{note-head-interface}.
3240
3241
3242 @node Shape note heads
3243 @unnumberedsubsubsec Shape note heads
3244
3245 @cindex note heads, shape
3246 @cindex note heads, Aiken
3247 @cindex note heads, sacred harp
3248 @cindex shape notes
3249 @cindex Aiken shape note heads
3250 @cindex sacred harp note heads
3251 @cindex note heads, Southern Harmony
3252 @cindex Southern Harmony note heads
3253 @cindex Funk shape note heads
3254 @cindex note heads, Funk
3255 @cindex note heads, Harmonica Sacra
3256 @cindex Harmonica Sacra note heads
3257 @cindex Christian Harmony note heads
3258 @cindex note heads, Christian Harmony
3259 @cindex Walker shape note heads
3260 @cindex note heads, Walker
3261
3262 @funindex \aikenHeads
3263 @funindex \sacredHarpHeads
3264 @funindex \southernHarmonyHeads
3265 @funindex \funkHeads
3266 @funindex \walkerHeads
3267
3268 In shape note head notation, the shape of the note head
3269 corresponds to the harmonic function of a note in the scale.  This
3270 notation was popular in nineteenth-century American song books.
3271 Shape note heads can be produced in Sacred Harp, Southern Harmony,
3272 Funk (Harmonica Sacra), Walker, and Aiken (Christian Harmony) styles:
3273
3274 @lilypond[verbatim,quote]
3275 \relative c'' {
3276   \aikenHeads
3277   c, d e f g2 a b1 c \break
3278   \sacredHarpHeads
3279   c,4 d e f g2 a b1 c \break
3280   \southernHarmonyHeads
3281   c,4 d e f g2 a b1 c \break
3282   \funkHeads
3283   c,4 d e f g2 a b1 c \break
3284   \walkerHeads
3285   c,4 d e f g2 a b1 c \break
3286 }
3287 @end lilypond
3288
3289 @funindex \key
3290 @funindex \aikenHeadsMinor
3291 @funindex \sacredHarpHeadsMinor
3292 @funindex \southernHarmonyHeadsMinor
3293 @funindex \funkHeadsMinor
3294 @funindex \walkerHeadsMinor
3295
3296 Shapes are typeset according to the step in the scale, where the base
3297 of the scale is determined by the @code{\key} command.  When writing
3298 in a minor key, the scale step can be determined from the relative
3299 major:
3300
3301 @lilypond[verbatim,quote]
3302 \relative c'' {
3303   \key a \minor
3304   \aikenHeads
3305   a b c d e2 f g1 a \break
3306   \aikenHeadsMinor
3307   a,4 b c d e2 f g1 a \break
3308   \sacredHarpHeadsMinor
3309   a,2 b c d \break
3310   \southernHarmonyHeadsMinor
3311   a2 b c d \break
3312   \funkHeadsMinor
3313   a2 b c d \break
3314   \walkerHeadsMinor
3315   a2 b c d \break
3316 }
3317 @end lilypond
3318
3319
3320 @predefined
3321 @code{\aikenHeads},
3322 @code{\aikenHeadsMinor},
3323 @code{\funkHeads},
3324 @code{\funkHeadsMinor},
3325 @code{\sacredHarpHeads},
3326 @code{\sacredHarpHeadsMinor},
3327 @code{\southernHarmonyHeads},
3328 @code{\southernHarmonyHeadsMinor},
3329 @code{\walkerHeads},
3330 @code{\walkerHeadsMinor}.
3331 @endpredefined
3332
3333
3334 @snippets
3335
3336 @lilypondfile[verbatim,quote,texidoc,doctitle]
3337 {applying-note-head-styles-depending-on-the-step-of-the-scale.ly}
3338
3339 To see all note head styles, see @ref{Note head styles}.
3340
3341 @seealso
3342 Snippets:
3343 @rlsr{Pitches}.
3344
3345 Notation Reference:
3346 @ref{Note head styles}.
3347
3348 Internals Reference:
3349 @rinternals{note-event},
3350 @rinternals{Note_heads_engraver},
3351 @rinternals{NoteHead},
3352 @rinternals{note-head-interface}.
3353
3354
3355 @node Improvisation
3356 @unnumberedsubsubsec Improvisation
3357
3358 @cindex improvisation
3359 @cindex slashed note heads
3360 @cindex note heads, improvisation
3361 @cindex note heads, slashed
3362
3363 @funindex \improvisationOn
3364 @funindex \improvisationOff
3365
3366 Improvisation is sometimes denoted with slashed note heads, where
3367 the performer may choose any pitch but should play the specified
3368 rhythm.  Such note heads can be created:
3369
3370 @lilypond[verbatim,quote]
3371 \new Voice \with {
3372   \consists "Pitch_squash_engraver"
3373 } \relative {
3374   e''8 e g a a16( bes) a8 g
3375   \improvisationOn
3376   e8 ~
3377   2 ~ 8 f4 f8 ~
3378   2
3379   \improvisationOff
3380   a16( bes) a8 g e
3381 }
3382 @end lilypond
3383
3384 @predefined
3385 @code{\improvisationOn},
3386 @code{\improvisationOff}.
3387 @endpredefined
3388
3389 @seealso
3390 Snippets:
3391 @rlsr{Pitches}.
3392
3393 Internals Reference:
3394 @rinternals{Pitch_squash_engraver},
3395 @rinternals{Voice},
3396 @rinternals{RhythmicStaff}.