### 1.1.3 Displaying pitches

This section discusses how to alter the output of pitches.

#### Clef

The clef may be altered. Middle C is shown in every example.

```\clef treble
c2 c
\clef alto
c2 c
\clef tenor
c2 c
\clef bass
c2 c
```

Other clefs include:

```\clef french
c2 c
\clef soprano
c2 c
\clef mezzosoprano
c2 c
\clef baritone
c2 c

\break

\clef varbaritone
c2 c
\clef subbass
c2 c
\clef percussion
c2 c
\clef tab
c2 c
```

Further supported clefs are described under Mensural clefs and Gregorian clefs.

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. The clef name must be enclosed in quotes when it contains underscores or digits.

```\clef treble
c2 c
\clef "treble_8"
c2 c
\clef "bass^15"
c2 c
```

#### Selected Snippets

Tweaking clef properties

The command `\clef "treble_8"` is equivalent to setting `clefGlyph`, `clefPosition` (which controls the vertical position of the clef), `middleCPosition` and `clefOctavation`. A clef is printed when any of the properties except `middleCPosition` are changed.

Note that changing the glyph, the position of the clef, or the octavation does not in itself change the position of subsequent notes on the staff: the position of middle C must also be specified to do this. The positional parameters are relative to the staff center line, positive numbers displacing upwards, counting one for each line and space. The `clefOctavation` value would normally be set to 7, -7, 15 or -15, but other values are valid.

When a clef change takes place at a line break the new clef symbol is printed at both the end of the previous line and the beginning of the new line by default. If the warning clef at the end of the previous line is not required it can be suppressed by setting the `Staff` property `explicitClefVisibility` to the value `end-of-line-invisible`. The default behavior can be recovered with `\unset Staff.explicitClefVisibility`.

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.

```\layout { ragged-right = ##t }

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

% The following clef changes do not preserve
% the normal relationship between notes 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.clefOctavation = #7
c'1
\set Staff.clefOctavation = #0
\set Staff.clefPosition = #0
c'1

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

Notation Reference: Mensural clefs, Gregorian clefs.

Snippets: Pitches.

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

#### 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 Accidentals 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`.

```\key g \major
fis1
f
fis
```

#### 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 "false" 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
}
```

The commonly used `\key` command sets the `keySignature` 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.keySignature = #`(((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. (Note the leading comma.) The accidentals in the key signature will appear in the reverse order to that in which they are specified.

Alternatively, for each item in the list, using the more concise format `(step . alter)` specifies that the same alteration should hold in all octaves.

For microtonal scales where a "sharp" is not 100 cents, `alter` refers to the alteration as a proportion of a 200-cent whole tone.

Here is an example of a possible key signature for generating a whole-tone scale:

```\relative c' {
\set Staff.keySignature = #`(((0 . 3) . ,SHARP)
((0 . 5) . ,FLAT)
((0 . 6) . ,FLAT))
c4 d e fis
aes4 bes c2
}
```

Music Glossary: church mode, scordatura.

Learning Manual: Accidentals and key signatures.

Snippets: Pitches.

#### Ottava brackets

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

```a'2 b
\ottava #1
a b
\ottava #0
a b
```

The `ottava` function also takes -1 (for 8va bassa), 2 (for 15ma), and -2 (for 15ma bassa) as arguments.

#### Selected Snippets

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`.

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

Music Glossary: octavation.

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" {
\relative c'' {
\set Staff.instrumentName = #"Vln"
\set Staff.midiInstrument = #"violin"
% not strictly necessary, but a good reminder
\transposition c'

\key c \major
g4( c8) r c r c4
}
}
\new Staff = "clarinet" {
\relative c'' {
\set Staff.instrumentName = \markup { Cl (B\flat) }
\set Staff.midiInstrument = #"clarinet"
\transposition bes

\key d \major
a4( d8) r d r d4
}
}
>>
```

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

```\set Staff.instrumentName = #"Cl (A)"
\key a \major
\transposition a
c d e f
\textLengthOn
s1*0^\markup { Switch to B\flat clarinet }
R1

\key bes \major
\transposition bes
c2 g
```

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 <<
#(set-accidental-style '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:

```#(set-accidental-style 'voice 'StaffGroup)
```

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

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

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

\new PianoStaff {
<<
\context Staff = "up" {
#(set-accidental-style 'default)
\musicA
}
\context Staff = "down" {
#(set-accidental-style '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 {
<<
\context Staff = "up" {
%%% change the next line as desired:
#(set-accidental-style 'default 'Score)
\musicA
}
\context 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 prints the same accidentals as `default`, with two exceptions 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 (the ones not typeset by `default`) are typeset as cautionary accidentals. They are by default printed with parentheses, but they can also be printed in reduced size by defining the `cautionary-style` property of `AccidentalSuggestion`.

`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.

`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.

`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.

`teaching`

This rule is intended for students, and makes it easy to create scale sheets with automagically 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. Unlike `dodecaphonic`, this rule never prints any naturals.

#### Selected Snippets

Dodecaphonic-style accidentals for each note including naturals In early 20th century works, starting with Schoenberg, Berg and Webern (the "Second" Viennese school), every pitch in the twelve-tone scale has to be regarded as equal, without any hierarchy such as the classical (tonal) degrees. Therefore, these composers print one accidental for each note, even at natural pitches, to emphasize their new approach to music theory and language.

This snippet shows how to achieve such notation rules.

```\score {
\new Staff {
#(set-accidental-style 'dodecaphonic)
c'4 dis' cis' cis'
c'4 dis' cis' cis'
c'4 c' dis' des'
}
\layout {
\context {
\Staff
\remove "Key_engraver"
}
}
}
```

Snippets: Pitches.

#### Known issues and warnings

Simultaneous notes are considered to be entered in sequential mode. This means that in a chord the accidentals are typeset as if the notes in the chord happen one at a time, in the order in which they appear in the input file. This is a problem when accidentals in a chord depend on each other, which does not happen for the default accidental style. The problem can be solved by manually inserting `!` and `?` for the problematic notes.

#### 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 c'' {
aes c e2
cis,1
}
```

#### Selected Snippets

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
}
>>

```

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.

Other languages: français, español, deutsch.