LilyPond Notation Reference: 1.1.3 Displaying pitches

### 1.1.3 Displaying pitches

This section discusses how to alter the output of pitches.

#### Clef

Without any explicit command, the default clef for LilyPond is the treble (or G) clef.

>     c'2 c'

However, the clef can be changed by using the `\clef` command and an appropriate clef name. Middle C is shown in each of the following examples.

>     \clef treble
>     c'2 c'
>     \clef alto
>     c'2 c'
>     \clef tenor
>     c'2 c'
>     \clef bass
>     c'2 c'

For the full range of possible clef names see Clef styles.

Specialized clefs, such as those used in Ancient music, are described in Mensural clefs and Gregorian clefs. Music that requires tablature clefs is discussed in Default tablatures and Custom tablatures.

For mixing clefs when using cue notes, see the `\cueClef` and `\cueDuringWithClef` commands in Formatting cue notes.

By adding `_8` or `^8` to the clef name, the clef is transposed one octave down or up respectively, and `_15` and `^15` transpose by two octaves. Other integers can be used if required. Clef names containing non-alphabetic characters must be enclosed in quotes

>     \clef treble
>     c'2 c'
>     \clef "treble_8"
>     c'2 c'
>     \clef "bass^15"
>     c'2 c'
>     \clef "alto_2"
>     c'2 c'
>     \clef "G_8"
>     c'2 c'
>     \clef "F^5"
>     c'2 c'

Optional octavation can be obtained by enclosing the numeric argument in parentheses or brackets:

>     \clef "treble_(8)"
>     c'2 c'
>     \clef "bass^[15]"
>     c'2 c'

The pitches are displayed as if the numeric argument were given without parentheses/brackets.

By default, a clef change taking place at a line break will cause the new clef symbol to be printed at the end of the previous line, as a warning clef, as well as the beginning of the next. This warning clef can be suppressed.

>     \clef treble { c'2 c' } \break
>     \clef bass { c'2 c' } \break
>     \clef alto
>       \set Staff.explicitClefVisibility = #end-of-line-invisible
>       { c'2 c' } \break
>       \unset Staff.explicitClefVisibility
>     \clef bass { c'2 c' } \break

By default, a clef that has previously been printed will not be re-printed if the same `\clef` command is issued again and will be ignored. The command `\set Staff.forceClef = ##t` changes this behaviour.

>       \clef treble
>       c'1
>       \clef treble
>       c'1
>       \set Staff.forceClef = ##t
>       c'1
>       \clef treble
>       c'1

To be more precise, it is not the `\clef` command itself that prints a clef. Instead, it sets or changes a property of the `Clef_engraver`, which then decides by its own whether to display a clef or not in the current staff. The `forceClef` property overrides this decision locally to re-print a clef once.

When there is a manual clef change, the glyph of the changed clef will be smaller than normal. This behaviour can be overridden.

>       \clef "treble"
>       c'1
>       \clef "bass"
>       c'1
>       \clef "treble"
>       c'1
>       \override Staff.Clef.full-size-change = ##t
>       \clef "bass"
>       c'1
>       \clef "treble"
>       c'1
>       \revert Staff.Clef.full-size-change
>       \clef "bass"
>       c'1
>       \clef "treble"
>       c'1

#### Selected Snippets

Tweaking clef properties

Changing the Clef glyph, its position, or the ottavation does not change the position of subsequent notes on the staff. To get key signatures on their correct staff lines `middleCClefPosition` must also be specified, with positive or negative values moving `middle C` up or down respectively, relative to the staff’s center line.

For example, `\clef "treble_8"` is equivalent to setting the `clefGlyph`, `clefPosition` (the vertical position of the clef itself on the staff), `middleCPosition` and `clefTransposition`. Note that when any of these properties (except `middleCPosition`) are changed a new clef symbol is printed.

The following examples show the possibilities when setting these properties manually. On the first line, the manual changes preserve the standard relative positioning of clefs and notes, whereas on the second line, they do not.

>     {
>       % The default treble clef
>       \key f \major
>       c'1
>       % The standard bass clef
>       \set Staff.clefGlyph = #"clefs.F"
>       \set Staff.clefPosition = #2
>       \set Staff.middleCPosition = #6
>       \set Staff.middleCClefPosition = #6
>       \key g \major
>       c'1
>       % The baritone clef
>       \set Staff.clefGlyph = #"clefs.C"
>       \set Staff.clefPosition = #4
>       \set Staff.middleCPosition = #4
>       \set Staff.middleCClefPosition = #4
>       \key f \major
>       c'1
>       % The standard choral tenor clef
>       \set Staff.clefGlyph = #"clefs.G"
>       \set Staff.clefPosition = #-2
>       \set Staff.clefTransposition = #-7
>       \set Staff.middleCPosition = #1
>       \set Staff.middleCClefPosition = #1
>       \key f \major
>       c'1
>       % A non-standard clef
>       \set Staff.clefPosition = #0
>       \set Staff.clefTransposition = #0
>       \set Staff.middleCPosition = #-4
>       \set Staff.middleCClefPosition = #-4
>       \key g \major
>       c'1 \break

>       % The following clef changes do not preserve
>       % the normal relationship between notes, key signatures
>       % and clefs:

>       \set Staff.clefGlyph = #"clefs.F"
>       \set Staff.clefPosition = #2
>       c'1
>       \set Staff.clefGlyph = #"clefs.G"
>       c'1
>       \set Staff.clefGlyph = #"clefs.C"
>       c'1
>       \set Staff.clefTransposition = #7
>       c'1
>       \set Staff.clefTransposition = #0
>       \set Staff.clefPosition = #0
>       c'1

>       % Return to the normal clef:

>       \set Staff.middleCPosition = #0
>       c'1
>     }

#### See also

Notation Reference: Mensural clefs, Gregorian clefs, Default tablatures, Custom tablatures, Formatting cue notes.

Installed Files: ‘`scm/parser-clef.scm`’.

Snippets: Pitches.

Internals Reference: Clef_engraver, Clef, ClefModifier, clef-interface.

#### Known issues and warnings

Ottavation numbers attached to clefs are treated as separate grobs. So any `\override` done to the Clef will also need to be applied, as a separate `\override`, to the ClefModifier grob.

>     \new Staff \with {
>       \override Clef.color = #blue
>       \override ClefModifier.color = #red
>     }

>     \clef "treble_8" c'4

#### Key signature

Note: New users are sometimes confused about accidentals and key signatures. In LilyPond, note names are the raw input; key signatures and clefs determine how this raw input is displayed. An unaltered note like `c` means ‘C natural’, regardless of the key signature or clef. For more information, see Pitches and key signatures.

The key signature indicates the tonality in which a piece is played. It is denoted by a set of alterations (flats or sharps) at the start of the staff. The key signature may be altered:

>     \key pitch mode

Here, `mode` should be `\major` or `\minor` to get a key signature of `pitch`-major or `pitch`-minor, respectively. You may also use the standard mode names, also called church modes: `\ionian`, `\dorian`, `\phrygian`, `\lydian`, `\mixolydian`, `\aeolian`, and `\locrian`.

>     \relative {
>       \key g \major
>       fis''1
>       f
>       fis
>     }

Additional modes can be defined, by listing the alterations for each scale step when the mode starts on C.

>     freygish = #`((0 . ,NATURAL) (1 . ,FLAT) (2 . ,NATURAL)
>         (3 . ,NATURAL) (4 . ,NATURAL) (5 . ,FLAT) (6 . ,FLAT))

>     \relative {
>       \key c \freygish c'4 des e f
>       \bar "||" \key d \freygish d es fis g
>     }

Accidentals in the key signature may be printed in octaves other than their traditional positions, or in multiple octaves, by using the `flat-positions` and `sharp-positions` properties of `KeySignature`. Entries in these properties specify the range of staff-positions where accidentals will be printed. If a single position is specified in an entry, the accidentals are placed within the octave ending at that staff position.

>     \override Staff.KeySignature.flat-positions = #'((-5 . 5))
>     \override Staff.KeyCancellation.flat-positions = #'((-5 . 5))
>     \clef bass \key es \major es g bes d'
>     \clef treble \bar "||" \key es \major es' g' bes' d''

>     \override Staff.KeySignature.sharp-positions = #'(2)
>     \bar "||" \key b \major b' fis' b'2

#### Selected Snippets

Preventing natural signs from being printed when the key signature changes

When the key signature changes, natural signs are automatically printed to cancel any accidentals from previous key signatures. This may be prevented by setting to `f` the `printKeyCancellation` property in the `Staff` context.

>     \relative c' {
>       \key d \major
>       a4 b cis d
>       \key g \minor
>       a4 bes c d
>       \set Staff.printKeyCancellation = ##f
>       \key d \major
>       a4 b cis d
>       \key g \minor
>       a4 bes c d
>     }

Non-traditional key signatures

The commonly used `\key` command sets the `keyAlterations` property in the `Staff` context. To create non-standard key signatures, set this property directly.

The format of this command is a list:

`\set Staff.keyAlterations = #`(((octave . step) . alter) ((octave . step) . alter) ...)`

where, for each element in the list `octave` specifies the octave (0 being the octave from middle c to the b above), `step` specifies the note within the octave (0 means c and 6 means b), and `alter` is `,SHARP ,FLAT ,DOUBLE-SHARP` etc.

Alternatively, using the more concise format for each item in the list, `(step . alter)` specifies the same alteration holds in all octaves. For microtonal scales where a “sharp” is not 100 cents, `alter` refers to the proportion of a 200-cent whole tone.

>     \include "arabic.ly"
>     \relative do' {
>       \set Staff.keyAlterations = #`((0 . ,SEMI-FLAT)
>                                      (1 . ,SEMI-FLAT)
>                                      (2 . ,FLAT)
>                                      (5 . ,FLAT)
>                                      (6 . ,SEMI-FLAT))
>     %\set Staff.extraNatural = ##f
>       re reb \dwn reb resd
>       dod dob dosd \dwn dob |
>       dobsb dodsd do do |
>     }

#### See also

Music Glossary: church mode, scordatura.

Learning Manual: Pitches and key signatures.

Snippets: Pitches.

Internals Reference: KeyChangeEvent, Key_engraver, Key_performer, KeyCancellation, KeySignature, key-signature-interface.

#### Ottava brackets

Ottava brackets introduce an extra transposition of an octave for the staff:

>     \relative c'' {
>       a2 b
>       \ottava #-2
>       a2 b
>       \ottava #-1
>       a2 b
>       \ottava #0
>       a2 b
>       \ottava #1
>       a2 b
>       \ottava #2
>       a2 b
>     }

By default, only a number is printed at the start of the bracket. That setting may be changed to include an abbreviated ordinal, either in superscript or in normal letters (the latter was formerly used by default); the default bold font weight of these characters may also be altered, as explained in Selecting font and font size.

The following example demonstrates various options, as well as how to go back to the current default behavior:

>     \relative c'' {
>       \ottava #1
>       a'2 b
>       \ottava #2
>       a'2 b
>       \bar "||"
>       \set Staff.ottavationMarkups = #ottavation-ordinals
>       \ottava #1
>       a,2 b
>       \ottava #2
>       a'2 b
>       \bar "||"
>       \override Staff.OttavaBracket.font-series = #'medium
>       \set Staff.ottavationMarkups = #ottavation-simple-ordinals
>       \ottava #1
>       a,2 b
>       \ottava #2
>       a'2 b
>       \bar "||"
>       \revert Staff.OttavaBracket.font-series
>       \set Staff.ottavationMarkups = #ottavation-numbers
>       \ottava #1
>       a,2 b
>       \ottava #2
>       a'2 b
>     }

#### Selected Snippets

Changing ottava text

Internally, `\ottava` sets the properties `ottavation` (for example, to `8va` or `8vb`) and `middleCPosition`. To override the text of the bracket, set `ottavation` after invoking `\ottava`.

Short text is especially useful when a brief ottava is used.

>     {
>       c'2
>       \ottava #1
>       \set Staff.ottavation = #"8"
>       c''2
>       \ottava #0
>       c'1
>       \ottava #1
>       \set Staff.ottavation = #"Text"
>       c''1
>     }

Adding an ottava marking to a single voice

If you have more than one voice on the staff, setting octavation in one voice will transpose the position of notes in all voices for the duration of the ottava bracket. If the ottavation is only intended to apply to one voice, the middleCPosition and ottava bracket may be set explicitly. In this snippet, the bass clef usually has middleCPosition set to 6, six positions above the center line, so in the 8va portion middleCPosition is 7 positions (one octave) higher still.

>     {
>       \clef bass
>       << { <g d'>1~ q2 <c' e'> }
>       \\
>         {
>           r2.
>           \set Staff.ottavation = #"8vb"
>           \once \override Staff.OttavaBracket.direction = #DOWN
>           \set Voice.middleCPosition = #(+ 6 7)
>           <b,,, b,,>4 ~ |
>           q2
>           \unset Staff.ottavation
>           \unset Voice.middleCPosition
>           <c e>2
>         }
>       >>
>     }

Modifying the Ottava spanner slope

It is possible to change the slope of the Ottava spanner.

>     \relative c'' {
>       \override Staff.OttavaBracket.stencil = #ly:line-spanner::print
>       \override Staff.OttavaBracket.bound-details =
>         #`((left . ((Y . 0) ; Change the integer here
>                     (attach-dir . ,LEFT)
>                     (padding . 0)
>                     (stencil-align-dir-y . ,CENTER)))
>            (right . ((Y . 5) ; Change the integer here
>                      (padding . 0)
>                      (attach-dir . ,RIGHT)
>                      (text . ,(make-draw-dashed-line-markup
>                                (cons 0 -1.2))))))
>       \override Staff.OttavaBracket.left-bound-info =
>          #ly:line-spanner::calc-left-bound-info-and-text
>       \override Staff.OttavaBracket.right-bound-info =
>          #ly:line-spanner::calc-right-bound-info
>       \ottava #1
>       c1
>       c'''1
>     }

#### See also

Music Glossary: octavation.

Notation Reference: Selecting font and font size.

Snippets: Pitches.

Internals Reference: Ottava_spanner_engraver, OttavaBracket, ottava-bracket-interface.

#### Instrument transpositions

When typesetting scores that involve transposing instruments, some parts can be typeset in a different pitch than the concert pitch. In these cases, the key of the transposing instrument should be specified; otherwise the MIDI output and cues in other parts will produce incorrect pitches. For more information about quotations, see Quoting other voices.

>     \transposition pitch

The pitch to use for `\transposition` should correspond to the real sound heard when a `c'` written on the staff is played by the transposing instrument. This pitch is entered in absolute mode, so an instrument that produces a real sound which is one tone higher than the printed music should use `\transposition d'`. `\transposition` should only be used if the pitches are not being entered in concert pitch.

Here are a few notes for violin and B-flat clarinet where the parts have been entered using the notes and key as they appear in each part of the conductor’s score. The two instruments are playing in unison.

>     \new GrandStaff <<
>       \new Staff = "violin" \with {
>         instrumentName = "Vln"
>         midiInstrument = "violin"
>       }
>       \relative c'' {
>         % not strictly necessary, but a good reminder
>         \transposition c'
>         \key c \major
>         g4( c8) r c r c4
>       }
>       \new Staff = "clarinet" \with {
>         instrumentName = \markup { Cl (B\flat) }
>         midiInstrument = "clarinet"
>       }
>       \relative c'' {
>         \transposition bes
>         \key d \major
>         a4( d8) r d r d4
>       }
>     >>

The `\transposition` may be changed during a piece. For example, a clarinetist may be required to switch from an A clarinet to a B-flat clarinet.

>     flute = \relative c'' {
>       \key f \major
>       \cueDuring "clarinet" #DOWN {
>         R1 _\markup\tiny "clarinet"
>         c4 f e d
>         R1 _\markup\tiny "clarinet"
>       }
>     }
>     clarinet = \relative c'' {
>       \key aes \major
>       \transposition a
>       aes4 bes c des
>       R1^\markup { muta in B\flat }
>       \key g \major
>       \transposition bes
>       d2 g,
>     }
>     \addQuote "clarinet" \clarinet
>     <<
>       \new Staff \with { instrumentName = "Flute" }
>         \flute
>       \new Staff \with { instrumentName = "Cl (A)" }
>         \clarinet
>     >>

#### See also

Music Glossary: concert pitch, transposing instrument.

Notation Reference: Quoting other voices, Transpose.

Snippets: Pitches.

#### Automatic accidentals

There are many different conventions on how to typeset accidentals. LilyPond provides a function to specify which accidental style to use. This function is called as follows:

>     \new Staff <<
>       \accidentalStyle voice
>       { … }
>     >>

The accidental style applies to the current `Staff` by default (with the exception of the styles `piano` and `piano-cautionary`, which are explained below). Optionally, the function can take a second argument that determines in which scope the style should be changed. For example, to use the same style in all staves of the current `StaffGroup`, use:

>     \accidentalStyle StaffGroup.voice

The following accidental styles are supported. To demonstrate each style, we use the following example:

>     musicA = {
>       <<
>         \relative {
>           cis''8 fis, bes4 <a cis>8 f bis4 |
>           cis2. <c, g'>4 |
>         }
>         \\
>         \relative {
>           ais'2 cis, |
>           fis8 b a4 cis2 |
>         }
>       >>
>     }

>     musicB = {
>       \clef bass
>       \new Voice {
>         \voiceTwo \relative {
>           <fis a cis>8[ <fis a cis>
>           \change Staff = up
>           cis' cis
>           \change Staff = down
>           <fis, a> <fis a>]
>           \showStaffSwitch
>           \change Staff = up
>           dis'4 |
>           \change Staff = down
>           <fis, a cis>4 gis <f a d>2 |
>         }
>       }
>     }

>     \new PianoStaff {
>       <<
>         \new Staff = "up" {
>           \accidentalStyle default
>           \musicA
>         }
>         \new Staff = "down" {
>           \accidentalStyle default
>           \musicB
>         }
>       >>
>     }

Note that the last lines of this example can be replaced by the following, as long as the same accidental style should be used in both staves.

>     \new PianoStaff {
>       <<
>         \new Staff = "up" {
>           %%% change the next line as desired:
>           \accidentalStyle Score.default
>           \musicA
>         }
>         \new Staff = "down" {
>           \musicB
>         }
>       >>
>     }

`default`

  This is the default typesetting behavior. It corresponds to eighteenth-century common practice: accidentals are remembered to the end of the measure in which they occur and only in their own octave. Thus, in the example below, no natural signs are printed before the `b` in the second measure or the last `c`:

`voice`

  The normal behavior is to remember the accidentals at `Staff`-level. In this style, however, accidentals are typeset individually for each voice. Apart from that, the rule is similar to `default`.

  As a result, accidentals from one voice do not get canceled in other voices, which is often an unwanted result: in the following example, it is hard to determine whether the second `a` should be played natural or sharp. The `voice` option should therefore be used only if the voices are to be read solely by individual musicians. If the staff is to be used by one musician (e.g., a conductor or in a piano score) then `modern` or `modern-cautionary` should be used instead.

`modern`

  This rule corresponds to the common practice in the twentieth century. It omits some extra natural signs, which were traditionally prefixed to a sharp following a double sharp, or a flat following a double flat. The `modern` rule prints the same accidentals as `default`, with two additions that serve to avoid ambiguity: after temporary accidentals, cancellation marks are printed also in the following measure (for notes in the same octave) and, in the same measure, for notes in other octaves. Hence the naturals before the `b` and the `c` in the second measure of the upper staff:

`modern-cautionary`

  This rule is similar to `modern`, but the ‘extra’ accidentals are printed as cautionary accidentals (with parentheses). They can also be printed at a different size by overriding `AccidentalCautionary`’s `font-size` property.

`modern-voice`

  This rule is used for multivoice accidentals to be read both by musicians playing one voice and musicians playing all voices. Accidentals are typeset for each voice, but they are canceled across voices in the same `Staff`. Hence, the `a` in the last measure is canceled because the previous cancellation was in a different voice, and the `d` in the lower staff is canceled because of the accidental in a different voice in the previous measure:

`modern-voice-cautionary`

  This rule is the same as `modern-voice`, but with the extra accidentals (the ones not typeset by `voice`) typeset as cautionaries. Even though all accidentals typeset by `default` are typeset with this rule, some of them are typeset as cautionaries.

`piano`

  This rule reflects twentieth-century practice for piano notation. Its behavior is very similar to `modern` style, but here accidentals also get canceled across the staves in the same `GrandStaff` or `PianoStaff`, hence all the cancellations of the final notes.

  This accidental style applies to the current `GrandStaff` or `PianoStaff` by default.

`piano-cautionary`

  This is the same as `piano` but with the extra accidentals typeset as cautionaries.

`choral`

  This rule is a combination of the `modern-voice` and the `piano` style. It shows all accidentals required for singers that only follow their own voice, as well as additional accidentals for readers that follow all voices of an entire `ChoirStaff` simultaneously.

  This accidental style applies to the current `ChoirStaff` by default.

`choral-cautionary`

  This is the same as `choral` but with the extra accidentals typeset as cautionaries.

`neo-modern`

  This rule reproduces a common practice in contemporary music: accidentals are printed like with `modern`, but they are printed again if the same note appears later in the same measure – except if the note is immediately repeated.

`neo-modern-cautionary`

  This rule is similar to `neo-modern`, but the ‘extra’ accidentals are printed as cautionary accidentals (with parentheses). They can also be printed at a different size by overriding `AccidentalCautionary`’s `font-size` property.

`neo-modern-voice`

  This rule is used for multivoice accidentals to be read both by musicians playing one voice and musicians playing all voices. Accidentals are typeset for each voice as with `neo-modern`, but they are canceled across voices in the same `Staff`.

`neo-modern-voice-cautionary`

  This rule is similar to `neo-modern-voice`, but the extra accidentals are printed as cautionary accidentals.

`dodecaphonic`

  This rule reflects a practice introduced by composers at the beginning of the 20th century, in an attempt to abolish the hierarchy between natural and non-natural notes. With this style, every note gets an accidental sign, including natural signs.

`dodecaphonic-no-repeat`

  Like with the dodecaphonic accidental style every note gets an accidental sign by default, but accidentals are suppressed for pitches immediately repeated within the same staff.

`dodecaphonic-first`

  Similar to the dodecaphonic accidental style every pitch gets an accidental sign, but only the first time it is encountered in a measure. Accidentals are only remembered for the actual octave but throughout voices.

`teaching`

  This rule is intended for students, and makes it easy to create scale sheets with automatically created cautionary accidentals. Accidentals are printed like with `modern`, but cautionary accidentals are added for all sharp or flat tones specified by the key signature, except if the note is immediately repeated.

`no-reset`

  This is the same as `default` but with accidentals lasting ‘forever’ and not only within the same measure:

`forget`

  This is the opposite of `no-reset`: Accidentals are not remembered at all – and hence all accidentals are typeset relative to the key signature, regardless of what came before in the music.

#### See also

Snippets: Pitches.

Internals Reference: Accidental, Accidental_engraver, GrandStaff, PianoStaff, Staff, AccidentalSuggestion, AccidentalPlacement, accidental-suggestion-interface.

#### Known issues and warnings

Simultaneous notes are not considered in the automatic determination of accidentals; only previous notes and the key signature are considered. Forcing accidentals with `!` or `?` may be required when the same note name occurs simultaneously with different alterations, as in ‘`<f! fis!>`’.

Cautionary cancellation of accidentals is done by looking at previous measure. However, in the `\alternative` block following a `\repeat volta N` section, one would expect the cancellation being calculated using the previous played measure, not previous printed measure. In the following example, the natural `c` in the second alternative does not need a natural sign:

The following work-around can be used: define a function that locally changes the accidental style to `forget`:

>     forget = #(define-music-function (music) (ly:music?) #{
>       \accidentalStyle forget
>       #music
>       \accidentalStyle modern
>     #})
>     {
>       \accidentalStyle modern
>       \time 2/4
>       \repeat volta 2 {
>         c'2
>       }
>       \alternative {
>          cis'
>          \forget c'
>       }
>     }

#### Ambitus

The term ambitus (pl. ambitus) denotes a range of pitches for a given voice in a part of music. It may also denote the pitch range that a musical instrument is capable of playing. Ambitus are printed on vocal parts so that performers can easily determine if it matches their capabilities.

Ambitus are denoted at the beginning of a piece near the initial clef. The range is graphically specified by two note heads that represent the lowest and highest pitches. Accidentals are only printed if they are not part of the key signature.

>     \layout {
>       \context {
>         \Voice
>         \consists "Ambitus_engraver"
>       }
>     }

>     \relative {
>       aes' c e2
>       cis,1
>     }

#### Selected Snippets

Adding ambitus per voice

Ambitus can be added per voice. In this case, the ambitus must be moved manually to prevent collisions.

>     \new Staff <<
>       \new Voice \with {
>         \consists "Ambitus_engraver"
>       } \relative c'' {
>         \override Ambitus.X-offset = #2.0
>         \voiceOne
>         c4 a d e
>         f1
>       }
>       \new Voice \with {
>         \consists "Ambitus_engraver"
>       } \relative c' {
>         \voiceTwo
>         es4 f g as
>         b1
>       }
>     >>

Ambitus with multiple voices

Adding the `Ambitus_engraver` to the `Staff` context creates a single ambitus per staff, even in the case of staves with multiple voices.

>     \new Staff \with {
>       \consists "Ambitus_engraver"
>       }
>     <<
>       \new Voice \relative c'' {
>         \voiceOne
>         c4 a d e
>         f1
>       }
>       \new Voice \relative c' {
>         \voiceTwo
>         es4 f g as
>         b1
>       }
>     >>

Changing the ambitus gap

It is possible to change the default gap between the ambitus noteheads and the line joining them.

>     \layout {
>       \context {
>         \Voice
>         \consists "Ambitus_engraver"
>       }
>     }

>     \new Staff {
>       \time 2/4
>       % Default setting
>       c'4 g''
>     }

>     \new Staff {
>       \time 2/4
>       \override AmbitusLine.gap = #0
>       c'4 g''
>     }

>     \new Staff {
>       \time 2/4
>       \override AmbitusLine.gap = #1
>       c'4 g''
>     }

>     \new Staff {
>       \time 2/4
>       \override AmbitusLine.gap = #1.5
>       c'4 g''
>     }

Ambitus after key signature

By default, ambitus are positioned at the left of the clef. The `\ambitusAfter` function allows for changing this placement. Syntax is `\ambitusAfter grob-interface` (see Interfaces Graphical Object Interfaces for a list of possible values for `grob-interface`). A common use case is printing the ambitus between key signature and time signature.

>     \new Staff \with {
>       \consists Ambitus_engraver
>     } \relative {
>       \ambitusAfter key-signature
>       \key d \major
>       es'8 g bes cis d2
>     }

#### See also

Music Glossary: ambitus.

Snippets: Pitches.

Internals Reference: Ambitus_engraver, Voice, Staff, Ambitus, AmbitusAccidental, AmbitusLine, AmbitusNoteHead, ambitus-interface.

#### Known issues and warnings

There is no collision handling in the case of multiple per-voice ambitus.

#### LilyPond — Notation Reference v2.22.2 (stable-branch).