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