### 4.4.1 Flexible vertical spacing within systems

Three separate mechanisms control the flexible vertical spacing within systems, one for each of the following categories:

• ungrouped staves,
• grouped staves (staves within a staff-group such as `ChoirStaff`, etc.), and
• non-staff lines (such as `Lyrics`, `ChordNames`, etc.).

The height of each system is determined in two steps. First, all of the staves are spaced according to the amount of space available. Then, the non-staff lines are distributed between the staves.

Note that the spacing mechanisms discussed in this section only control the vertical spacing of staves and non-staff lines within individual systems. The vertical spacing between separate systems, scores, markups, and margins is controlled by `\paper` variables, which are discussed in Flexible vertical spacing `\paper` variables.

#### Within-system spacing properties

The within-system vertical spacing mechanisms are controlled by two sets of grob properties. The first set is associated with the `VerticalAxisGroup` grob, which is created by all staves and non-staff lines. The second set is associated with the `StaffGrouper` grob, which can be created by staff-groups, but only if explicitly called. These properties are described individually at the end of this section.

The names of these properties (except for `staff-affinity`) follow the format `item1-item2-spacing`, where `item1` and `item2` are the items to be spaced. Note that `item2` is not necessarily below `item1`; for example, `nonstaff-relatedstaff-spacing` will measure upwards from the non-staff line if `staff-affinity` is `UP`.

Each distance is measured between the reference points of the two items. The reference point for a staff is the vertical center of its `StaffSymbol` (i.e. the middle line if `line-count` is odd; the middle space if `line-count` is even). The reference points for individual non-staff lines are given in the following table:

Non-staff lineReference point
`ChordNames`baseline
`NoteNames`baseline
`Lyrics`baseline
`Dynamics`mid-height of ‘m’
`FiguredBass`highest point
`FretBoards`top line

In the following image, horizontal lines indicate the positions of these reference points:

Each of the vertical spacing grob properties (except `staff-affinity`) uses the same alist structure as the `\paper` spacing variables discussed in Flexible vertical spacing `\paper` variables. Specific methods for modifying alists are discussed in Modifying alists. Grob properties should be adjusted with an `\override` inside a `\score` or `\layout` block, and not inside a `\paper` block.

The following example demonstrates the two ways these alists can be modified. The first declaration updates one key-value individually, and the second completely re-defines the property:

```\new Staff \with {
\override VerticalAxisGroup.default-staff-staff-spacing.basic-distance = #10
} { … }

\new Staff \with {
\override VerticalAxisGroup.default-staff-staff-spacing =
#'((basic-distance . 10)
(minimum-distance . 9)
(stretchability . 10))
} { … }
```

To change any spacing settings globally, put them in the `\layout` block:

```\layout {
\context {
\Staff
\override VerticalAxisGroup.default-staff-staff-spacing.basic-distance = #10
}
}
```

Standard settings for the vertical spacing grob properties are listed in VerticalAxisGroup and StaffGrouper. Default overrides for specific types of non-staff lines are listed in the relevant context descriptions in Contexts.

#### Properties of the `VerticalAxisGroup` grob

`VerticalAxisGroup` properties are typically adjusted with an `\override` at the `Staff` level (or equivalent).

`staff-staff-spacing`

Used to determine the distance between the current staff and the staff just below it in the same system, even if one or more non-staff lines (such as `Lyrics`) are placed between the two staves. Does not apply to the bottom staff of a system.

Initially, the `staff-staff-spacing` of a `VerticalAxisGroup` is a Scheme function that applies the properties of the `StaffGrouper` if the staff is part of a group, or the `default-staff-staff-spacing` of the staff otherwise. This allows staves to be spaced differently when they are grouped. For uniform spacing regardless of grouping, this function may be replaced by a flexible-spacing alist, using the complete-redefinition form of override shown above.

`default-staff-staff-spacing`

A flexible-spacing alist defining the `staff-staff-spacing` used for ungrouped staves, unless `staff-staff-spacing` has been explicitly set with an `\override`.

`staff-affinity`

The direction of the staff to use for spacing the current non-staff line. Choices are `UP`, `DOWN`, and `CENTER`. If `CENTER`, the non-staff line will be placed equidistant between the two nearest staves on either side, unless collisions or other spacing constraints prevent this. Adjacent non-staff lines should have non-increasing `staff-affinity` from top to bottom, e.g. a non-staff line set to `UP` should not immediately follow one that is set to `DOWN`. Non-staff lines at the top of a system should use `DOWN`; those at the bottom should use `UP`. Setting `staff-affinity` for a staff causes it to be treated as a non-staff line. Setting `staff-affinity` to `#f` causes a non-staff line to be treated as a staff. Setting `staff-affinity` to `UP`, `CENTER`, or `DOWN` causes a staff to be spaced as a non-staff line.

`nonstaff-relatedstaff-spacing`

The distance between the current non-staff line and the nearest staff in the direction of `staff-affinity`, if there are no non-staff lines between the two, and `staff-affinity` is either `UP` or `DOWN`. If `staff-affinity` is `CENTER`, then `nonstaff-relatedstaff-spacing` is used for the nearest staves on both sides, even if other non-staff lines appear between the current one and either of the staves. This means that the placement of a non-staff line depends on both the surrounding staves and the surrounding non-staff lines. Setting the `stretchability` of one of these types of spacing to a small value will make that spacing dominate. Setting the `stretchability` to a large value will make that spacing have little effect.

`nonstaff-nonstaff-spacing`

The distance between the current non-staff line and the next non-staff line in the direction of `staff-affinity`, if both are on the same side of the related staff, and `staff-affinity` is either `UP` or `DOWN`.

`nonstaff-unrelatedstaff-spacing`

The distance between the current non-staff line and the staff in the opposite direction from `staff-affinity`, if there are no other non-staff lines between the two, and `staff-affinity` is either `UP` or `DOWN`. This can be used, for example, to require a minimum amount of padding between a `Lyrics` line and the staff to which it does not belong.

#### Properties of the `StaffGrouper` grob

`StaffGrouper` properties are typically adjusted with an `\override` at the `StaffGroup` level (or equivalent).

`staff-staff-spacing`

The distance between consecutive staves within the current staff-group. The `staff-staff-spacing` property of an individual staff’s `VerticalAxisGroup` grob can be overriden with different spacing settings for that staff.

`staffgroup-staff-spacing`

The distance between the last staff of the current staff-group and the staff just below it in the same system, even if one or more non-staff lines (such as `Lyrics`) exist between the two staves. Does not apply to the bottom staff of a system. The `staff-staff-spacing` property of an individual staff’s `VerticalAxisGroup` grob can be overriden with different spacing settings for that staff.

Notation Reference: Flexible vertical spacing `\paper` variables, Modifying alists.

Installed Files: ‘ly/engraver-init.ly’, ‘scm/define-grobs.scm’.

Internals Reference: Contexts, VerticalAxisGroup, StaffGrouper.

#### Spacing of ungrouped staves

Staves (such as `Staff`, `DrumStaff`, `TabStaff`, etc.) are contexts that can contain one or more voice contexts, but cannot contain any other staves.

The following properties affect the spacing of ungrouped staves:

• `VerticalAxisGroup` properties:
• `default-staff-staff-spacing`
• `staff-staff-spacing`

These grob properties are described individually above; see Within-system spacing properties.

Additional properties are involved for staves that are part of a staff-group; see Spacing of grouped staves.

The following example shows how the `default-staff-staff-spacing` property can affect the spacing of ungrouped staves. The same overrides applied to `staff-staff-spacing` would have the same effect, but would also apply in cases where the staves are combined in a group or groups.

```\layout {
\context {
\Staff
\override VerticalAxisGroup.default-staff-staff-spacing =
#'((basic-distance . 8)
(minimum-distance . 7)
}
}

<<
% The very low note here needs more room than 'basic-distance
% can provide, so the distance between this staff and the next
\new Staff { b,2 r | }

% Here, 'basic-distance provides enough room, and there is no
% need to compress the space (towards 'minimum-distance) to make
% room for anything else on the page, so the distance between
% this staff and the next is determined by 'basic-distance.
\new Staff { \clef bass g2 r | }

% By setting 'padding to a negative value, staves can be made to
% collide.  The lowest acceptable value for 'basic-distance is 0.
\new Staff \with {
\override VerticalAxisGroup.default-staff-staff-spacing =
#'((basic-distance . 3.5)
} { \clef bass g2 r | }
\new Staff { \clef bass g2 r | }
>>
```

Installed Files: ‘scm/define-grobs.scm’.

Snippets: Spacing.

Internals Reference: VerticalAxisGroup.

#### Spacing of grouped staves

In orchestral and other large scores, it is common to place staves in groups. The space between groups is typically larger than the space between staves of the same group.

Staff-groups (such as `StaffGroup`, `ChoirStaff`, etc.) are contexts that can contain one or more staves simultaneously.

The following properties affect the spacing of staves inside staff-groups:

• `VerticalAxisGroup` properties:
• `staff-staff-spacing`
• `StaffGrouper` properties:
• `staff-staff-spacing`
• `staffgroup-staff-spacing`

These grob properties are described individually above; see Within-system spacing properties.

The following example shows how properties of the `StaffGrouper` grob can affect the spacing of grouped staves:

```\layout {
\context {
\Score
\override StaffGrouper.staff-staff-spacing.basic-distance = #1
}
}

<<
\new PianoStaff \with {
\override StaffGrouper.staffgroup-staff-spacing.basic-distance = #20
} <<
\new Staff { c'1 }
\new Staff { c'1 }
>>

\new StaffGroup <<
\new Staff { c'1 }
\new Staff { c'1 }
>>
>>
```

Installed Files: ‘scm/define-grobs.scm’.

Snippets: Spacing.

Internals Reference: VerticalAxisGroup, StaffGrouper.

#### Spacing of non-staff lines

Non-staff lines (such as `Lyrics`, `ChordNames`, etc.) are contexts whose layout objects are engraved like staves (i.e. in horizontal lines within systems). Specifically, non-staff lines are non-staff contexts that contain the Axis_group_engraver.

The following properties affect the spacing of non-staff lines:

• `VerticalAxisGroup` properties:
• `staff-affinity`
• `nonstaff-relatedstaff-spacing`
• `nonstaff-nonstaff-spacing`
• `nonstaff-unrelatedstaff-spacing`

These grob properties are described individually above; see Within-system spacing properties.

The following example shows how the `nonstaff-nonstaff-spacing` property can affect the spacing of consecutive non-staff lines. Here, by setting the `stretchability` key to a very high value, the lyrics are able to stretch much more than usual:

```\layout {
\context {
\Lyrics
\override VerticalAxisGroup.nonstaff-nonstaff-spacing.stretchability = #1000
}
}

\new StaffGroup
<<
\new Staff \with {
\override VerticalAxisGroup.staff-staff-spacing = #'((basic-distance . 30))
} { c'1 }
\new Lyrics \with {
\override VerticalAxisGroup.staff-affinity = #UP
} \lyricmode { up }
\new Lyrics \with {
\override VerticalAxisGroup.staff-affinity = #CENTER
} \lyricmode { center }
\new Lyrics \with {
\override VerticalAxisGroup.staff-affinity = #DOWN
} \lyricmode { down }
\new Staff { c'1 }
>>
```