LilyPond Learning Manual: 4.4.2 Within-staff objects

### 4.4.2 Within-staff objects

We have already seen how the commands `\voiceXXX` affect the direction of slurs, ties, fingering and everything else which depends on the direction of the stems. These commands are essential when writing polyphonic music to permit interweaving melodic lines to be distinguished. But occasionally it may be necessary to override this automatic behavior. This can be done for whole sections of music or even for an individual note. The property which controls this behavior is the `direction` property of each layout object. We first explain what this does, and then introduce a number of ready-made commands which avoid your having to code explicit overrides for the more common modifications.

Some layout objects like slurs and ties curve, bend or point either up or down; others like stems and flags also move to right or left when they point up or down. This is controlled automatically when `direction` is set.

The following example shows in bar 1 the default behavior of stems, with those on high notes pointing down and those on low notes pointing up, followed by four notes with all stems forced down, four notes with all stems forced up, and finally four notes reverted back to the default behavior.

>     a4 g c a |
>     \override Stem #'direction = #DOWN
>     a4 g c a |
>     \override Stem #'direction = #UP
>     a4 g c a |
>     \revert Stem #'direction
>     a4 g c a |

Here we use the constants `DOWN` and `UP`. These have the values `-1` and `+1` respectively, and these numerical values may be used instead. The value `0` may also be used in some cases. It is simply treated as meaning `UP` for stems, but for some objects it means ‘center’. There is a constant, `CENTER` which has the value `0`.

However, these explicit overrides are not usually used, as there are simpler equivalent predefined commands available. Here is a table of the commonest. The meaning of each is stated where it is not obvious.

Down/Left | Up/Right | Revert | Effect
--- | --- | --- | ---
`\arpeggioArrowDown` | `\arpeggioArrowUp` | `\arpeggioNormal` | Arrow is at bottom, at top, or no arrow
`\dotsDown` | `\dotsUp` | `\dotsNeutral` | Direction of movement to avoid staff lines
`\dynamicDown` | `\dynamicUp` | `\dynamicNeutral` |
`\phrasingSlurDown` | `\phrasingSlurUp` | `\phrasingSlurNeutral` | Note: distinct from slur commands
`\slurDown` | `\slurUp` | `\slurNeutral` |
`\stemDown` | `\stemUp` | `\stemNeutral` |
`\textSpannerDown` | `\textSpannerUp` | `\textSpannerNeutral` | Text entered as spanner is below/above staff
`\tieDown` | `\tieUp` | `\tieNeutral` |
`\tupletDown` | `\tupletUp` | `\tupletNeutral` | Tuplets are below/above notes

Note that these predefined commands may not be preceded by `\once`. If you wish to limit the effect to a single note you must either use the equivalent `\once \override` command or use the predefined command followed after the affected note by the corresponding `\xxxNeutral` command.

#### Fingering

The placement of fingering on single notes can also be controlled by the `direction` property, but changing `direction` has no effect on chords. As we shall see, there are special commands which allow the fingering of individual notes of chords to be controlled, with the fingering being placed above, below, to the left or to the right of each note.

First, here’s the effect of `direction` on the fingering attached to single notes. The first bar shows the default behaviour, and the following two bars shows the effect of specifying `DOWN` and `UP`:

>     c4-5 a-3 f-1 c'-5 |
>     \override Fingering #'direction = #DOWN
>     c4-5 a-3 f-1 c'-5 |
>     \override Fingering #'direction = #UP
>     c4-5 a-3 f-1 c'-5 |

However, overriding the `direction` property is not the easiest way of manually setting the fingering above or below the notes; using `_` or `^` instead of `-` before the fingering number is usually preferable. Here is the previous example using this method:

>     c4-5 a-3 f-1 c'-5 |
>     c4_5 a_3 f_1 c'_5 |
>     c4^5 a^3 f^1 c'^5 |

The `direction` property is ignored for chords, but the directional prefixes, `_` and `^` do work. By default, the fingering is automatically placed both above and below the notes of a chord, as shown:

>     <c-5 g-3>4
>     <c-5 g-3 e-2>4
>     <c-5 g-3 e-2 c-1>4

but this may be overridden to manually force all or any of the individual fingering numbers above or below:

>     <c-5 g-3 e-2 c-1>4
>     <c^5 g_3 e_2 c_1>4
>     <c^5 g^3 e^2 c_1>4

Even greater control over the placement of fingering of the individual notes in a chord is possible by using the `\set fingeringOrientations` command. The format of this command is:

>     \set fingeringOrientations = #'([up] [left/right] [down])

`\set` is used because `fingeringOrientations` is a property of the `Voice` context, created and used by the `New_fingering_engraver`.

The property may be set to a list of one to three values. It controls whether fingerings may be placed above (if `up` appears in the list), below (if `down` appears), to the left (if `left` appears, or to the right (if `right` appears). Conversely, if a location is not listed, no fingering is placed there. LilyPond takes these constraints and works out the best placement for the fingering of the notes of the following chords. Note that `left` and `right` are mutually exclusive – fingering may be placed only on one side or the other, not both.

Note: To control the placement of the fingering of a single note using this command it is necessary to write it as a single note chord by placing angle brackets round it.

Here are a few examples:

>     \set fingeringOrientations = #'(left)
>     <f-2>4
>     <c-1 e-2 g-3 b-5>4
>     \set fingeringOrientations = #'(left)
>     <f-2>4
>     <c-1 e-2 g-3 b-5>4 |
>     \set fingeringOrientations = #'(up left down)
>     <f-2>4
>     <c-1 e-2 g-3 b-5>4
>     \set fingeringOrientations = #'(up left)
>     <f-2>4
>     <c-1 e-2 g-3 b-5>4 |
>     \set fingeringOrientations = #'(right)
>     <f-2>4
>     <c-1 e-2 g-3 b-5>4

If the fingering seems a little crowded the `font-size` could be reduced. The default value can be seen from the `Fingering` object in the IR to be `-5`, so let’s try `-7`:

>     \override Fingering #'font-size = #-7
>     \set fingeringOrientations = #'(left)
>     <f-2>4
>     <c-1 e-2 g-3 b-5>4
>     \set fingeringOrientations = #'(left)
>     <f-2>4
>     <c-1 e-2 g-3 b-5>4 |
>     \set fingeringOrientations = #'(up left down)
>     <f-2>4
>     <c-1 e-2 g-3 b-5>4
>     \set fingeringOrientations = #'(up left)
>     <f-2>4
>     <c-1 e-2 g-3 b-5>4 |
>     \set fingeringOrientations = #'(right)
>     <f-2>4
>     <c-1 e-2 g-3 b-5>4

Other languages: česky, deutsch, español, français, italiano, 日本語, nederlands.

#### LilyPond — Learning Manual